@funnelsgrove/cli 0.1.233 → 0.1.237

package/README.md

@@ -154,8 +154,10 @@ Use `--config` or `FUNNELSGROVE_CONFIG` to keep test credentials separate from t
 ### 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
+object into `src/localization/ru/`, preserving its path relative to `src/`.
+Original content stays in place; translated files import its structural type.
+Repeat runs preserve translations, add missing exports and repair registrations.
+Translate the new content, run `npx tsc --noEmit`, 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

@@ -2984,7 +2984,7 @@ addExamples(githubCommand
 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')
+    .description('Create or complete typed localization files without translating')
     .option('--dir <path>', 'Local funnel directory', '.')
     .action(async (locale, options) => {
     const result = await addFunnelLocale(path.resolve(options.dir), locale);

package/dist/localeContentSource.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+export declare const modulePath: (from: string, to: string) => string;
+export declare function property(object: ts.ObjectLiteralExpression, name: string): ts.PropertyAssignment | undefined;
+export type ContentDefinition = {
+    name: string;
+    type: string;
+    defaultLocale: string;
+    map: ts.ObjectLiteralExpression;
+};
+export declare function readContentDefinitions(parsed: ts.SourceFile): ContentDefinition[];
+/** Copies authored expressions, redirecting same-file inheritance to the translated export. */
+export declare function translatedExpression(value: ts.Expression, parsed: ts.SourceFile, definitions: ContentDefinition[], locale: string, existingBindings?: ReadonlyMap<string, string | null>): string;
+export declare function contentImports(parsed: ts.SourceFile, destination: string, payload: string): string[];

package/dist/localeContentSource.js

@@ -0,0 +1,117 @@
+import path from 'node:path';
+import ts from 'typescript';
+import { selectImport } from './localeModuleEdits.js';
+export const modulePath = (from, to) => {
+    const relative = path.relative(path.dirname(from), to).split(path.sep).join('/').replace(/\.ts$/, '');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+};
+export function property(object, name) {
+    return object.properties.find((node) => ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) && node.name.text === name);
+}
+export function readContentDefinitions(parsed) {
+    const definitions = [];
+    for (const statement of parsed.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            let expression = declaration.initializer;
+            let type = declaration.type;
+            while (expression && (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression) || ts.isParenthesizedExpression(expression))) {
+                if (!ts.isParenthesizedExpression(expression) && ts.isTypeReferenceNode(expression.type) && expression.type.typeArguments?.length)
+                    type = expression.type;
+                expression = expression.expression;
+            }
+            if (!expression || !ts.isObjectLiteralExpression(expression))
+                continue;
+            const base = property(expression, 'defaultLocale');
+            const locales = property(expression, 'locales');
+            if (!base || !locales)
+                continue;
+            if (!ts.isStringLiteral(base.initializer) || !ts.isObjectLiteralExpression(locales.initializer))
+                throw new Error('defaultLocale and locales must be literals.');
+            if (locales.initializer.properties.some((item) => !ts.isPropertyAssignment(item) || !(ts.isIdentifier(item.name) || ts.isStringLiteral(item.name))))
+                throw new Error('locale entries must be explicit properties, without spreads or computed names.');
+            const contentType = type && ts.isTypeReferenceNode(type) && type.typeArguments?.[0];
+            if (!ts.isIdentifier(declaration.name) || !contentType || !ts.isTypeReferenceNode(contentType) || !ts.isIdentifier(contentType.typeName))
+                throw new Error('Declare a named content type and use satisfies LocalizedStepContent<YourContentType>.');
+            if (contentType.typeArguments?.length)
+                throw new Error('Use a named non-generic content type; generic content types are not supported by locale copying.');
+            const typeName = contentType.typeName.text;
+            const owner = parsed.statements.find((item) => (ts.isTypeAliasDeclaration(item) || ts.isInterfaceDeclaration(item)) && item.name.text === typeName);
+            if (!owner)
+                throw new Error(`Declare ${typeName} in this original content file so translations can import its structure.`);
+            definitions.push({ name: declaration.name.text, type: typeName, defaultLocale: base.initializer.text, map: locales.initializer });
+        }
+    }
+    if (!definitions.length)
+        throw new Error('No localized content definition found.');
+    return definitions;
+}
+/** Copies authored expressions, redirecting same-file inheritance to the translated export. */
+export function translatedExpression(value, parsed, definitions, locale, existingBindings = new Map()) {
+    const edits = [];
+    const options = { noLib: true, noResolve: true };
+    const host = ts.createCompilerHost(options);
+    host.getSourceFile = (name) => path.resolve(name) === path.resolve(parsed.fileName) ? parsed : undefined;
+    const checker = ts.createProgram([parsed.fileName], options, host).getTypeChecker();
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+            const map = node.expression;
+            const key = ts.isPropertyAccessExpression(node) ? node.name.text : ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text : null;
+            if (ts.isPropertyAccessExpression(map) && map.name.text === 'locales' && ts.isIdentifier(map.expression)) {
+                const definition = definitions.find((item) => item.name === map.expression.getText(parsed));
+                if (definition && key) {
+                    if (key !== definition.defaultLocale && key !== locale) {
+                        throw new Error(`Cannot copy ${node.getText(parsed)}: inheritance must use the default or requested locale. Make this copy explicit before retrying.`);
+                    }
+                    const binding = existingBindings.get(definition.name);
+                    if (binding === null)
+                        throw new Error(`Import the re-exported ${definition.name} into the translation before adding inherited content.`);
+                    edits.push({ start: node.getStart(parsed), end: node.end, text: binding ?? definition.name });
+                    return;
+                }
+            }
+        }
+        if (ts.isIdentifier(node)
+            && !(ts.isPropertyAssignment(node.parent) && node.parent.name === node)
+            && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node)) {
+            const symbol = ts.isShorthandPropertyAssignment(node.parent)
+                ? checker.getShorthandAssignmentValueSymbol(node.parent)
+                : checker.getSymbolAtLocation(node);
+            const uncopied = symbol?.declarations?.some((declaration) => {
+                if (declaration.getSourceFile() !== parsed || declaration.pos >= value.pos && declaration.end <= value.end)
+                    return false;
+                let parent = declaration;
+                while (parent && parent !== parsed) {
+                    if (ts.isImportDeclaration(parent))
+                        return false;
+                    parent = parent.parent;
+                }
+                return true;
+            });
+            if (uncopied)
+                throw new Error(`Content references local helper ${node.text}. Inline it in the content object or move it into an independent imported module before adding a locale.`);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(value);
+    let result = value.getText(parsed);
+    const offset = value.getStart(parsed);
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+        result = result.slice(0, edit.start - offset) + edit.text + result.slice(edit.end - offset);
+    return result;
+}
+export function contentImports(parsed, destination, payload) {
+    const identifiers = new Set();
+    const visit = (node) => { if (ts.isIdentifier(node))
+        identifiers.add(node.text); ts.forEachChild(node, visit); };
+    visit(ts.createSourceFile('content.ts', payload, ts.ScriptTarget.Latest, true));
+    return parsed.statements.flatMap((statement) => {
+        if (!ts.isImportDeclaration(statement) || !statement.importClause || !ts.isStringLiteral(statement.moduleSpecifier))
+            return [];
+        const specifier = statement.moduleSpecifier.text;
+        const target = specifier.startsWith('.') ? modulePath(destination, path.resolve(path.dirname(parsed.fileName), specifier)) : specifier;
+        const selected = selectImport(statement, parsed, (name) => identifiers.has(name), ts.factory.createStringLiteral(target));
+        return selected ? [selected] : [];
+    });
+}

package/dist/localeFilePlan.d.ts

@@ -0,0 +1,4 @@
+export declare function planLocaleFile(file: string, source: string, destination: string, translated: string | null, locale: string): {
+    source: string;
+    translated: string | null;
+};

package/dist/localeFilePlan.js

@@ -0,0 +1,63 @@
+import ts from 'typescript';
+import { contentImports, modulePath, property, readContentDefinitions, translatedExpression } from './localeContentSource.js';
+import { appendTranslation, applySourceEdits, exportedBindings, importedNames, insertImports } from './localeModuleEdits.js';
+export function planLocaleFile(file, source, destination, translated, locale) {
+    const parsed = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+    const definitions = readContentDefinitions(parsed);
+    const canonical = (tag) => Intl.getCanonicalLocales(tag)[0];
+    if (new Set(definitions.map((item) => canonical(item.defaultLocale))).size !== 1) {
+        throw new Error('Definitions in one content file must use the same defaultLocale.');
+    }
+    if (canonical(definitions[0].defaultLocale) === locale)
+        return { source, translated };
+    const translatedModule = ts.createSourceFile(destination, translated ?? '', ts.ScriptTarget.Latest, true);
+    const present = exportedBindings(translatedModule);
+    const sourceImports = importedNames(parsed);
+    const registrationPath = modulePath(file, destination);
+    const edits = [];
+    const exports = [];
+    const imports = [];
+    const newTypes = new Set();
+    const typeNames = new Set(definitions.map((item) => item.type));
+    for (const definition of definitions) {
+        const previous = definition.map.properties.find((item) => ts.isPropertyAssignment(item)
+            && canonical(item.name.text) === locale);
+        if (!present.has(definition.name)) {
+            const value = (previous ?? property(definition.map, definition.defaultLocale))?.initializer;
+            if (!value || !ts.isObjectLiteralExpression(value)) {
+                throw new Error(`Restore the missing translation for ${definition.name} or provide inline object content before retrying.`);
+            }
+            exports.push(`export const ${definition.name}: ${definition.type} = ${translatedExpression(value, parsed, definitions, locale, present)};`);
+            newTypes.add(definition.type);
+        }
+        const registered = [...sourceImports].find(([, value]) => value.module === registrationPath && value.name === definition.name && !value.typeOnly)?.[0];
+        if (registered && previous && ts.isIdentifier(previous.initializer) && previous.initializer.text === registered)
+            continue;
+        let alias = registered ?? `${definition.name}_${locale.replace(/-/g, '_')}`;
+        if (!registered) {
+            const initial = alias;
+            let suffix = 1;
+            while (source.includes(alias))
+                alias = `${initial}_${suffix++}`;
+            imports.push(`import { ${definition.name} as ${alias} } from ${JSON.stringify(registrationPath)};`);
+        }
+        if (previous)
+            edits.push({ start: previous.initializer.getStart(parsed), end: previous.initializer.end, text: alias });
+        else
+            edits.push({ start: definition.map.end - 1, end: definition.map.end - 1, text: `${definition.map.properties.hasTrailingComma ? '' : ','}\n    ${JSON.stringify(locale)}: ${alias},\n  ` });
+    }
+    for (const statement of parsed.statements) {
+        if ((ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) && typeNames.has(statement.name.text)
+            && !statement.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) {
+            edits.push({ start: statement.getStart(parsed), end: statement.getStart(parsed), text: 'export ' });
+        }
+    }
+    const payload = exports.join('\n\n');
+    const dependencies = exports.length ? contentImports(parsed, destination, payload) : [];
+    if (newTypes.size)
+        dependencies.unshift(`import type { ${[...newTypes].join(', ')} } from ${JSON.stringify(modulePath(destination, file))};`);
+    return {
+        source: insertImports(applySourceEdits(source, edits), imports),
+        translated: appendTranslation(translated ?? '', dependencies, exports),
+    };
+}

package/dist/localeModuleEdits.d.ts

@@ -0,0 +1,19 @@
+import ts from 'typescript';
+export type SourceEdit = {
+    start: number;
+    end: number;
+    text: string;
+};
+export declare function applySourceEdits(source: string, edits: SourceEdit[]): string;
+/** Keep module directives and leading comments before generated imports. */
+export declare function insertImports(source: string, imports: string[]): string;
+export declare function importedNames(parsed: ts.SourceFile): Map<string, {
+    module: string;
+    name: string;
+    typeOnly: boolean;
+}>;
+export declare function exportedBindings(parsed: ts.SourceFile): Map<string, string | null>;
+/** Print the selected bindings, preserving import kinds and attributes. */
+export declare function selectImport(statement: ts.ImportDeclaration, parsed: ts.SourceFile, keep: (name: string) => boolean, module?: ts.Expression): string | null;
+/** Reuse matching imports when adding definitions to an already translated module. */
+export declare function appendTranslation(source: string, imports: string[], definitions: string[]): string;

package/dist/localeModuleEdits.js

@@ -0,0 +1,97 @@
+import ts from 'typescript';
+export function applySourceEdits(source, edits) {
+    return [...edits].sort((a, b) => b.start - a.start).reduce((result, edit) => result.slice(0, edit.start) + edit.text + result.slice(edit.end), source);
+}
+/** Keep module directives and leading comments before generated imports. */
+export function insertImports(source, imports) {
+    if (!imports.length)
+        return source;
+    const parsed = ts.createSourceFile('content.ts', source, ts.ScriptTarget.Latest, true);
+    const first = parsed.statements.find((statement) => !ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression));
+    const offset = first?.getStart(parsed) ?? source.length;
+    return source.slice(0, offset) + imports.join('\n') + '\n' + source.slice(offset);
+}
+export function importedNames(parsed) {
+    const names = new Map();
+    for (const statement of parsed.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const clause = statement.importClause;
+        if (!clause)
+            continue;
+        const module = statement.moduleSpecifier.text;
+        if (clause.name)
+            names.set(clause.name.text, { module, name: 'default', typeOnly: clause.isTypeOnly });
+        const bindings = clause.namedBindings;
+        if (bindings && ts.isNamespaceImport(bindings))
+            names.set(bindings.name.text, { module, name: '*', typeOnly: clause.isTypeOnly });
+        if (bindings && ts.isNamedImports(bindings)) {
+            for (const item of bindings.elements)
+                names.set(item.name.text, { module, name: (item.propertyName ?? item.name).text, typeOnly: clause.isTypeOnly || item.isTypeOnly });
+        }
+    }
+    return names;
+}
+export function exportedBindings(parsed) {
+    const names = new Map();
+    for (const statement of parsed.statements) {
+        if (ts.isVariableStatement(statement)
+            && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name))
+                    names.set(declaration.name.text, declaration.name.text);
+            }
+        }
+        if (ts.isExportDeclaration(statement) && !statement.isTypeOnly
+            && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+            for (const item of statement.exportClause.elements) {
+                if (!item.isTypeOnly)
+                    names.set(item.name.text, statement.moduleSpecifier ? null : (item.propertyName ?? item.name).text);
+            }
+        }
+    }
+    return names;
+}
+/** Print the selected bindings, preserving import kinds and attributes. */
+export function selectImport(statement, parsed, keep, module = statement.moduleSpecifier) {
+    const clause = statement.importClause;
+    if (!clause)
+        return null;
+    const name = clause.name && keep(clause.name.text) ? clause.name : undefined;
+    const bindings = clause.namedBindings;
+    const named = bindings && (ts.isNamespaceImport(bindings)
+        ? keep(bindings.name.text) ? bindings : undefined
+        : ts.factory.createNamedImports(bindings.elements.filter((item) => keep(item.name.text))));
+    if (!name && (!named || ts.isNamedImports(named) && !named.elements.length))
+        return null;
+    const updated = ts.factory.updateImportDeclaration(statement, statement.modifiers, ts.factory.updateImportClause(clause, clause.isTypeOnly, name, named), module, statement.attributes);
+    return ts.createPrinter().printNode(ts.EmitHint.Unspecified, updated, parsed);
+}
+/** Reuse matching imports when adding definitions to an already translated module. */
+export function appendTranslation(source, imports, definitions) {
+    const parsed = ts.createSourceFile('content.ts', source, ts.ScriptTarget.Latest, true);
+    const existing = importedNames(parsed);
+    const additions = [];
+    for (const text of imports) {
+        const imported = ts.createSourceFile('import.ts', text, ts.ScriptTarget.Latest, true);
+        const statement = imported.statements[0];
+        const names = importedNames(imported);
+        const needed = (name) => {
+            const previous = existing.get(name);
+            const next = names.get(name);
+            if (!previous) {
+                existing.set(name, next);
+                return true;
+            }
+            if (previous.module !== next.module || previous.name !== next.name || previous.typeOnly !== next.typeOnly) {
+                throw new Error(`Translation import ${name} conflicts with an existing import. Resolve the import before retrying.`);
+            }
+            return false;
+        };
+        const addition = selectImport(statement, imported, needed);
+        if (addition)
+            additions.push(addition);
+    }
+    const updated = insertImports(source, additions);
+    return definitions.length ? `${updated}${updated.endsWith('\n') || !updated ? '' : '\n'}\n${definitions.join('\n\n')}\n` : updated;
+}

package/dist/locales.d.ts

@@ -1,4 +1,4 @@
-/** Prepare every edit before writing so unsupported content cannot leave a partly added locale. */
+/** Plan every source change before writing; original content keeps its existing location. */
 export declare function addFunnelLocale(directory: string, requestedLocale: string): Promise<{
     locale: string;
     added: string[];

package/dist/locales.js

@@ -1,126 +1,92 @@
-import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import ts from 'typescript';
+import { planLocaleFile } from './localeFilePlan.js';
 function canonicalLocale(value) {
     try {
         const [locale] = Intl.getCanonicalLocales(value);
         if (locale)
             return locale;
     }
-    catch { /* Report the invalid input below. */ }
+    catch { /* Invalid tag. */ }
     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 });
+async function contentFiles(directory, localizationRoot) {
     const files = [];
-    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
         const file = path.join(directory, entry.name);
+        if (file === localizationRoot)
+            continue;
         if (entry.isDirectory())
-            files.push(...await contentFiles(file));
+            files.push(...await contentFiles(file, localizationRoot));
         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);
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
 }
-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);
-            }
+async function assertDestinationPath(root, file) {
+    let current = root;
+    for (const part of path.relative(root, file).split(path.sep)) {
+        current = path.join(current, part);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error(`Localization destination contains a symbolic link: ${current}`);
         }
-    }
-    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;
-            }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
         }
-        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. */
+/** Plan every source change before writing; original content keeps its existing location. */
 export async function addFunnelLocale(directory, requestedLocale) {
+    directory = path.resolve(directory);
     const locale = canonicalLocale(requestedLocale);
-    const edits = [];
-    const existing = [];
-    const files = await contentFiles(path.join(directory, 'src'));
+    const sourceRoot = path.join(directory, 'src');
+    const localizationRoot = path.join(sourceRoot, 'localization');
+    const files = await contentFiles(sourceRoot, localizationRoot);
     if (!files.length)
         throw new Error('No src/**/*.content.ts files found. Move translatable copy into content definitions first.');
+    const edits = [];
+    const added = [];
+    const existing = [];
     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;
-                }
+        try {
+            const source = await readFile(file, 'utf8');
+            const destination = path.join(localizationRoot, locale, path.relative(sourceRoot, file));
+            const localizedPath = path.relative(directory, destination).split(path.sep).join('/');
+            await assertDestinationPath(sourceRoot, destination);
+            const translated = await exists(destination) ? await readFile(destination, 'utf8') : null;
+            const plan = planLocaleFile(file, source, destination, translated, locale);
+            if (plan.source === source && plan.translated === translated) {
+                existing.push(translated === null ? relative : localizedPath);
+                continue;
             }
-            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);
+            if (plan.translated !== translated && plan.translated !== null) {
+                edits.push({ file: destination, source: plan.translated, create: translated === null });
             }
-            edits.push({ file, source: nextSource });
+            if (plan.source !== source)
+                edits.push({ file, source: plan.source });
+            added.push(localizedPath);
         }
+        catch (error) {
+            throw new Error(`${relative}: ${error.message}`);
+        }
+    }
+    for (const edit of edits) {
+        await mkdir(path.dirname(edit.file), { recursive: true });
+        await writeFile(edit.file, edit.source, edit.create ? { flag: 'wx' } : undefined);
     }
-    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 };
+    return { locale, added, existing };
 }

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.233",
+      "repositoryCliVersion": "0.1.237",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.225",
+        "bundleVersion": "2.0.229",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -29,7 +29,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
+            "sha256": "17c8a91800ec1d2247b1e0fd12cc80fbfce162297aa928432cc0a574acd9fc06"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
+            "sha256": "eec04cc76ab67b9ba06ff1b32c68c657d86488883942c70c5a8ce526d05c4c20"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54"
+            "sha256": "6018305fe5a4b85b9411dc53e1d7169e9d0a3670f422b046ab24759f66392c98"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.232",
+      "repositoryCliVersion": "0.1.236",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.224",
+        "bundleVersion": "2.0.228",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "cd4e0392bc88e2c24459a5132b8c7573bdb3e5a01aa7d9684139c30de39e4813"
+            "sha256": "9c83f0df832c3279b39e7eec870ce48831ffbbca5a329f20e98a0c5f981fdb70"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,22 +292,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "fd3117529acd5a83faf9ffb7bc004d5c1166ba783bcc57c2457ffc5e83c936f4"
+            "sha256": "1ca7b4ab4b9bfebb726441adf8af784b7fc4405524b6ec0435382315e61e7a07"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.231",
+      "repositoryCliVersion": "0.1.235",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.223",
+        "bundleVersion": "2.0.227",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
           {
             "path": "AGENTS.md",
-            "sha256": "22118f0f909a747f8a27f4eed16ceb5ec2a9283fd9645114fda961c0405a2a6b"
+            "sha256": "3860d21f4a3f9b0c25ca54f7a87762d801f14b82a181b4c0b941c57187908f99"
           },
           {
             "path": "CLAUDE.md",
@@ -323,7 +323,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+            "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "b77101d16260357a891c26a6f0e6298f5763b3a8d76b38ba94378064a753e9f0"
+            "sha256": "b3cf273905125a0308291828e4f9ec39d6478cbcbe27396f1b1756686850bba6"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "e111086760618c659a1f72b0e463bf2aa4c67ba9ebc1b4728c84e0d6b20b6510"
+            "sha256": "a8289d598d0adb9bfb3f20ada3d20c3e175dafce4efcdf6a6e5ec2af6b29a625"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.230",
+      "repositoryCliVersion": "0.1.234",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.222",
+        "bundleVersion": "2.0.226",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "1447228902ae180df9db9a7b3778558bd1e2837ba63b20d66207b83cfd36772b"
+            "sha256": "898f23a02a53cc70322fae87a715c0ffc4192a8d06dcdd1f4672af3a1d69e527"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,22 +586,22 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "eac90701cb7c2ae42d90b23f8cd7d7f7b3abd5b64b09a754fa4e61af910cd334"
+            "sha256": "2c6634aec2abd46a30c6eecac138323396af8ca9550d2d91488c6a80613af179"
           }
         ]
       }
     },
     {
-      "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",
@@ -617,7 +617,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+            "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "d86fab03c5a3bb31b2b62302a4fba47422c7f39d049decf4604b052cd55ae363"
+            "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,22 +733,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",
@@ -764,7 +764,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
-            "sha256": "403b286060dd6cda33757df7c55c5b0e17395f2d90aad0fc133d6ba1919a04b3"
+            "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "16343b066ffd8a56f9490f8c54ec724528166d41b812665565dca507aa4a65b1"
+            "sha256": "cd4e0392bc88e2c24459a5132b8c7573bdb3e5a01aa7d9684139c30de39e4813"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,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": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "3456a7f44a9b1e76adba665588a13a65e923e64bfa599199067196031731799e"
+            "sha256": "b77101d16260357a891c26a6f0e6298f5763b3a8d76b38ba94378064a753e9f0"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "b40f461f4d0ee96592a9d2de99cef14c8eb809b6e315d7524e9ef89c217f04e7"
+            "sha256": "e111086760618c659a1f72b0e463bf2aa4c67ba9ebc1b4728c84e0d6b20b6510"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.233",
+  "version": "0.1.237",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",

package/template_docs/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.225",
+  "bundleVersion": "2.0.229",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -22,7 +22,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/content-answers.md",
-      "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
+      "sha256": "17c8a91800ec1d2247b1e0fd12cc80fbfce162297aa928432cc0a574acd9fc06"
     },
     {
       "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
+      "sha256": "eec04cc76ab67b9ba06ff1b32c68c657d86488883942c70c5a8ce526d05c4c20"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54"
+      "sha256": "6018305fe5a4b85b9411dc53e1d7169e9d0a3670f422b046ab24759f66392c98"
     }
   ]
 }

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

@@ -52,20 +52,39 @@ 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.
+1. Keep original `*.content.ts` files at their existing locations alongside the
+   funnel's steps/shared code. They own the default English content and exported
+   content types. Run `fgrove locales add ru --dir .` to create translations under
+   `src/localization/ru/`, mirroring each original path relative to `src/`:
+   `src/steps/content/intro.content.ts` →
+   `src/localization/ru/steps/content/intro.content.ts`.
+   Use BCP 47 tags such as `pt-BR`. CLI copies source only: no translation, login,
+   sync or publication. Repeating the command preserves translated values, adds missing exports and
+   repairs missing registrations in the originals.
+   An existing inline locale is extracted with its authored text preserved.
+2. Translate **every** generated content file, including shared shell and
+   returning-subscriber content. Each translated export imports its named type
+   with `import type` from the original file. Original definitions import these
+   translated values into their `locales` map; the reverse import is type-only.
+   Preserve keys, option IDs, placeholders such as `{amount}`, URLs and tokens.
+   Same-file inheritance from the default or requested locale refers to the
+   translated export. References to other locales require explicit copy before
+   running the command. Relative imports
+   are rebased; imported expressions remain authored references. Inspect those
+   references for remaining visitor copy before completing a translation.
+3. Define the complete structure in an exported type in the original content file
+   and use `satisfies LocalizedStepContent<YourContentType>`. When adding a field,
+   update this type and the English content, then supply the field in **every**
+   translation. Keep required fields required; do not silence errors with casts,
+   optional fields or English spreads. Run `npx tsc --noEmit` at the funnel root:
+   an incomplete translation must fail with its file and missing field.
+   Keep `defaultLocale` and `locales` as explicit literal properties. CLI preflights
+   unsupported definitions before writing. Use named non-generic content types
+   and one default language per file. Local helpers referenced by copied
+   content (including enums, classes and type casts) must be inlined or moved to
+   independent imported modules. If a registered translation file is lost, restore
+   it before retrying; CLI cannot recover translated text from an import. A new step
+   must include every supported locale: rerun `locales add` for each language.
 4. Resolve step copy with `usePreviewStepLocalizedContent(stepId, definition,
    getStepContentLocale(attributes))`. Runtime versions supporting localization
    give `?locale=ru` priority; otherwise the requested/browser language applies.

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.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.
+Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.19.0`, then `@funnelsgrove/analytics` `0.1.110`, then `@funnelsgrove/payments` `0.20.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.237`, 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.225",
+  "bundleVersion": "2.0.229",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.225",
+  "bundleVersion": "2.0.229",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -22,7 +22,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/content-answers.md",
-      "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01"
+      "sha256": "17c8a91800ec1d2247b1e0fd12cc80fbfce162297aa928432cc0a574acd9fc06"
     },
     {
       "path": "docs/funnelsgrove/contracts/flow-routing.md",
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047"
+      "sha256": "eec04cc76ab67b9ba06ff1b32c68c657d86488883942c70c5a8ce526d05c4c20"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54"
+      "sha256": "6018305fe5a4b85b9411dc53e1d7169e9d0a3670f422b046ab24759f66392c98"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "30901fb7b8177a1ba9430b78ba2fc14dfddd9b664eaaea88ddb33f60aa0a3da5",
+  "sourceTreeHash": "f14834edab3f8d7a98828a6a0253b40c4457f4d720ec913e3f917da0d3a626e4",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.225",
+  "docsBundleVersion": "2.0.229",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "bd3b4bfecc4384106929d79f0b9c3e20cbf959faba28efe513f8419e719d5b7e",
+      "sha256": "c56225fdfe22673279acfa36ee110d4098d3b2ccc44a2290042f4ede26b0988b",
       "mode": "100644"
     },
     {
@@ -81,7 +81,7 @@
     },
     {
       "path": "docs/funnelsgrove/contracts/content-answers.md",
-      "sha256": "44686934b2a6837142a12e76f9fc84bd5181179bcd3bf82d636a8ad26b72ce01",
+      "sha256": "17c8a91800ec1d2247b1e0fd12cc80fbfce162297aa928432cc0a574acd9fc06",
       "mode": "100644"
     },
     {
@@ -101,7 +101,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "02e1409d391497b8860b5c2942bc07881853f53480daa4fb2972f561e8baa047",
+      "sha256": "eec04cc76ab67b9ba06ff1b32c68c657d86488883942c70c5a8ce526d05c4c20",
       "mode": "100644"
     },
     {
@@ -236,7 +236,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "6767f2a0ee02bc43a4fd4b1b9c07e938099fac90976796636ebc66202050fe54",
+      "sha256": "6018305fe5a4b85b9411dc53e1d7169e9d0a3670f422b046ab24759f66392c98",
       "mode": "100644"
     },
     {
@@ -491,7 +491,7 @@
     },
     {
       "path": "src/steps/content/runtime.content.ts",
-      "sha256": "c0db996c0040b0ed50349017249c8f418332e0a27410ab70dac64cc65b2e6dc6",
+      "sha256": "c69d6129aac089842d3c046abeae0d6a0e29ff53471116651194d02e4000a9af",
       "mode": "100644"
     },
     {
@@ -506,7 +506,7 @@
     },
     {
       "path": "src/steps/content/subscription-dashboard.content.ts",
-      "sha256": "ef47843635e5a3dd6c184ededb40c64e081e61281a5e0056213feaf75265f251",
+      "sha256": "b54b05675a3c239f6003508818e64f6ee19e02e2bcec2fe8c3ce95bed4b90d04",
       "mode": "100644"
     },
     {

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

@@ -52,20 +52,39 @@ 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.
+1. Keep original `*.content.ts` files at their existing locations alongside the
+   funnel's steps/shared code. They own the default English content and exported
+   content types. Run `fgrove locales add ru --dir .` to create translations under
+   `src/localization/ru/`, mirroring each original path relative to `src/`:
+   `src/steps/content/intro.content.ts` →
+   `src/localization/ru/steps/content/intro.content.ts`.
+   Use BCP 47 tags such as `pt-BR`. CLI copies source only: no translation, login,
+   sync or publication. Repeating the command preserves translated values, adds missing exports and
+   repairs missing registrations in the originals.
+   An existing inline locale is extracted with its authored text preserved.
+2. Translate **every** generated content file, including shared shell and
+   returning-subscriber content. Each translated export imports its named type
+   with `import type` from the original file. Original definitions import these
+   translated values into their `locales` map; the reverse import is type-only.
+   Preserve keys, option IDs, placeholders such as `{amount}`, URLs and tokens.
+   Same-file inheritance from the default or requested locale refers to the
+   translated export. References to other locales require explicit copy before
+   running the command. Relative imports
+   are rebased; imported expressions remain authored references. Inspect those
+   references for remaining visitor copy before completing a translation.
+3. Define the complete structure in an exported type in the original content file
+   and use `satisfies LocalizedStepContent<YourContentType>`. When adding a field,
+   update this type and the English content, then supply the field in **every**
+   translation. Keep required fields required; do not silence errors with casts,
+   optional fields or English spreads. Run `npx tsc --noEmit` at the funnel root:
+   an incomplete translation must fail with its file and missing field.
+   Keep `defaultLocale` and `locales` as explicit literal properties. CLI preflights
+   unsupported definitions before writing. Use named non-generic content types
+   and one default language per file. Local helpers referenced by copied
+   content (including enums, classes and type casts) must be inlined or moved to
+   independent imported modules. If a registered translation file is lost, restore
+   it before retrying; CLI cannot recover translated text from an import. A new step
+   must include every supported locale: rerun `locales add` for each language.
 4. Resolve step copy with `usePreviewStepLocalizedContent(stepId, definition,
    getStepContentLocale(attributes))`. Runtime versions supporting localization
    give `?locale=ru` priority; otherwise the requested/browser language applies.

package/template_scaffold/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.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.
+Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.19.0`, then `@funnelsgrove/analytics` `0.1.110`, then `@funnelsgrove/payments` `0.20.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.237`, 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_scaffold/funnel-docs.config.json

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

package/template_scaffold/src/steps/content/runtime.content.ts

@@ -1,6 +1,6 @@
 import type { LocalizedStepContent } from '@funnelsgrove/runtime';
 
-type RuntimeContent = {
+export type RuntimeContent = {
   loadingLabel: string;
   unavailableTitle: string;
   unavailableDescription: string;

package/template_scaffold/src/steps/content/subscription-dashboard.content.ts

@@ -1,6 +1,6 @@
 import type { LocalizedStepContent } from '@funnelsgrove/runtime';
 
-type SubscriptionDashboardContent = {
+export type SubscriptionDashboardContent = {
   brand: string;
   title: string;
   description: string;