fimo 2.4.0-staging.2 → 2.4.0-staging.4

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

@@ -145,7 +145,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
 - **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's anti-patterns.
-- **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — Fimo handles deploys; don't bolt another platform on.
+- **Adding another deploy tool**. Fimo handles deploys; don't bolt another platform on.
 - **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
 - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).
 - **Treating the daily allowance as extra credits** — the allowance section appears only for legacy Premium organizations, and `fimo credits` already includes its spendable credits in "Available now"; it is accounting context, not an amount to add.

package/assets/skills/fimo-cli/references/branches.md

@@ -36,7 +36,7 @@ fimo --branch <name> <command>  # peek at another Branch for one command (does n
 | `fimo diff [from] [to]` | `git diff`          | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                              |
 | `fimo status`           | `git status`        | Multi-surface status for the current Branch vs its parent. See below.                                                                                                        |
 | `fimo merge <from>`     | `git merge`         | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                 |
-| `fimo publish`          | —                   | Publish the synced Production source revision with a stable Fimo publication ID. See "Publishing" below.                                                                     |
+| `fimo publish`          | —                   | Publish the revision already on the Fimo remote (no push) with a stable Fimo publication ID. See "Publishing" below.                                                         |
 
 All of these accept the global `--branch` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
 
@@ -98,10 +98,10 @@ Syncs the current Branch's data plane from its parent (or `--from <ancestor>`).
 
 Two different "go live" mechanisms — don't confuse them:
 
-- **`fimo publish [--label <text>] [--notes <md>]`** — publishes the synced Production source revision. Fimo assigns the immutable publication ID; the label and notes are optional annotations. `--skip-validate` is an operator override.
-- **`fimo deploy --publish`** — the project-publish path. Pushes the current Production source code and flips the project live in one shot. See `references/deploy.md`.
+- **`fimo publish [--label <text>] [--notes <md>]`** — publishes the revision already on the Fimo remote without pushing. Fimo assigns the immutable publication ID; labels and notes are optional annotations. `--skip-validate` is an operator override.
+- **`fimo deploy --publish`** — pushes the current Production source Branch and flips the project live. See `references/deploy.md`.
 
-Use `fimo publish` when the Production source Branch is already synced; use `fimo deploy --publish` when the local revision still needs to be pushed first. Both only run from the configured Production source Branch. Existing projects use `main`.
+Choose `fimo deploy --publish` when local changes need to go live; choose `fimo publish` when the remote revision is the intended release. Both only run from the configured Production source Branch. Existing projects use `main`.
 
 ## Anti-patterns
 

package/assets/skills/fimo-cli/references/deploy.md

@@ -123,12 +123,9 @@ There's nothing special about this — it's the same `fimo deploy` you'd run lat
 
 ## Publishing: `fimo deploy --publish` vs `fimo publish`
 
-Two different "go live" mechanisms — pick deliberately:
+Use `fimo deploy --publish` to push and publish local changes. Use `fimo publish` to publish the revision already on the Fimo remote without pushing. Both target the configured Production source Branch.
 
-- **`fimo deploy --publish`** — push what's on the Production source Branch now and flip the project live in one shot. The simple "ship it" path. Runs from that Branch only.
-- **`fimo publish [--label <text>] [--notes <md>]`** — publish the synced Production source revision without pushing. Fimo assigns the immutable publication ID; a label and notes are optional human annotations. See `references/branches.md`.
-
-When unsure, use `fimo deploy --publish` so the local revision is pushed before it goes live. Use `fimo publish` when the Production source Branch is already synced.
+Check the reported source commit and warnings before reporting completion. If local work is excluded or the built commit cannot be confirmed, follow the CLI's hint.
 
 ## Markdown for AI agents
 

package/assets/skills/fimo-cli/references/domains.md

@@ -51,8 +51,8 @@ Global flags: `--project <id>` / `-C, --cwd <dir>` for project resolution, `--or
 When a user says "I want to change my website's URL," ask which case fits:
 
 - **"It's fine as-is, just nicer"** → `rename-default` or `suggest-default`. Free, instant, no DNS.
-- **"I own example.com already"** → `add example.com`. Premium. They configure CNAME at their registrar.
-- **"I want to buy a domain"** → `search` → `pricing` → `buy`. Premium + the registered-domains feature flag has to be on (it's not enabled in every environment).
+- **"I own example.com already"** → `add example.com`. Pay as you go or higher. They configure CNAME at their registrar.
+- **"I want to buy a domain"** → `search` → `pricing` → `buy`. The registered-domains feature flag and an eligible plan must be on (the flag is not enabled in every environment).
 
 If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
 
@@ -60,7 +60,7 @@ If they aren't sure, run `fimo domains suggest-default` first — it's free, tak
 
 After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
 
-The default URL is free and needs no DNS. A custom domain is the separate Premium workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
+The default URL is free and needs no DNS. A custom domain uses the Pay as you go (or higher) workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
 
 1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
 2. Show the candidates and ask the user to choose one explicitly.
@@ -72,7 +72,7 @@ Choosing the slug does not publish the site. The first successful `fimo deploy -
 
 The CLI never charges directly. Two distinct money paths:
 
-1. **Premium subscription** — gates `add`, `buy`, `owned`, `refresh`, `remove` for custom domains. The user upgrades through the Fimo web app (Hyperline-hosted checkout). When a free user runs a gated command they get a 403 with the upgrade URL — surface it as-is to the user.
+1. **Pay as you go or higher** — gates custom-domain operations. A valid card activates Pay as you go through the Fimo web app (Hyperline-hosted checkout). When a Free user runs a gated command they get a 403 with the billing URL; surface it as-is to the user.
 2. **Domain registration** — `fimo domains buy` creates a Hyperline invoice with `payment_method_strategy: 'external'` and returns a `checkoutUrl`. The user opens that URL in a browser to pay. **No money moves until they pay the invoice.** That's why `--yes` on `buy` is safe: it queues an invoice; the human still has to consent at checkout.
 
 Domain prices come from name.com via the registrar reseller. They vary by TLD and can change. Pricing is in USD (cents in the API, formatted as dollars in CLI output).
@@ -121,7 +121,7 @@ Propagation: typically 15–30 minutes, up to 48 hours rarely.
 ## Common errors
 
 - **"Project Not Found" on a new URL or custom domain.** The route exists but the site was never published — run `fimo deploy --publish`.
-- **"Custom domains require a Premium plan."** — the operation is paid; the message includes the org billing URL. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
+- **"Custom domains require Pay as you go or higher."** — add a card at `/app/billing`, then retry. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
 - **"Domain purchase is not enabled on this account."** — the registered-domains feature flag is off on this API instance. Contact support.
 - **"This URL is not available."** — slug or hostname collides with another project or is reserved.
 - **"That's a Fimo-owned domain."** — user tried `add <something>.fimo.site`. Use `rename-default` instead.

package/assets/skills/fimo-cli/references/hosting.md

@@ -57,9 +57,9 @@ them are present.
 {
   "redirects": [
     {
-      "source": "/(.*)",
-      "has": [{ "type": "header", "key": "x-vercel-ip-country", "value": "GB" }],
-      "destination": "/uk/:path*"
+      "source": "/offers",
+      "has": [{ "type": "header", "key": "x-promo", "value": "summer" }],
+      "destination": "/summer-sale"
     }
   ],
   "rewrites": [
@@ -74,12 +74,13 @@ them are present.
 
 | `type`   | Matches on                                           |
 | -------- | ---------------------------------------------------- |
-| `header` | a request header, including CDN-injected geo headers |
+| `header` | a request header                                     |
 | `cookie` | a cookie                                             |
 | `query`  | a query parameter                                    |
 | `host`   | the hostname the request arrived on — takes no `key` |
 
 Omit `value` to match on presence alone, as the `consent` cookie above does.
+The redirect example requires the request to include `x-promo: summer`.
 
 **Prefer doing this in the application when it can.** Middleware, a loader, or a
 server component can be run and tested locally; a condition here only takes

package/assets/skills/fimo-cli/references/preview.md

@@ -24,7 +24,7 @@ JSON output contains only the Branch identity and hosted URL:
     "project_id": "prj_abc",
     "branch": "main",
     "env": "main",
-    "preview_url": "https://fimo-preview-example.vercel.app"
+    "preview_url": "https://preview.example.com"
   }
 }
 ```

package/assets/skills/fimo-cli/references/projects.md

@@ -43,10 +43,10 @@ fimo rename "<Site Name>"        # local edit: set seo.siteName in the project c
 
 ## Publish commands
 
-| Command                 | Effect                                                                     |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `fimo deploy --publish` | Push the current Production source + flip the project live in one shot.    |
-| `fimo projects publish` | Flip the project live (no git push).                                       |
-| `fimo publish`          | Flip the synced Production source revision live; optional label and notes. |
+| Command                 | Effect                                                                  |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `fimo deploy --publish` | Push the current Production source + flip the project live in one shot. |
+| `fimo projects publish` | Flip the project live (no git push).                                    |
+| `fimo publish`          | Flip the revision already on the Fimo remote live (no git push).        |
 
 See `references/deploy.md` and `references/branches.md` for the full picture.

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

@@ -72,6 +72,7 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Locale ownership and framework handoff → `references/locales.md`
 - Upgrading a React Router app that imports `fimo/react-router/routes` → `references/migrations/react-router-route-ownership.md`
 - Astro connector and output/adapter contract → `references/frameworks/astro.md`
+- Astro/SvelteKit SEO or a new content route → the framework reference, then `references/frameworks/seo-head.md` for value ownership and edit-and-render acceptance
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`
 

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

@@ -6,7 +6,9 @@ This file covers media fields and the Fimo image components.
 
 ## Media field values
 
-A media field stores a reference to an asset, not a copy of the asset metadata. Write the value returned by upload or generation:
+For single-image and gallery schemas, see `references/content/schema.md`.
+
+Each media object stores a reference to an asset, not a copy of the asset metadata. Use the value returned by upload or generation:
 
 ```json
 {
@@ -31,7 +33,7 @@ const withAsset = await Post.getBySlug('hello', { populate: ['cover'] });
 
 `populate` takes top-level field names. A blocks field populates every media value inside it. One lookup covers all selected media in the response. Media inside a populated reference target stays a reference. Use `fimo assets open <id> --download` to inspect the source file.
 
-Generated reads wrap media in `FimoMedia`. Its `id`, `alt`, `name`, `mime`, `width`, and `height` can be absent. A populated value has the current facts when the asset resolves; missing or external assets stay unchanged. `source` is internal. Pass the whole value to `<Image>` or `<Video>`.
+Generated reads wrap each media object in `FimoMedia`. Its `id`, `alt`, `name`, `mime`, `width`, and `height` can be absent. A populated value has the current facts when the asset resolves; missing or external assets stay unchanged. `source` is internal. Pass one `FimoMedia` value, not the array, to `<Image>` or `<Video>`.
 
 ## Rendering in application code
 

package/assets/skills/fimo-code/references/best-practices/next.md

@@ -38,5 +38,3 @@ Use `instant = true` to find blocking code, then verify with `next build` and `n
 - Avoid duplicate content reads between `generateMetadata` and the page.
 
 Verify valid and missing slugs, canonical and initial HTML, shipped JavaScript, duplicate reads, image sizing, instant shell rendering, streaming, freshness, and bounded prefetching.
-
-Sources: [Instant Navigations](https://nextjs.org/blog/next-16-3-instant-navigations), [`partialPrefetching`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/05-config/01-next-config-js/partialPrefetching.mdx), and [`instant`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/instant.mdx).

package/assets/skills/fimo-code/references/content/schema.md

@@ -14,6 +14,7 @@ Write one schema per `src/schemas/<Uid>.json`. The PascalCase filename must matc
     "publishedAt": { "type": "date" },
     "featured": { "type": "boolean" },
     "cover": { "type": "media" },
+    "gallery": { "type": "media", "multiple": true },
     "metadata": { "type": "json" },
     "author": { "type": "reference", "target": "Author" },
     "contributors": { "type": "reference", "target": "Author", "many": true }
@@ -80,11 +81,13 @@ Never declare `id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `upd
 | `boolean`   | boolean                    | flags                                    |
 | `date`      | ISO date string            | calendar days; loose about the form      |
 | `datetime`  | ISO instant with offset    | exact moments (`2026-08-13T09:30:00Z`)   |
-| `media`     | media object or array      | images, video, files                     |
+| `media`     | media object by default    | images, video, files                     |
 | `json`      | JSON                       | structured metadata                      |
 | `reference` | `{ "id": "..." }` or array | links to another schema                  |
 | `blocks`    | ordered object array       | nested/repeatable sections               |
 
+Set `multiple: true` on a media field for an array, even with one image. See `references/assets.md` for the object shape.
+
 A `datetime` value must carry `Z` or `±HH:MM`; a bare day or a naive local time is rejected. Render it with `<DateTime>`, which keeps the whole instant in the `<time datetime>` attribute, and a `date` with `<Date>`. `unique` is not supported on `datetime`.
 
 An enum string uses `options`; its optional `default` must be one of them:

package/assets/skills/fimo-code/references/design.md

@@ -44,10 +44,10 @@ Reference sites to anchor the aesthetic direction. Pull any well-known site, bra
 | Category                 | Example Anchors                                                                                           | Quality Bar                                                                |
 | ------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
 | **Creative / Agency**    | Awwwards, FWA, CSS Design Awards, Pentagram, Sagmeister & Walsh, Active Theory, Fantasy Interactive, Resn | Would it win Awwwards SOTD? Would Pentagram put this in their portfolio?   |
-| **SaaS / Product**       | Linear, Vercel, Stripe, Notion, Figma, Raycast, Arc Browser, Supabase, Mercury, Clerk, Loom, Pitch        | Is it Linear-polished? Would a developer tweet "their site is so clean"?   |
+| **SaaS / Product**       | Linear, Stripe, Notion, Figma, Raycast, Arc Browser, Supabase, Mercury, Clerk, Loom, Pitch                | Is it Linear-polished? Would a developer tweet "their site is so clean"?   |
 | **Editorial / Blog**     | Medium, Substack, The Verge, NYT, The Atlantic, Monocle, It's Nice That, Eye on Design, Wired             | Would The Verge's design team respect this? Is it magazine-worthy?         |
 | **E-commerce**           | Apple Store, Shopify Dawn, Gumroad, Everlane, Glossier, SSENSE, Mr Porter, Mejuri, Allbirds               | Does it feel Apple Store premium? Would you trust buying from this?        |
-| **Documentation**        | Stripe Docs, Tailwind Docs, Vercel Docs, Supabase Docs, Prisma Docs, Algolia Docs, Clerk Docs             | Is it Stripe Docs clear? Can a developer find what they need in 3 seconds? |
+| **Documentation**        | Stripe Docs, Tailwind Docs, Supabase Docs, Prisma Docs, Algolia Docs, Clerk Docs                          | Is it Stripe Docs clear? Can a developer find what they need in 3 seconds? |
 | **Personal / Portfolio** | Read.cv, Paco Coursey, Josh Comeau, Rauno Freiberg, Brian Lovin, Lee Robinson, Linus Rogge                | Would Read.cv feature this? Is it memorable and distinctly personal?       |
 | **Corporate**            | Apple, Stripe, Airbnb, Slack, Square, Intercom, Dropbox, Zendesk                                          | Does it feel Airbnb-trustworthy? Premium but not flashy?                   |
 | **Dashboard**            | Linear, Figma, Raycast, Retool, Rows, Height, Airtable, Coda                                              | Is it Linear-efficient? Dense but never cluttered?                         |

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

@@ -1,6 +1,6 @@
 # Astro integration
 
-Use this reference for an existing Astro application. The application keeps its route files, output mode, adapter, locale system, links, `<html lang/dir>`, and SEO. Fimo connects content, labels, native rendering, preview, and hosting.
+Use this reference for an existing Astro application. The application keeps its route files, output mode, adapter, locale system, links, `<html lang/dir>`, and per-page SEO. Fimo connects content, labels, native rendering, preview, hosting, and the site-wide SEO defaults from Studio's Settings → SEO.
 
 ## Setup
 
@@ -90,6 +90,42 @@ browser values before submitting. Do not import the server form module into a
 client island; add a project endpoint if the form is intentionally browser-
 submitted.
 
+## SEO defaults
+
+Resolve the current route, apply page values, then convert to native attributes.
+New projects have this in `src/layouts/Base.astro`. Existing apps should extend
+their current head component, preserving unrelated metadata.
+
+```astro
+---
+import { resolveSeoForPath, toSeoHead } from 'fimo/seo';
+import config from '../../.fimo/config.json';
+
+const { seo = resolveSeoForPath(Astro.url.pathname, config) } = Astro.props;
+const canonicalUrl = seo?.url ? new URL(Astro.url.pathname, seo.url).href : undefined;
+const head = toSeoHead(seo, { canonicalUrl });
+---
+<head>
+  <title>{head.title ?? 'My site'}</title>
+  {head.meta.map((attributes) => <meta {...attributes} />)}
+  {head.links.map((attributes) => <link {...attributes} />)}
+</head>
+```
+
+For a content page, resolve after loading the entry and pass the final values
+to the layout: `const seo = resolveSeoForPath(Astro.url.pathname, config, { article })`,
+then `<Base lang={locale} seo={seo}>`. Route templates can read
+`{{article.title}}`. Apply app-owned overrides before conversion so the title,
+Open Graph and Twitter tags agree.
+
+The example canonical policy fits a root-hosted site. Preserve the app's own
+production domain, base path and trailing-slash policy. Omitting the converter's
+`canonicalUrl` omits canonical and `og:url`; `seo.url` alone is only a site base.
+Imported config changes need sync and rebuild/redeploy. Content freshness
+follows the route's rendering and caching policy.
+
+Full field and composition contract: read `references/frameworks/seo-head.md` when changing SEO.
+
 ## Static and on-demand rendering
 
 Keep the application's per-route rendering choice:

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

@@ -23,11 +23,11 @@ Vite plugin from `fimo-react-router/vite`, which builds on the installed
 SvelteKit installs `fimo` and `fimo-sveltekit`. Move a project to a new release
 with `fimo update <exact-version>`, which keeps the whole set on one version.
 
-React projects pinned before framework companions shipped keep their legacy
-runtime imports. The current CLI generates content clients through `fimo/ui`
-for those projects and does not require `fimo-react`. Run `fimo update
-<exact-version>` only when the developer chooses to move the project to a split
-runtime release.
+React and Next.js projects pinned before framework companions shipped keep
+their legacy runtime imports. The current CLI generates content clients through
+`fimo/ui` or `fimo/next` for those projects and does not require `fimo-react`
+or `fimo-next`. Run `fimo update <exact-version>` only when the developer
+chooses to move the project to a split runtime release.
 
 `runtime.framework` must match a dependency in `package.json`; a profile the
 code does not use fails the production build. Shape and rules: `hosting.md`

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

@@ -64,6 +64,28 @@ local environment alias by hand.
 projects. Do not add it to new code, env files, setup instructions, or migration
 plans.
 
+## `hosting`: how the deployed site is served
+
+Declare hosting rules only in `.fimo/config.json#hosting`, not provider
+deployment files. Run `fimo validate` to catch unsupported keys and malformed rules.
+
+| Key             | Shape                                                            |
+| --------------- | ---------------------------------------------------------------- |
+| `rewrites`      | `{ source, destination }`, URL unchanged                         |
+| `redirects`     | `{ source, destination, permanent?, statusCode? }`               |
+| `headers`       | `{ source, headers: [{ key, value }] }`, response headers        |
+| `cleanUrls`     | Serve `/about` for `/about.html` and redirect the extension away |
+| `trailingSlash` | `true` requires a trailing slash, `false` forbids one            |
+
+Rewrites, redirects, and header rules accept `has` / `missing` conditions:
+`header`, `cookie`, and `query` require `key`; `host` requires only `value`.
+
+Redirects default to temporary. Use `permanent: true` only for lasting moves;
+browsers cache it. `statusCode`, one of 301, 302, 307, 308, overrides `permanent`.
+
+Verify rules on a hosted Preview or published site, not a local dev server.
+Legacy static hosting ignores them; contact support if deployed rules have no effect.
+
 ## React Router framework mode
 
 For the supported client-rendered setup, keep `ssr: false` and add Fimo's
@@ -111,5 +133,4 @@ Astro has a dedicated connector — load `references/frameworks/astro.md` before
 editing an Astro config.
 
 `.fimo/config.json#routes` is the Studio page catalog, not deployment routing.
-Never generate hosting rewrites from it. If a project already has a
-provider-specific deployment file, preserve it; that file remains authoritative.
+Never generate hosting rewrites from it.

package/assets/skills/fimo-code/references/frameworks/seo-head.md

@@ -0,0 +1,78 @@
+# Astro and SvelteKit SEO
+
+Resolve route data, apply the app's policy, then convert. Both imports are pure
+and bundle-safe. Neither reads files, fetches content, discovers a route, nor
+sets framework caching. Use the installed package's exports.
+
+```ts
+import { resolveSeoForPath, toSeoHead, type FimoSEO } from 'fimo/seo';
+import config from '../../.fimo/config.json'; // adjust to the actual file
+
+const resolved = resolveSeoForPath(pathname, config, { article });
+const seo: FimoSEO = { ...resolved, title: String(article.title) };
+const head = toSeoHead(seo, { canonicalUrl });
+```
+
+`resolveSeoForPath` combines global defaults and the matching catalog route's
+`seo`. Supply the actual pathname, including the app's locale/base path, and
+the already-loaded data named by templates such as `{{article.title}}`.
+Unresolved tokens fall back for the entire field. The route catalog is not a
+router. For domain/custom locale routing, the app selects locale-specific
+values explicitly. No global defaults are required to use route SEO.
+
+All `FimoSEO` fields are optional strings:
+
+| Fields                 | Output                                                                            |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `title`, `description` | Native title/description and matching Open Graph/Twitter values                   |
+| `image`                | Open Graph and Twitter share image                                                |
+| `favicon`              | Icon and apple-touch-icon links                                                   |
+| `siteName`, `locale`   | Open Graph site name and locale                                                   |
+| `twitterSite`          | Twitter site account                                                              |
+| `robots`, `themeColor` | Native meta tags                                                                  |
+| `url`                  | Site base only. The app computes `canonicalUrl`; it emits canonical and `og:url`. |
+
+`toSeoHead` returns `{ title?, meta, links }`. No configured values produces
+empty arrays. Absent/empty fields emit no corresponding tags. The default
+social type/card are `website`/`summary_large_image`; use the existing head
+component for article tags, alternate languages, JSON-LD, and other app-owned
+metadata. Filter a converter attribute before replacing that same tag.
+
+Preserve editor-owned settings through resolution; do not copy their initial
+values into app constants that overwrite config. Derive content-owned title
+and description from the same loaded entry or singleton as the visible page,
+including Home/About. Pass that data to resolution or compose its current
+values before conversion. A correct first render does not prove editability.
+
+App values win only where intentionally required. Keep overrides together and
+record their reason in the existing code or handoff, not a new ownership
+registry. Set `image: undefined` to remove a
+global image, or `robots: 'noindex'` for an editorial page before conversion. An
+explicit `undefined` in a spread removes a field; use conditional spreads to
+retain defaults for missing optional overrides. Resolve once, then compose;
+do not resolve again after applying policy.
+
+Pass a final absolute canonical URL from the app's production URL policy.
+`new URL(pathname, seo.url).href` fits a root-hosted starter; preserve existing
+base paths, domains, trailing slashes and query policy in other apps. Never use
+the preview/request origin as a production canonical. Omit `canonicalUrl` to
+emit neither canonical nor `og:url`.
+
+For existing apps, inventory the current head owner and extend it in place.
+Do not add duplicate tags or overwrite unrelated metadata. Framework-escape
+attributes; never render a raw HTML string. Each new route must use the app's
+SEO path, with route data where needed. Verify title, description, canonical,
+robots and social values in built HTML, not only the browser tab title.
+
+Imported JSON is a build snapshot. Studio config changes need sync and
+rebuild/redeploy. Content freshness follows the app's SSR/prerender/cache
+policy; changing a helper does not change that policy.
+
+For SEO integration acceptance, use an authorized isolated project to change
+one inherited setting and one content-owned value after the initial render.
+Follow the app's sync/build/cache policy, then compare built HTML and the
+hydrated head; verify intentional overrides remain unchanged. Restore the
+test values. Include client navigation and Back where supported. Never mutate
+customer production data for this check. If edits or rendering are unavailable,
+report freshness unproven. `fimo validate` checks declared contracts, not rendered
+head propagation; a green result or helper import is not this acceptance proof.

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

@@ -224,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.

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-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,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-09-05T10:27:58.561Z",
+  "bundledAt": "2026-09-05T18:55:36.599Z",
   "cliVersion": "2.3.2",
   "external": [
     "oxc-parser",