fimo 2.10.1-staging.2 → 2.10.1-staging.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/assets/skills/fimo-cli/SKILL.md +2 -2
  2. package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
  3. package/assets/skills/fimo-cli/references/branches.md +43 -106
  4. package/assets/skills/fimo-cli/references/content/bulk.md +3 -12
  5. package/assets/skills/fimo-cli/references/content/localized.md +1 -1
  6. package/assets/skills/fimo-cli/references/content/sql.md +3 -10
  7. package/assets/skills/fimo-cli/references/deploy.md +35 -126
  8. package/assets/skills/fimo-cli/references/domains.md +38 -131
  9. package/assets/skills/fimo-cli/references/init.md +36 -170
  10. package/assets/skills/fimo-cli/references/projects.md +1 -1
  11. package/assets/skills/fimo-code/references/design.md +42 -126
  12. package/assets/skills/fimo-migration/SKILL.md +114 -408
  13. package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
  14. package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
  15. package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
  16. package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
  17. package/assets/skills/fimo-migration/references/qa/results.md +78 -0
  18. package/assets/skills/fimo-migration/references/qa.md +102 -383
  19. package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
  20. package/assets/skills/fimo-migration/references/setup.md +90 -0
  21. package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
  22. package/assets/skills/fimo-migration/references/workers.md +1 -1
  23. package/assets/skills/fimo-migration/references/workflow.md +117 -171
  24. package/assets/skills/fimo-studio/SKILL.md +4 -1
  25. package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
  26. package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
  27. package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
  28. package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
  29. package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
  30. package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
  31. package/dist/cli/bundle.json +1 -1
  32. package/dist/cli/index.js +32 -11
  33. package/package.json +8 -8
  34. package/templates/astro/package.json +3 -3
  35. package/templates/nextjs/package.json +4 -4
  36. package/templates/react-router/package.json +5 -5
  37. package/templates/sveltekit/package.json +3 -3
  38. package/templates/vite/package.json +5 -5
@@ -1,430 +1,136 @@
1
1
  ---
2
2
  name: fimo-migration
3
3
  description: >-
4
- End-to-end, LLM-agnostic website migration workflow for moving any published
5
- site, website-builder export, source repository, CMS export, media folder, or
6
- form-heavy site into Fimo. Use when the migration must preserve routes,
7
- media, CMS schemas and entries, forms, SEO, redirects, locales, and unresolved
8
- gaps with a verifiable manifest and QA gate. This is the single canonical
9
- migration skill for URL-only, source-backed, and hybrid migrations.
4
+ Move a published site, website-builder export, source repository, CMS
5
+ export, media folder, or form-heavy site into Fimo. Use for URL-only,
6
+ source-backed, and hybrid migrations that must keep routes, media, CMS
7
+ schemas and entries, forms, SEO, redirects, and locales, and record every
8
+ gap with a QA gate.
10
9
  ---
11
10
 
12
11
  # Fimo Migration
13
12
 
14
- Move published URLs, exports, source repositories, CMS data, media, and forms
15
- into a real Fimo project without silently dropping source material.
16
-
17
- > **Experimental:** migration support is limited. Assess what can be preserved,
18
- > explain unsupported parts, record every gap as an owner-visible unresolved
19
- > item, and do not promise behavior that the target cannot prove. When the CLI
20
- > supports the source framework, preserve it explicitly and verify the runtime
21
- > before importing data.
22
- >
23
- > Use the pinned CLI invocation selected for this flow for every `fimo` command in the migration (see CLI provenance); do not install it globally.
24
-
25
- The first pass is a faithful migration, not a framework conversion. Detect the
26
- source framework before setup. When `fimo migrate init` creates the target, pass
27
- it explicitly: for a Next.js source, use `--framework nextjs`; never rely
28
- on the React Router default. The setup receipt must report the target runtime
29
- framework, and a mismatch is a setup failure before any schemas, entries,
30
- assets, labels, or forms are imported.
31
-
32
- Keep third-party integrations when Fimo does not reproduce their behavior
33
- end-to-end. Preserve the original code path and record required environment
34
- variable names only; never read or copy secret values. A missing secret is a
35
- follow-up for the owner, not permission to silently remove the integration.
36
-
37
- Before any source, target, Fimo, or remote write, inspect the available source
38
- read-only and follow [questions-and-improvements.md](references/questions-and-improvements.md).
39
- Use the coding agent's native structured-question UI when available. Ask one
40
- stacked batch of the decisions the source cannot answer instead of interrupting
41
- the migration for each question. A migration request never authorizes moving
42
- environment values or credentials.
43
-
44
- When migration replaces local or bundled content with Fimo reads, preserving
45
- content-delivery performance is part of fidelity. Keep build-time and
46
- server-rendered content off the browser request path, use direct generated-client
47
- lookups, avoid duplicate or sequential reads, and prove edit freshness. Do not
48
- ask a generic optimization question or bundle a framework upgrade into the
49
- migration.
50
-
51
- ## Shared site knowledge
52
-
53
- Before site planning, recommendations, design, copy, content, or code work, read the site's
54
- knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
55
- Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
56
- empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
57
-
58
- ## Execution environment
59
-
60
- Run this skill from a coding-agent process that has direct access to the
61
- migration checkout. The process must be able to read and write source files,
62
- run bounded shell scripts, spawn its own subagents, and invoke the selected
63
- standalone Fimo CLI. The root agent owns the complete loop: fan out workers,
64
- fan in their reports, repair what they missed, and validate the real target.
65
-
66
- A plan, an evidence pack, or a generated report without source changes and
67
- verified Fimo state is only a draft. Do not finish with an explanation when the
68
- migration request requires an implementation.
69
-
70
- ## CLI provenance
71
-
72
- Run every `fimo` command in the migration through one released, pinned CLI
73
- artifact, and record which one.
74
-
75
- - Use the exact CLI invocation selected for this flow. If none was provided,
76
- stop and request an exact released version or immutable package URL. Never
77
- default to `latest` or another moving dist-tag, never install it globally,
78
- and never switch artifacts mid-run.
79
- - Never run the migration through a `file:`-linked workspace CLI from a Fimo
80
- source checkout: the workspace binary skips the publish-time bundle and can
81
- miss bundled workspace packages such as `@fimo/cli-kit`. When the migration
82
- must exercise unreleased CLI changes, publish a pinned dev artifact from that
83
- checkout first (`pnpm -F fimo publish-cli -- --id <task-name>`, or
84
- `node scripts/remote-dev-publish-cli.mjs --id <task-name>` when the checkout
85
- runs on a Dev Remote box) and use the exact package the publish recorded in
86
- that checkout's `.fimo/dev.json`.
87
- - Record the provenance in the migration report - the `fimo --version` output
88
- plus the artifact source (an npm version, or the pinned artifact URL from
89
- `.fimo/dev.json`).
13
+ Move a site into a real Fimo project and drop no source material silently.
14
+ Migration is experimental: say what Fimo cannot keep, record each gap as an
15
+ owner-visible unresolved item, and promise nothing the target cannot prove.
16
+ Load a reference with `fimo skills get fimo-migration --ref <name>`.
17
+
18
+ ## Before you start
19
+
20
+ - **Own the loop.** You need direct access to the checkout, a shell, the
21
+ selected Fimo CLI, and subagents when the host has them. Load `fimo-cli` for
22
+ commands and `fimo-code` for schemas and framework code. A plan or report
23
+ without source changes and verified Fimo state is only a draft.
24
+ - **Pinned CLI.** Run every `fimo` command with the exact CLI invocation
25
+ selected for this flow. If there is none, stop and ask for an exact release
26
+ or an immutable package URL.
27
+ Never use `latest` or another moving tag, a global install, a `file:`
28
+ workspace CLI, or a second artifact. Record `fimo --version` and the
29
+ artifact source in the report.
30
+ - **Site knowledge.** Before planning, design, copy, content, or code work, run
31
+ `fimo knowledge get --json` (add `--project <id>` before the folder is
32
+ linked) and load `fimo skills get fimo-cli --ref knowledge`.
33
+ - **Ask once.** Inspect the source read-only, then ask one stacked batch of
34
+ the decisions the source cannot answer (`questions-and-improvements`). Set
35
+ up, link, import, edit, or move environment values only after the owner
36
+ answers every consent gate.
90
37
 
91
38
  ## Initialized target precondition
92
39
 
93
- This is the one setup decision; every other reference points here. Pick the
94
- row that matches the user's request and the folder's state. When the target is
95
- genuinely unclear, ask once in the preflight question batch.
40
+ Pick the case that matches the request and the folder (`setup` has details).
41
+ For an existing folder, first keep a baseline outside it.
96
42
 
97
- | Starting point | Setup | Original evidence |
98
- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
- | The user asked to put this existing folder on Fimo; it is already linked | Reuse it. Verify its project, branch, and framework. Run `fimo link <same-id> -C <folder>` only to repair it. | Keep the baseline below. |
100
- | The same, but the folder is not linked | Keep the baseline, then run `fimo link -C <folder> --branch <branch>`, with the project id when one was chosen. | Keep the baseline below. Never reset, overwrite, or discard existing work. |
101
- | The source is read-only input, or the user asked for a separate target; same framework | Copy or clone the source into the target first. If the copy kept a `.fimo/project.json`, reuse that project or resolve it on purpose. Then run `fimo link -C <target> --branch <branch>`. | The original stays read-only. A `git worktree` shares the repository's config and remotes: use an independent copy or clone when adding the `fimo` remote must not touch the original. |
102
- | An empty or new target with nothing to adopt, or an explicit framework conversion | `fimo migrate init <target> --framework <chosen>` (see Target setup). Never overlay a template on populated source. | The source repository or export stays separate. |
43
+ - **The user asked to put this existing folder on Fimo; it is already linked:**
44
+ reuse it. Verify its project, Branch, and framework.
45
+ - **The same folder, not linked:**
46
+ `fimo link -C <folder> --branch <branch>`, with the chosen project id.
47
+ - **Read-only source or a separate target, same framework:** copy or clone the
48
+ source into the target, then `fimo link -C <target> --branch <branch>`.
49
+ - **Empty target, or an explicit framework conversion:**
50
+ `fimo migrate init <target> --framework <chosen> --source-platform <platform>`.
103
51
 
104
- The baseline is an exact copy of the folder's pre-migration state, kept outside
105
- the folder. A commit plus a detached worktree is enough only when the tree is
106
- clean; otherwise also keep the dirty and untracked files. Never copy secret
107
- values into evidence.
52
+ Never invent a project or organization id. Never reset, overwrite, or relink
53
+ existing work without the owner's choice.
108
54
 
109
- `fimo link` keeps the folder's code, framework, git history, branches, and
110
- `origin`, initializes a repository when there is none, and adds only the Fimo
111
- dependency, `.fimo/project.json`, the `fimo` remote, and
112
- `.fimo/config.json#runtime.framework`. It never overlays a template.
113
-
114
- Never invent a project or organization id, and never silently relink a folder
115
- to another project (`fimo link --relink` needs the owner's explicit choice).
116
- In a non-interactive shell, `fimo link` on an unlinked folder without an id,
117
- and `fimo migrate init` without `--project-id`, create a new project in the
118
- active organization, else the only one; `fimo migrate init` also takes `--org`. With several organizations and none
119
- active, the CLI fails clearly: ask the user which one. Ask only for a selection
120
- the CLI cannot resolve.
121
-
122
- Every row ends at the same gate. Before workers start, prove the actual project
123
- id and branch, a runtime framework that matches the source or the chosen
124
- conversion, the selected pinned CLI, and a successful data-plane read such as
125
- `fimo schemas list -C <target> --branch <branch>`. A local marker, generated
126
- `.fimo` JSON, or a `ready: true` receipt without that read is not
127
- initialization. Give workers the project id, branch, exact CLI invocation, and
128
- verification command. If any setup step fails, stop before workers and report
129
- the exact failed command and setup requirement.
55
+ **Setup gate.** Before workers start, prove the project id and Branch, a
56
+ runtime framework that matches the source or the chosen conversion, the pinned
57
+ CLI, and a data-plane read: `fimo schemas list -C <target> --branch <branch>`.
58
+ A marker file or `ready: true` without that read is not setup. If a step
59
+ fails, stop and report the failed command.
130
60
 
131
61
  ## Core contract
132
62
 
133
- - Migrate 1:1, not a compact approximation. Keep the source's route surface
134
- and user-visible behavior: do not refactor routes merely to make the
135
- migration easier, and do not replace many source pages with one generic
136
- static shell. Every source page, content construct, array item, Markdown or
137
- MDX block, imported component, and meaningful UI behavior ends with a
138
- consuming target route or component, or with an explicit
139
- unresolved/incompatible item in the text plan/report.
140
- - The first migration produces a working Fimo app with minimal refactoring.
141
- Source-backed migrations preserve the detected source framework, router,
142
- runtime, provider structure, and configuration by default: React Router/Vite
143
- stays React Router/Vite, and Next.js stays Next.js. Framework conversion is
144
- always an explicit user choice. URL-only and rebuild migrations have no
145
- source framework to preserve, so the user must choose the target framework
146
- explicitly; do not silently inherit a scaffold default. An explicit
147
- conversion is still a faithful first pass: the framework conversion worker
148
- ports the source's APIs, loaders, hardcoded content, integrations, and
149
- visible behavior into the new framework unchanged, and Fimo schemas,
150
- payloads, imports, and code wiring happen later through the content workers
151
- (`references/workers/content-execution.md`). That content pass is part of the
152
- migration, never a follow-up: the `editable-text` guardrail
153
- (`references/qa.md`) fails while visible text is still typed in the code. If the framework or hosting
154
- setup is unclear or unsupported, stop and ask instead of guessing,
155
- converting it, or deleting provider-specific files.
156
- - Inventory provider-specific files and rules before editing them. Classify each
157
- as `preserved`, `replaced`, `safely-unnecessary-implementation-detail`, or
158
- `unresolved`, with source evidence and affected behavior. Delete only after
159
- proving redundancy or recording the user's acceptance of the loss.
160
- - Preserve an existing third-party integration (email, marketing, payments,
161
- analytics) unless Fimo reproduces its exact user-visible behavior end to
162
- end. When behavior is not 1:1 - a Brevo newsletter flow, for example - keep
163
- the original integration wired and record the credential environment keys it
164
- needs by name, without reading secret values. A missing secret is a user
165
- follow-up in the report, never a reason to delete behavior or to block
166
- local build, evaluation, or QA checks.
167
- - Record every route, CMS record, media asset, form, locale, redirect, SEO
168
- field, and unsupported behavior as imported, deliberately ignored with a
169
- reason, or unresolved.
170
- - When Fimo cannot support a source feature, do not silently drop or simplify
171
- it. Preserve the original behavior when possible; otherwise leave the
172
- existing source behavior or its documented fallback in place and record an
173
- unresolved item with the source evidence, the owner action, and the
174
- user-visible impact. Never claim completion while source content is
175
- unwired.
176
- - Prefer source code and exports over what a page renders. Use a public URL as
177
- visual, SEO, route, and behavior evidence when better source material exists.
178
- When the source defines an active CMS but its deployed records are unavailable,
179
- rebuild published content from the public site only after the user explicitly
180
- chooses that lower-confidence path.
181
- - Read local files and exports directly and public APIs without credentials.
182
- Private APIs and CMSs require a user-provided export or a narrowly scoped
183
- server-side credential. Never read credentials from browser code or copy
184
- them into browser code, migration artifacts, or reports. Target-project
185
- authentication does not grant source access. If the source API URL or access
186
- is missing or unreachable, stop and ask whether the owner wants to provide a
187
- scoped export or read-only access, reconstruct the selected published routes
188
- from public pages, or migrate code only and leave those records external. Never
189
- infer permission to scrape, discover secrets, or contact private endpoints.
190
- - Model content before page code. Generated JSON is not imported content.
191
- - Model editorial content Fimo-natively: blocks for structured or repeatable
192
- sections, richtext for rich bodies, references for categories, authors,
193
- related items, and repeated taxonomies, and singleton content types for
194
- editable header, footer, navigation, and site settings. A `json` field is the
195
- last resort for opaque or application-owned data and carries a recorded
196
- reason. Better modeling never redesigns the site: preserve the source's
197
- content shape and behavior, and record the source-to-Fimo mapping
198
- (`references/content.md`).
199
- - Before writing media or wiring `<Image>`, load
200
- `fimo skills get fimo-migration --ref media` for the stored value, explicit
201
- `populate`, and responsive-image checks (`references/media.md`).
202
- - Every write is create-or-update, so any step can be rerun without duplicating
203
- a schema, entry, asset, single, or label.
204
- - Every decision cites the source file (and line when it matters) that proves
205
- it. What no worker could prove stays unresolved with an owner action.
206
- - Keep coordination evidence in the plain-text files
207
- `.fimo/migration/migration-plan.md` and
208
- `.fimo/migration/migration-report.md`. Use JSON for actual Fimo
209
- schema/content import payloads and the rendered guardrail inventory and
210
- capture response metadata required by `references/qa.md`. Do not
211
- create a target description, worker plan, decision registry, or JSON receipt
212
- just to describe the filesystem or agent work.
213
- - Do not report completion until the QA gate passes or every failed check is
214
- present in the migration report.
215
- - Import through the data-plane commands and verify locally before deployment.
216
- Deployment is not QA evidence. After successful local QA, follow the
217
- new-project or existing-project rule in Completion and deployment. Never
218
- publish without an explicit user request.
219
-
220
- ## Orient and route
221
-
222
- 1. Read the target project's `AGENTS.md`.
223
- 2. When creating or changing a Fimo application, load its `fimo` and
224
- `fimo-cli` skills for the required schemas, entries, forms, assets, and
225
- framework APIs.
226
- 3. Classify the available evidence:
227
- - **source-backed**: source repository, export, downloaded HTML, CMS data,
228
- or media folder. The source files are truth; the workers read them
229
- directly.
230
- - **url-only**: only a published URL. You read the site yourself: open each
231
- route in a browser, let client-side rendering finish, and record the
232
- sections, copy, images, links, and forms you actually see. Fetching HTML
233
- without executing JavaScript is not evidence — a client-rendered page
234
- returns an empty root element, which reads as a site with no content.
235
- Never report a route as covered from a fetch that returned no sections.
236
- - **hybrid**: source material plus a public URL. Treat source material as
237
- truth and the URL as comparison evidence.
238
- 4. Read `references/questions-and-improvements.md`, finish its read-only
239
- preflight, and collect the user's decisions before setup or implementation.
240
- 5. Read `references/workflow.md` before implementation and create or update the
241
- plain-text migration plan.
242
- 6. Load the references that apply:
243
- - Coordinator ownership and dependency gates -> `references/workers.md`.
244
- - Framework conversion worker -> `references/workers/framework.md`.
245
- - Content planner -> `references/workers/content-planner.md`.
246
- - Content data/code workers -> `references/workers/content-execution.md`.
247
- - Independent validator -> `references/workers/validator.md`.
248
- - Next.js source -> `references/frameworks/nextjs.md`.
249
- - Astro/SvelteKit SEO -> the target's `fimo-code` framework reference and
250
- `frameworks/seo-head`. Preserve the existing head owner and URL policy;
251
- follow its value-ownership and edit-and-render contract, preserving
252
- intentional source overrides rather than freezing editor-owned values.
253
- - React Router/Vite source -> load the target project's `fimo-code`
254
- `frameworks/react-router`, `frameworks/vite-react`, and
255
- `frameworks/hosting` references as applicable.
256
- - Next.js implementation -> load the target project's `fimo-code`
257
- `frameworks/next` and `frameworks/hosting` references. Those references
258
- describe available equivalents; verify hosting support instead of assuming
259
- every Next.js rule or runtime behavior is automatic.
260
- Framework, provider, and rendering-primitive rules live in the `fimo-code`
261
- skill; this skill routes to them and does not restate them.
262
-
263
- ## Target setup
264
-
265
- Choose the setup row in "Initialized target precondition". Never modify an
266
- original that the row keeps read-only, and never hand-write a
267
- `.fimo/project.json` marker to fake a link.
268
-
269
- `fimo migrate init` serves the empty-target and conversion row. It validates
270
- the target and CLI auth, then delegates project selection and creation to the
271
- standard `fimo init` flow (same options, no separate creation path), and
272
- returns a setup receipt covering auth, the target link, the migration
273
- directory, and readiness. It fails with a structured error when auth is
274
- missing, the target is missing or invalid, the target is populated but not
275
- linked, or the project or organization is inaccessible:
276
-
277
- - Use an existing (empty) project:
278
- `fimo migrate init <target-dir> --project-id <projectId> --framework <framework> --source-platform <platform>`
279
- - Create a new project:
280
- `fimo migrate init <target-dir> --framework <framework> --source-platform <platform>`,
281
- adding `--org <organizationId>` when the precondition's organization rule
282
- needs it.
283
-
284
- `--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
285
- `astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
286
- `other`); pass what the source proves, `unknown` only when nothing does. It is
287
- explicit only — nothing detects it, and omitting it records `unknown`.
288
-
289
- After setup, check `.fimo/config.json#runtime.framework` and the scaffold's
290
- framework files before starting workers. A Next.js target must still have its
291
- Next runtime/configuration (`next.config.*` and the source router shape), not a
292
- React Router scaffold.
293
-
294
- `fimo migrate init` on a new target scaffolds it and pushes its initial
295
- commit. `fimo link` and reusing a linked folder scaffold and push nothing; the
296
- first commit waits for `fimo deploy`. Project creation or linking and that
297
- initial push are the only remote writes setup performs — it never pushes
298
- schemas, uploads assets, or imports entries. Setup itself never deploys or publishes; the one new-project preview
299
- deploy happens only after successful local QA (see Completion and deployment).
300
-
301
- ## Command surface
302
-
303
- `fimo migrate init <dir>` is the only migration subcommand. It sets the target
304
- up and nothing else: it never reads, fetches, or renders the source site, and
305
- it produces no evidence pack, draft, manifest, or scaffold to inspect. Reading
306
- the source is your job, and every finding is yours to prove.
307
-
308
- - `fimo migrate init <dir> --project-id <projectId>` — use an existing project.
309
- - `fimo migrate init <dir> [--org <organizationId>]` — create a new project.
310
- - Both accept `--framework`, `--source-platform` (see Target setup),
311
- `--install` / `--no-install`, `--agents` / `-a`, `--mode`, `--template-root`,
312
- and `--json`; `-C <dir>` replaces the positional for an already-linked target.
313
-
314
- Setup (`fimo migrate init` or `fimo link`, chosen in Initialized target
315
- precondition) makes only the remote writes listed in Target setup. Data writes
316
- go through the normal commands against the linked target:
317
-
318
- - `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
319
- `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
320
- - `fimo deploy` / `fimo publish` — owner-approved only.
63
+ - **1:1.** Keep every route and visible behavior. Each source page, content
64
+ item, block, component, and behavior ends in a target route or as an
65
+ unresolved item. Never replace pages with a generic shell.
66
+ - **Keep the framework.** A source-backed migration keeps its framework,
67
+ router, runtime, and config. Convert only on the owner's explicit choice. For
68
+ URL-only or rebuild work, the owner chooses the framework. If hosting is
69
+ unclear, stop and ask.
70
+ - **Keep integrations.** Keep email, payment, analytics, and other
71
+ integrations wired unless Fimo gives the same behavior end to end. Record
72
+ environment key names only; never read or copy their values. A missing
73
+ secret is an owner follow-up, never a reason to remove behavior.
74
+ - **Account for everything.** Each route, record, asset, form, locale,
75
+ redirect, SEO field, provider file, and unsupported behavior is imported,
76
+ ignored with a reason, or unresolved with evidence, owner action, and
77
+ impact. Cite the source file for each decision.
78
+ - **Source access.** Prefer source code and exports to rendered pages. A
79
+ private source needs an owner export or a scoped server-side credential.
80
+ Never take credentials from browser code or put them in artifacts.
81
+ - **Content before code.** Model content the Fimo way (blocks, richtext,
82
+ references, Singles for shared chrome; `json` only with a reason) and keep
83
+ the source's shape (`content`). Generated JSON is not imported content.
84
+ - **Media.** Before you write media or wire `<Image>`, load
85
+ `fimo skills get fimo-migration --ref media`.
86
+ - **Safe writes.** Every write is create-or-update, so a rerun makes no
87
+ duplicates.
88
+ - **Plain text.** Plan in `.fimo/migration/migration-plan.md`, report in
89
+ `.fimo/migration/migration-report.md`. JSON is only for import payloads and
90
+ guardrail evidence.
91
+ - **Delivery is fidelity.** Content moved from local files to Fimo must not add
92
+ a browser wait (`content-delivery`). No generic speed question, no framework
93
+ upgrade.
321
94
 
322
95
  ## Migration loop
323
96
 
324
- 1. Inspect the source read-only, then ask the one preflight question batch from
325
- `references/questions-and-improvements.md`. Do not initialize, link, import,
326
- edit, or move environment values until the user answers every consent gate.
327
- 2. Run the setup path from "Initialized target precondition" and inspect the
328
- initialized target before any worker edits it. A `fimo link` adoption keeps
329
- the source framework; the `fimo migrate init` path chooses the
330
- target framework through the same canonical option as
331
- `fimo init`: pass the detected source framework for a source-backed
332
- migration, the framework the user explicitly chose for a conversion, and —
333
- for a URL-only or rebuild migration — the framework the user selected (ask
334
- when they have not). `--template-root` is a development/test
335
- override only; normal migration prompts must not select a framework by
336
- copying an arbitrary template path. The target's real files and directories
337
- are the authority for framework paths; do not invent a second `app/` or
338
- `src/app/` tree from an example.
339
- 3. Write a short `.fimo/migration/migration-plan.md` containing the chosen
340
- framework, source/target paths, worker owners, important dependencies, and
341
- known questions. Start the independent workers in `references/workers.md`:
342
- runtime/config, routes/SEO, content planning, and locales when those surfaces
343
- exist. When the user explicitly chose a framework conversion,
344
- one framework conversion worker replaces the runtime and routes lanes, owns
345
- all structural target code, and must pass the framework gate in
346
- `references/workers/framework.md` before content data and code workers
347
- start. Worker prompts and worker reports are plain text.
348
- 4. The content planner reads every content-bearing source and consumer. When
349
- content comes from an API, it traces the active application client and
350
- retrieves the complete accessible dataset before pushing schemas. It then
351
- writes complete schemas and import payloads, recording source items,
352
- consumers, batches, and unresolved behavior in the text plan rather than a
353
- second orchestration format.
354
- 5. Each discovery lane reports active media in its own surface. After the
355
- runtime/framework, routes/SEO, and content discovery receipts are terminal,
356
- the coordinator performs one fan-in: combine and deduplicate them into the
357
- complete media-obligation list. Give only that list to the media worker; do
358
- not require a content-planner rescan. Once it returns every mapping, patch
359
- code and payload consumers. Start data after the asset gate and content code
360
- only after its imported records read back successfully.
361
- 6. Fan in the workers' plain-text reports. Compare their claimed files with
362
- `git diff`, their Fimo writes with read-back CLI queries, and their source
363
- coverage with the content plan. Every source item must be migrated,
364
- deliberately preserved, or listed as unresolved with an owner action. A
365
- report that merely says “done” is not evidence.
366
- 7. Validate against the real target with a validator that did not author the
367
- changes and starts only after every other worker report is terminal: read
368
- back schemas, entries, singles, labels, and assets through the CLI, build
369
- the project, render the migrated routes, and verify hosting compatibility
370
- (local startup, Fimo Preview embeddability, build). Record `browserProof`
371
- when a browser is available; otherwise use deterministic
372
- HTTP/header/process/log checks and mark visual proof unavailable. Then run
373
- the QA gate in `references/qa.md`.
374
- 8. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
375
- unresolved items, timings from worker reports, and next actions.
376
-
377
- ## References
378
-
379
- - `references/workflow.md` - phase order, source intake, URL artifacts, and
380
- implementation loop.
381
- - `references/questions-and-improvements.md` - structured preflight questions,
382
- integration consent, and content-delivery performance preservation.
383
- - `references/decision.md` - plain-text decision and schema guidance; no
384
- decision JSON is required.
385
- - `references/content.md` - CMS, entries, references, and source value rules.
386
- - `references/media.md` - media obligations, upload, dedupe, and replacement.
387
- - `references/forms.md` - form classification and Fimo replacement.
388
- - `references/import-contract.md` - import obligations for media, entries, and
389
- forms.
390
- - `references/platforms.md` - platform-specific source-of-truth and rebuild
391
- notes.
392
- - `references/qa.md` - acceptance gate and report format.
393
- - `references/frameworks/nextjs.md` - Next.js routes, config, locales, and
394
- Markdown or MDX content.
395
- - `references/workers.md` - coordinator schedule, ownership, and gates.
396
- - `references/workers/framework.md` - explicit framework-conversion contract.
397
- - `references/workers/content-planner.md` - discovery, schemas, payloads, and
398
- handoff contract.
399
- - `references/workers/content-execution.md` - data import and code-wiring
400
- contracts.
401
- - `references/workers/validator.md` - independent fan-in validation.
402
- - `scripts/check-rendered-guardrails.mjs` evaluates the cited guardrail
403
- inventory against rendered HTML or a local server and fails closed on empty,
404
- missing, redirected, or vacuous evidence.
405
- - `scripts/apply-decision.mjs` and `scripts/write-migration-report.mjs` replay
406
- an older JSON-ledger migration. A new migration writes the plain-text plan
407
- and report instead; do not invoke them unless the user asks for that replay.
97
+ 1. Inspect read-only. Ask the preflight batch.
98
+ 2. Run setup and pass the setup gate. Read `workflow`.
99
+ 3. Write the plan, then start the workers in `workers`.
100
+ 4. The content planner retrieves the complete source data, then writes schemas
101
+ and payloads.
102
+ 5. When all discovery reports are terminal,
103
+ the coordinator performs one fan-in into one deduplicated media list.
104
+ Give only that list to the media worker. Start data after the asset gate, and content code only after its
105
+ imported records read back successfully.
106
+ 6. Check each worker claim against `git diff`, CLI read-back, and the plan.
107
+ "Done" is not evidence.
108
+ 7. A validator that changed nothing runs the QA gate (`qa`) after every writer.
109
+ 8. Write the report.
408
110
 
409
111
  ## Completion and deployment
410
112
 
411
- Use one final status:
412
-
413
- - **complete**: QA passed, counts match, and imports are verified.
414
- - **complete-with-unresolved**: the site builds and every known gap has an
415
- owner-readable reason and next action.
416
- - **draft-only**: imports or verification are incomplete, or the user asked for
417
- a draft.
418
-
419
- Never call a migration complete when CMS entries, media mappings, forms, route
420
- coverage, or migration-induced content-delivery regressions are unknown. Local
421
- QA remains the acceptance gate. If setup created a new Fimo project
422
- (`fimo migrate init` or `fimo link`), run one `fimo deploy` after QA
423
- and return its preview and dashboard links; skip it when the user said not to
424
- deploy or `FIMO_MIGRATION_NO_DEPLOY=1` is set. For an existing linked project,
425
- offer the deployment and wait for approval. Never run `fimo publish` without an
426
- explicit request.
427
-
428
- Broader performance work and framework modernization are separate tasks. Start
429
- them only when the user explicitly asks, and never use them to hide a migration
430
- regression.
113
+ Statuses: `complete` (QA passed, counts match), `complete-with-unresolved`
114
+ (the site works and each gap has an owner action), `draft-only` (imports or
115
+ checks incomplete). Never call a migration complete while entries, media,
116
+ forms, routes, or delivery regressions are unknown.
117
+
118
+ Local QA is the gate; a deploy is not QA evidence.
119
+ If setup created a new Fimo project (`fimo migrate init` or `fimo link`),
120
+ run one `fimo deploy` after QA and give the owner its `studio_url` (and the
121
+ `fimo preview url` link when they need the hosted site). Skip it
122
+ when the owner said not to deploy or `FIMO_MIGRATION_NO_DEPLOY=1` is set.
123
+ For an existing linked project, offer the deployment and wait for approval.
124
+ Never run `fimo publish` without an explicit request.
125
+
126
+ ## Where to look
127
+
128
+ - Setup commands, baseline, what setup writes, unreleased CLI → `setup`
129
+ - Preflight questions, integrations, environment values, missing CMS, partial scope → `questions-and-improvements`
130
+ - Content reads moved to Fimo, proof of no slowdown → `content-delivery`
131
+ - Phases, source intake, URL-only evidence, repairs → `workflow`
132
+ - Worker order and gates → `workers`; one worker → `workers/<framework|content-planner|content-execution|validator>`
133
+ - Content model and imports → `content`, `decision`, `import-contract`; media → `media`; forms → `forms`; platforms → `platforms`
134
+ - Next.js source → `frameworks/nextjs`; target code → fimo-code `frameworks/next`, `frameworks/react-router`, `frameworks/vite-react`, `frameworks/hosting`
135
+ - Astro or SvelteKit SEO → fimo-code `frameworks/seo-head`: keep the head owner, URL policy, and intentional overrides
136
+ - QA gate → `qa`; guardrails → `qa/guardrails`; browser checks → `qa/browser`; counts and report → `qa/results`