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
@@ -0,0 +1,67 @@
1
+ # Content delivery
2
+
3
+ When local Markdown, MDX, JSON, or hardcoded content becomes Fimo reads, the
4
+ reads must not add an avoidable runtime wait. This is migration correctness: apply it
5
+ without asking an optimization question.
6
+
7
+ ## Keep the delivery mode
8
+
9
+ Record how the source delivers each content family: at build time, on the
10
+ server per request, or in the browser. Load the target's `fimo-code` framework
11
+ and generated-client references, and keep the same rendering and freshness
12
+ unless the framework needs a documented equivalent.
13
+
14
+ - Keep build-time and server-rendered content on the server. Never turn a
15
+ local Markdown page into a client loading state or a browser API waterfall.
16
+ - Keep known-route generation. For a static blog, list the slugs once for route
17
+ generation, then read each detail route with `getBySlug` or another direct
18
+ generated-client lookup. Do not list the whole collection and filter it on
19
+ every page.
20
+ - Start independent reads together. Keep page-only reads out of shared root
21
+ layouts. Deduplicate a read that metadata, a layout, and a page all need.
22
+ - Query only the fields, relations, and page of records the route uses.
23
+ Populate required references explicitly. No unbounded reads, no N+1 lookups.
24
+ - Keep framework links and their normal prefetch. Do not add broad forced
25
+ prefetch.
26
+ - Keep edit freshness: static output, revalidation, or caching is valid only
27
+ when a normal rebuild or the source's normal refresh shows the new Fimo
28
+ value. Cold-build once as a diagnostic when the normal result is stale.
29
+ - Do not upgrade the framework, change routers, add loading placeholders, or
30
+ redesign a page for this rule, unless the user asked for it.
31
+
32
+ Examples:
33
+
34
+ - **Static Markdown blog:** import every post, generate the known routes from a
35
+ bounded slug list, read each post on the server at build time, and ship the
36
+ article in the first HTML. A browser fetch for the
37
+ article body is a migration regression.
38
+ - **Large collection:** a paginated, projected list for the index and a direct
39
+ slug lookup for the detail page. Reading every full record on each navigation
40
+ is a regression, even when the page looks right.
41
+ - **Fresh request-time page:** keep the Fimo read in the server loader or
42
+ Server Component. Stream only when the source already accepted partial
43
+ rendering, or when a new wait would otherwise block the whole page.
44
+
45
+ ## Prove the transport did not regress
46
+
47
+ Use the production build and production server. Development mode can compile
48
+ on demand and turn off prefetch: label any development observation as
49
+ development-only.
50
+
51
+ For each content family that moved from local files to Fimo:
52
+
53
+ 1. Record whether source and target read at build time, request time, or in
54
+ the browser.
55
+ 2. Check one cold and one warm navigation separately.
56
+ 3. Record the Fimo/API request count, duplicate reads, request order, and the
57
+ longest blocking read when you can observe them.
58
+ 4. Verify that server-rendered content is in the first server response and is
59
+ not fetched again after hydration.
60
+ 5. Run the edit, render, and revert proof. With caching or static output,
61
+ record normal-build and cold-build freshness separately.
62
+
63
+ There is no fixed millisecond budget; timing is evidence. Fail the migration
64
+ when it adds a transport regression: a new client waterfall, repeated
65
+ full-list reads, avoidable sequential requests, or stale edits. A wider
66
+ performance review or framework upgrade is separate work, started only when the
67
+ user asks.
@@ -147,7 +147,7 @@ Fimo. Keep `generateStaticParams` when the source has known routes, list the
147
147
  required slugs once, and use the generated client's `getBySlug` for each detail
148
148
  page. Do not fetch the full post collection and filter it on every route, and do
149
149
  not introduce a Client Component solely to load Fimo content. Follow the shared
150
- evidence and freshness contract in `references/questions-and-improvements.md`.
150
+ evidence and freshness contract in `references/content-delivery.md`.
151
151
 
152
152
  Create one source item per Markdown/MDX document and per independently handled
153
153
  construct inside it. Portable prose and an executable MDX component are
@@ -0,0 +1,41 @@
1
+ # Browser smoke and visual checks
2
+
3
+ ## Browser smoke (required)
4
+
5
+ A build and HTTP 200 responses are not enough: a page can build, return 200,
6
+ and still show blank labels or an empty collection. Run one bounded,
7
+ scriptable browser pass (Playwright, agent-browser, or similar):
8
+
9
+ 1. Start the app and wait for hydration, not only the HTTP response. Do not
10
+ wait for `networkidle` on a dev or HMR server; wait for the expected visible
11
+ content and images.
12
+ 2. Open a representative set: home, one collection listing, one collection
13
+ detail, one static page.
14
+ 3. Do one representative interaction (nav menu, accordion, or filter) and
15
+ check its visible result.
16
+ 4. Check the expected visible text on each page, and at least one collection
17
+ item rendered from imported Fimo data.
18
+ 5. Check that global labels and buttons (header and footer navigation, CTAs,
19
+ cookie banner) are not empty. Blank text usually means the component is
20
+ outside the label provider.
21
+ 6. Check that visible text and attributes contain no `undefined`, `null`,
22
+ `[object Object]`, or `NaN` that the source does not have.
23
+ 7. Read the browser console and the server output for runtime errors.
24
+
25
+ Keep it bounded: representative pages and one interaction, not every route.
26
+
27
+ ## Visual checks
28
+
29
+ Visual checks need a browser. Without one, run the deterministic hosting
30
+ checks in `qa` and mark visual proof unavailable; never claim a check that did
31
+ not run.
32
+
33
+ - Compare the source and the migrated site at desktop and mobile widths:
34
+ layout, typography, hierarchy, media, and brand tokens.
35
+ - Remove generated placeholder copy from visible UI.
36
+ - Check media aspect ratios and that no image is broken on the main routes.
37
+ - Compare the bounds of representative components; the whole page height can
38
+ hide a local layout change.
39
+ - Compare image loading before and after scroll: eager and lazy counts,
40
+ preloads, response formats, and typical transfer sizes. An optimizer URL
41
+ alone does not prove delivery.
@@ -0,0 +1,95 @@
1
+ # Rendered guardrails (required)
2
+
3
+ Prove brand, legal, compliance, navigation, and editability rules on the
4
+ final rendered app, never by a grep of the target source. When copy moves into
5
+ Fimo it leaves the repository: a grep for a forbidden phrase passes because
6
+ nothing is there, and a grep for the brand name fails. Worker reports and
7
+ coverage tables are diagnostics; this check is the acceptance evidence.
8
+
9
+ ## 1. Write the inventory
10
+
11
+ Before the validation wave, the coordinator writes
12
+ `.fimo/migration/guardrails.json`: every route the migration must prove, and
13
+ every rule the source, owner, or accepted scope sets. Each rule has `source`:
14
+ the page, file, or owner decision that requires it. A rule without a source is
15
+ an invention.
16
+
17
+ Rule kinds:
18
+
19
+ - `required-text`: copy that must render, such as the brand name or a legal
20
+ notice.
21
+ - `forbidden-text`: copy that must never render, such as an old brand name,
22
+ placeholder text, or a withdrawn claim.
23
+ - `required-link`: a link every page must carry, such as the privacy policy.
24
+ - `links-resolve`: each internal link on the inventoried routes goes to an
25
+ inventoried route or an allowed path prefix (`allow`). Links resolve against
26
+ the final document URL and any `<base href>`; query and fragment do not
27
+ change the route.
28
+ - `editable-text` (required in every inventory): each visible body text node
29
+ is inside an element a Fimo primitive renders, so an editor can change it in
30
+ Studio. Text still typed in the code shows "Nothing to edit": move it to a
31
+ label or a CMS field. Put in `allow` only the exact text the owner keeps in
32
+ code (a brand glyph, a legal line) and give the reason in the report.
33
+ Assistive and hidden text does not count.
34
+
35
+ Add `routes` to a rule only when it is not global. When the source has no rule
36
+ of a kind (no legal page, for example), say so in the report.
37
+
38
+ ```json
39
+ {
40
+ "routes": ["/", "/about", "/legal/privacy"],
41
+ "rules": [
42
+ { "id": "brand-name", "kind": "required-text", "text": "<target brand>", "source": "<source page or file>" },
43
+ {
44
+ "id": "no-old-brand",
45
+ "kind": "forbidden-text",
46
+ "text": ["<previous brand>", "Lorem ipsum"],
47
+ "source": "<owner decision>"
48
+ },
49
+ { "id": "footer-privacy", "kind": "required-link", "href": "/legal/privacy", "source": "<source navigation>" },
50
+ { "id": "nav-resolves", "kind": "links-resolve", "allow": ["/blog"], "source": "<source navigation>" },
51
+ { "id": "editable-text", "kind": "editable-text", "allow": [], "source": "Fimo: visitors' text is editable" }
52
+ ]
53
+ }
54
+ ```
55
+
56
+ ## 2. Observe the rendered app
57
+
58
+ Turn on Fimo editing metadata: build and serve with
59
+ `FIMO_EDITING_METADATA=true`, or use the dev server. Without it no text is
60
+ marked editable, and `editable-text` fails as unmeasured.
61
+
62
+ - **Server-rendered target:** serve it locally and pass `--base-url`.
63
+ - **Client-rendered target:** in the browser pass, save each hydrated document
64
+ as `<captures>/index.html` and `<captures>/<route>.html`, and pass
65
+ `--captures <captures>`. Next to each HTML file, save a JSON sidecar with the
66
+ real final response status and document URL (trailing slash included), for
67
+ example `legal/privacy.html.json`:
68
+
69
+ ```json
70
+ { "status": 200, "url": "http://localhost:3000/legal/privacy", "error": null }
71
+ ```
72
+
73
+ Put navigation or capture failures in `error`. Never guess a status from the
74
+ HTML or fill in missing evidence: missing, malformed, non-200, or error
75
+ metadata fails the route. The checker cannot authenticate captures, so the
76
+ browser smoke (`qa/browser`) must still prove content and controls.
77
+
78
+ The check reads body text and readable attributes (`alt`, `title`,
79
+ `aria-label`, `placeholder`, `meta` content), not script, style, or comments.
80
+
81
+ ```bash
82
+ node node_modules/fimo/assets/skills/fimo-migration/scripts/check-rendered-guardrails.mjs <target> \
83
+ --base-url http://localhost:3000 --output .fimo/migration/guardrails-report.md
84
+ ```
85
+
86
+ ## 3. Read the result
87
+
88
+ The check fails closed and caps the status at `draft-only` when the inventory
89
+ or evidence is empty, a route is missing or not 200, a final URL does not match
90
+ its route, or a rule observes nothing.
91
+
92
+ Copy the emitted `## Guardrails` block unchanged into the validator's report
93
+ and the migration report. Acceptance is `Result: passed`, with every route
94
+ rendered and every rule observed on at least one route. Each failure names the
95
+ route and the phrase or link, so the repair owner needs no rerun to find it.
@@ -0,0 +1,78 @@
1
+ # Import counts and the migration report
2
+
3
+ ## Import verification
4
+
5
+ Record in `.fimo/migration/migration-report.md` and the worker reports (no
6
+ JSON QA registry):
7
+
8
+ - schemas pushed;
9
+ - entries created or updated per content type;
10
+ - media uploaded and failed;
11
+ - forms pushed;
12
+ - redirects and locales imported or unresolved;
13
+ - the exact CLI used (`fimo --version` and the artifact source), in Source.
14
+
15
+ Media, entries, and forms block the gate. Entries left as seed JSON and media
16
+ left in `public/` are not covered: the status is `draft-only` unless each gap
17
+ is an owner-visible unresolved item.
18
+
19
+ ## Report
20
+
21
+ Write the report as plain text:
22
+
23
+ ```md
24
+ # Migration Report
25
+
26
+ ## Status
27
+
28
+ complete | complete-with-unresolved | draft-only
29
+
30
+ ## Source
31
+
32
+ ## Coverage by dimension
33
+
34
+ ## Routes
35
+
36
+ ## Content
37
+
38
+ ## Media
39
+
40
+ ## Forms
41
+
42
+ ## SEO and OG
43
+
44
+ ## Redirects and Headers
45
+
46
+ ## Integrations
47
+
48
+ ## Hosting
49
+
50
+ ## Content Delivery
51
+
52
+ ## Guardrails
53
+
54
+ ## Timing
55
+
56
+ ## Checks
57
+
58
+ ## Unresolved
59
+
60
+ ## Next Actions
61
+ ```
62
+
63
+ - `Coverage by dimension` has one row per surface (routes, content, forms,
64
+ SEO/OG, redirects/headers, integrations, hosting, media, labels, locales) with
65
+ `gate`, `discovered`, `migrated`, `verified`, `unresolved`, `unsupported`,
66
+ `denominator`, and `coverage`. Never merge them into one score: full route
67
+ coverage must not hide a missing entry or asset.
68
+ - `Timing` is copied from the worker reports and stays apart from coverage.
69
+ - `Guardrails` is the unchanged block from `check-rendered-guardrails.mjs`
70
+ (`qa/guardrails`). A report without it, or with `Result: failed`, cannot be
71
+ `complete` or `complete-with-unresolved`.
72
+ - Report cache freshness when the migration changes how content is read or
73
+ rendered. Missing provider cache mechanics alone do not fail a migration;
74
+ stale Fimo edits caused by the new read path do.
75
+
76
+ `scripts/apply-decision.mjs` and `scripts/write-migration-report.mjs` replay an
77
+ old JSON-ledger migration. A new migration writes the plain-text plan and
78
+ report; run those scripts only when the user asks for that replay.