fimo 2.10.1-staging.1 → 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.
- package/assets/skills/fimo-cli/SKILL.md +57 -139
- package/assets/skills/fimo-cli/SKILL.studio.md +42 -0
- package/assets/skills/fimo-cli/references/branches.md +43 -106
- package/assets/skills/fimo-cli/references/content/bulk.md +48 -0
- package/assets/skills/fimo-cli/references/content/entries.md +54 -0
- package/assets/skills/fimo-cli/references/content/localized.md +56 -0
- package/assets/skills/fimo-cli/references/content/schemas.md +29 -0
- package/assets/skills/fimo-cli/references/content/sql.md +57 -0
- package/assets/skills/fimo-cli/references/content.md +33 -272
- package/assets/skills/fimo-cli/references/deploy.md +35 -126
- package/assets/skills/fimo-cli/references/domains.md +38 -131
- package/assets/skills/fimo-cli/references/forms.md +1 -1
- package/assets/skills/fimo-cli/references/init.md +36 -170
- package/assets/skills/fimo-cli/references/locales.md +2 -2
- package/assets/skills/fimo-cli/references/projects.md +1 -1
- package/assets/skills/fimo-code/references/design.md +42 -126
- package/assets/skills/fimo-migration/SKILL.md +114 -408
- package/assets/skills/fimo-migration/references/content-delivery.md +67 -0
- package/assets/skills/fimo-migration/references/frameworks/nextjs.md +1 -1
- package/assets/skills/fimo-migration/references/qa/browser.md +41 -0
- package/assets/skills/fimo-migration/references/qa/guardrails.md +95 -0
- package/assets/skills/fimo-migration/references/qa/results.md +78 -0
- package/assets/skills/fimo-migration/references/qa.md +102 -383
- package/assets/skills/fimo-migration/references/questions-and-improvements.md +77 -168
- package/assets/skills/fimo-migration/references/setup.md +90 -0
- package/assets/skills/fimo-migration/references/workers/validator.md +2 -2
- package/assets/skills/fimo-migration/references/workers.md +1 -1
- package/assets/skills/fimo-migration/references/workflow.md +117 -171
- package/assets/skills/fimo-studio/SKILL.md +12 -11
- package/assets/skills/fimo-studio/references/ai-chat/agents.md +46 -0
- package/assets/skills/fimo-studio/references/ai-chat/default-agents.md +57 -0
- package/assets/skills/fimo-studio/references/ai-chat/routines.md +53 -0
- package/assets/skills/fimo-studio/references/ai-chat.md +39 -76
- package/assets/skills/fimo-studio/references/custom-domains.md +2 -2
- package/assets/skills/fimo-studio/references/publish-and-deploy.md +1 -1
- package/dist/cli/bundle.json +1 -1
- package/dist/cli/index.js +38 -17
- package/package.json +8 -8
- package/templates/astro/package.json +3 -3
- package/templates/nextjs/package.json +4 -4
- package/templates/react-router/package.json +5 -5
- package/templates/sveltekit/package.json +3 -3
- package/templates/vite/package.json +5 -5
|
@@ -1,430 +1,136 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: fimo-migration
|
|
3
3
|
description: >-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
94
|
-
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
105
|
-
|
|
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
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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
|
-
-
|
|
134
|
-
and
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
(`
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
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
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
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
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
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`
|