fimo 2.4.0-staging.1 → 2.4.0-staging.10

package/dist/runtime/astro/server-runtime.js

@@ -9,8 +9,8 @@ export const astroServerContentRuntime = {
     headers(extra) {
         const headers = { ...extra };
         // `FIMO_ENV` is the variable name a customer's deployed build reads and
-        // keeps its spelling; only the header this build emits is canonical
-        // (branch-cutover ledger, F5). Builds already in production keep sending
+        // keeps its spelling; only the header this build emits is canonical.
+        // Builds already in production keep sending
         // `X-Fimo-Env`, which the API still accepts.
         const branch = import.meta.env.FIMO_ENV?.trim();
         if (branch) {

package/dist/runtime/paths/get-fimo-paths.js

@@ -47,7 +47,7 @@ async function fetchEntries(baseUrl, schema, rootDir, locale) {
     }
     const headers = {};
     // `FIMO_ENV` is a customer-facing variable name and keeps its spelling; the
-    // header this build emits is canonical (branch-cutover ledger, F5). A
+    // header this build emits is canonical. A
     // deployed site always talks to the current API, and builds produced by an
     // older `fimo` keep sending `X-Fimo-Env`, which the API still accepts.
     const branch = readEnvValue(rootDir, 'FIMO_ENV') ?? resolveLocalRuntimeEnv({ cwd: rootDir })?.env;

package/dist/runtime/seo/head.d.ts

@@ -0,0 +1,31 @@
+import type { FimoSEO } from '../shared/fimo-config.types.js';
+export type FimoHeadMeta = {
+    name: string;
+    content: string;
+} | {
+    property: string;
+    content: string;
+};
+export interface FimoHeadLink {
+    rel: string;
+    href: string;
+}
+/** Document head for one page: spread each entry onto a `<meta>` or `<link>`. */
+export interface FimoHead {
+    title?: string;
+    meta: FimoHeadMeta[];
+    links: FimoHeadLink[];
+}
+export interface SeoHeadOptions {
+    /** Final canonical URL chosen by the app, also used for og:url. Omit to emit neither tag. */
+    canonicalUrl?: string;
+}
+/**
+ * Convert final SEO values to native tag attributes without I/O, route resolution
+ * or merging. The app resolves content and policy first. Absent/empty fields emit
+ * no tags; omitted SEO emits an empty head unless a canonical URL is supplied.
+ * `seo.url` is a site base, not a page canonical: only options.canonicalUrl emits
+ * canonical/og:url. Render attributes through the framework, never as raw HTML.
+ */
+export declare function toSeoHead(seo?: FimoSEO, options?: SeoHeadOptions): FimoHead;
+//# sourceMappingURL=head.d.ts.map

package/dist/runtime/seo/head.js

@@ -0,0 +1,47 @@
+/**
+ * Convert final SEO values to native tag attributes without I/O, route resolution
+ * or merging. The app resolves content and policy first. Absent/empty fields emit
+ * no tags; omitted SEO emits an empty head unless a canonical URL is supplied.
+ * `seo.url` is a site base, not a page canonical: only options.canonicalUrl emits
+ * canonical/og:url. Render attributes through the framework, never as raw HTML.
+ */
+export function toSeoHead(seo = {}, options = {}) {
+    const canonical = options.canonicalUrl;
+    if (!Object.values(seo).some(Boolean) && !canonical) {
+        return { meta: [], links: [] };
+    }
+    const meta = [];
+    const named = (name, content) => {
+        if (content) {
+            meta.push({ name, content });
+        }
+    };
+    const property = (name, content) => {
+        if (content) {
+            meta.push({ property: name, content });
+        }
+    };
+    named('description', seo.description);
+    named('robots', seo.robots);
+    named('theme-color', seo.themeColor);
+    property('og:type', 'website');
+    property('og:site_name', seo.siteName);
+    property('og:title', seo.title);
+    property('og:description', seo.description);
+    property('og:url', canonical);
+    property('og:image', seo.image);
+    property('og:locale', seo.locale);
+    named('twitter:card', 'summary_large_image');
+    named('twitter:site', seo.twitterSite);
+    named('twitter:title', seo.title);
+    named('twitter:description', seo.description);
+    named('twitter:image', seo.image);
+    const links = [];
+    if (canonical) {
+        links.push({ rel: 'canonical', href: canonical });
+    }
+    if (seo.favicon) {
+        links.push({ rel: 'icon', href: seo.favicon }, { rel: 'apple-touch-icon', href: seo.favicon });
+    }
+    return { ...(seo.title ? { title: seo.title } : {}), meta, links };
+}

package/dist/runtime/seo/index.d.ts

@@ -1,2 +1,4 @@
 export * from './resolver.js';
+export * from './head.js';
+export type { FimoSEO } from '../shared/fimo-config.types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/seo/index.js

@@ -1 +1,2 @@
 export * from './resolver.js';
+export * from './head.js';

package/dist/runtime/seo/resolver.d.ts

@@ -1,4 +1,4 @@
-import type { FimoConfig, FimoRouteConfig, FimoSEO } from '../shared/fimo-config.types.js';
+import type { FimoRouteConfig, FimoSEO, RouteSEO } from '../shared/fimo-config.types.js';
 /**
  * Shared SEO resolver for the generated app.
  *
@@ -40,5 +40,19 @@ export declare function matchRoutePath(pathname: string, pathPattern: string): {
 export declare function resolveRouteConfig(pathname: string, routes: Record<string, FimoRouteConfig> | undefined): FimoRouteConfig | undefined;
 export declare function getNestedValue(input: unknown, path: string): unknown;
 export declare function resolveTemplate(template: string, context: Record<string, unknown>): string;
-export declare function resolveSeoForPath(pathname: string, config: FimoConfig, routeData?: unknown): FimoSEO | undefined;
+/** SEO slices of an imported JSON config; unrelated framework literal unions need not be preserved. */
+export interface FimoSeoConfig {
+    seo?: FimoSEO;
+    i18n?: {
+        defaultLocale?: string;
+        locales?: string[];
+    };
+    routes?: Record<string, {
+        path?: string;
+        label?: string;
+        seo?: RouteSEO;
+        params?: object;
+    }>;
+}
+export declare function resolveSeoForPath(pathname: string, config: FimoSeoConfig, routeData?: unknown): FimoSEO | undefined;
 //# sourceMappingURL=resolver.d.ts.map

package/dist/runtime/seo/resolver.js

@@ -86,6 +86,16 @@ export function resolveTemplate(template, context) {
 }
 function resolveSeoField(routeValue, globalValue, context) {
     if (routeValue) {
+        for (const token of routeValue.matchAll(/\{\{([^}]+)\}\}/g)) {
+            const raw = getNestedValue(context, token[1].trim());
+            const value = raw instanceof String || raw instanceof Number || raw instanceof Boolean ? raw.valueOf() : raw;
+            if (value == null ||
+                (typeof value === 'string' && value.trim() === '') ||
+                !['string', 'number', 'boolean'].includes(typeof value) ||
+                (typeof value === 'number' && !Number.isFinite(value))) {
+                return globalValue;
+            }
+        }
         return resolveTemplate(routeValue, context);
     }
     return globalValue;

package/dist/runtime/seo/server.d.ts

@@ -0,0 +1,13 @@
+import type { FimoSEO } from '../shared/fimo-config.types.js';
+export interface GetFimoSeoOptions {
+    pathname?: string;
+    routeData?: Record<string, unknown>;
+    rootDir?: string;
+}
+/**
+ * Read global SEO, or resolve an explicit pathname against the project's route
+ * catalog. Node only. Missing config/SEO returns undefined; other read and JSON
+ * errors propagate. No cache: rendering/revalidation remains application-owned.
+ */
+export declare function getFimoSeo({ pathname, routeData, rootDir }?: GetFimoSeoOptions): FimoSEO | undefined;
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime/seo/server.js

@@ -0,0 +1,23 @@
+import { readConfigServer } from '../shared/fimo-config.server.js';
+import { resolveSeoForPath } from './resolver.js';
+/**
+ * Read global SEO, or resolve an explicit pathname against the project's route
+ * catalog. Node only. Missing config/SEO returns undefined; other read and JSON
+ * errors propagate. No cache: rendering/revalidation remains application-owned.
+ */
+export function getFimoSeo({ pathname, routeData, rootDir = process.cwd() } = {}) {
+    let config;
+    try {
+        config = readConfigServer(rootDir);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+    if (pathname !== undefined) {
+        return resolveSeoForPath(pathname, config, routeData);
+    }
+    return config.seo && Object.keys(config.seo).length > 0 ? config.seo : undefined;
+}

package/dist/runtime/shared/branch-identity.d.ts

@@ -19,8 +19,7 @@ export declare const PROD_BRANCH_PREFIX = "release/";
 export declare function isValidBranch(branch: string): boolean;
 /**
  * Mirror of `envResourceKey` in `@fimo/api-contracts`. Keeps that name on both
- * sides: its OUTPUT is a live tenant hostname and R2 prefix, and the symbol
- * rename is a later slice (branch-cutover ledger, F10).
+ * sides: its OUTPUT is a live tenant hostname and R2 prefix.
  */
 export declare function envResourceKey(branch: string): string;
 /** Mirror of `buildTenantApiUrl` in `@fimo/api-contracts`. */
@@ -32,15 +31,14 @@ export declare function buildTenantApiUrl(projectId: string, branch: string, ten
  * reads is one more line to reason about when a site talks to the wrong Branch.
  *
  * These are process-env variable names in a CUSTOMER's app; they keep their
- * `ENV` spelling (branch-cutover ledger, F3 "Preserve").
+ * `ENV` spelling.
  */
 export declare const LOCAL_CONTENT_API_ENV_KEYS: readonly ['FIMO_CONTENT_API_URL', 'VITE_API_URL', 'NEXT_PUBLIC_FIMO_API_URL', 'PUBLIC_FIMO_API_URL'];
 /**
  * Branch selectors a runtime turns into the Branch request header.
  *
  * `FIMO_ENV` / `NEXT_PUBLIC_FIMO_ENV` are the variable names a customer's
- * deployed build reads; renaming either breaks it (branch-cutover ledger,
- * "Names that must not be mechanically renamed").
+ * deployed build reads; renaming either breaks it.
  */
 export declare const LOCAL_ENV_SELECTOR_KEYS: readonly ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
 /**

package/dist/runtime/shared/branch-identity.js

@@ -46,8 +46,7 @@ function fnv1a8(s) {
 }
 /**
  * Mirror of `envResourceKey` in `@fimo/api-contracts`. Keeps that name on both
- * sides: its OUTPUT is a live tenant hostname and R2 prefix, and the symbol
- * rename is a later slice (branch-cutover ledger, F10).
+ * sides: its OUTPUT is a live tenant hostname and R2 prefix.
  */
 export function envResourceKey(branch) {
     const base = branch
@@ -71,7 +70,7 @@ export function buildTenantApiUrl(projectId, branch, tenantApiBaseUrl) {
  * reads is one more line to reason about when a site talks to the wrong Branch.
  *
  * These are process-env variable names in a CUSTOMER's app; they keep their
- * `ENV` spelling (branch-cutover ledger, F3 "Preserve").
+ * `ENV` spelling.
  */
 export const LOCAL_CONTENT_API_ENV_KEYS = [
     'FIMO_CONTENT_API_URL',
@@ -83,8 +82,7 @@ export const LOCAL_CONTENT_API_ENV_KEYS = [
  * Branch selectors a runtime turns into the Branch request header.
  *
  * `FIMO_ENV` / `NEXT_PUBLIC_FIMO_ENV` are the variable names a customer's
- * deployed build reads; renaming either breaks it (branch-cutover ledger,
- * "Names that must not be mechanically renamed").
+ * deployed build reads; renaming either breaks it.
  */
 export const LOCAL_ENV_SELECTOR_KEYS = ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
 /**

package/dist/runtime/shared/fimo-config.server.d.ts

@@ -4,6 +4,8 @@ import type { FimoConfig } from './fimo-config.types.js';
  * Reads JSON directly to avoid virtual module issues during config loading.
  */
 export declare function getConfigServer(rootDir: string): FimoConfig;
+/** Read the selected config without swallowing I/O or JSON errors. */
+export declare function readConfigServer(rootDir: string): FimoConfig;
 export declare function getConfigVersion(rootDir: string): number;
 /** Resolve the current config path while keeping legacy projects readable. */
 export declare function resolveFimoConfigPath(rootDir: string): string;

package/dist/runtime/shared/fimo-config.server.js

@@ -13,25 +13,29 @@ const defaultConfig = {
  */
 export function getConfigServer(rootDir) {
     try {
-        const configPath = resolveFimoConfigPath(rootDir);
-        const content = readFileSync(configPath, 'utf-8');
-        // `fimo validate` owns strict config validation. The public runtime only
-        // reads the already-validated values and must stay self-contained: importing
-        // the repository-private API contracts package would break installed apps.
-        const raw = JSON.parse(content);
-        return {
-            runtime: raw.runtime,
-            hosting: raw.hosting,
-            seo: raw.seo,
-            i18n: raw.i18n,
-            routes: raw.routes,
-            version: raw.version,
-        };
+        return readConfigServer(rootDir);
     }
     catch {
         return defaultConfig;
     }
 }
+/** Read the selected config without swallowing I/O or JSON errors. */
+export function readConfigServer(rootDir) {
+    const configPath = resolveFimoConfigPath(rootDir);
+    const content = readFileSync(configPath, 'utf-8');
+    // `fimo validate` owns strict config validation. The public runtime only
+    // reads the already-validated values and must stay self-contained: importing
+    // the repository-private API contracts package would break installed apps.
+    const raw = JSON.parse(content);
+    return {
+        runtime: raw.runtime,
+        hosting: raw.hosting,
+        seo: raw.seo,
+        i18n: raw.i18n,
+        routes: raw.routes,
+        version: raw.version,
+    };
+}
 export function getConfigVersion(rootDir) {
     try {
         const configPath = resolveFimoConfigPath(rootDir);

package/dist/scripts/export-static.d.ts

@@ -2,10 +2,9 @@ export interface ExportStaticOptions {
     cwd?: string;
 }
 /**
- * Post-build cleanup for `react-router build` output:
- * - Removes `dist/server/` (we ship a fully prerendered SPA, no SSR runtime needed)
- * - Removes `*.data` files (data is embedded in the prerendered HTML and
- *   never fetched because navigation uses full-page <a> loads)
+ * Removes `dist/server/` after a static React Router build. Requires
+ * `dist/client/` to exist and preserves its contents, including `*.data`
+ * files used by React Router client navigation or authored as static assets.
  *
  * Run from `react-router build && fimo export-static`.
  */

package/dist/scripts/export-static.js

@@ -9,23 +9,10 @@ async function pathExists(targetPath) {
         return false;
     }
 }
-async function removeDataFiles(dir) {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            await removeDataFiles(fullPath);
-        }
-        else if (entry.name.endsWith('.data')) {
-            await fs.rm(fullPath);
-        }
-    }
-}
 /**
- * Post-build cleanup for `react-router build` output:
- * - Removes `dist/server/` (we ship a fully prerendered SPA, no SSR runtime needed)
- * - Removes `*.data` files (data is embedded in the prerendered HTML and
- *   never fetched because navigation uses full-page <a> loads)
+ * Removes `dist/server/` after a static React Router build. Requires
+ * `dist/client/` to exist and preserves its contents, including `*.data`
+ * files used by React Router client navigation or authored as static assets.
  *
  * Run from `react-router build && fimo export-static`.
  */
@@ -36,12 +23,8 @@ export async function exportStatic(options = {}) {
     if (!(await pathExists(clientDir))) {
         throw new Error('Missing dist/client output. Run `react-router build` first.');
     }
-    // In framework mode with buildDirectory=dist, the static output already lives in dist/client.
     if (await pathExists(serverDir)) {
         await fs.rm(serverDir, { recursive: true, force: true });
     }
-    // Remove .data files — all data is embedded in prerendered HTML.
-    // Navigation uses <a> tags (full page loads), so .data files are never fetched.
-    await removeDataFiles(clientDir);
     console.log('Static export complete.');
 }

package/dist/scripts/sync-schemas.js

@@ -144,6 +144,7 @@ function resolveProjectRuntime(cwd) {
         version,
         providesLegacyReactRuntime: packageExportsSubpath(packageJson, './ui'),
         providesReactRuntime: packageExportsSubpath(readProjectPackage(cwd, 'fimo-react'), '.'),
+        providesLegacyNextRuntime: packageExportsSubpath(packageJson, './next') && packageExportsSubpath(packageJson, './next/client'),
         providesNextRuntime: packageExportsSubpath(readProjectPackage(cwd, 'fimo-next'), '.') &&
             packageExportsSubpath(readProjectPackage(cwd, 'fimo-next'), './client'),
         providesAstroRuntime: packageExportsSubpath(packageJson, './astro'),
@@ -154,7 +155,7 @@ function resolveProjectRuntime(cwd) {
 }
 function contentRuntimeImportFor(framework, runtime) {
     if (framework === 'nextjs') {
-        return 'fimo-next';
+        return isVersionAtLeast(runtime.version, MINIMUM_FRAMEWORK_COMPANION_RUNTIME_VERSION) ? 'fimo-next' : 'fimo/next';
     }
     if (framework === 'astro') {
         return 'fimo/astro';
@@ -196,6 +197,12 @@ function resolveSchemaGenerationTarget(runtimeImport, runtime) {
     if (runtimeImport === 'fimo-react') {
         return 'react';
     }
+    if (runtimeImport === 'fimo/next' && !runtime.providesLegacyNextRuntime) {
+        throw new Error(`Cannot generate schema clients because project-local fimo@${runtime.version} does not provide the ` +
+            'legacy fimo/next and fimo/next/client exports required by this Next.js project. ' +
+            `Run \`${CONTENT_CLIENT_RUNTIME_UPGRADE_COMMAND}\` in the project, then run \`npx fimo@latest validate\` again. ` +
+            'No generated files were changed.');
+    }
     if (runtimeImport === 'fimo-next' && !runtime.providesNextRuntime) {
         throw new Error(`Cannot generate schema clients because the project does not provide the ` +
             'fimo-next and fimo-next/client exports required by this Next.js project. ' +
@@ -213,7 +220,7 @@ function resolveSchemaGenerationTarget(runtimeImport, runtime) {
             `Run \`npm install fimo-sveltekit@${runtime.version}\` in the project, then run \`npx fimo@latest validate\` again. ` +
             'No generated files were changed.');
     }
-    if (runtimeImport === 'fimo-next') {
+    if (runtimeImport === 'fimo/next' || runtimeImport === 'fimo-next') {
         return 'next';
     }
     return runtimeImport === 'fimo/astro' ? 'astro' : 'sveltekit';
@@ -224,17 +231,17 @@ function templatesForTarget(target, runtime, runtimeImport) {
             {
                 suffix: '.types.ts',
                 path: templatePath(runtime, 'types'),
-                runtimeImport: 'fimo-next',
+                runtimeImport,
             },
             {
                 suffix: '.ts',
                 path: templatePath(runtime, 'nextServer'),
-                runtimeImport: 'fimo-next',
+                runtimeImport,
             },
             {
                 suffix: '.client.ts',
                 path: templatePath(runtime, 'nextClient'),
-                runtimeImport: 'fimo-next/client',
+                runtimeImport: `${runtimeImport}/client`,
             },
         ];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "2.4.0-staging.1",
+  "version": "2.4.0-staging.10",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "keywords": [
     "astro-component"
@@ -57,6 +57,10 @@
       "types": "./dist/runtime/seo/index.d.ts",
       "import": "./dist/runtime/seo/index.js"
     },
+    "./seo/server": {
+      "types": "./dist/runtime/seo/server.d.ts",
+      "import": "./dist/runtime/seo/server.js"
+    },
     "./sync": {
       "types": "./dist/scripts/index.d.ts",
       "import": "./dist/scripts/index.js"
@@ -189,13 +193,13 @@
   "devDependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
-    "@fimo/agents-bundle": "2.4.0-staging.1",
-    "@fimo/api-contracts": "2.4.0-staging.1",
-    "@fimo/cli-kit": "2.4.0-staging.1",
-    "@fimo/framework-detect": "2.4.0-staging.1",
-    "@fimo/routes": "2.4.0-staging.1",
-    "@fimo/sdk": "2.4.0-staging.1",
-    "@fimo/tsconfig": "2.4.0-staging.1",
+    "@fimo/agents-bundle": "2.4.0-staging.10",
+    "@fimo/api-contracts": "2.4.0-staging.10",
+    "@fimo/cli-kit": "2.4.0-staging.10",
+    "@fimo/framework-detect": "2.4.0-staging.10",
+    "@fimo/routes": "2.4.0-staging.10",
+    "@fimo/sdk": "2.4.0-staging.10",
+    "@fimo/tsconfig": "2.4.0-staging.10",
     "@types/node": "22.18.6",
     "agent-install": "^0.0.5",
     "astro": "^7.1.6",

package/templates/astro/.fimo/config.json

@@ -18,6 +18,7 @@
     "project": {
       "label": "Project",
       "path": "/:locale/projects/:slug",
+      "seo": { "title": "{{project.title}}", "description": "{{project.summary}}" },
       "params": {
         "locale": { "type": "locale", "optional": true },
         "slug": { "schema": "Project", "queryField": "slug", "displayField": "title" }

package/templates/astro/AGENTS.md

@@ -31,7 +31,7 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 - Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale. Load `fimo skills get fimo-cli --ref locales` and use `fimo locales` to configure the exact locale set and default. Never edit `i18n.defaultLocale` or `i18n.locales` directly. If no language is requested, keep `en` and state that choice. Astro reads the synchronized config, keeps the default locale unprefixed, and prefixes the others.
 - Preserve both the unprefixed default pages and the `[locale]` page tree. Astro has no optional single-segment file route, so the paired native pages keep one-locale URLs clean and allow another locale without changing the route shape. Use `Astro.currentLocale` for Fimo content reads, `getLabels`, and document language.
 - Keep `.fimo/config.json#routes` as Studio metadata aligned with Astro's page files. It does not configure Astro routing.
-- Astro owns routes, locale resolution, links, HTML language/direction, and SEO. Fimo connects to those decisions.
+- Astro owns routes, locale resolution, links and SEO. Base.astro resolves the actual path with `resolveSeoForPath` and renders `toSeoHead` from `fimo/seo`. Content pages pass already-resolved `seo` with their route data. Keep title/social tags in agreement and preserve the app's canonical policy.
 - Use generated schema clients, `getLabels({ locale })`, and native components from `fimo/astro/components` for editable values.
 - Do not add React or a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory to the remote project.

package/templates/astro/astro.config.mjs

@@ -4,6 +4,7 @@ import { fimo } from 'fimo-astro/config';
 import fimoConfig from './.fimo/config.json' with { type: 'json' };
 
 export default defineConfig({
+  devToolbar: { enabled: false },
   integrations: [fimo()],
   i18n: {
     defaultLocale: fimoConfig.i18n.defaultLocale,

package/templates/astro/package.json

@@ -9,8 +9,8 @@
     "check": "astro sync && astro check"
   },
   "dependencies": {
-    "fimo": "2.4.0-staging.1",
-    "fimo-astro": "2.4.0-staging.1"
+    "fimo": "2.4.0-staging.10",
+    "fimo-astro": "2.4.0-staging.10"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/templates/astro/src/layouts/Base.astro

@@ -1,10 +1,25 @@
 ---
+import { resolveSeoForPath, toSeoHead, type FimoSEO } from 'fimo/seo';
+
+import fimoConfig from '../../.fimo/config.json';
+
 interface Props {
   lang: string;
-  title: string;
+  title?: string;
+  description?: string;
+  seo?: FimoSEO;
+  canonicalUrl?: string | null;
 }
 
-const { lang, title } = Astro.props;
+const { lang, title, description, seo = resolveSeoForPath(Astro.url.pathname, fimoConfig) } = Astro.props;
+const canonicalUrl = Astro.props.canonicalUrl === undefined
+  ? (seo?.url ? new URL(Astro.url.pathname, seo.url).href : undefined)
+  : Astro.props.canonicalUrl ?? undefined;
+const head = toSeoHead({
+  ...seo,
+  ...(title !== undefined ? { title } : {}),
+  ...(description !== undefined ? { description } : {}),
+}, { canonicalUrl });
 ---
 
 <!doctype html>
@@ -12,10 +27,11 @@ const { lang, title } = Astro.props;
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width" />
-    <meta name="description" content="A new Fimo project built with Astro." />
+    <title>{head.title ?? 'Fimo + Astro'}</title>
+    {head.meta.map((attributes) => <meta {...attributes} />)}
+    {head.links.map((attributes) => <link {...attributes} />)}
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
-    <title>{title}</title>
   </head>
   <body>
     <slot />

package/templates/astro/src/pages/[locale]/index.astro

@@ -14,6 +14,6 @@ if (!routeLocale || !prefixedLocales.has(routeLocale)) {
 const locale = Astro.currentLocale ?? routeLocale;
 ---
 
-<Base lang={locale} title="Fimo + Astro">
+<Base lang={locale}>
   <StarterHome />
 </Base>

package/templates/astro/src/pages/[locale]/projects/[slug].astro

@@ -1,7 +1,9 @@
 ---
 import { getLabels } from 'fimo/astro';
 import { Text } from 'fimo/astro/components';
+import { resolveSeoForPath } from 'fimo/seo';
 
+import config from '../../../../.fimo/config.json';
 import Base from '../../../layouts/Base.astro';
 import { prefixedLocales } from '../../../locales';
 import * as Project from '../../../schemas/Project';
@@ -22,9 +24,10 @@ const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale })
 if (!project) {
   return Astro.redirect('/404');
 }
+const seo = resolveSeoForPath(Astro.url.pathname, config, { project });
 ---
 
-<Base lang={locale} title={String(project.title)}>
+<Base lang={locale} seo={seo} title={seo?.title ?? String(project.title)}>
   <main data-framework="astro" data-rendering="server" data-project-slug={slug}>
     <a href={`/${locale}/projects`}><Text as="span" value={labels.t('navigation.projects')} /></a>
     <article>

package/templates/astro/src/pages/index.astro

@@ -8,6 +8,6 @@ export const prerender = true;
 const locale = Astro.currentLocale ?? defaultLocale;
 ---
 
-<Base lang={locale} title="Fimo + Astro">
+<Base lang={locale}>
   <StarterHome />
 </Base>

package/templates/astro/src/pages/projects/[slug].astro

@@ -1,7 +1,9 @@
 ---
 import { getLabels } from 'fimo/astro';
 import { Text } from 'fimo/astro/components';
+import { resolveSeoForPath } from 'fimo/seo';
 
+import config from '../../../.fimo/config.json';
 import Base from '../../layouts/Base.astro';
 import { defaultLocale } from '../../locales';
 import * as Project from '../../schemas/Project';
@@ -15,9 +17,10 @@ const [project, labels] = await Promise.all([Project.getBySlug(slug, { locale })
 if (!project) {
   return Astro.redirect('/404');
 }
+const seo = resolveSeoForPath(Astro.url.pathname, config, { project });
 ---
 
-<Base lang={locale} title={String(project.title)}>
+<Base lang={locale} seo={seo} title={seo?.title ?? String(project.title)}>
   <main data-framework="astro" data-rendering="server" data-project-slug={slug}>
     <a href="/projects"><Text as="span" value={labels.t('navigation.projects')} /></a>
     <article>

package/templates/nextjs/AGENTS.md

@@ -40,7 +40,7 @@ The scaffolded homepage is disposable. Replace it on the first real generation.
 - Next's `app` tree is the router and stays authoritative: the default shell is one ordinary root layout plus `/` as the homepage, and unknown paths get Next's native 404. When a product requires locale URLs, implement the framework-native strategy (`[locale]` segments, middleware, cookies, domains, or an i18n library), pass the resolved locale into Fimo server reads and `FimoProvider`, and load `fimo skills get fimo-code --ref frameworks/next/locales` first. Do not impose locale-prefixed URLs on a default-only project.
 - `FimoProvider` owns the optional Studio preview runtime. Do not add a preview bridge component, read Fimo preview environment variables, or inject Fimo scripts in application code.
 - Keep `.fimo/config.json#routes` as Studio metadata, not as the Next.js router. Describe only URLs the application actually serves; add a `:locale` segment to a route's metadata only after the application implements that locale routing. There, `params.locale.optional: true` means omit the configured default locale from the URL; use `optional: false` only when every locale, including the default, must be prefixed.
-- The application owns routes, locale resolution, links, HTML language/direction, and per-page SEO overrides. Fimo supplies the site-wide SEO defaults (title, description, favicon, share image) from `.fimo/config.json#seo` through the root layout's `generateMetadata`/`generateViewport` (`buildFimoMetadata`/`buildFimoViewport` from `fimo-next`); keep that wiring, and add page-level `metadata`/`generateMetadata` exports where a page needs its own values — they merge over the defaults.
+- The application owns SEO policy. Keep the root's global SEO wiring and the homepage's explicit route wiring. When creating or adding a page, load `fimo skills get fimo-code --ref frameworks/next/seo` and reuse the established route pattern. Resolve the real pathname and content in that route module; add route viewport wiring only for route-specific theme color. Preserve app-owned metadata and file-based images; Next replaces nested metadata objects rather than merging their fields.
 - Do not add a second deployment platform.
 - Never edit `.fimo/project.json`; it links this directory to the remote project.
 - Keep `.fimo/config.json#runtime` true to the code: framework, `dev`/`build`/`install` commands, output directory. Update it when you rename a package script, move the build output, or change framework; the reference is `fimo skills get fimo-code --ref frameworks/hosting`.