fimo 2.2.0-staging.8 → 2.2.0

package/dist/runtime/primitives/lib/primitives.js

@@ -4,10 +4,21 @@
  * All Fimo types carry hidden metadata that enables the preview editor
  * to know where content comes from (schema field, translation key, etc.)
  */
-var _a, _b, _c, _d, _e, _f;
+var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
 // Symbol for accessing fimo metadata (hidden from JSON.stringify)
 export const FIMO_SOURCE = Symbol.for('fimo.source');
+export const FIMO_SOURCE_CONTEXT = Symbol.for('fimo.sourceContext');
 export const FIMO_PARTS = Symbol.for('fimo.parts');
+function defineSourceContext(value, context) {
+    if (context && context.length > 0) {
+        Object.defineProperty(value, FIMO_SOURCE_CONTEXT, {
+            value: Object.freeze([...context]),
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    return value;
+}
 /**
  * FimoString - A string with source tracking
  *
@@ -15,7 +26,7 @@ export const FIMO_PARTS = Symbol.for('fimo.parts');
  * but carries hidden metadata for inline editing.
  */
 export class FimoString extends String {
-    constructor(value, source) {
+    constructor(value, source, context) {
         super(value);
         Object.defineProperty(this, _a, {
             enumerable: true,
@@ -29,7 +40,14 @@ export class FimoString extends String {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, _c, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this[FIMO_SOURCE] = source;
+        defineSourceContext(this, context);
     }
     /**
      * Compose multiple tracked values into one FimoString.
@@ -41,7 +59,7 @@ export class FimoString extends String {
         const trackedParts = parts.filter((p) => p.source);
         // Single tracked part with no static text — just return a normal FimoString
         if (trackedParts.length === 1 && parts.length === 1) {
-            return new FimoString(text, trackedParts[0].source);
+            return new FimoString(text, trackedParts[0].source, trackedParts[0].context);
         }
         const instance = new FimoString(text, null);
         instance[FIMO_PARTS] = parts;
@@ -54,31 +72,50 @@ export class FimoString extends String {
         return { source: this[FIMO_SOURCE] ?? '' };
     }
 }
-_a = FIMO_SOURCE, _b = FIMO_PARTS;
+_a = FIMO_SOURCE, _b = FIMO_SOURCE_CONTEXT, _c = FIMO_PARTS;
 /**
  * FimoDate - A date with source tracking
  */
 export class FimoDate extends Date {
-    constructor(value, source) {
+    constructor(value, source, context) {
         super(value);
-        Object.defineProperty(this, _c, {
+        Object.defineProperty(this, _d, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, _e, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
         this[FIMO_SOURCE] = source;
+        defineSourceContext(this, context);
     }
     get __fimo() {
         return { source: this[FIMO_SOURCE] };
     }
 }
-_c = FIMO_SOURCE;
+_d = FIMO_SOURCE, _e = FIMO_SOURCE_CONTEXT;
 /**
- * FimoMedia - Media object with source tracking
+ * FimoMedia - a media value with source tracking.
+ *
+ * A stored media value is a reference: the media-library `id`, the `url` that
+ * still resolves if the asset is deleted, and the `alt` the entry owns. The
+ * facts the asset owns, such as `name`, `mime`, and intrinsic `width`/`height`,
+ * are optional because a read only carries them when it named the field in
+ * `populate`. Renderers must treat them as enrichment.
  */
 export class FimoMedia {
-    constructor(data, source) {
+    constructor(data, source, context) {
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "url", {
             enumerable: true,
             configurable: true,
@@ -115,12 +152,19 @@ export class FimoMedia {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, _d, {
+        Object.defineProperty(this, _f, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, _g, {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        this.id = data.id;
         this.url = data.url;
         this.alt = data.alt;
         this.name = data.name;
@@ -128,24 +172,31 @@ export class FimoMedia {
         this.width = data.width;
         this.height = data.height;
         this[FIMO_SOURCE] = source;
+        defineSourceContext(this, context);
     }
     get __fimo() {
         return { source: this[FIMO_SOURCE] };
     }
 }
-_d = FIMO_SOURCE;
+_f = FIMO_SOURCE, _g = FIMO_SOURCE_CONTEXT;
 /**
  * FimoBoolean - Boolean with source tracking (for display purposes)
  */
 export class FimoBoolean {
-    constructor(value, source) {
+    constructor(value, source, context) {
         Object.defineProperty(this, "value", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, _e, {
+        Object.defineProperty(this, _h, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, _j, {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -153,6 +204,7 @@ export class FimoBoolean {
         });
         this.value = value;
         this[FIMO_SOURCE] = source;
+        defineSourceContext(this, context);
     }
     get __fimo() {
         return { source: this[FIMO_SOURCE] };
@@ -161,21 +213,27 @@ export class FimoBoolean {
         return this.value;
     }
 }
-_e = FIMO_SOURCE;
+_h = FIMO_SOURCE, _j = FIMO_SOURCE_CONTEXT;
 /**
  * FimoRichText - Rich text content with source tracking
  *
  * Wraps Tiptap JSONContent for rich text fields with inline editing support.
  */
 export class FimoRichText {
-    constructor(content, source) {
+    constructor(content, source, context) {
         Object.defineProperty(this, "content", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, _f, {
+        Object.defineProperty(this, _k, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, _l, {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -183,12 +241,13 @@ export class FimoRichText {
         });
         this.content = content;
         this[FIMO_SOURCE] = source;
+        defineSourceContext(this, context);
     }
     get __fimo() {
         return { source: this[FIMO_SOURCE] };
     }
 }
-_f = FIMO_SOURCE;
+_k = FIMO_SOURCE, _l = FIMO_SOURCE_CONTEXT;
 /**
  * Type guard to check if a value is a FimoString
  */
@@ -219,6 +278,13 @@ export function getFimoSource(value) {
     }
     return undefined;
 }
+/** Get the hidden relation/component ancestry from a wrapped value. */
+export function getFimoSourceContext(value) {
+    if (value != null && typeof value === 'object' && FIMO_SOURCE_CONTEXT in value) {
+        return value[FIMO_SOURCE_CONTEXT];
+    }
+    return undefined;
+}
 /**
  * Get the decomposed parts from a composed FimoString, or undefined
  */

package/dist/runtime/primitives/lib/template.js

@@ -1,4 +1,4 @@
-import { FIMO_SOURCE, FimoString, hasFimoSource } from './primitives.js';
+import { FIMO_SOURCE, getFimoSourceContext, FimoString, hasFimoSource } from './primitives.js';
 /**
  * Template literal helper for composing multiple Fimo values
  *
@@ -19,7 +19,7 @@ export function fimo(strings, ...values) {
             const value = values[i];
             const text = String(value);
             const source = hasFimoSource(value) ? value[FIMO_SOURCE] : undefined;
-            parts.push({ text, source: source ?? undefined });
+            parts.push({ text, source: source ?? undefined, context: getFimoSourceContext(value) });
         }
     }
     return FimoString.compose(parts);

package/dist/runtime/shared/local-runtime-env.d.ts

@@ -31,8 +31,8 @@ export interface LocalProjectLink {
 }
 /**
  * Derive the local runtime env, or `null` when this directory is not a linked
- * Fimo project (or the link predates `tenantApiBaseUrl` — nothing safe to
- * derive, so nothing is).
+ * Fimo project, Git cannot name the current Branch, or the link predates
+ * `tenantApiBaseUrl`.
  */
 export declare function resolveLocalRuntimeEnv(options: {
     readonly cwd: string;

package/dist/runtime/shared/local-runtime-env.js

@@ -19,11 +19,11 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { CURRENT_PROJECT_LAYOUT, LEGACY_PROJECT_LAYOUT } from '../project-layout.js';
-import { DEFAULT_BRANCH, LOCAL_CONTENT_API_ENV_KEYS, buildLocalRuntimeEnv, buildTenantApiUrl, isValidBranch, } from './branch-identity.js';
+import { LOCAL_CONTENT_API_ENV_KEYS, buildLocalRuntimeEnv, buildTenantApiUrl, isValidBranch, } from './branch-identity.js';
 /**
  * Derive the local runtime env, or `null` when this directory is not a linked
- * Fimo project (or the link predates `tenantApiBaseUrl` — nothing safe to
- * derive, so nothing is).
+ * Fimo project, Git cannot name the current Branch, or the link predates
+ * `tenantApiBaseUrl`.
  */
 export function resolveLocalRuntimeEnv(options) {
     const root = findProjectRoot(options.cwd);
@@ -31,15 +31,17 @@ export function resolveLocalRuntimeEnv(options) {
     if (!root || !link) {
         return null;
     }
-    const gitBranch = currentBranch(root);
-    const branch = gitBranch ?? DEFAULT_BRANCH;
+    const branch = currentBranch(root);
+    if (!branch) {
+        return null;
+    }
     const tenantApiUrl = buildTenantApiUrl(link.projectId, branch, link.tenantApiBaseUrl);
     return {
         // `env` stays the field name: `resolveLocalRuntimeEnv` is a published
         // `fimo/config` export that framework adapters destructure.
         env: branch,
         tenantApiUrl,
-        source: gitBranch ? 'branch' : 'fallback',
+        source: 'branch',
         values: buildLocalRuntimeEnv({ tenantApiUrl, branch }),
         link,
     };
@@ -125,12 +127,12 @@ export function readLocalEnvFiles(cwd) {
  */
 function currentBranch(root) {
     try {
-        const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        const branch = execFileSync('git', ['symbolic-ref', '--short', '-q', 'HEAD'], {
             cwd: root,
             stdio: ['ignore', 'pipe', 'ignore'],
             encoding: 'utf-8',
         }).trim();
-        return branch && branch !== 'HEAD' && isValidBranch(branch) ? branch : null;
+        return branch && isValidBranch(branch) ? branch : null;
     }
     catch {
         return null;
@@ -162,7 +164,10 @@ function readProjectLink(root) {
                 parsed.projectId.length > 0 &&
                 typeof parsed.tenantApiBaseUrl === 'string' &&
                 parsed.tenantApiBaseUrl.length > 0) {
-                return { projectId: parsed.projectId, tenantApiBaseUrl: parsed.tenantApiBaseUrl };
+                return {
+                    projectId: parsed.projectId,
+                    tenantApiBaseUrl: parsed.tenantApiBaseUrl,
+                };
             }
         }
         catch {

package/dist/runtime/templates.d.ts

@@ -12,6 +12,7 @@ export declare const DEFAULT_TEMPLATE: TemplateFramework;
  * out of `dist`) to reach the package root, then into `templates/<framework>`.
  */
 export declare function getTemplatePath(framework?: TemplateFramework): string;
+export declare function getWelcomeTemplatePath(): string;
 /**
  * Absolute path to the legacy template at `apps/api/templates/default/`.
  *
@@ -30,7 +31,9 @@ export declare function getTemplatePath(framework?: TemplateFramework): string;
  */
 export declare function getLegacyTemplateDir(): string;
 export interface ReleaseMeta {
-    source: 'npm' | 'dev' | null;
+    source: 'npm' | 'url' | 'dev' | null;
+    /** Immutable artifact URL, baked into `source: 'url'` development tarballs. */
+    url?: string | null;
 }
 export interface DevReleaseVersion {
     devJsonPath: string | null;
@@ -40,7 +43,11 @@ export declare function readReleaseMeta(): ReleaseMeta;
 export declare function readCliSemver(): string | null;
 /**
  * Pure version: given a release manifest + CLI semver, return the value
- * to pin `fimo` to (or null for dev). Exported for unit tests.
+ * to pin `fimo` to (or null when nothing is known). Exported for unit tests.
+ *
+ * Throws rather than returning an unreproducible pin: a project that records a
+ * package-manager cache path (or a `fimo` its companions cannot follow) is
+ * broken on every other machine, and the error names the missing publish step.
  */
 export declare function computeFimoPin(meta: ReleaseMeta, semver: string | null, options?: {
     devPackageRoot?: string | null;

package/dist/runtime/templates.js

@@ -42,6 +42,9 @@ export const DEFAULT_TEMPLATE = 'nextjs';
 export function getTemplatePath(framework = DEFAULT_TEMPLATE) {
     return path.resolve(PACKAGE_ROOT, 'templates', framework);
 }
+export function getWelcomeTemplatePath() {
+    return path.resolve(PACKAGE_ROOT, 'templates', 'welcome');
+}
 /**
  * Absolute path to the legacy template at `apps/api/templates/default/`.
  *
@@ -69,8 +72,8 @@ export function readReleaseMeta() {
     try {
         const raw = fs.readFileSync(RELEASE_FILE, 'utf8');
         const parsed = JSON.parse(raw);
-        const source = parsed.source === 'npm' || parsed.source === 'dev' ? parsed.source : null;
-        return { source };
+        const source = parsed.source === 'npm' || parsed.source === 'dev' || parsed.source === 'url' ? parsed.source : null;
+        return { source, url: typeof parsed.url === 'string' && parsed.url.length > 0 ? parsed.url : null };
     }
     catch {
         return { source: null };
@@ -91,16 +94,34 @@ export function readCliSemver() {
 }
 /**
  * Pure version: given a release manifest + CLI semver, return the value
- * to pin `fimo` to (or null for dev). Exported for unit tests.
+ * to pin `fimo` to (or null when nothing is known). Exported for unit tests.
+ *
+ * Throws rather than returning an unreproducible pin: a project that records a
+ * package-manager cache path (or a `fimo` its companions cannot follow) is
+ * broken on every other machine, and the error names the missing publish step.
  */
 export function computeFimoPin(meta, semver, options = {}) {
     if (meta.source === 'npm') {
-        if (semver) {
-            return semver;
+        return semver;
+    }
+    // A checkout wins over a baked artifact URL: `publish-cli --id` keeps its
+    // release.json in the workspace so the next local run still iterates on
+    // source, not on the tarball it just uploaded.
+    const localPin = options.devPackageRoot ? `file:${options.devPackageRoot}` : null;
+    if (localPin && pinsWholeGroup(localPin)) {
+        return localPin;
+    }
+    if (meta.source === 'url') {
+        if (!meta.url) {
+            throw new Error('Refusing to create a project from a development CLI that was published without a public artifact URL. ' +
+                'Republish it remotely with `pnpm -F fimo publish-cli -- --id <task-name>` and install that artifact.');
         }
+        return meta.url;
     }
-    if ((meta.source === 'dev' || meta.source === null) && options.devPackageRoot) {
-        return `file:${options.devPackageRoot}`;
+    if (localPin) {
+        throw new Error(`Refusing to create a project pinned to ${localPin}: that path is not a Fimo checkout, so it is neither ` +
+            'reproducible on another machine nor able to pin the matching companion packages. Install `fimo` from npm, ' +
+            'or publish this CLI with `pnpm -F fimo publish-cli -- --id <task-name>` and install that artifact.');
     }
     return null;
 }
@@ -233,6 +254,14 @@ export function deriveFimoPackagePin(name, fimoPin) {
     }
     return fimoPin;
 }
+/**
+ * Whether every Fimo package can be pinned from this `fimo` pin. A pin that
+ * only the CLI can follow leaves the companions on the template's `latest`,
+ * which silently mixes channels inside one project (FIMO-2070).
+ */
+function pinsWholeGroup(fimoPin) {
+    return FIMO_PACKAGES.every((name) => deriveFimoPackagePin(name, fimoPin) !== null);
+}
 /**
  * Rewrite `fimo` and any companion packages present (in dependencies +
  * devDependencies) to the current pin. Only touches entries that look like a

package/dist/scripts/validate-schemas.js

@@ -271,23 +271,18 @@ export function validateSchemaFile(absolutePath, file, schemaUids = new Set()) {
                         file,
                     });
                 }
-                if (!insideStructuredContent || field.type !== 'reference') {
+                if (!insideStructuredContent || field.type !== 'reference' || schemaUids.size === 0) {
                     return;
                 }
-                if (field.targets) {
-                    errors.push({
-                        rule: 'schemas/structured-content-reference',
-                        message: `Reference field "${path.join('.')}" must use one fixed "target" inside blocks.`,
-                        file,
-                    });
-                    return;
-                }
-                if (field.target && schemaUids.size > 0 && !schemaUids.has(field.target)) {
-                    errors.push({
-                        rule: 'schemas/reference-target',
-                        message: `Reference field "${path.join('.')}" targets unknown schema "${field.target}".`,
-                        file,
-                    });
+                const referenceTargets = Array.isArray(field.targets) ? field.targets : field.target ? [field.target] : [];
+                for (const target of referenceTargets) {
+                    if (!schemaUids.has(target)) {
+                        errors.push({
+                            rule: 'schemas/reference-target',
+                            message: `Reference field "${path.join('.')}" targets unknown schema "${target}".`,
+                            file,
+                        });
+                    }
                 }
             });
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "2.2.0-staging.8",
+  "version": "2.2.0",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "keywords": [
     "astro-component"
@@ -176,6 +176,7 @@
     "test:integration:frameworks": "vitest run --config vitest.integration.config.ts",
     "test:integration:next": "vitest run --config vitest.integration.config.ts test/integration/next-runtime.test.ts",
     "test:integration:sveltekit": "vitest run --config vitest.integration.config.ts test/integration/sveltekit-runtime.test.ts",
+    "test:package-manager-compat": "pnpm --workspace-root run build --filter=fimo && node test/package-manager-compat/run.mjs",
     "test:watch": "vitest",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
@@ -183,17 +184,18 @@
     "change-case": "^5.4.4",
     "eta": "^3.5.0",
     "oxc-parser": "^0.118.0",
-    "zod": "4.4.3"
+    "zod": "4.5.2"
   },
   "devDependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
-    "@fimo/agents-bundle": "2.2.0-staging.8",
-    "@fimo/api-contracts": "2.2.0-staging.8",
-    "@fimo/cli-kit": "2.2.0-staging.8",
-    "@fimo/framework-detect": "2.2.0-staging.8",
-    "@fimo/routes": "2.2.0-staging.8",
-    "@fimo/tsconfig": "2.2.0-staging.8",
+    "@fimo/agents-bundle": "2.2.0",
+    "@fimo/api-contracts": "2.2.0",
+    "@fimo/cli-kit": "2.2.0",
+    "@fimo/framework-detect": "2.2.0",
+    "@fimo/routes": "2.2.0",
+    "@fimo/sdk": "2.2.0",
+    "@fimo/tsconfig": "2.2.0",
     "@types/node": "22.18.6",
     "agent-install": "^0.0.5",
     "astro": "^7.1.6",

package/release.json

@@ -1,5 +1,5 @@
 {
   "source": "npm",
-  "apiUrl": "https://api.staging.fimo.team",
-  "webUrl": "https://staging.fimo.team"
+  "apiUrl": "https://api.fimo.ai",
+  "webUrl": "https://fimo.ai"
 }

package/templates/astro/AGENTS.md

@@ -28,7 +28,7 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
 - Use the selected package manager's committed build-script policy. pnpm projects pin `pnpm@10.26.0` and approve `esbuild` and `fimo` through `pnpm-workspace.yaml#allowBuilds`; Bun projects trust the same packages through `package.json#trustedDependencies`. Run a plain install with the selected manager so local installation matches Preview and production publishing. Review new dependencies before extending the policy; all three paths stop on unreviewed scripts.
-- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`. If no language is requested, keep `en` and state that choice. Astro reads this configuration directly, keeps the default locale unprefixed, and prefixes the others.
+- 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.

package/templates/astro/package.json

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

package/templates/nextjs/AGENTS.md

@@ -36,11 +36,11 @@ The scaffolded homepage is disposable. Replace it on the first real generation.
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
 - Use the selected package manager's committed build-script policy. pnpm projects pin `pnpm@10.26.0` and approve `esbuild` and `fimo` through `pnpm-workspace.yaml#allowBuilds`; Bun projects trust the same packages through `package.json#trustedDependencies`. Run a plain install with the selected manager so local installation matches Preview and production publishing. Review new dependencies before extending the policy; all three paths stop on unreviewed scripts.
-- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`, with every requested locale in `i18n.locales`. If no language is requested, keep `en` and state that choice. That file is the only place to change: `src/locales.ts` reads it, so the served language and `<html lang>` follow. It does not create locale URLs; implement a URL strategy only when the product asks for one. Never introduce a default-locale environment variable.
+- 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. `src/locales.ts` reads the synchronized config, so the served language and `<html lang>` follow. Locale configuration does not create locale URLs; implement a URL strategy only when the product asks for one. Never introduce a default-locale environment variable.
 - 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 SEO. Fimo connects to those decisions.
+- 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.
 - 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`.

package/templates/nextjs/package.json

@@ -12,9 +12,9 @@
   },
   "dependencies": {
     "@tanstack/react-query": "^5.80.6",
-    "fimo": "2.2.0-staging.8",
-    "fimo-next": "2.2.0-staging.8",
-    "fimo-react": "2.2.0-staging.8",
+    "fimo": "2.2.0",
+    "fimo-next": "2.2.0",
+    "fimo-react": "2.2.0",
     "next": "^16.3.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"

package/templates/nextjs/src/app/layout.tsx

@@ -1,10 +1,13 @@
-import { FimoProvider } from 'fimo-next';
+import { FimoProvider, buildFimoMetadata, buildFimoViewport } from 'fimo-next';
 import type { ReactNode } from 'react';
 
 import { defaultLocale } from '../locales';
 
 import './globals.css';
 
+export const generateMetadata = () => buildFimoMetadata();
+export const generateViewport = () => buildFimoViewport();
+
 export default function RootLayout({ children }: Readonly<{ children: ReactNode }>) {
   return (
     <html lang={defaultLocale}>

package/templates/react-router/AGENTS.md

@@ -41,8 +41,8 @@ breaks that. Load `fimo-code` for the exact primitives, but the rule is:
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
 - Use the selected package manager's committed build-script policy. pnpm projects pin `pnpm@10.26.0` and approve `esbuild` and `fimo` through `pnpm-workspace.yaml#allowBuilds`; Bun projects trust the same packages through `package.json#trustedDependencies`. Run a plain install with the selected manager so local installation matches Preview and production publishing. Review new dependencies before extending the policy; all three paths stop on unreviewed scripts.
-- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`. If no language is requested, keep `en` and state that choice.
-- Preserve the application-owned `:locale?` route boundary in `src/routes.ts` and pass its route parameter to `FimoProviders` in `LocaleLayout.tsx`. The missing parameter uses the configured default, so a one-locale site stays at `/`. Add locales in `.fimo/config.json` without rebuilding the route tree; use `:locale` without `?` only when every locale must be prefixed.
+- 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.
+- Preserve the application-owned `:locale?` route boundary in `src/routes.ts` and pass its route parameter to `FimoProviders` in `LocaleLayout.tsx`. The missing parameter uses the configured default, so a one-locale site stays at `/`. Configured locales use the same route tree; use `:locale` without `?` only when every locale must be prefixed.
 - Keep `.fimo/config.json#routes` aligned as Studio metadata, not as the React Router source of truth. Do not add a global locale-routing strategy, a Fimo route helper, or a Fimo-owned route tree.
 - Do not add a second deploy tool (Vercel, Netlify, etc.).
 - **Never edit `.fimo/project.json`** — it links this folder to the remote project.

package/templates/react-router/package.json

@@ -21,10 +21,10 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "2.2.0-staging.8",
-    "fimo-react": "2.2.0-staging.8",
-    "fimo-react-router": "2.2.0-staging.8",
-    "fimo-vite": "2.2.0-staging.8",
+    "fimo": "2.2.0",
+    "fimo-react": "2.2.0",
+    "fimo-react-router": "2.2.0",
+    "fimo-vite": "2.2.0",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",

package/templates/sveltekit/AGENTS.md

@@ -28,7 +28,7 @@ a code-only task, or use `npx fimo@latest` for project-local code generation and
 
 - **Deploy is on-demand**, not a save step. Batch related edits into one deploy.
 - Use the selected package manager's committed build-script policy. pnpm projects pin `pnpm@10.26.0` and approve `esbuild` and `fimo` through `pnpm-workspace.yaml#allowBuilds`; Bun projects trust the same packages through `package.json#trustedDependencies`. Run a plain install with the selected manager so local installation matches Preview and production publishing. Review new dependencies before extending the policy; all three paths stop on unreviewed scripts.
-- Treat the user's language request as part of setup. The first explicitly requested locale is the primary locale; put it first and set it as `i18n.defaultLocale` in `.fimo/config.json`. If no language is requested, keep `en` and state that choice. `src/locales.ts` derives the default and prefixed locale set from that config.
+- 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. `src/locales.ts` derives the default and prefixed locale set from the synchronized config.
 - Preserve the native `[[locale=locale]]` route boundary. The optional parameter keeps the default locale at `/`; the matcher prevents ordinary top-level routes from being mistaken for locales. The root server layout passes the tracked `event.params` through `resolveLocale`, then sends that locale to `getLabels` and `FimoProvider`. Remove the extra brackets only when every locale must be prefixed.
 - Keep the document language request-aware: `src/hooks.server.ts` renders the initial `<html lang>`, and the root layout updates it after client navigation.
 - Keep `.fimo/config.json#routes` as Studio metadata aligned with SvelteKit's route files. It does not configure SvelteKit routing.

package/templates/sveltekit/package.json

@@ -11,8 +11,8 @@
     "prepare": "svelte-kit sync"
   },
   "dependencies": {
-    "fimo": "2.2.0-staging.8",
-    "fimo-sveltekit": "2.2.0-staging.8"
+    "fimo": "2.2.0",
+    "fimo-sveltekit": "2.2.0"
   },
   "devDependencies": {
     "@sveltejs/kit": "^2.70.2",