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,188 +1,97 @@
1
- # Migration questions and content delivery
1
+ # Migration preflight questions
2
2
 
3
3
  ## Inspect before asking
4
4
 
5
- Start with read-only source inspection. Find the framework, router, version,
6
- content sources, integrations, API routes, environment variable names, and
7
- obvious runtime constraints. Do not initialize or link the target, edit files,
8
- write Fimo data, contact private services, deploy, or publish yet.
5
+ First inspect the source read-only: framework, router, version, content
6
+ sources, integrations, API routes, environment variable names, and runtime
7
+ limits. Do not set up or link the target, edit files, write Fimo data, contact
8
+ private services, deploy, or publish yet.
9
9
 
10
- Do not ask the user to explain facts the source already proves. Ask only when
11
- the answer changes authorization or forces a real choice:
10
+ Do not ask about facts the source proves. Ask only when the answer changes
11
+ authorization or forces a real choice:
12
12
 
13
13
  - an integration may be removed, replaced, disconnected, or moved;
14
- - environment configuration or credentials may need to move into Fimo;
15
- - the source framework is unknown or the user requested a conversion;
16
- - the source defines CMS content but the deployed records are unavailable;
17
- - two systems could own the same content or behavior; or
18
- - the requested migration includes a destructive or mutually exclusive choice.
19
-
20
- Preserve the source's visible behavior by default. Do not ask the user to list
21
- the routes, metadata, feeds, forms, locales, analytics, or content that must
22
- survive. Discovering and preserving them is the migration job. Do not ask a
23
- generic speed, optimization, or framework-upgrade question during migration.
14
+ - environment values or credentials may move into Fimo;
15
+ - the framework is unknown, the source is URL-only, or the user asked for a
16
+ conversion;
17
+ - the source defines CMS content but the deployed records are not available;
18
+ - two systems could own the same content or behavior;
19
+ - the request includes a destructive or mutually exclusive choice;
20
+ - a setup blocker: the target, the organization or project, or the pinned CLI.
21
+
22
+ Keep the source's visible behavior by default. Do not ask the user to list
23
+ the routes, metadata, feeds, forms, locales, analytics, or content to keep:
24
+ finding and keeping them is the migration's job. Do not ask a
25
+ generic speed, optimization, or framework-upgrade question.
24
26
 
25
27
  ## Ask one stacked batch
26
28
 
27
- Use the coding agent's native structured-question UI when it has one. The tool
28
- name differs between Codex, Claude Code, and other hosts.
29
-
30
- - Collect decisions from the same inspection and ask one preflight batch. Aim
31
- for one to three questions.
32
- - Include setup blockers already visible at that point, such as a missing target
33
- choice, organization or project, URL-only framework choice, or pinned CLI
34
- artifact. Do not save them for separate follow-up turns.
35
- - Give each question a short subject and two or three concrete choices. Put the
36
- recommended safe default first and state the consequence of each choice.
37
- - Write for the site owner, who may not know Fimo or the migration process. Do
38
- not put evaluator terms such as faithful acceptance, frozen result, or probe
39
- in a user-facing question. Explain Fimo terms the first time they matter.
40
- - Group environment keys by the integration they enable. Never ask one question
41
- per key.
42
- - Use multi-select for independent choices when the host supports it. Otherwise
43
- offer a few useful bundles.
44
- - Restate the accepted contract once after the answers, then start. Ask again
45
- only when new evidence creates a safety or consent decision that the initial
46
- inspection could not reveal.
47
- - When the host has no structured-question UI, send the whole batch as one
48
- numbered message. Do not drip questions across turns.
49
-
50
- ## Protect integrations and environment values
51
-
52
- Detect integration and environment key names without printing or reading their
53
- values. A request to migrate the website is not consent to move any environment
54
- value.
55
-
56
- - Keep third-party behavior wired when Fimo does not replace it exactly.
57
- - Never silently remove, replace, or partly imitate an integration.
58
- - Ask before changing its owner, credential store, or runtime behavior.
59
- - Without consent, leave current environment references unchanged. Mark live
60
- verification blocked when credentials are unavailable.
61
- - When the user chooses Fimo storage, load the current `fimo-cli`
62
- `project-vars-and-secrets` reference. Browser-safe configuration uses project
63
- variables. Hidden API keys and tokens use project secrets. Never turn a
64
- secret into a public variable.
65
- - When the owner chooses Fimo-managed secrets, ask them to add the values to
66
- Fimo. Never read existing secret values from env files, logs, browser code,
67
- migration artifacts, or worker transcripts.
68
-
69
- ## Ask before reconstructing missing CMS content
70
-
71
- Source repositories often contain CMS schemas and rendering code without the
72
- deployed records. A public website can recover what visitors can see, but it
73
- cannot prove drafts, unlinked records, editorial metadata, hidden relations, or
74
- private fields. Do not silently substitute scraped pages for the missing CMS.
75
-
76
- When required CMS records are unavailable, ask one question with these choices:
77
-
78
- - **Provide CMS access or an export (Recommended).** Use a scoped read-only
79
- credential or export to preserve the selected records, relations, locales,
80
- SEO, and media as completely as the source allows.
81
- - **Rebuild from the public website.** Use credential-free public APIs when
82
- available, then the rendered pages for the user-approved route slice. Treat
83
- the run as hybrid, import only published evidence, and report everything the
84
- public site cannot reveal.
85
- - **Migrate code only.** Keep the CMS integration and its records outside Fimo;
86
- do not claim that editorial content moved.
87
-
88
- The question should sound like this:
29
+ - Use the host's structured-question UI when it has one. Otherwise send the
30
+ whole batch as one numbered message. Never drip questions across turns.
31
+ - Aim for one to three questions. Give each a short subject and two or three
32
+ concrete choices, the recommended safe default first, with the result of each.
33
+ - Write for a site owner who may not know Fimo. Explain a Fimo term the first
34
+ time it matters. Do not use evaluator words such as "faithful acceptance" or
35
+ "probe".
36
+ - Group environment keys by the integration they enable, not one question per
37
+ key. Use multi-select for independent choices when the host supports it.
38
+ - After the answers, restate the accepted contract once and start. Ask again
39
+ only when new evidence creates a safety or consent decision.
40
+
41
+ ## Integrations and environment values
42
+
43
+ Find integration and environment key names without reading or printing their
44
+ values. A request to migrate the site is not consent to move any value.
45
+
46
+ - Keep third-party behavior wired when Fimo does not replace it exactly. Never
47
+ silently remove, replace, or partly imitate an integration.
48
+ - Ask before you change its owner, credential store, or runtime behavior.
49
+ Without consent, leave the current environment references unchanged and mark
50
+ live checks blocked when credentials are missing.
51
+ - When the owner chooses Fimo storage, load `fimo skills get fimo-cli --ref project-vars-and-secrets`:
52
+ browser-safe configuration goes in project variables, and hidden keys and
53
+ tokens in project secrets. Never turn a secret into a public variable.
54
+ - Ask the owner to add secret values to Fimo. Never read existing values from
55
+ env files, logs, browser code, migration artifacts, or worker transcripts.
56
+
57
+ ## Missing CMS records
58
+
59
+ A repository often has the CMS schemas and rendering code but not the deployed
60
+ records. The public site shows what visitors see, but not drafts, unlinked
61
+ records, editorial metadata, hidden relations, or private fields. Never
62
+ silently replace the CMS with scraped pages. Ask one question with three
63
+ choices:
64
+
65
+ - **Provide CMS access or an export (recommended).** A scoped read-only
66
+ credential or an export keeps records, relations, locales, SEO, and media.
67
+ - **Rebuild from the public website.** Use credential-free public APIs, then
68
+ the rendered pages of the approved routes. Import only published evidence
69
+ and report what the public site cannot show.
70
+ - **Migrate the code only.** The CMS and its records stay outside Fimo; do not
71
+ claim that content moved.
89
72
 
90
73
  > The repository contains the CMS structure, but not the content currently
91
74
  > published on the site. Should I use a read-only CMS export, rebuild the
92
- > selected pages from the public website, or migrate only the code and leave the
93
- > content where it is?
75
+ > selected pages from the public website, or migrate only the code and leave
76
+ > the content where it is?
94
77
 
95
- If the owner chooses the public website, stay inside the selected route scope.
96
- Public retrieval does not authorize private endpoint discovery, credential use,
97
- or a broader sweep. Record the URL, retrieval time, redirects, and every field
98
- or relation that remains unknown.
78
+ Public rebuild stays inside the selected routes. It does not authorize
79
+ private endpoints, credentials, or a broader sweep. Record the URL, retrieval
80
+ time, redirects, and each field or relation that stays unknown.
99
81
 
100
- ## Ask what happens outside a partial migration
82
+ ## Partial migration
101
83
 
102
- When the request selects only part of a website and does not say what should
103
- happen to the remaining pages, ask in the same preflight batch:
84
+ When the request moves only part of a site and does not say what happens to
85
+ the other pages, ask in the same batch:
104
86
 
105
87
  > We're moving only part of the site. What should happen when someone follows
106
88
  > a link to a page we aren't moving?
107
89
 
108
- Offer these choices:
109
-
110
- - **Keep opening the current site.** Preserve working absolute source URLs for
111
- pages outside the selected slice.
90
+ - **Keep opening the current site.** Keep working absolute source URLs for the
91
+ pages that do not move.
112
92
  - **Remove those pages.** Remove their navigation links and redirect known old
113
- routes to the migrated homepage instead of leaving broken relative links.
114
-
115
- Do not ask when every route is migrating or the request already settles this
116
- behavior. If the coordinator discovers an omitted route only after preflight,
117
- preserve its working absolute source URL and report it. Do not interrupt the
118
- migration with a late preference question.
119
-
120
- ## Preserve content delivery performance
121
-
122
- Replacing local Markdown, MDX, JSON, or hardcoded content with Fimo reads must
123
- not add an avoidable runtime wait. This is migration correctness, so apply it
124
- without asking an optimization question.
125
-
126
- First record how the source delivers each content family: at build time, on the
127
- server per request, or in the browser. Load the current `fimo-code` framework
128
- and generated-client references, then keep the same rendering and freshness
129
- semantics unless the target framework requires a documented equivalent.
130
-
131
- - Keep build-time or server-rendered source content on the server. Do not turn
132
- a local Markdown page into a client-side loading state or browser API
133
- waterfall.
134
- - Preserve known-route generation. For a static blog, list slugs once for route
135
- generation, then use `getBySlug` or another direct generated-client lookup for
136
- each detail route. Do not list the whole collection and filter it again on
137
- every page request.
138
- - Start independent reads together. Keep page-only content out of shared root
139
- layouts, and deduplicate the same read when metadata, a layout, and a page
140
- need it during one render.
141
- - Query only the fields, relations, and page of records the route consumes.
142
- Populate required references explicitly. Avoid unbounded collection reads and
143
- N+1 relation lookups.
144
- - Keep framework links and their normal prefetch behavior. Do not add broad
145
- forced prefetching that turns a page list into a burst of Fimo requests.
146
- - Preserve edit freshness. Static generation, revalidation, or caching is valid
147
- only when a normal rebuild or the source's normal refresh path shows the new
148
- Fimo value. Cold-build once as a diagnostic when the normal result is stale.
149
- - Do not upgrade the framework, change routers, add loading placeholders, or
150
- redesign the page to satisfy this rule. Those are separate changes unless the
151
- user explicitly requested them.
152
-
153
- Examples:
154
-
155
- - **Static Markdown blog:** import every post into Fimo, generate the known
156
- routes from a bounded slug list, read each post on the server during static
157
- generation, and ship the article in the initial HTML. A browser fetch for the
158
- article body is a migration regression.
159
- - **Large collection:** use a paginated, projected list for the index and a
160
- direct slug lookup for the detail page. Fetching every full record for every
161
- navigation is a migration regression even when the page eventually matches.
162
- - **Fresh request-time page:** keep the Fimo read in the framework's server
163
- loader or Server Component. Stream only when the source already tolerated
164
- partial rendering or a new wait would otherwise block the whole page.
165
-
166
- ## Prove the transport did not regress
167
-
168
- Run the production build and production server. Development mode may include
169
- compilation and may disable prefetching, so label any development observation
170
- as development-only.
171
-
172
- For every content family moved from local or bundled source files to Fimo:
173
-
174
- 1. Record whether the source and target reads happen at build time, request
175
- time, or in the browser.
176
- 2. Check one cold navigation and one warm navigation separately.
177
- 3. Capture Fimo/API request count, duplicate reads, request order, and the
178
- longest blocking read when observable.
179
- 4. Verify that server-rendered source content remains in the initial server
180
- result and is not fetched again after hydration.
181
- 5. Run the normal edit, render, and revert proof. When caching or static output
182
- is involved, record normal-build and cold-build freshness separately.
183
-
184
- Do not invent a universal millisecond budget. Timing starts as evidence. Fail
185
- the migration when it introduces an objective transport regression, such as a
186
- new client waterfall, repeated full-list reads, avoidable sequential requests,
187
- or stale edits. A broader performance review or framework upgrade is separate
188
- work and starts only when the user explicitly asks for it.
93
+ routes to the migrated homepage, so no relative link breaks.
94
+
95
+ Do not ask when every route moves or the request settles it. A route found
96
+ after preflight keeps its working absolute source URL and goes in the report;
97
+ do not interrupt the migration for it.
@@ -0,0 +1,90 @@
1
+ # Migration target setup
2
+
3
+ SKILL.md "Initialized target precondition" picks the case. This page gives the
4
+ details of each case and of the commands. Setup ends at the SKILL.md setup
5
+ gate. Then give each worker the project id, Branch, exact CLI invocation, and
6
+ the check command.
7
+
8
+ ## Case details
9
+
10
+ - **Existing folder, already linked.** Run `fimo link <same-id> -C <folder>`
11
+ only to repair the link.
12
+ - **Existing folder.** Never reset, overwrite, or discard existing work.
13
+ - **Read-only source or a separate target.** If the copy kept a
14
+ `.fimo/project.json`, reuse that project or resolve it on purpose. The
15
+ original stays read-only. A `git worktree` shares the repository's config and
16
+ remotes: use an independent copy or clone when the `fimo` remote must not
17
+ touch the original.
18
+ - **Empty target or conversion.** Never put a template over populated source.
19
+ Keep the source repository or export separate, for example in
20
+ `.fimo/migration/source`.
21
+
22
+ **Baseline:** an exact copy of the folder's state before the migration, kept
23
+ outside the folder. A commit plus a detached worktree is enough only when the
24
+ tree is clean; otherwise also copy the dirty and untracked files. Never copy
25
+ secret values into evidence.
26
+
27
+ Never hand-write `.fimo/project.json` to fake a link. Never relink a folder to
28
+ another project: `fimo link --relink` needs the owner's explicit choice.
29
+
30
+ ## `fimo link`
31
+
32
+ `fimo link` keeps the folder's code, framework, git history, branches, and
33
+ `origin`. It creates a git repository when there is none, and adds the Fimo
34
+ dependency, `.fimo/project.json`, the `fimo` remote, and
35
+ `.fimo/config.json#runtime.framework`. It never adds a template.
36
+
37
+ In a non-interactive shell, `fimo link` on an unlinked folder without an id
38
+ creates a new project in the active organization, else in the only one. With
39
+ several organizations and none active, the CLI fails: ask the user which one.
40
+
41
+ ## `fimo migrate init`
42
+
43
+ `fimo migrate init` is the only migration command. It sets up the target and
44
+ nothing else: it never reads, fetches, or renders the source site, and gives no
45
+ evidence pack or draft. Reading the source is your job.
46
+
47
+ ```bash
48
+ fimo migrate init <target> --framework <framework> --source-platform <platform> # new project
49
+ fimo migrate init <target> --project-id <projectId> --framework <framework> --source-platform <platform> # existing empty project
50
+ ```
51
+
52
+ - It checks the target and CLI auth, then uses the normal `fimo init` flow to
53
+ select or create the project. In a non-interactive shell it fails with a
54
+ structured error when auth is missing, or the target is invalid or populated
55
+ but not linked. The setup gate's data read proves project access.
56
+ - Always pass `--framework`: the detected source framework for a
57
+ source-backed migration, or the framework the owner chose for a conversion or
58
+ a URL-only rebuild. Never rely on the default (`react-router`).
59
+ - `--source-platform` names what the site comes from (values in
60
+ `fimo migrate init --help`). Pass what the source proves; omit it when
61
+ nothing proves it (it records `unknown`).
62
+ - Add `--org <organizationId>` when the CLI cannot resolve one organization.
63
+ - `--template-root` is for development tests only.
64
+ - After setup, check `.fimo/config.json#runtime.framework` and the framework
65
+ files. A Next.js target keeps `next.config.*` and the source router shape,
66
+ not a React Router scaffold. The target's real files are the authority for
67
+ paths: do not make a second `app/` or `src/app/` tree from an example.
68
+
69
+ ## What setup writes
70
+
71
+ `fimo migrate init` on a new target scaffolds it and pushes its first commit
72
+ (a failed push is a warning in the receipt: fix it before workers start).
73
+ `fimo link` and a reused linked folder push nothing; the first commit waits for
74
+ `fimo deploy`. Setup never pushes schemas, uploads assets, imports entries,
75
+ deploys, or publishes.
76
+
77
+ Data writes go through the normal commands on the linked target:
78
+ `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
79
+ `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
80
+ `fimo deploy` and `fimo publish` follow SKILL.md "Completion and deployment".
81
+
82
+ ## Unreleased CLI
83
+
84
+ Never run the migration through a `file:`-linked CLI from a Fimo source
85
+ checkout: it skips the publish bundle and can miss bundled packages. To test
86
+ unreleased CLI changes, publish a pinned development artifact from that
87
+ checkout first (`pnpm -F fimo publish-cli -- --id <task-name>`, or
88
+ `node scripts/remote-dev-publish-cli.mjs --id <task-name>` on a Dev Remote box).
89
+ Use the exact package that the publish wrote to `.fimo/dev.json`, and record
90
+ its URL as the artifact source.
@@ -3,7 +3,7 @@
3
3
  Validation is one independent read-only wave after all writers return. The
4
4
  coordinator gives every validator the accepted migration scope, deliberate
5
5
  user-approved differences, and the guardrail inventory path
6
- (`references/qa.md`, Rendered guardrails), but no producer findings, repair
6
+ (`references/qa/guardrails.md`), but no producer findings, repair
7
7
  reasoning, transcript, or expected verdict. A validator may add a rule the
8
8
  source proves; it never removes or narrows one. A validator checks the
9
9
  finished target against the source within that contract. It does not report an
@@ -27,7 +27,7 @@ Verify:
27
27
  navigation, and `editable-text` rules are proven on rendered HTML or a running
28
28
  local server with `scripts/check-rendered-guardrails.mjs`, never by grepping
29
29
  target source. An inventory without an `editable-text` rule is incomplete.
30
- Browser captures include the response metadata required by `references/qa.md`;
30
+ Browser captures include the response metadata required by `references/qa/guardrails.md`;
31
31
  - schemas, entries, singles, labels, media, forms, and locales exist through
32
32
  CLI read-back;
33
33
  - every planned source item is consumed at its original behavior path, not in
@@ -77,7 +77,7 @@ other after it. Do not add a metadata format for a small overlap.
77
77
  6. Start each code worker only after its own imported records read back as
78
78
  non-empty. A build over empty data proves nothing.
79
79
  7. Before the validation wave, write the cited rendered-guardrail inventory
80
- required by `references/qa.md`. After every writer returns, start one
80
+ required by `references/qa/guardrails.md`. After every writer returns, start one
81
81
  read-only validation wave. When subagents are available, run build and
82
82
  runtime, Fimo data and content, and rendered browser checks concurrently
83
83
  after their prerequisites pass.