fimo 2.4.0-staging.1 → 2.4.0-staging.3

package/assets/skills/fimo-code/references/frameworks/sveltekit.md

@@ -2,7 +2,8 @@
 
 Use this reference when `fimo describe --json` reports
 `framework.slug: "sveltekit"`. SvelteKit keeps owning routes, load functions,
-locale resolution, links, document metadata, and SEO.
+locale resolution, links, document metadata, and per-page SEO; Fimo supplies the
+site-wide SEO defaults from Studio's Settings → SEO.
 
 ## Compatibility
 
@@ -12,7 +13,7 @@ SvelteKit 1 or Svelte 4 projects are compatible.
 
 ## Install both packages
 
-Every SvelteKit surface lives in `fimo-sveltekit`, installed at the same version
+SvelteKit-specific APIs live in `fimo-sveltekit`, installed at the same version
 as `fimo`:
 
 ```bash
@@ -95,9 +96,10 @@ export async function load(event) {
 <script lang="ts">
   import { afterNavigate } from '$app/navigation';
   import { FimoProvider } from 'fimo-sveltekit/components';
-  import type { LayoutData } from './$types';
   import type { Snippet } from 'svelte';
 
+  import type { LayoutData } from './$types';
+
   let { data, children }: { data: LayoutData; children: Snippet } = $props();
 
   afterNavigate(() => {
@@ -110,6 +112,57 @@ export async function load(event) {
 </FimoProvider>
 ```
 
+## SEO defaults
+
+Resolve SEO in the existing server load and return `seoHead`. Preserve the
+load's other data, including labels. A content page resolves after its read:
+`resolveSeoForPath(event.url.pathname, config, { article })`, applies app
+overrides, and returns its complete `seoHead` using `toSeoHead`.
+
+```ts
+// src/routes/+layout.server.ts, or a content page's +page.server.ts
+import { resolveSeoForPath, toSeoHead } from 'fimo/seo';
+import config from '../../.fimo/config.json';
+
+export function load({ url }) {
+  const seo = resolveSeoForPath(url.pathname, config);
+  return {
+    seoHead: toSeoHead(seo, {
+      canonicalUrl: seo?.url ? new URL(url.pathname, seo.url).href : undefined,
+    }),
+  };
+}
+```
+
+Render the final merged route data from one head owner. A leaf load's
+`seoHead` replaces the default head as a whole.
+
+```svelte
+<!-- Inside the existing root layout, alongside its provider and children -->
+<script lang="ts">
+  import { page } from '$app/state';
+  const head = $derived(page.data.seoHead ?? { meta: [], links: [] });
+</script>
+
+<svelte:head>
+  <title>{head.title ?? 'My site'}</title>
+  {#each head.meta as attributes}<meta {...attributes} />{/each}
+  {#each head.links as attributes}<link {...attributes} />{/each}
+</svelte:head>
+```
+
+Do not add a second page title beside root social tags. Use the same final
+values for all tags and check client navigation, including returning to a page
+without overrides. Existing apps can keep their current head component and
+extend it in place.
+
+The example canonical policy fits a root-hosted site; preserve existing
+production domains, base paths and trailing slashes. Imported config needs
+sync and rebuild/redeploy. Content freshness follows the app's load,
+prerender and cache policy.
+
+Read `references/frameworks/seo-head.md` for the field and composition contract.
+
 Generated values are serialized at a `load` boundary and hydrated in the
 component that renders them. Use `Text`, `RichText`, `Image`, `Video`, `Date`,
 `DateTime`, `Boolean`, `Json`, and `Number` from
@@ -142,7 +195,7 @@ component, read Fimo preview environment variables, or inject Fimo scripts.
 
 ## Boundaries
 
-- SvelteKit owns routing, history, 404s, locale URLs, and SEO.
+- SvelteKit owns routing, history, 404s, locale URLs, and per-page SEO; the root layout renders Fimo's site-wide SEO defaults.
 - `fimo-sveltekit/vite` owns dev source tagging only.
 - `FimoProvider` owns labels and the optional Studio preview bridge.
 - Do not add React, React Query, or a Vite SPA fallback to a SvelteKit project.

package/assets/skills/fimo-migration/SKILL.md

@@ -100,9 +100,9 @@ Pick the setup path from the evidence:
   and adds only the Fimo dependency, `.fimo/project.json`, the `fimo` remote,
   and `.fimo/config.json#runtime.framework`. It never overlays a template, so
   the target must already contain the source.
-- **Empty target, or an explicit framework conversion** — `fimo init` with the
-  chosen `--framework`, or `fimo migrate init <url> <dir>` for a URL crawl.
-  Both refuse a non-empty target and write nothing when they refuse.
+- **Empty target, or an explicit framework conversion** — `fimo init` or
+  `fimo migrate init <dir>` with the chosen `--framework`. Both refuse a
+  non-empty target and write nothing when they refuse.
 
 If authentication, organization selection, project creation, environment
 resolution, linking, or the verification read fails, stop before workers and
@@ -151,7 +151,7 @@ report the exact failed command and setup requirement.
   unresolved item with the source evidence, the owner action, and the
   user-visible impact. Never claim completion while source content is
   unwired.
-- Prefer source code and exports over inferred crawl data. Use a public URL as
+- Prefer source code and exports over what a page renders. Use a public URL as
   visual, SEO, route, and behavior evidence when better source material exists.
   When the source defines an active CMS but its deployed records are unavailable,
   rebuild published content from the public site only after the user explicitly
@@ -205,8 +205,12 @@ report the exact failed command and setup requirement.
    - **source-backed**: source repository, export, downloaded HTML, CMS data,
      or media folder. The source files are truth; the workers read them
      directly.
-   - **url-only**: only a published URL. Run `fimo migrate <url> [dir]` to
-     create the draft evidence pack.
+   - **url-only**: only a published URL. You read the site yourself: open each
+     route in a browser, let client-side rendering finish, and record the
+     sections, copy, images, links, and forms you actually see. Fetching HTML
+     without executing JavaScript is not evidence — a client-rendered page
+     returns an empty root element, which reads as a site with no content.
+     Never report a route as covered from a fetch that returned no sections.
    - **hybrid**: source material plus a public URL. Treat source material as
      truth and the URL as comparison evidence.
 4. Read `references/questions-and-improvements.md`, finish its read-only
@@ -220,6 +224,10 @@ report the exact failed command and setup requirement.
    - Content data/code workers -> `references/workers/content-execution.md`.
    - Independent validator -> `references/workers/validator.md`.
    - Next.js source -> `references/frameworks/nextjs.md`.
+   - Astro/SvelteKit SEO -> the target's `fimo-code` framework reference and
+     `frameworks/seo-head`. Preserve the existing head owner and URL policy;
+     follow its value-ownership and edit-and-render contract, preserving
+     intentional source overrides rather than freezing editor-owned values.
    - React Router/Vite source -> load the target project's `fimo-code`
      `frameworks/react-router`, `frameworks/vite-react`, and
      `frameworks/hosting` references as applicable.
@@ -254,7 +262,8 @@ instead of inventing an ID:
 
 `--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
 `astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
-`other`); pass what the source checkout proves, `unknown` only when nothing does.
+`other`); pass what the source proves, `unknown` only when nothing does. It is
+explicit only — nothing detects it, and omitting it records `unknown`.
 
 After setup, check `.fimo/config.json#runtime.framework` and the scaffold's
 framework files before starting workers. A Next.js target must still have its
@@ -268,32 +277,23 @@ deploy happens only after successful local QA (see Completion and deployment).
 
 ## Command surface
 
-Plan-only commands operate on local artifacts and work before the target is
-linked:
-
-- `fimo migrate init <url> [dir]` — URL migrations only: crawl the live site
-  into the draft evidence pack.
-- `fimo migrate inspect` — summarize the URL draft or an existing legacy ledger.
-- `fimo migrate import` — print the import plan; it writes no data.
-- `fimo migrate apply` / `fimo migrate refine` — URL-draft-only scaffold and
-  refinement handoff; they play no role in a source-backed migration. `apply`
-  must never run against an initialized non-React-Router target: it is the
-  legacy React Router scaffold path and must fail instead of downgrading a
-  Next.js (or another framework) project.
-- `fimo migrate manifest` / `fimo migrate report` — legacy URL-draft helpers.
-  New source-backed migrations use the plain-text migration plan, worker
-  reports, and final migration report; they do not bootstrap another JSON
-  registry.
-
-Commands that perform actual data writes, all requiring the linked target:
+`fimo migrate init <dir>` is the only migration subcommand. It sets the target
+up and nothing else: it never reads, fetches, or renders the source site, and
+it produces no evidence pack, draft, manifest, or scaffold to inspect. Reading
+the source is your job, and every finding is yours to prove.
+
+- `fimo migrate init <dir> --project-id <projectId>` — link an owner-supplied
+  project.
+- `fimo migrate init <dir> --org <organizationId>` — create a new project.
+- Both accept `--framework`, `--source-platform` (see Target setup),
+  `--install` / `--no-install`, `--agents` / `-a`, `--mode`, `--template-root`,
+  and `--json`; `-C <dir>` replaces the positional for an already-linked target.
+
+The link/creation and its initial commit push are the only remote writes. Data
+writes go through the normal commands against the linked target:
 
 - `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
-- `fimo migrate init` (source-backed form): the project link/creation and
-  initial commit push described above. Pass `--source-platform <platform>`
-  (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
-  react-router, other) when the source is known; URL crawls detect it.
-
 - `fimo link`: project creation or selection plus the in-place adoption of a
   copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
@@ -378,9 +378,9 @@ Commands that perform actual data writes, all requiring the linked target:
 - `references/workers/content-execution.md` - data import and code-wiring
   contracts.
 - `references/workers/validator.md` - independent fan-in validation.
-- Existing manifest/decision helper scripts are legacy compatibility tools for
-  older migration artifacts. Do not invoke them in a new migration unless the
-  user explicitly asks to replay an older artifact.
+- `scripts/apply-decision.mjs` and `scripts/write-migration-report.mjs` replay
+  an older JSON-ledger migration. A new migration writes the plain-text plan
+  and report instead; do not invoke them unless the user asks for that replay.
 
 ## Completion and deployment
 

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

@@ -119,7 +119,7 @@ Then use source headers, values, and repeated patterns:
 - excerpt/summary/dek -> `text`
 - image/photo/thumbnail/media/asset/file -> `media`, carrying the source alt on
   the media value; never add a separate alt field (`references/media.md`)
-- date/published/created/updated -> `date`; use `datetime` only when the crawled
+- date/published/created/updated -> `date`; use `datetime` only when the source
   values carry a time and a UTC offset, which `datetime` requires
 - event start/end time -> `datetime`
 - price/amount/rating/order/count -> `number`

package/assets/skills/fimo-migration/references/frameworks/nextjs.md

@@ -86,6 +86,13 @@ behavior in place; when one cannot be preserved, record an explicit gap with
 the affected routes instead of shipping pages that silently lost their share
 metadata.
 
+Before adopting Fimo SEO values, load the target's `fimo-code` reference
+`frameworks/next/seo`. Record which fields remain app-owned and which become
+editor-managed. Preserve section robots policies, title templates and
+file-based images; verify the rendered result on representative routes. Link
+the established route pattern in the project's instructions so later pages
+reuse it. Do not replace an existing SEO library or add a universal merge wrapper.
+
 ## Fimo connection
 
 Follow the target project's `fimo-code` Next.js reference and render its

package/assets/skills/fimo-migration/references/import-contract.md

@@ -9,18 +9,16 @@ assets, schemas, entries, and forms, or the gaps are owner-visible unresolved
 items.
 
 Every data-plane write in this contract targets the linked project from
-workflow Phase 0. Local artifacts never require the link — `fimo migrate
-import` only prints the import plan (it writes no data) and warns in an
-unlinked directory — running the printed commands is what needs the link.
-When no owner-supplied target exists, the writes stay unresolved owner
-actions; do not fake a link to make them pass.
+workflow Phase 0. Planning and payload authoring need no link; running the
+writes does. When no owner-supplied target exists, the writes stay unresolved
+owner actions; do not fake a link to make them pass.
 
 ## Media Files
 
 Discovery must include:
 
 - local export media folders
-- media URLs from crawled HTML/CSS
+- media URLs found in the source HTML/CSS
 - CMS media fields
 - SEO/share images
 - downloadable files linked from pages or entries

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

@@ -4,9 +4,10 @@ New migrations do not create a canonical `manifest.json`. The coordinator uses
 the readable `.fimo/migration/migration-plan.md` and
 `.fimo/migration/migration-report.md` instead.
 
-Older URL-only migrations may contain `.fimo/migrations/current/manifest.json`.
-Read it as source evidence when useful, but do not copy it into another
-registry or ask workers to keep it synchronized.
+A pre-existing project may still contain `.fimo/migrations/current/manifest.json`
+from a retired URL crawl. Nothing writes it any more, and it was never
+trustworthy on a client-rendered site: read it as a hint at most, re-verify
+every claim against the source, and do not copy it into another registry.
 
 JSON remains appropriate for actual Fimo artifacts: schema files and the
 content payloads passed to data-plane commands. It is not needed to describe

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

@@ -67,6 +67,12 @@ items.
   categories, tags, redirects, and locales are preserved when present.
 - Existing SEO, OG, and social behavior - including dynamic OG image routes -
   is preserved or explicitly reported as a gap.
+- Editor-owned SEO remains connected to its setting, entry, or singleton.
+  Inspect the implementation lane's before/after edit-and-render receipt from
+  an authorized isolated target, including preserved intentional overrides and
+  required rebuild/cache steps. If absent, report freshness unproven and hand
+  back a bounded test; this read-only validator does not mutate content.
+  `fimo validate` and matching initial tags do not prove later edits propagate.
 - When the source has no low-risk SEO or social value, safe defaults derived
   from verified page/site data are present or the missing behavior is reported;
   the migration must not invent marketing claims.

package/assets/skills/fimo-migration/references/questions-and-improvements.md

@@ -94,7 +94,7 @@ The question should sound like this:
 
 If the owner chooses the public website, stay inside the selected route scope.
 Public retrieval does not authorize private endpoint discovery, credential use,
-or a broader crawl. Record the URL, retrieval time, redirects, and every field
+or a broader sweep. Record the URL, retrieval time, redirects, and every field
 or relation that remains unknown.
 
 ## Ask what happens outside a partial migration

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

@@ -18,12 +18,11 @@ ask a generic optimization question.
 1. Confirm the target path. The target is a separate directory; the source
    checkout remains read-only evidence.
 2. Initialize or reuse exactly one linked Fimo target before workers start:
-   - URL migration: `fimo migrate init <source-url> <target-dir> --framework <framework>`
    - link an existing project: `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
    - create a project: `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
    - add `--source-platform <platform>` when the source platform is known
      (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
-     react-router, other); URL crawls detect it themselves.
+     react-router, other). Nothing detects it; omitting it records `unknown`.
      Use the detected source framework for source-backed migrations. A framework
      conversion requires an explicit user choice; URL-only and rebuild
      migrations ask the user which framework to use. Never choose a framework by
@@ -78,9 +77,12 @@ Treat absent/private fields as unknown, keep uncertain fields optional, and do
 not turn sampled values into enums. Bounded retrieval scripts are accelerators
 the planner may adapt or replace, never schema decision makers.
 
-For URL-only migrations, run `fimo migrate <url> [dir]` and inspect the
-generated `.fimo/migrations/current/` files as source evidence. Do not copy
-that crawl manifest into another canonical JSON registry.
+For URL-only migrations, read the published site yourself with a browser. Open
+every selected route, let client-side rendering finish, and record the sections,
+copy, images, links, and forms you actually see. An HTML response fetched
+without executing JavaScript is not evidence: a client-rendered page returns an
+empty root element, and treating that as the page reports an empty site as a
+complete one.
 
 ## Phase 2: Fan out workers
 

package/assets/skills/fimo-studio/references/billing-and-credits.md

@@ -19,13 +19,13 @@ From a linked project directory, `fimo credits` shows the same organization bala
 
 ## Buying More Credits
 
-Buying credits is available on paid plans, since it charges the payment method already on file.
+Buying credits is available while a paid plan is effective, including after scheduling its cancellation. Cancellation stops automatic spending immediately but keeps the current plan until renewal. A deliberate credit purchase still charges the payment method on file.
 
 1. Click the credit display near the chat input.
 2. Click **Buy credits**.
 3. Enter a dollar amount (up to $10,000) or pick one of the presets: **$25**, **$50**, **$100**, or **$200**.
-4. You get **1,000 credits per $1** spent.
-5. Confirm the purchase. Your card on file is charged and the credits are added to your account immediately -- there is no separate checkout page to complete.
+4. Check the rate shown in the dialog. It comes from your current plan, so the same dollar amount can buy a different number of credits on Pay as you go than on Pro.
+5. Confirm the purchase. Your card on file is charged and the credits are added after confirmation; there is no separate checkout page to complete. If confirmation stays pending, retry the same purchase or contact support. Do not start another purchase to replace an unresolved one.
 
 ## Refilling Credits Automatically
 
@@ -33,7 +33,7 @@ Organization billing admins on a paid plan can configure auto-refill from **Sett
 
 1. Choose the balance threshold that should trigger a refill.
 2. Choose the dollar amount to purchase when the balance crosses that threshold.
-3. Save the configuration. Hyperline stores the setting and charges the payment method on file when the threshold is crossed.
+3. Check the plan rate shown in the dialog, then save. Fimo charges the payment method on file and buys credits at that rate when the balance crosses the threshold.
 
 Turn auto-refill off from the same control. Fimo does not keep a separate copy of this configuration; the Billing page always shows the provider's current setting. Leaving a paid plan clears auto-refill, and billing admins retain the off-switch if provider cleanup is delayed.
 
@@ -54,6 +54,9 @@ From there:
 ## Changing or leaving a paid plan
 
 - Free to Pay as you go or Pro, and Pay as you go to Pro, use checkout and take effect after payment succeeds.
+- Cancelling Pay as you go or Pro stops auto-refill and paid bandwidth immediately. The current plan, remaining allowances, credits, and reset date stay unchanged until Free takes over at renewal. Manual credit purchases remain available while the paid plan is active.
+- Automatic spending cannot be enabled while cancellation is scheduled. Keep your plan first; then you can immediately enable auto-refill and paid bandwidth independently. Keeping the plan itself leaves both off.
+- Usage before cancellation remains payable. Enabling paid bandwidth again does not make usage from the off-period billable.
 - Pro to Pay as you go or Free takes effect at the end of the current billing period. Billing shows the destination and effective date until then.
 - Choosing the current plan again before that date cancels the scheduled change.
 - Pay as you go requires an active payment method. Removing its only valid card returns the organization to Free immediately.

package/assets/skills/fimo-studio/references/seo-settings.md

@@ -24,6 +24,8 @@ This is the image that shows up when someone shares your link on social media (F
 
 All SEO changes auto-save as you make them. However, a small amber reminder appears in the top-right corner: "Publish your website to apply your changes." Click Publish to push the changes to your live site.
 
+Current templates include SEO wiring. For older Next.js, Astro or SvelteKit sites, ask the coding agent to update Fimo and connect these values to the app's existing SEO flow. Route-specific content must reach that flow too. Load the matching recipe: `fimo skills get fimo-code --ref frameworks/next`, `fimo skills get fimo-code --ref frameworks/astro`, or `fimo skills get fimo-code --ref frameworks/sveltekit`.
+
 ## Why SEO Matters
 
 - **Favicon** -- Makes your site look professional and easy to find among open tabs.

package/dist/cli/bundle.json

@@ -1,8 +1,8 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-09-04T20:24:57.392Z",
-  "cliVersion": "2.3.1",
+  "bundledAt": "2026-09-05T15:57:16.360Z",
+  "cliVersion": "2.3.2",
   "external": [
     "oxc-parser",
     "fsevents",