@funnelsgrove/cli 0.1.229 → 0.1.233

package/README.md

@@ -150,3 +150,12 @@ rows changed since the last pull. Pull again to resolve a concurrent edit.
 
 Use `--api-url` or `FUNNELSGROVE_API_URL` for non-production APIs.
 Use `--config` or `FUNNELSGROVE_CONFIG` to keep test credentials separate from the default `~/.funnelsgrove/config.json`.
+
+### Add a content locale
+
+Run `fgrove locales add ru --dir ./my-funnel` to copy every default content
+object into the new locale without translation. Existing translations are kept.
+Translate the new entries, review `?locale=ru` and the live builder Preview language
+selector, then sync and publish through the normal workflow. Run `fgrove docs`
+for the full localization guide. The funnel must use a runtime release supporting
+URL locale selection; this command does not upgrade dependencies.

package/dist/cli.js

@@ -7,6 +7,7 @@ import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
+import { addFunnelLocale } from './locales.js';
 import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, PREVIOUS_STEP_CONTRACT_VERSION, createFunnelContractDiagnostic, } from '@funnelsgrove/runtime';
 import { abortFunnelSourceCandidate, applyFunnelDraftPatch, beginFunnelSourceCandidate, callTrpcProcedure, createFunnelExperimentFromSpec, finalizeFunnelDirectAssetUpload, finalizeFunnelSourceCandidate, prepareFunnelDirectAssetUpload, stageFunnelSourceCandidate, } from './apiClient.js';
 import { cliReleaseIdentity } from './cliIdentity.js';
@@ -2980,6 +2981,15 @@ addExamples(githubCommand
     });
     printValueRows(formatGitHubJobRows(result));
 });
+program.command('locales')
+    .description('Manage local funnel content languages')
+    .command('add <locale>')
+    .description('Copy default content into a locale without translating or overwriting existing entries')
+    .option('--dir <path>', 'Local funnel directory', '.')
+    .action(async (locale, options) => {
+    const result = await addFunnelLocale(path.resolve(options.dir), locale);
+    console.log(`${result.locale}\t${result.added.length} added\t${result.existing.length} already present`);
+});
 addExamples(program
     .command('validate')
     .description('Validate a local funnel against the current authoring contract')

package/dist/locales.d.ts

@@ -0,0 +1,6 @@
+/** Prepare every edit before writing so unsupported content cannot leave a partly added locale. */
+export declare function addFunnelLocale(directory: string, requestedLocale: string): Promise<{
+    locale: string;
+    added: string[];
+    existing: string[];
+}>;

package/dist/locales.js

@@ -0,0 +1,126 @@
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import ts from 'typescript';
+function canonicalLocale(value) {
+    try {
+        const [locale] = Intl.getCanonicalLocales(value);
+        if (locale)
+            return locale;
+    }
+    catch { /* Report the invalid input below. */ }
+    throw new Error(`Invalid locale: ${value}. Use a language tag such as ru or pt-BR.`);
+}
+async function contentFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...await contentFiles(file));
+        else if (entry.isFile() && entry.name.endsWith('.content.ts'))
+            files.push(file);
+    }
+    return files;
+}
+function property(object, name) {
+    return object.properties.find((node) => ts.isPropertyAssignment(node) &&
+        (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) && node.name.text === name);
+}
+function copyLocaleContent(content, parsed, locale) {
+    const localDefinitions = new Map();
+    for (const statement of parsed.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            let value = declaration.initializer;
+            while (value && (ts.isAsExpression(value) || ts.isSatisfiesExpression(value) || ts.isParenthesizedExpression(value)))
+                value = value.expression;
+            if (!value || !ts.isObjectLiteralExpression(value) || !ts.isIdentifier(declaration.name))
+                continue;
+            const defaultLocale = property(value, 'defaultLocale')?.initializer;
+            if (defaultLocale && ts.isStringLiteral(defaultLocale) && property(value, 'locales')) {
+                localDefinitions.set(declaration.name.text, defaultLocale.text);
+            }
+        }
+    }
+    const replacements = [];
+    const visit = (node) => {
+        const key = ts.isPropertyAccessExpression(node) ? node.name.text
+            : ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text : null;
+        if (key && (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node))) {
+            const map = node.expression;
+            if (ts.isPropertyAccessExpression(map) && map.name.text === 'locales' && ts.isIdentifier(map.expression)
+                && localDefinitions.get(map.expression.text) === key) {
+                replacements.push({ start: node.getStart(parsed), end: node.end, text: `${map.getText(parsed)}[${JSON.stringify(locale)}]` });
+                return;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(content);
+    const offset = content.getStart(parsed);
+    let source = content.getText(parsed);
+    for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+        source = source.slice(0, replacement.start - offset) + replacement.text + source.slice(replacement.end - offset);
+    }
+    return source;
+}
+/** Prepare every edit before writing so unsupported content cannot leave a partly added locale. */
+export async function addFunnelLocale(directory, requestedLocale) {
+    const locale = canonicalLocale(requestedLocale);
+    const edits = [];
+    const existing = [];
+    const files = await contentFiles(path.join(directory, 'src'));
+    if (!files.length)
+        throw new Error('No src/**/*.content.ts files found. Move translatable copy into content definitions first.');
+    for (const file of files) {
+        const source = await readFile(file, 'utf8');
+        const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const relative = path.relative(directory, file).split(path.sep).join('/');
+        const insertions = [];
+        let definitions = 0;
+        const visit = (node) => {
+            if (ts.isObjectLiteralExpression(node)) {
+                const defaultLocale = property(node, 'defaultLocale');
+                const locales = property(node, 'locales');
+                if (defaultLocale && locales) {
+                    definitions++;
+                    if (!ts.isStringLiteral(defaultLocale.initializer) || !ts.isObjectLiteralExpression(locales.initializer)) {
+                        throw new Error(`${relative}: defaultLocale and locales must be literals.`);
+                    }
+                    const map = locales.initializer;
+                    if (map.properties.some((item) => !ts.isPropertyAssignment(item) ||
+                        !(ts.isIdentifier(item.name) || ts.isStringLiteral(item.name)))) {
+                        throw new Error(`${relative}: locale entries must be explicit properties, without spreads or computed names.`);
+                    }
+                    const keys = map.properties;
+                    if (keys.some((item) => canonicalLocale(item.name.text) === locale))
+                        return;
+                    const base = property(map, defaultLocale.initializer.text);
+                    if (!base || !ts.isObjectLiteralExpression(base.initializer)) {
+                        throw new Error(`${relative}: default locale content must be an object literal.`);
+                    }
+                    const separator = map.properties.hasTrailingComma ? '' : ',';
+                    insertions.push({ offset: map.end - 1, text: `${separator}\n    ${JSON.stringify(locale)}: ${copyLocaleContent(base.initializer, parsed, locale)},\n  ` });
+                    return;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(parsed);
+        if (!definitions)
+            throw new Error(`${relative}: no localized content definition found.`);
+        if (!insertions.length)
+            existing.push(relative);
+        else {
+            let nextSource = source;
+            for (const insertion of insertions.sort((a, b) => b.offset - a.offset)) {
+                nextSource = nextSource.slice(0, insertion.offset) + insertion.text + nextSource.slice(insertion.offset);
+            }
+            edits.push({ file, source: nextSource });
+        }
+    }
+    for (const edit of edits)
+        await writeFile(edit.file, edit.source);
+    return { locale, added: edits.map(({ file }) => path.relative(directory, file).split(path.sep).join('/')), existing };
+}

package/funnel-contract-compatibility.json

@@ -4,16 +4,16 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.229",
+      "repositoryCliVersion": "0.1.233",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.221",
+        "bundleVersion": "2.0.225",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "22118f0f909a747f8a27f4eed16ceb5ec2a9283fd9645114fda961c0405a2a6b"
+            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
           },
           {
             "path": "CLAUDE.md",
@@ -29,7 +29,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+            "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "d86fab03c5a3bb31b2b62302a4fba47422c7f39d049decf4604b052cd55ae363"
+            "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,22 +145,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "d59565cd958ed65a1794437e1c69ba5b1d2a0d4465b30e52073374caf0130095"
+            "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.228",
+      "repositoryCliVersion": "0.1.232",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.220",
+        "bundleVersion": "2.0.224",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "22118f0f909a747f8a27f4eed16ceb5ec2a9283fd9645114fda961c0405a2a6b"
+            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
           },
           {
             "path": "CLAUDE.md",
@@ -176,7 +176,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+            "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "16343b066ffd8a56f9490f8c54ec724528166d41b812665565dca507aa4a65b1"
+            "sha256": "cd4e0392bc88e2c24459a5132b8c7573bdb3e5a01aa7d9684139c30de39e4813"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "9f2ca1c4b99902f065c3588df9662403708ae732388668200141cfd95cdd6282"
+            "sha256": "fd3117529acd5a83faf9ffb7bc004d5c1166ba783bcc57c2457ffc5e83c936f4"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.227",
+      "repositoryCliVersion": "0.1.231",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.219",
+        "bundleVersion": "2.0.223",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "3456a7f44a9b1e76adba665588a13a65e923e64bfa599199067196031731799e"
+            "sha256": "b77101d16260357a891c26a6f0e6298f5763b3a8d76b38ba94378064a753e9f0"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "b40f461f4d0ee96592a9d2de99cef14c8eb809b6e315d7524e9ef89c217f04e7"
+            "sha256": "e111086760618c659a1f72b0e463bf2aa4c67ba9ebc1b4728c84e0d6b20b6510"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.226",
+      "repositoryCliVersion": "0.1.230",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.218",
+        "bundleVersion": "2.0.222",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "57c5cd1d7d6cf333738d71eec5b9ec16ff28b69aae9619c38c16a804e1c19a2f"
+            "sha256": "1447228902ae180df9db9a7b3778558bd1e2837ba63b20d66207b83cfd36772b"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "b9c1bf3bb96fbc188469c2670db166c06714a8a5037cc3f137791e1229dc0a36"
+            "sha256": "eac90701cb7c2ae42d90b23f8cd7d7f7b3abd5b64b09a754fa4e61af910cd334"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.225",
+      "repositoryCliVersion": "0.1.229",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.217",
+        "bundleVersion": "2.0.221",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "90fd6a334c715f4a3623cba69fef89bec33e8c77d41a66b2b56145a5a67f0a77"
+            "sha256": "d86fab03c5a3bb31b2b62302a4fba47422c7f39d049decf4604b052cd55ae363"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "1b7c8003831619dc7bec1e63523783fc65306eb3cca721bd006aaa6575fe5e34"
+            "sha256": "d59565cd958ed65a1794437e1c69ba5b1d2a0d4465b30e52073374caf0130095"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.223",
+      "repositoryCliVersion": "0.1.228",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.215",
+        "bundleVersion": "2.0.220",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "ce781cf22929d6e1ff1c74c04d12ad9c2be06e1b1171e62da09ec7b277d3867f"
+            "sha256": "16343b066ffd8a56f9490f8c54ec724528166d41b812665565dca507aa4a65b1"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "2a8e04f9a0e36ea5248dbade1259f8328bbea8e67c7a7e7d33ef1ff9094809fb"
+            "sha256": "9f2ca1c4b99902f065c3588df9662403708ae732388668200141cfd95cdd6282"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.222",
+      "repositoryCliVersion": "0.1.227",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.214",
+        "bundleVersion": "2.0.219",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "a0575e85660e8b1d5b51e1527740e02c267fb4b632aa10d9f17fa83324a8ccf7"
+            "sha256": "3456a7f44a9b1e76adba665588a13a65e923e64bfa599199067196031731799e"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "f7ed68bd91966f1fc77fab35315eff8f04987d4d2f841319722cd4f720e458ef"
+            "sha256": "b40f461f4d0ee96592a9d2de99cef14c8eb809b6e315d7524e9ef89c217f04e7"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.229",
+  "version": "0.1.233",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",
@@ -34,14 +34,14 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@funnelsgrove/runtime": "0.12.0",
+    "@funnelsgrove/runtime": "0.14.4",
     "commander": "^12.0.0",
     "ignore": "^7.0.8",
     "typescript": "^5.8.3"
   },
   "devDependencies": {
-    "@funnelsgrove/analytics": "0.1.97",
-    "@funnelsgrove/payments": "0.12.0",
+    "@funnelsgrove/analytics": "0.1.106",
+    "@funnelsgrove/payments": "0.15.11",
     "vitest": "^3.0.0"
   }
 }

package/template_docs/.funnelsgrove-docs.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.221",
+  "bundleVersion": "2.0.225",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
     {
       "path": "AGENTS.md",
-      "sha256": "22118f0f909a747f8a27f4eed16ceb5ec2a9283fd9645114fda961c0405a2a6b"
+      "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
     },
     {
       "path": "CLAUDE.md",
@@ -22,7 +22,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/content-answers.md",
-      "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+      "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
     },
     {
       "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "d86fab03c5a3bb31b2b62302a4fba47422c7f39d049decf4604b052cd55ae363"
+      "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "d59565cd958ed65a1794437e1c69ba5b1d2a0d4465b30e52073374caf0130095"
+      "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54"
     }
   ]
 }

package/template_docs/AGENTS.md

@@ -9,6 +9,7 @@ This file is generated from the FunnelsGrove step contract. Start at [the agent
 | Add a step | [Add a step](docs/funnelsgrove/recipes/add-step.md) |
 | Edit a step | [Edit a step](docs/funnelsgrove/recipes/edit-step.md) |
 | Change metadata or routing | [Step metadata](docs/funnelsgrove/contracts/step-metadata.md) and [flow routing](docs/funnelsgrove/contracts/flow-routing.md) |
+| Add a locale or translate visitor copy | [Localization](docs/funnelsgrove/contracts/content-answers.md#localization) |
 | Add or edit choices | [Content and answers](docs/funnelsgrove/contracts/content-answers.md) |
 | Edit product strategy, plan, or copy | [Content and answers](docs/funnelsgrove/contracts/content-answers.md) |
 | Add an experiment | [Add an experiment](docs/funnelsgrove/recipes/add-experiment.md) |

package/template_docs/docs/funnelsgrove/contracts/content-answers.md

@@ -42,3 +42,53 @@ Keep builder-editable values in content definitions, expose matching editor sect
 - Update the owning artifact in the same change. Never implement a step absent from `PLAN.md`.
 
 See the exact choice and form pages in the [step-type index](../steps/INDEX.md). Run `fgrove validate` and test reload persistence before completion.
+
+## Localization
+
+All funnel-authored visitor copy belongs in `src/**/*.content.ts` localized
+content definitions: headings, options, CTA labels, placeholders, validation and
+error messages, loading/empty states, accessible labels, shared shell copy, and
+paywall/legal copy. JSX renders resolved content; metadata IDs, answer keys,
+provider IDs, prices and billing rules retain their existing owners. Provider-hosted
+payment fields and messages are configured through that provider's locale support.
+
+1. Run `fgrove locales add ru --dir .` to copy each definition's `defaultLocale`
+   into `locales.ru`. Use BCP 47 tags such as `pt-BR`. The command edits local source
+   only, requires no login, and never translates, syncs or publishes. Repeating it
+   keeps existing translations and fills only missing locale entries.
+2. Translate the new entries in **every** content module, including shared shell
+   and returning-subscriber content. Preserve object keys, option IDs, placeholders
+   such as `{amount}`, URLs and variable tokens. Same-file references to another
+   definition's base locale are copied as references to its new locale. Imported
+   content and other expressions remain references: inspect them and move any
+   remaining visitor copy into locale-owned definitions before completion.
+3. Keep `defaultLocale` and `locales` as explicit literal properties. Locale maps
+   use explicit keys; CLI rejects dynamic maps, spreads at the locale-map level,
+   and non-object base content before writing files. Nested content may contain
+   expressions. A new step must include every supported funnel locale.
+4. Resolve step copy with `usePreviewStepLocalizedContent(stepId, definition,
+   getStepContentLocale(attributes))`. Runtime versions supporting localization
+   give `?locale=ru` priority; otherwise the requested/browser language applies.
+   Lookup uses exact match, base language (`pt-BR` → `pt`), then `defaultLocale`.
+   The override persists in step URLs and never changes country, currency or offers.
+5. Review each language with `?locale=ru`, including direct step links, reload,
+   next/back, validation errors, long text and checkout. Builder **Preview language**
+   selects languages announced by its live frame and carries the choice into the
+   external preview link. Static screenshots cannot switch language. Older
+   published runtimes need an SDK update and republish before exposing this control.
+6. Run `fgrove validate`, sync through the funnel's normal CLI/GitHub workflow,
+   then publish preview. Existing funnels keep their own source and package pins;
+   adding a locale does not upgrade their SDK or migrate hard-coded JSX. Update
+   those explicitly and review the diff. Refresh this managed guide with `fgrove docs`.
+
+New funnel code must route shell buttons and custom action-bar text through
+content too. `src/steps/content/runtime.content.ts` owns the starter's shared
+Continue/loading/unavailable messages. Server-returned display labels need
+locale-owned presentation overrides; changing copy must not change plan IDs,
+amounts, billing intervals or provider configuration.
+
+The starter paywall's `catalogLabels` maps exact catalog display text to localized
+text. Keep its keys unchanged and translate the values, preserving monetary
+amounts. Add mappings for new admin-authored labels as needed. Unrecognized
+catalog labels remain unchanged; translation never substitutes one offer for
+another or alters payment identifiers and amounts.

package/template_docs/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/runtime` `0.14.2` first, then `@funnelsgrove/analytics` `0.1.104`, then `@funnelsgrove/payments` `0.15.8`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.229`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/runtime` `0.14.4` first, then `@funnelsgrove/analytics` `0.1.106`, then `@funnelsgrove/payments` `0.15.11`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.233`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_docs/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.221",
+  "bundleVersion": "2.0.225",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/.funnelsgrove-docs.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.221",
+  "bundleVersion": "2.0.225",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
     {
       "path": "AGENTS.md",
-      "sha256": "22118f0f909a747f8a27f4eed16ceb5ec2a9283fd9645114fda961c0405a2a6b"
+      "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
     },
     {
       "path": "CLAUDE.md",
@@ -22,7 +22,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/content-answers.md",
-      "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+      "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
     },
     {
       "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "d86fab03c5a3bb31b2b62302a4fba47422c7f39d049decf4604b052cd55ae363"
+      "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "d59565cd958ed65a1794437e1c69ba5b1d2a0d4465b30e52073374caf0130095"
+      "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54"
     }
   ]
 }