@funnelsgrove/cli 0.1.14 → 0.1.18

package/dist/cli.js

@@ -1,18 +1,26 @@
 #!/usr/bin/env node
-import { readFileSync, realpathSync } from 'node:fs';
-import { cp, mkdir, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { constants as fsConstants, readFileSync, realpathSync } from 'node:fs';
+import { cp, link, lstat, mkdir, mkdtemp, open, readFile, readdir, rmdir, rm, unlink, writeFile, } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
-import { callTrpcProcedure } from './apiClient.js';
+import { CURRENT_STEP_CONTRACT_VERSION, FUNNEL_CONTRACT_DIAGNOSTIC_CODES, PREVIOUS_STEP_CONTRACT_VERSION, createFunnelContractDiagnostic, } from '@funnelsgrove/runtime';
+import { abortFunnelSourceCandidate, beginFunnelSourceCandidate, callTrpcProcedure, finalizeFunnelSourceCandidate, stageFunnelSourceCandidate, } from './apiClient.js';
 import { clearActiveContext, getDefaultAuthConfigPath, loadActiveContext, loadAuthToken, saveActiveContext, saveAuthToken, } from './authStore.js';
-import { buildSyncManifest, chunkChangedSourceFiles, collectChangedSourceFiles, collectSourceFiles, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, readSyncManifest, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
+import { buildSyncManifest, buildCommittedSyncManifest, buildSourceCandidateOperations, collectChangedSourceFiles, collectSourceSnapshot, ensureGitignore, formatSyncUploadSummary, hasLocalSourceChanges, readSyncManifest, runSyncDownLocalLifecycle, runSourceCandidateSync, writeLocalEnvFile, writeSourceFiles, writeSyncManifest, } from './localSync.js';
 import { pullEnvFile } from './envSync.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { syncGitHubDraftIfConnected } from './githubSyncFlow.js';
-import { isKnownTemplate, KNOWN_TEMPLATE_SLUGS, reskinFunnel } from './reskin.js';
-import { syncTemplateDocs, TEMPLATE_DOCS_DIR } from './templateDocs.js';
+import { reskinFunnel } from './reskin.js';
+import { TEMPLATE_DOCS_DIR } from './templateDocs.js';
+import { renderDocsHuman, renderDocsJson, } from './docsOutput.js';
+import { applyTemplateDocsUpdate, inspectTemplateDocs, loadBundledDocs, planTemplateDocsUpdate, recoverTemplateDocs, resolveTemplateDocsConflict, } from './docsTransaction.js';
+import { renderValidationHuman, renderValidationJson, } from './diagnosticOutput.js';
+import { validateFunnel } from './funnelValidation.js';
+import { StepContractMigrationError, applyStepContractV2Migration, checkStepContractV2Migration, recoverStepContractV2Migration, resolveStepContractMigrationMode, stepContractMigrationReportPath, } from './stepContractMigration.js';
 import { assertHasCohortData, assertHasConversionData, assertHasFunnelPathData, assertHasTransitionData, buildCohortReportPayload, buildConversionReportPayload, buildFunnelPathReportPayload, buildTransitionReportPayload, formatAnalyticsJson, formatCohortTable, formatConversionsTable, formatFunnelPathTable, formatTransitionsTable, normalizeAnalyticsOutputFormat, parseAnalyticsDate, } from './analyticsOutput.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const readCliVersion = () => {
@@ -32,12 +40,1018 @@ const toKebabCase = (value) => value
     .replace(/([a-z])([A-Z])/g, '$1-$2')
     .replace(/[\s_]+/g, '-')
     .toLowerCase();
-const resolveTemplatePath = (slug) => path.resolve(__dirname, '..', '..', '..', 'funnels', 'rag-catalog', slug);
+export const CANONICAL_CREATE_TEMPLATE_SLUG = 'template';
+export const SCAFFOLD_TRANSIENT_PATHS = [
+    'node_modules',
+    '.next',
+    'out',
+    'tsconfig.tsbuildinfo',
+    '.funnelsgrove-scaffold.json',
+];
+const STEP_CONTRACT_MIGRATION_GUIDANCE = 'fgrove migrate step-contract --to 3';
+export class CliContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message.startsWith(`[${code}]`) ? message : `[${code}] ${message}`);
+        this.name = 'CliContractError';
+        this.code = code;
+    }
+}
+export const assertCanonicalCreateTemplateSlug = (slug) => {
+    if (slug !== CANONICAL_CREATE_TEMPLATE_SLUG) {
+        throw new CliContractError('FG-VERSION-002', `Legacy template slug "${slug}" is not supported by this CLI. For an existing local checkout, run ${STEP_CONTRACT_MIGRATION_GUIDANCE}.`);
+    }
+};
+export const resolveCreateTemplatePath = (slug = CANONICAL_CREATE_TEMPLATE_SLUG) => {
+    assertCanonicalCreateTemplateSlug(slug);
+    return path.resolve(__dirname, '..', 'template_scaffold');
+};
+const removeScaffoldTransientPaths = async (dir) => {
+    await Promise.all(SCAFFOLD_TRANSIENT_PATHS.map((relativePath) => rm(path.join(dir, relativePath), { recursive: true, force: true })));
+};
 const resolveTemplateDocsPath = () => path.resolve(__dirname, '..', TEMPLATE_DOCS_DIR);
+const resolveLegacyDocsCatalogPath = () => path.resolve(__dirname, '..', 'legacy-docs-catalog.json');
+const resolveBundledContractPath = () => path.resolve(__dirname, '..', 'contracts', 'step-contract-v2.json');
+const resolveTemplateValidationPath = () => path.resolve(__dirname, '..', 'template_validation');
 const DEFAULT_API_URL = 'https://api.funnelsgrove.com/trpc';
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PUBLISH_POLL_INTERVAL_MS = 2_000;
 const PUBLISH_WAIT_TIMEOUT_MS = 30 * 60_000;
+export function resolveDocsCommandMode(options) {
+    const selectedModes = [options.check, options.diff, Boolean(options.resolve)].filter(Boolean);
+    if (selectedModes.length > 1) {
+        throw new Error('Choose only one of --check, --diff, or --resolve.');
+    }
+    if (options.resolve && !options.replaceManaged) {
+        throw new Error('--resolve requires --replace-managed.');
+    }
+    if (options.replaceManaged && !options.resolve) {
+        throw new Error('--replace-managed requires --resolve <path>.');
+    }
+    const json = options.json === true;
+    if (options.resolve) {
+        return { mode: 'resolve', json, path: options.resolve };
+    }
+    if (options.check) {
+        return { mode: 'check', json };
+    }
+    if (options.diff) {
+        return { mode: 'diff', json };
+    }
+    return { mode: 'apply', json };
+}
+const loadPackagedLegacyDocsCatalog = async () => {
+    const value = JSON.parse(await readFile(resolveLegacyDocsCatalogPath(), 'utf8'));
+    if (!Array.isArray(value)) {
+        throw Object.assign(new Error('Legacy docs catalog must be an array.'), {
+            code: 'FG-DOC-001',
+        });
+    }
+    return value;
+};
+const createDefaultDocsCommandBackend = () => {
+    let bundlePromise;
+    let catalogPromise;
+    const loadBundle = () => {
+        bundlePromise ??= loadBundledDocs(resolveTemplateDocsPath());
+        return bundlePromise;
+    };
+    const loadCatalog = () => {
+        catalogPromise ??= loadPackagedLegacyDocsCatalog();
+        return catalogPromise;
+    };
+    return {
+        recover: async (targetDir) => {
+            await recoverTemplateDocs(targetDir);
+        },
+        inspect: async (targetDir) => planTemplateDocsUpdate(await inspectTemplateDocs(await loadBundle(), targetDir, {
+            legacyCatalog: await loadCatalog(),
+        })),
+        apply: async (targetDir, status) => {
+            await applyTemplateDocsUpdate(await loadBundle(), targetDir, status, {
+                legacyCatalog: await loadCatalog(),
+            });
+        },
+        resolve: async (targetDir, relativePath) => {
+            await resolveTemplateDocsConflict(await loadBundle(), targetDir, relativePath);
+        },
+    };
+};
+export const docsResolveConfirmation = (relativePath) => `replace-managed ${relativePath}`;
+const docsCommandLabel = (mode) => {
+    if (mode.mode === 'check') {
+        return 'docs --check';
+    }
+    if (mode.mode === 'diff') {
+        return 'docs --diff';
+    }
+    if (mode.mode === 'resolve') {
+        return `docs --resolve ${mode.path} --replace-managed`;
+    }
+    return 'docs';
+};
+const unknownDocsStatus = () => ({
+    bundleVersion: 'unknown',
+    contractVersion: 0,
+    clean: false,
+    files: [],
+    diagnostics: [],
+});
+const addDocsDiagnostic = (status, diagnostic) => ({
+    ...status,
+    clean: false,
+    diagnostics: [...status.diagnostics, diagnostic],
+});
+const docsErrorDiagnostic = (error) => {
+    const code = typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && typeof error.code === 'string'
+        ? error.code
+        : 'FG-DOC-CLI';
+    return {
+        code,
+        message: error instanceof Error ? error.message : String(error),
+    };
+};
+const renderDocsCommandResult = (mode, status, exitCode) => {
+    const input = { command: docsCommandLabel(mode), status, exitCode };
+    return {
+        exitCode,
+        output: mode.json
+            ? renderDocsJson(input)
+            : renderDocsHuman(input, mode.mode === 'diff' ? 'diff' : 'status'),
+    };
+};
+const hasDocsConflicts = (status) => status.files.some((file) => file.action === 'conflict');
+const docsFailureExitCode = (phase, diagnostic) => {
+    if (phase === 'recovery') {
+        return 4;
+    }
+    if (diagnostic.code === 'FG-DOC-001') {
+        return 2;
+    }
+    if (diagnostic.code === 'FG-DOC-002') {
+        return 3;
+    }
+    if (diagnostic.code === 'FG-DOC-RECOVERY'
+        || diagnostic.code === 'FG-DOC-CONCURRENT'
+        || phase === 'apply'
+        || phase === 'resolve') {
+        return 4;
+    }
+    return 2;
+};
+export async function executeDocsCommand(input) {
+    let mode;
+    try {
+        mode = resolveDocsCommandMode(input.options);
+    }
+    catch (error) {
+        const fallbackMode = { mode: 'apply', json: input.options.json === true };
+        return renderDocsCommandResult(fallbackMode, addDocsDiagnostic(unknownDocsStatus(), docsErrorDiagnostic(error)), 2);
+    }
+    if (mode.mode === 'resolve' && input.isTTY !== true) {
+        return renderDocsCommandResult(mode, addDocsDiagnostic(unknownDocsStatus(), {
+            code: 'FG-DOC-USAGE',
+            message: '--resolve requires an interactive TTY.',
+        }), 2);
+    }
+    const backend = input.backend ?? createDefaultDocsCommandBackend();
+    const render = async (currentStatus, exitCode) => {
+        const diagnostic = await input.auditLegacy?.(input.targetDir);
+        const auditedStatus = diagnostic && !currentStatus.diagnostics.some((item) => item.code === diagnostic.code && item.path === diagnostic.path)
+            ? { ...currentStatus, diagnostics: [...currentStatus.diagnostics, diagnostic] }
+            : currentStatus;
+        return renderDocsCommandResult(mode, auditedStatus, exitCode);
+    };
+    let phase = 'recovery';
+    let status;
+    try {
+        await backend.recover(input.targetDir);
+        phase = 'inspection';
+        status = await backend.inspect(input.targetDir);
+        if (mode.mode === 'check') {
+            return render(status, status.clean ? 0 : hasDocsConflicts(status) ? 3 : 1);
+        }
+        if (mode.mode === 'diff') {
+            return render(status, 0);
+        }
+        if (mode.mode === 'apply') {
+            if (hasDocsConflicts(status)) {
+                return render(status, 3);
+            }
+            if (!status.clean) {
+                phase = 'apply';
+                await backend.apply(input.targetDir, status);
+                phase = 'inspection';
+                status = await backend.inspect(input.targetDir);
+            }
+            return render(status, hasDocsConflicts(status) ? 3 : status.clean ? 0 : 1);
+        }
+        const conflict = status.files.find((file) => file.path === mode.path && file.action === 'conflict');
+        if (!conflict) {
+            return render(addDocsDiagnostic(status, {
+                code: 'FG-DOC-002',
+                path: mode.path,
+                message: 'The requested managed path is not an unresolved conflict.',
+            }), 3);
+        }
+        const confirmation = docsResolveConfirmation(mode.path);
+        const answer = await input.prompt?.(`Type "${confirmation}" to replace this managed file: `);
+        if (answer !== confirmation) {
+            return render(addDocsDiagnostic(status, {
+                code: 'FG-DOC-USAGE',
+                path: mode.path,
+                message: 'Managed file replacement was not confirmed exactly.',
+            }), 2);
+        }
+        phase = 'resolve';
+        await backend.resolve(input.targetDir, mode.path);
+        phase = 'inspection';
+        status = await backend.inspect(input.targetDir);
+        return render(status, hasDocsConflicts(status) ? 3 : 0);
+    }
+    catch (error) {
+        const diagnostic = docsErrorDiagnostic(error);
+        const exitCode = docsFailureExitCode(phase, diagnostic);
+        return renderDocsCommandResult(mode, addDocsDiagnostic(status ?? unknownDocsStatus(), diagnostic), exitCode);
+    }
+}
+const validatePackagedFunnel = async (targetDir) => validateFunnel({
+    projectDir: path.resolve(targetDir),
+    bundledDocsDir: resolveTemplateDocsPath(),
+    bundledContractPath: resolveBundledContractPath(),
+    bundledValidationDir: resolveTemplateValidationPath(),
+    legacyCatalog: await loadPackagedLegacyDocsCatalog(),
+});
+export async function executeValidateCommand(input) {
+    const result = await (input.validate ?? validatePackagedFunnel)(path.resolve(input.targetDir));
+    const outputInput = { command: 'validate', result };
+    return {
+        exitCode: result.exitCode,
+        output: input.json ? renderValidationJson(outputInput) : renderValidationHuman(outputInput),
+    };
+}
+export async function auditLegacyFunnel(targetDir, validate = validatePackagedFunnel) {
+    try {
+        const manifest = await lstat(path.join(targetDir, 'src/config/funnel.manifest.ts'));
+        if (!manifest.isFile() || manifest.isSymbolicLink())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const result = await validate(path.resolve(targetDir));
+    const versionDiagnostic = result.diagnostics.find((diagnostic) => diagnostic.code === 'FG-VERSION-001' || diagnostic.code === 'FG-VERSION-002');
+    if (!versionDiagnostic)
+        return null;
+    return {
+        code: versionDiagnostic.code,
+        path: versionDiagnostic.file ?? undefined,
+        message: `${versionDiagnostic.reason} ${versionDiagnostic.repair}`,
+    };
+}
+export class FunnelValidationError extends CliContractError {
+    result;
+    constructor(result) {
+        const diagnostic = result.diagnostics[0];
+        super(diagnostic?.code ?? 'FG-CLIENT-001', renderValidationHuman({ command: 'validate', result }).trimEnd());
+        this.name = 'FunnelValidationError';
+        this.result = result;
+    }
+}
+export async function runValidatedFunnelMutation(input) {
+    const result = await (input.validate ?? validatePackagedFunnel)(path.resolve(input.targetDir));
+    if (!result.valid || result.exitCode !== 0 || result.diagnostics.length > 0) {
+        throw new FunnelValidationError(result);
+    }
+    return input.mutate();
+}
+const assertFunnelValidForMutation = async (targetDir) => {
+    await runValidatedFunnelMutation({ targetDir, mutate: async () => undefined });
+};
+const isFunnelContractDiagnosticCode = (code) => FUNNEL_CONTRACT_DIAGNOSTIC_CODES.includes(code);
+export const toMigrationValidationResult = (result) => ({
+    valid: result.valid && result.exitCode === 0 && result.diagnostics.length === 0,
+    diagnostics: result.diagnostics.map((diagnostic) => createFunnelContractDiagnostic({
+        code: isFunnelContractDiagnosticCode(diagnostic.code)
+            ? diagnostic.code
+            : 'FG-CLIENT-001',
+        file: diagnostic.file,
+        stepId: diagnostic.stepId,
+        expected: diagnostic.expected ?? null,
+        received: diagnostic.received ?? null,
+        reason: diagnostic.reason,
+        guide: diagnostic.guide,
+        repair: diagnostic.repair,
+    })),
+});
+const migrationCommandLabel = (mode, targetVersion) => `migrate step-contract --to ${targetVersion} --${mode}`;
+const renderMigrationResult = (input) => {
+    const errorMessage = input.error instanceof Error
+        ? input.error.message
+        : input.error === undefined ? null : String(input.error);
+    const output = {
+        schemaVersion: 1,
+        command: migrationCommandLabel(input.mode, input.targetVersion),
+        mode: input.mode,
+        reportPath: input.result?.reportPath ?? null,
+        report: input.result?.report ?? null,
+        applied: 'applied' in (input.result ?? {}) ? true : false,
+        diagnostics: errorMessage === null ? [] : [{
+                code: input.error instanceof CliContractError
+                    ? input.error.code
+                    : 'FG-CLIENT-001',
+                message: errorMessage,
+            }],
+        exitCode: input.exitCode,
+    };
+    if (input.json) {
+        return { exitCode: input.exitCode, output: `${JSON.stringify(output, null, 2)}\n` };
+    }
+    const lines = [
+        `Step contract migration: ${input.exitCode === 0 ? 'ready' : input.exitCode === 1 ? 'blocked' : 'error'} (${input.mode})`,
+        ...(input.result ? [
+            `Report: ${input.result.reportPath}`,
+            `Operations: ${input.result.report.operations.length}`,
+            ...input.result.report.diagnostics.map((diagnostic) => `[${diagnostic.code}] ${diagnostic.reason}`),
+        ] : []),
+        ...(errorMessage === null ? [] : [errorMessage]),
+    ];
+    return { exitCode: input.exitCode, output: `${lines.join('\n')}\n` };
+};
+const CONTRACT_TOOLS_MANIFEST_PATH = '.funnelsgrove-contract-tools.json';
+const SUPPORTED_CLI_CONTRACT_VERSIONS = new Set([
+    PREVIOUS_STEP_CONTRACT_VERSION,
+    CURRENT_STEP_CONTRACT_VERSION,
+]);
+const isSafeManagedValidatorPath = (relativePath) => (relativePath.startsWith('src/contract/')
+    && !relativePath.includes('\\')
+    && !/[\u0000-\u001f\u007f]/.test(relativePath)
+    && path.posix.normalize(relativePath) === relativePath
+    && relativePath.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..'));
+const parseContractToolsManifest = (bytes, code) => {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new CliContractError(code, 'The managed validator ownership manifest is malformed.');
+    }
+    if (value === null
+        || typeof value !== 'object'
+        || Array.isArray(value)
+        || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new CliContractError(code, 'The managed validator ownership manifest is malformed.');
+    }
+    const manifest = value;
+    if (JSON.stringify(Object.keys(manifest).sort())
+        !== JSON.stringify(['contractHash', 'managedFiles', 'schemaVersion', 'stepContractVersion'])
+        ||
+            manifest.schemaVersion !== 1
+        || typeof manifest.stepContractVersion !== 'number'
+        || !SUPPORTED_CLI_CONTRACT_VERSIONS.has(manifest.stepContractVersion)
+        || typeof manifest.contractHash !== 'string'
+        || !/^[a-f0-9]{64}$/.test(manifest.contractHash)
+        || !Array.isArray(manifest.managedFiles)
+        || manifest.managedFiles.length === 0) {
+        throw new CliContractError(code, 'The managed validator ownership manifest is malformed.');
+    }
+    const managedFiles = [];
+    const paths = new Set();
+    for (const item of manifest.managedFiles) {
+        if (item === null
+            || typeof item !== 'object'
+            || Array.isArray(item)
+            || Object.getPrototypeOf(item) !== Object.prototype) {
+            throw new CliContractError(code, 'The managed validator ownership manifest is malformed.');
+        }
+        const entry = item;
+        if (Object.keys(entry).sort().join(',') !== 'path,sha256'
+            ||
+                typeof entry.path !== 'string'
+            || typeof entry.sha256 !== 'string'
+            || !isSafeManagedValidatorPath(entry.path)
+            || !/^[a-f0-9]{64}$/.test(entry.sha256)
+            || paths.has(entry.path)) {
+            throw new CliContractError(code, 'The managed validator ownership manifest is malformed.');
+        }
+        paths.add(entry.path);
+        managedFiles.push({ path: entry.path, sha256: entry.sha256 });
+    }
+    if (managedFiles.some((entry, index) => (index > 0 && managedFiles[index - 1].path.localeCompare(entry.path) >= 0))) {
+        throw new CliContractError(code, 'The managed validator ownership manifest is malformed.');
+    }
+    return { managedFiles };
+};
+const listManagedValidatorSourceFiles = async (rootDir, relativeDir = '') => {
+    const entries = await readdir(path.join(rootDir, relativeDir), { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+        if (entry.isSymbolicLink()) {
+            throw new CliContractError('FG-DOC-001', 'Managed validator files may not be symlinks.');
+        }
+        if (entry.isDirectory()) {
+            files.push(...await listManagedValidatorSourceFiles(rootDir, relativePath));
+        }
+        else if (entry.isFile()) {
+            files.push(relativePath);
+        }
+        else {
+            throw new CliContractError('FG-DOC-001', 'Managed validator files must be regular files.');
+        }
+    }
+    return files;
+};
+const readTargetRegularFile = async (rootDir, relativePath) => {
+    const segments = relativePath.split('/');
+    for (let index = 0; index < segments.length; index += 1) {
+        const absolutePath = path.join(rootDir, ...segments.slice(0, index + 1));
+        let stats;
+        try {
+            stats = await lstat(absolutePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new CliContractError('FG-DOC-002', 'Managed validator targets may not be symlinks.');
+        }
+        if (index < segments.length - 1 && !stats.isDirectory()) {
+            throw new CliContractError('FG-DOC-002', 'Managed validator target parents must be directories.');
+        }
+        if (index === segments.length - 1 && !stats.isFile()) {
+            throw new CliContractError('FG-DOC-002', 'Managed validator targets must be regular files.');
+        }
+    }
+    return readFile(path.join(rootDir, relativePath));
+};
+export const copyManagedValidationFiles = async (targetDir, sourceDir = resolveTemplateValidationPath()) => {
+    const sourcePaths = await listManagedValidatorSourceFiles(sourceDir);
+    const sourceManifestBytes = await readFile(path.join(sourceDir, CONTRACT_TOOLS_MANIFEST_PATH));
+    const sourceManifest = parseContractToolsManifest(sourceManifestBytes, 'FG-DOC-001');
+    const expectedSourcePaths = [
+        CONTRACT_TOOLS_MANIFEST_PATH,
+        ...sourceManifest.managedFiles.map(({ path: filePath }) => filePath),
+    ].sort();
+    if (JSON.stringify(sourcePaths) !== JSON.stringify(expectedSourcePaths)) {
+        throw new CliContractError('FG-DOC-001', 'The managed validator bundle does not match its ownership manifest.');
+    }
+    const sourceFiles = new Map();
+    for (const entry of sourceManifest.managedFiles) {
+        const bytes = await readFile(path.join(sourceDir, entry.path));
+        const digest = createHash('sha256').update(bytes).digest('hex');
+        if (digest !== entry.sha256) {
+            throw new CliContractError('FG-DOC-001', 'The managed validator bundle does not match its ownership manifest.');
+        }
+        sourceFiles.set(entry.path, bytes);
+    }
+    const priorManifestBytes = await readTargetRegularFile(targetDir, CONTRACT_TOOLS_MANIFEST_PATH);
+    const priorManifest = priorManifestBytes === null
+        ? null
+        : parseContractToolsManifest(priorManifestBytes, 'FG-DOC-002');
+    const priorHashes = new Map(priorManifest?.managedFiles.map((entry) => [entry.path, entry.sha256]) ?? []);
+    for (const [relativePath, incomingBytes] of sourceFiles) {
+        const currentBytes = await readTargetRegularFile(targetDir, relativePath);
+        if (currentBytes === null || currentBytes.equals(incomingBytes)) {
+            continue;
+        }
+        const currentHash = createHash('sha256').update(currentBytes).digest('hex');
+        if (priorHashes.get(relativePath) !== currentHash) {
+            throw new CliContractError('FG-DOC-002', `Managed validator conflicts with local changes: ${relativePath}`);
+        }
+    }
+    for (const [relativePath, bytes] of sourceFiles) {
+        const absolutePath = path.join(targetDir, relativePath);
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, bytes);
+    }
+    await writeFile(path.join(targetDir, CONTRACT_TOOLS_MANIFEST_PATH), sourceManifestBytes);
+};
+const MANAGED_VALIDATOR_SCRIPT = 'vite-node --config src/contract/funnel-validator.vite.config.ts src/contract/validate-funnel.cli.ts';
+const ensureManagedValidatorPackage = async (targetDir) => {
+    const packagePath = path.join(targetDir, 'package.json');
+    const packageJson = JSON.parse(await readFile(packagePath, 'utf8'));
+    const scripts = packageJson.scripts ?? {};
+    const existingScript = scripts['validate:funnel'];
+    if (existingScript !== undefined
+        && existingScript !== MANAGED_VALIDATOR_SCRIPT
+        && existingScript !== 'vite-node src/contract/validate-funnel.cli.ts'
+        && existingScript !== 'vite-node --config vitest.config.ts src/contract/validate-funnel.cli.ts') {
+        throw new CliContractError('FG-VERSION-002', 'The existing validate:funnel script is not a known managed value.');
+    }
+    if (packageJson.dependencies?.['vite-node'] !== undefined) {
+        throw new CliContractError('FG-VERSION-002', 'Move the custom vite-node runtime dependency before migrating.');
+    }
+    const devDependencies = packageJson.devDependencies ?? {};
+    const existingViteNode = devDependencies['vite-node'];
+    if (existingViteNode !== undefined && existingViteNode !== '3.2.4') {
+        throw new CliContractError('FG-VERSION-002', 'The existing vite-node dependency is not the managed version 3.2.4.');
+    }
+    packageJson.scripts = { ...scripts, 'validate:funnel': MANAGED_VALIDATOR_SCRIPT };
+    packageJson.devDependencies = { ...devDependencies, 'vite-node': '3.2.4' };
+    await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+};
+const installManagedFunnelFiles = async (targetDir) => {
+    await copyManagedValidationFiles(targetDir);
+    await ensureManagedValidatorPackage(targetDir);
+    const docs = await executeDocsCommand({ targetDir, options: { json: true } });
+    if (docs.exitCode !== 0) {
+        const output = JSON.parse(docs.output);
+        const diagnostic = output.diagnostics?.[0];
+        throw new CliContractError(diagnostic?.code ?? 'FG-DOC-001', diagnostic?.message ?? 'Managed documentation could not be installed.');
+    }
+};
+export const runBoundedNpmCommand = async (targetDir, args, options = {}) => new Promise((resolve, reject) => {
+    const timeoutMs = options.timeoutMs ?? 10 * 60_000;
+    const terminationGraceMs = options.terminationGraceMs ?? 5_000;
+    const finalizationGraceMs = options.finalizationGraceMs ?? 1_000;
+    const child = spawn('npm', [...args], {
+        cwd: targetDir,
+        detached: process.platform !== 'win32',
+        env: process.env,
+        shell: false,
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+    let timedOut = false;
+    let settled = false;
+    let terminationTimer;
+    let finalizationTimer;
+    const settle = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timeout);
+        if (terminationTimer)
+            clearTimeout(terminationTimer);
+        if (finalizationTimer)
+            clearTimeout(finalizationTimer);
+        if (error)
+            reject(error);
+        else
+            resolve();
+    };
+    const killProcessTree = (signal) => {
+        if (process.platform === 'win32' && child.pid !== undefined) {
+            // Killing npm first can orphan its descendants before taskkill can discover the tree.
+            const taskkill = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            taskkill.once('error', () => {
+                // A second bounded attempt is made after the termination grace period.
+            });
+            taskkill.unref();
+            return;
+        }
+        if (process.platform !== 'win32' && child.pid !== undefined) {
+            try {
+                process.kill(-child.pid, signal);
+                return;
+            }
+            catch {
+                // The group may already be gone; fall back to the npm process handle.
+            }
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Completion is bounded by the finalization timer even if signaling fails.
+        }
+    };
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        killProcessTree('SIGTERM');
+        terminationTimer = setTimeout(() => {
+            killProcessTree('SIGKILL');
+            finalizationTimer = setTimeout(() => {
+                child.unref();
+                settle(new CliContractError('FG-CLIENT-001', 'npm dependency installation timed out.'));
+            }, finalizationGraceMs);
+        }, terminationGraceMs);
+    }, timeoutMs);
+    child.once('error', (error) => {
+        if (!timedOut)
+            settle(error);
+    });
+    child.once('close', (code, signal) => {
+        if (timedOut)
+            return;
+        if (code !== 0) {
+            settle(new CliContractError('FG-CLIENT-001', `npm dependency installation failed${signal ? ` (${signal})` : ''}.`));
+        }
+        else {
+            settle();
+        }
+    });
+});
+const managedBundleAvailable = async () => {
+    try {
+        await Promise.all([
+            loadBundledDocs(resolveTemplateDocsPath()),
+            lstat(resolveBundledContractPath()),
+            lstat(resolveTemplateValidationPath()),
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const createDefaultMigrationBackend = () => ({
+    recoverMigration: recoverStepContractV2Migration,
+    recoverDocs: recoverTemplateDocs,
+    check: async (targetDir, targetVersion) => checkStepContractV2Migration({
+        projectDir: targetDir,
+        managedBundleAvailable: await managedBundleAvailable(),
+        targetVersion,
+    }),
+    apply: async (targetDir, targetVersion) => applyStepContractV2Migration({
+        projectDir: targetDir,
+        managedBundleAvailable: await managedBundleAvailable(),
+        targetVersion,
+        installManagedCandidate: async ({ candidateDir }) => {
+            await installManagedFunnelFiles(candidateDir);
+            await runBoundedNpmCommand(candidateDir, [
+                'install',
+                '--ignore-scripts',
+                '--no-audit',
+                '--no-fund',
+                '--workspaces=false',
+            ]);
+        },
+        validateCandidate: async ({ candidateDir, phase }) => {
+            if (phase === 'committed') {
+                await runBoundedNpmCommand(candidateDir, [
+                    'ci',
+                    '--ignore-scripts',
+                    '--no-audit',
+                    '--no-fund',
+                    '--workspaces=false',
+                ]);
+            }
+            return toMigrationValidationResult(await validatePackagedFunnel(candidateDir));
+        },
+    }),
+});
+export async function executeStepContractMigrationCommand(input) {
+    let mode = 'check';
+    let targetVersion = 3;
+    try {
+        if (String(input.to) !== '3') {
+            throw new CliContractError('FG-VERSION-002', '--to must be 3.');
+        }
+        targetVersion = Number(input.to);
+        mode = resolveStepContractMigrationMode(input.options);
+    }
+    catch (error) {
+        return renderMigrationResult({
+            mode,
+            targetVersion,
+            error,
+            json: input.options.json === true,
+            exitCode: 2,
+        });
+    }
+    const targetDir = path.resolve(input.targetDir);
+    const backend = input.backend ?? createDefaultMigrationBackend();
+    try {
+        await backend.recoverMigration(targetDir, targetVersion);
+        await backend.recoverDocs(targetDir);
+        const result = mode === 'apply'
+            ? await backend.apply(targetDir, targetVersion)
+            : await backend.check(targetDir, targetVersion);
+        return renderMigrationResult({
+            mode,
+            targetVersion,
+            result,
+            json: input.options.json === true,
+            exitCode: result.report.valid ? 0 : 1,
+        });
+    }
+    catch (error) {
+        const report = error instanceof StepContractMigrationError && error.report
+            ? {
+                reportPath: path.join(targetDir, stepContractMigrationReportPath(targetVersion)),
+                report: error.report,
+            }
+            : undefined;
+        return renderMigrationResult({
+            mode,
+            targetVersion,
+            result: report,
+            error,
+            json: input.options.json === true,
+            exitCode: report ? 1 : 2,
+        });
+    }
+}
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const isSafeScaffoldPath = (relativePath) => {
+    if (!relativePath
+        || relativePath.includes('\\')
+        || /[\u0000-\u001f\u007f]/.test(relativePath)
+        || path.posix.isAbsolute(relativePath)
+        || /^[A-Za-z]:/.test(relativePath)
+        || path.posix.normalize(relativePath) !== relativePath)
+        return false;
+    return relativePath.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+};
+const scaffoldTreeHash = (files) => {
+    const hash = createHash('sha256');
+    hash.update('funnelsgrove-scaffold-v1\0');
+    for (const file of files) {
+        hash.update(file.path);
+        hash.update('\0');
+        hash.update(file.mode);
+        hash.update('\0');
+        hash.update(file.sha256);
+        hash.update('\n');
+    }
+    return hash.digest('hex');
+};
+const parseScaffoldManifest = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new CliContractError('FG-DOC-001', 'The packaged scaffold manifest is invalid.');
+    }
+    const manifest = value;
+    if (manifest.schemaVersion !== 1
+        || typeof manifest.stepContractVersion !== 'number'
+        || !SUPPORTED_CLI_CONTRACT_VERSIONS.has(manifest.stepContractVersion)
+        || typeof manifest.sourceTreeHash !== 'string'
+        || !/^[a-f0-9]{64}$/.test(manifest.sourceTreeHash)
+        || typeof manifest.docsBundleVersion !== 'string'
+        || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(manifest.docsBundleVersion)
+        || !Array.isArray(manifest.files)) {
+        throw new CliContractError('FG-DOC-001', 'The packaged scaffold manifest is invalid.');
+    }
+    const files = [];
+    const seen = new Set();
+    let previousPath = '';
+    for (const value of manifest.files) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new CliContractError('FG-DOC-001', 'The packaged scaffold file list is invalid.');
+        }
+        const file = value;
+        if (typeof file.path !== 'string'
+            || !isSafeScaffoldPath(file.path)
+            || typeof file.sha256 !== 'string'
+            || !/^[a-f0-9]{64}$/.test(file.sha256)
+            || (file.mode !== '100644' && file.mode !== '100755')
+            || (previousPath !== '' && previousPath >= file.path)
+            || seen.has(file.path.normalize('NFC').toLowerCase())
+            || file.path === '.funnelsgrove-scaffold.json') {
+            throw new CliContractError('FG-DOC-001', 'The packaged scaffold file list is invalid.');
+        }
+        previousPath = file.path;
+        seen.add(file.path.normalize('NFC').toLowerCase());
+        files.push(file);
+    }
+    const parsed = manifest;
+    if (scaffoldTreeHash(files) !== parsed.sourceTreeHash) {
+        throw new CliContractError('FG-DOC-001', 'The packaged scaffold tree hash is invalid.');
+    }
+    return { ...parsed, files };
+};
+const collectScaffoldFiles = async (rootDir, relativeDir = '') => {
+    const files = [];
+    const entries = (await readdir(path.join(rootDir, relativeDir), { withFileTypes: true }))
+        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+        const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+        if (!isSafeScaffoldPath(relativePath)) {
+            throw new CliContractError('FG-DOC-001', `Unsafe packaged scaffold path: ${relativePath}`);
+        }
+        const absolutePath = path.join(rootDir, ...relativePath.split('/'));
+        const metadata = await lstat(absolutePath);
+        if (metadata.isSymbolicLink()) {
+            throw new CliContractError('FG-DOC-001', `Packaged scaffold symlink: ${relativePath}`);
+        }
+        if (metadata.isDirectory()) {
+            files.push(...await collectScaffoldFiles(rootDir, relativePath));
+        }
+        else if (metadata.isFile() && relativePath !== '.funnelsgrove-scaffold.json') {
+            files.push({
+                path: relativePath,
+                sha256: sha256(await readFile(absolutePath)),
+                mode: metadata.mode & 0o111 ? '100755' : '100644',
+            });
+        }
+        else if (!metadata.isFile()) {
+            throw new CliContractError('FG-DOC-001', `Unsupported packaged scaffold entry: ${relativePath}`);
+        }
+    }
+    return files.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+};
+export const verifyPackagedScaffold = async (templatePath) => {
+    const root = await lstat(templatePath);
+    if (!root.isDirectory() || root.isSymbolicLink()) {
+        throw new CliContractError('FG-DOC-001', 'The packaged template scaffold is invalid.');
+    }
+    let manifest;
+    try {
+        manifest = parseScaffoldManifest(JSON.parse(await readFile(path.join(templatePath, '.funnelsgrove-scaffold.json'), 'utf8')));
+    }
+    catch (error) {
+        if (error instanceof CliContractError)
+            throw error;
+        throw new CliContractError('FG-DOC-001', 'The packaged scaffold manifest is unreadable.');
+    }
+    const actualFiles = await collectScaffoldFiles(templatePath);
+    if (actualFiles.length !== manifest.files.length
+        || actualFiles.some((file, index) => {
+            const expected = manifest.files[index];
+            return file.path !== expected.path
+                || file.sha256 !== expected.sha256
+                || file.mode !== expected.mode;
+        })) {
+        throw new CliContractError('FG-DOC-001', 'The packaged template scaffold does not match its manifest.');
+    }
+};
+export const materializePackagedScaffoldAliases = async (stageDir) => {
+    const aliasPath = path.join(stageDir, 'gitignore.template');
+    const gitignorePath = path.join(stageDir, '.gitignore');
+    let alias;
+    try {
+        alias = await lstat(aliasPath);
+    }
+    catch {
+        throw new CliContractError('FG-DOC-001', 'The verified scaffold gitignore alias is missing.');
+    }
+    if (!alias.isFile() || alias.isSymbolicLink()) {
+        throw new CliContractError('FG-DOC-001', 'The verified scaffold gitignore alias is unsafe.');
+    }
+    try {
+        await link(aliasPath, gitignorePath);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new CliContractError('FG-DOC-001', 'The scaffold .gitignore path already exists.');
+        }
+        throw error;
+    }
+    await unlink(aliasPath);
+};
+const defaultCreateHooks = {
+    verifyScaffold: verifyPackagedScaffold,
+    materializeAliases: materializePackagedScaffoldAliases,
+    reskin: reskinFunnel,
+    installManagedFiles: installManagedFunnelFiles,
+    installDependencies: async (stageDir) => runBoundedNpmCommand(stageDir, [
+        'ci',
+        '--ignore-scripts',
+        '--no-audit',
+        '--no-fund',
+        '--workspaces=false',
+    ]),
+    validate: validatePackagedFunnel,
+};
+const localPathExists = async (target) => {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+const reserveOutputPath = async (outputPath) => {
+    try {
+        await mkdir(outputPath);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new CliContractError('FG-CLIENT-001', `Output path was created while the funnel was staged: ${outputPath}`);
+        }
+        throw error;
+    }
+    let handle;
+    try {
+        // Pin the reservation inode so delete/recreate cannot pass via inode reuse.
+        handle = await open(outputPath, 'r');
+        const [handleMetadata, pathMetadata] = await Promise.all([
+            handle.stat(),
+            lstat(outputPath),
+        ]);
+        if (!pathMetadata.isDirectory()
+            || pathMetadata.isSymbolicLink()
+            || pathMetadata.dev !== handleMetadata.dev
+            || pathMetadata.ino !== handleMetadata.ino) {
+            throw new CliContractError('FG-CLIENT-001', `Output path reservation changed while it was opened: ${outputPath}`);
+        }
+        return { dev: handleMetadata.dev, ino: handleMetadata.ino, handle };
+    }
+    catch (error) {
+        await handle?.close();
+        // The pathname could have changed while it was opened, so preserve it unless ownership
+        // was fully established and returned to the caller.
+        throw error;
+    }
+};
+const closeOutputPathReservation = async (reservation) => {
+    const handle = reservation.handle;
+    reservation.handle = null;
+    await handle?.close();
+};
+const removeOwnedOutputReservation = async (outputPath, reservation) => {
+    try {
+        const metadata = await lstat(outputPath);
+        if (!metadata.isDirectory()
+            || metadata.isSymbolicLink()
+            || metadata.dev !== reservation.dev
+            || metadata.ino !== reservation.ino
+            || (await readdir(outputPath)).length > 0) {
+            return;
+        }
+        await rmdir(outputPath);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
+            throw error;
+    }
+};
+const assertOwnedOutputReservation = async (outputPath, reservation, { requireEmpty = true } = {}) => {
+    let metadata;
+    let handleMetadata;
+    try {
+        [metadata, handleMetadata] = await Promise.all([
+            lstat(outputPath),
+            reservation.handle?.stat(),
+        ]);
+    }
+    catch {
+        throw new CliContractError('FG-CLIENT-001', `Output path reservation disappeared before commit: ${outputPath}`);
+    }
+    if (!metadata.isDirectory()
+        || metadata.isSymbolicLink()
+        || !handleMetadata
+        || metadata.dev !== reservation.dev
+        || metadata.ino !== reservation.ino
+        || handleMetadata.dev !== reservation.dev
+        || handleMetadata.ino !== reservation.ino
+        || (requireEmpty && (await readdir(outputPath)).length > 0)) {
+        throw new CliContractError('FG-CLIENT-001', `Output path reservation changed before commit: ${outputPath}`);
+    }
+};
+export async function executeCreateFunnel(input) {
+    assertCanonicalCreateTemplateSlug(input.templateSlug);
+    const templatePath = path.resolve(input.templatePath ?? resolveCreateTemplatePath(input.templateSlug));
+    const outputPath = path.resolve(input.outputPath);
+    if (await localPathExists(outputPath)) {
+        throw new CliContractError('FG-CLIENT-001', `Output path already exists: ${outputPath}`);
+    }
+    const hooks = input.hooks ?? defaultCreateHooks;
+    await hooks.verifyScaffold(templatePath);
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    const stageRoot = await mkdtemp(path.join(path.dirname(outputPath), `.${path.basename(outputPath)}.fgrove-create-`));
+    const stageDir = path.join(stageRoot, 'project');
+    let outputReservation;
+    try {
+        await cp(templatePath, stageDir, { recursive: true, force: false, errorOnExist: true });
+        await hooks.verifyScaffold(stageDir);
+        await hooks.materializeAliases(stageDir);
+        await hooks.installManagedFiles(stageDir);
+        const updatedFiles = await hooks.reskin(stageDir, input.appName);
+        await hooks.installDependencies(stageDir);
+        const validation = await hooks.validate(stageDir);
+        if (!validation.valid || validation.exitCode !== 0 || validation.diagnostics.length > 0) {
+            throw new FunnelValidationError(validation);
+        }
+        await removeScaffoldTransientPaths(stageDir);
+        outputReservation = await reserveOutputPath(outputPath);
+        await hooks.beforeCommit?.(outputPath);
+        await assertOwnedOutputReservation(outputPath, outputReservation);
+        // Populate the mkdir-owned final directory without replacing its pathname. Besides keeping
+        // the reservation identity intact, this avoids platform-specific directory rename behavior.
+        await cp(stageDir, outputPath, {
+            recursive: true,
+            force: false,
+            errorOnExist: true,
+            mode: fsConstants.COPYFILE_EXCL,
+        });
+        await assertOwnedOutputReservation(outputPath, outputReservation, { requireEmpty: false });
+        await closeOutputPathReservation(outputReservation);
+        outputReservation = undefined;
+        return { outputPath, updatedFiles };
+    }
+    finally {
+        if (outputReservation) {
+            await closeOutputPathReservation(outputReservation);
+            await removeOwnedOutputReservation(outputPath, outputReservation);
+        }
+        await rm(stageRoot, { recursive: true, force: true });
+    }
+}
 const GENERATED_CONFIG_PATH_BY_KIND = {
     offerSets: 'src/config/offer-sets.generated.ts',
     experiments: 'src/config/experiments.generated.ts',
@@ -88,6 +1102,13 @@ export function buildPatchSourceInput(input) {
         deletedPaths: input.deletedPaths,
     };
 }
+export function formatSourceCandidateSyncSuccess(input) {
+    const synced = `${input.syncedFileCount} ${input.syncedFileCount === 1 ? 'file' : 'files'}`;
+    const deleted = input.deletedFileCount > 0
+        ? ` and removed ${input.deletedFileCount} ${input.deletedFileCount === 1 ? 'file' : 'files'}`
+        : '';
+    return `Synced ${synced}${deleted} to draft version ${input.versionId}`;
+}
 export function buildSyncOfferSetPlansInput(input) {
     const offerSet = input.offerSet.trim();
     if (!offerSet) {
@@ -185,6 +1206,18 @@ const readCodeFromStdin = async () => {
         rl.close();
     }
 };
+const readDocsConfirmationFromStdin = async (question) => {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+};
 const getCurrentUser = async (token) => {
     return callApi({
         path: 'auth.me',
@@ -396,7 +1429,7 @@ const syncGeneratedConfigFilesForCli = async (input) => {
     return files;
 };
 const addExamples = (command, examples) => command.addHelpText('after', `\nExamples:\n${examples.map((example) => `  $ ${example}`).join('\n')}`);
-const program = new Command();
+export const program = new Command();
 program
     .name('fgrove')
     .description('FunnelsGrove CLI for editing, syncing, and publishing funnels')
@@ -508,6 +1541,10 @@ addExamples(program
         console.log(`localFunnel\t${manifest.funnelId}`);
         console.log(`localDraft\t${manifest.draftVersionId}`);
     }
+    const legacyDiagnostic = await auditLegacyFunnel(path.resolve(process.cwd(), options.dir));
+    if (legacyDiagnostic) {
+        console.log(`${legacyDiagnostic.code}\t${legacyDiagnostic.message}`);
+    }
 });
 const projectsCommand = addExamples(program.command('projects').description('Manage projects'), [
     'fgrove projects list',
@@ -684,8 +1721,8 @@ const loadProjectAnalyticsContext = async (options) => {
         commandInput: buildAnalyticsCommandInput(options),
     };
 };
-const fetchStepDropoffAnalytics = async (input) => {
-    return callApi({
+const fetchStepDropoffAnalytics = async (input, apiCall = callApi) => {
+    return apiCall({
         path: 'projects.analyticsStepDropoff',
         type: 'query',
         token: input.token,
@@ -699,6 +1736,25 @@ const fetchStepDropoffAnalytics = async (input) => {
         },
     });
 };
+const fetchPublishedFunnelFlow = async (input, apiCall = callApi) => {
+    return apiCall({
+        path: 'projects.publishedFunnelFlow',
+        type: 'query',
+        token: input.token,
+        data: {
+            workspaceId: input.workspaceId,
+            projectId: input.projectId,
+            funnelId: input.funnelId,
+        },
+    });
+};
+export const fetchFunnelPathAnalytics = async (input, apiCall = callApi) => {
+    const [stepDropoff, publishedFunnelFlow] = await Promise.all([
+        fetchStepDropoffAnalytics(input, apiCall),
+        fetchPublishedFunnelFlow(input, apiCall),
+    ]);
+    return { stepDropoff, publishedFunnelFlow };
+};
 addExamples(analyticsCommand
     .command('conversions')
     .description('Download one-day conversion data, full funnel path, and step transitions')
@@ -714,7 +1770,7 @@ addExamples(analyticsCommand
 ])
     .action(async (options) => {
     const context = await loadFunnelAnalyticsContext(options);
-    const [overview, stepDropoff] = await Promise.all([
+    const [overview, pathAnalytics] = await Promise.all([
         callApi({
             path: 'projects.analyticsOverview',
             type: 'query',
@@ -729,7 +1785,7 @@ addExamples(analyticsCommand
                 limit: 20_000,
             },
         }),
-        fetchStepDropoffAnalytics({
+        fetchFunnelPathAnalytics({
             token: context.token,
             workspaceId: context.workspace.id,
             projectId: context.project.id,
@@ -737,6 +1793,7 @@ addExamples(analyticsCommand
             commandInput: context.commandInput,
         }),
     ]);
+    const { stepDropoff, publishedFunnelFlow } = pathAnalytics;
     assertHasConversionData(context.commandInput.date, overview, stepDropoff);
     const payload = buildConversionReportPayload({
         date: context.commandInput.date,
@@ -744,6 +1801,7 @@ addExamples(analyticsCommand
         project: context.project,
         overview,
         stepDropoff,
+        publishedFunnelFlow,
     });
     await writeOrPrintAnalyticsOutput({
         format: context.commandInput.format,
@@ -752,6 +1810,7 @@ addExamples(analyticsCommand
             date: context.commandInput.date,
             overview,
             stepDropoff,
+            publishedFunnelFlow,
         }),
         out: options.out,
     });
@@ -771,19 +1830,20 @@ addExamples(analyticsCommand
 ])
     .action(async (options) => {
     const context = await loadFunnelAnalyticsContext(options);
-    const stepDropoff = await fetchStepDropoffAnalytics({
+    const { stepDropoff, publishedFunnelFlow } = await fetchFunnelPathAnalytics({
         token: context.token,
         workspaceId: context.workspace.id,
         projectId: context.project.id,
         funnelId: context.funnel.id,
         commandInput: context.commandInput,
     });
-    assertHasFunnelPathData(context.commandInput.date, stepDropoff);
+    assertHasFunnelPathData(context.commandInput.date, stepDropoff, publishedFunnelFlow);
     const payload = buildFunnelPathReportPayload({
         date: context.commandInput.date,
         workspaceId: context.workspace.id,
         project: context.project,
         stepDropoff,
+        publishedFunnelFlow,
     });
     await writeOrPrintAnalyticsOutput({
         format: context.commandInput.format,
@@ -791,6 +1851,7 @@ addExamples(analyticsCommand
         table: formatFunnelPathTable({
             date: context.commandInput.date,
             stepDropoff,
+            publishedFunnelFlow,
         }),
         out: options.out,
     });
@@ -918,11 +1979,26 @@ addExamples(syncCommand
     });
     await writeLocalEnvFile(target.sourceDir, result.envFile);
     await ensureGitignore(target.sourceDir);
-    await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
-        workspaceId: target.workspaceId,
-        funnelId: target.funnelId,
-        draftVersionId: result.draftVersionId,
-    }));
+    await runSyncDownLocalLifecycle({
+        recoverMigration: async () => recoverStepContractV2Migration(target.sourceDir),
+        recoverDocs: async () => recoverTemplateDocs(target.sourceDir),
+        refreshDocs: async () => {
+            const docs = await executeDocsCommand({
+                targetDir: target.sourceDir,
+                options: { json: true },
+            });
+            if (docs.exitCode !== 0) {
+                const output = JSON.parse(docs.output);
+                const diagnostic = output.diagnostics?.[0];
+                throw new CliContractError(diagnostic?.code ?? 'FG-DOC-001', diagnostic?.message ?? 'Managed documentation refresh failed after sync down.');
+            }
+        },
+        writeSyncState: async () => writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
+            workspaceId: target.workspaceId,
+            funnelId: target.funnelId,
+            draftVersionId: result.draftVersionId,
+        })),
+    });
     console.log(`Synced ${result.files.length} files to ${target.sourceDir}`);
     console.log(`Wrote ${formatGeneratedFileCount(generatedFiles.length)}`);
 });
@@ -971,6 +2047,8 @@ addExamples(syncCommand
     'fgrove sync up --dir ./claimbee-ios --message "Update paywall"',
 ])
     .action(async (options) => {
+    const sourceDir = path.resolve(process.cwd(), options.dir);
+    await assertFunnelValidForMutation(sourceDir);
     const token = await readAuthToken();
     const target = await resolveSyncTarget({
         token,
@@ -1001,33 +2079,63 @@ addExamples(syncCommand
         return;
     }
     let result = null;
+    let uploadedManifestFiles = null;
     let syncedFileCount = 0;
     let deletedFileCount = 0;
     if (changes) {
+        uploadedManifestFiles = changes.currentManifest.files;
         console.log(formatSyncUploadSummary(changes).join('\n'));
-        const batches = chunkChangedSourceFiles(changes);
-        let baseDraftVersionId = changes.currentManifest.draftVersionId;
-        for (const batch of batches) {
-            result = await callApi({
-                path: 'funnels.patchSource',
-                type: 'mutation',
-                token,
-                data: buildPatchSourceInput({
-                    workspaceId: target.workspaceId,
-                    funnelId: target.funnelId,
-                    message: options.message,
-                    baseDraftVersionId,
-                    files: batch.files,
-                    deletedPaths: batch.deletedPaths,
+        const cancellation = new AbortController();
+        const cancel = () => cancellation.abort();
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+        try {
+            const candidateResult = await runSourceCandidateSync({
+                workspaceId: target.workspaceId,
+                funnelId: target.funnelId,
+                baseDraftVersionId: changes.currentManifest.draftVersionId,
+                message: options.message,
+                operations: buildSourceCandidateOperations({
+                    previousFiles: target.manifest?.files ?? [],
+                    files: changes.files,
+                    deletedPaths: changes.deletedPaths,
                 }),
+                signal: cancellation.signal,
+                api: {
+                    begin: (input) => beginFunnelSourceCandidate({
+                        apiUrl: getApiUrl(),
+                        token,
+                        signal: cancellation.signal,
+                    }, input),
+                    stage: (input) => stageFunnelSourceCandidate({
+                        apiUrl: getApiUrl(),
+                        token,
+                        signal: cancellation.signal,
+                    }, input),
+                    finalize: (input) => finalizeFunnelSourceCandidate({
+                        apiUrl: getApiUrl(),
+                        token,
+                        signal: cancellation.signal,
+                    }, input),
+                    abort: (input) => abortFunnelSourceCandidate({
+                        apiUrl: getApiUrl(),
+                        token,
+                    }, input),
+                },
             });
-            baseDraftVersionId = result.versionId;
-            syncedFileCount += result.syncedFiles.length;
-            deletedFileCount += result.deletedFiles?.length || 0;
+            result = { versionId: candidateResult.versionId };
+        }
+        finally {
+            process.off('SIGINT', cancel);
+            process.off('SIGTERM', cancel);
         }
+        syncedFileCount = changes.files.length;
+        deletedFileCount = changes.deletedPaths.length;
     }
     else {
-        const files = await collectSourceFiles(target.sourceDir);
+        const snapshot = await collectSourceSnapshot(target.sourceDir);
+        const files = snapshot.sourceFiles;
+        uploadedManifestFiles = snapshot.manifestFiles;
         console.log(formatSyncUploadSummary({ deletedPaths: [], files }).join('\n'));
         result = await callApi({
             path: 'funnels.importSource',
@@ -1040,24 +2148,31 @@ addExamples(syncCommand
                 files,
             },
         });
-        syncedFileCount = result.syncedFiles.length;
+        syncedFileCount = result.syncedFiles?.length ?? files.length;
         deletedFileCount = result.deletedFiles?.length || 0;
     }
     if (!result) {
         throw new Error('No sync result returned.');
     }
-    await writeSyncManifest(target.sourceDir, await buildSyncManifest(target.sourceDir, {
+    if (!uploadedManifestFiles) {
+        throw new Error('No uploaded source snapshot was recorded.');
+    }
+    await writeSyncManifest(target.sourceDir, buildCommittedSyncManifest({
         workspaceId: target.workspaceId,
         funnelId: target.funnelId,
         draftVersionId: result.versionId,
+        files: uploadedManifestFiles,
     }));
     await syncGitHubDraftForCli({
         token,
         workspaceId: target.workspaceId,
         funnelId: target.funnelId,
     });
-    const deletedSummary = deletedFileCount > 0 ? ` and removed ${deletedFileCount} files` : '';
-    console.log(`Synced ${syncedFileCount} files${deletedSummary} to draft v${result.versionSeq} (${result.versionId})`);
+    console.log(formatSourceCandidateSyncSuccess({
+        syncedFileCount,
+        deletedFileCount,
+        versionId: result.versionId,
+    }));
 });
 addExamples(program
     .command('publish')
@@ -1072,13 +2187,6 @@ addExamples(program
     'fgrove publish --env production --domain claimbee.example.com --message "Launch"',
 ])
     .action(async (options) => {
-    const token = await readAuthToken();
-    const target = await resolveSyncTarget({
-        token,
-        workspace: options.workspace,
-        funnel: options.funnel,
-        dir: options.dir,
-    });
     const publishEnv = options.env.trim().toLowerCase();
     if (publishEnv !== 'preview' && publishEnv !== 'production') {
         throw new Error('--env must be preview or production');
@@ -1086,6 +2194,15 @@ addExamples(program
     if (publishEnv === 'production' && !options.domain?.trim()) {
         throw new Error('--domain is required when publishing production');
     }
+    const sourceDir = path.resolve(process.cwd(), options.dir);
+    await assertFunnelValidForMutation(sourceDir);
+    const token = await readAuthToken();
+    const target = await resolveSyncTarget({
+        token,
+        workspace: options.workspace,
+        funnel: options.funnel,
+        dir: options.dir,
+    });
     await syncGitHubDraftForCli({
         token,
         workspaceId: target.workspaceId,
@@ -1234,49 +2351,93 @@ addExamples(githubCommand
     });
     printValueRows(formatGitHubJobRows(result));
 });
+addExamples(program
+    .command('validate')
+    .description('Validate a local funnel against the current authoring contract')
+    .option('--dir <path>', 'Local funnel directory', '.')
+    .option('--json', 'Emit one machine-readable validation object'), [
+    'fgrove validate',
+    'fgrove validate --dir ./claimbee-ios --json',
+])
+    .action(async (options) => {
+    const result = await executeValidateCommand({
+        targetDir: path.resolve(process.cwd(), options.dir),
+        json: options.json,
+    });
+    process.stdout.write(result.output);
+    process.exitCode = result.exitCode;
+});
+const migrateCommand = program.command('migrate').description('Migrate local funnel contracts');
+addExamples(migrateCommand
+    .command('step-contract')
+    .description('Plan or apply the version-3 step contract migration')
+    .requiredOption('--to <version>', 'Target step contract version')
+    .option('--dir <path>', 'Local funnel directory', '.')
+    .option('--check', 'Plan the migration without writing (default)')
+    .option('--apply', 'Apply the migration transactionally')
+    .option('--json', 'Emit one machine-readable migration object'), [
+    'fgrove migrate step-contract --to 3',
+    'fgrove migrate step-contract --to 3 --apply',
+])
+    .action(async (options) => {
+    const result = await executeStepContractMigrationCommand({
+        targetDir: path.resolve(process.cwd(), options.dir),
+        to: options.to,
+        options,
+    });
+    process.stdout.write(result.output);
+    process.exitCode = result.exitCode;
+});
 addExamples(program
     .command('docs')
     .description('Install or refresh local funnel editing docs in a funnel directory')
-    .option('--dir <path>', 'Local funnel directory', '.'), [
+    .option('--dir <path>', 'Local funnel directory', '.')
+    .option('--check', 'Report documentation drift without writing')
+    .option('--diff', 'Show proposed managed documentation changes')
+    .option('--resolve <path>', 'Resolve one conflicted managed documentation path')
+    .option('--replace-managed', 'Confirm that --resolve may replace the managed path')
+    .option('--json', 'Emit machine-readable documentation status'), [
     'fgrove docs',
     'fgrove docs --dir ./claimbee-ios',
+    'fgrove docs --check --json',
+    'fgrove docs --diff',
 ])
     .action(async (options) => {
     const targetDir = path.resolve(process.cwd(), options.dir);
-    const copiedFiles = await syncTemplateDocs(resolveTemplateDocsPath(), targetDir);
-    console.log(`Synced ${copiedFiles.length} docs files to ${targetDir}`);
+    const result = await executeDocsCommand({
+        targetDir,
+        options,
+        auditLegacy: auditLegacyFunnel,
+        isTTY: process.stdin.isTTY === true && process.stdout.isTTY === true,
+        prompt: readDocsConfirmationFromStdin,
+    });
+    process.stdout.write(result.output);
+    process.exitCode = result.exitCode;
 });
 addExamples(program
     .command('create')
-    .description('Create a new funnel from a template')
-    .requiredOption('--from <template>', 'Template slug from rag-catalog')
+    .description('Create a new funnel from the canonical funnel template')
+    .option('--from <template>', 'Template slug; defaults to the canonical funnel-template', CANONICAL_CREATE_TEMPLATE_SLUG)
     .requiredOption('--app <name>', 'Your app name')
     .option('--output <dir>', 'Output directory'), [
-    'fgrove create --from headway-funnel --app ClaimBee',
-    'fgrove create --from promova --app ClaimBee --output ./claimbee-funnel',
+    'fgrove create --app ClaimBee',
+    'fgrove create --app ClaimBee --output ./claimbee-funnel',
 ])
     .action(async (options) => {
     const { from: templateSlug, app: appName, output } = options;
-    if (!isKnownTemplate(templateSlug)) {
-        console.error(`Unknown template "${templateSlug}". Available templates:\n${KNOWN_TEMPLATE_SLUGS.map((s) => `  - ${s}`).join('\n')}`);
-        process.exit(1);
-    }
-    const templatePath = resolveTemplatePath(templateSlug);
+    assertCanonicalCreateTemplateSlug(templateSlug);
     const outputDir = output ?? `./${toKebabCase(appName)}-funnel`;
     const outputPath = path.resolve(process.cwd(), outputDir);
     console.log(`Creating funnel from "${templateSlug}" for "${appName}"...`);
-    try {
-        await cp(templatePath, outputPath, { recursive: true });
-    }
-    catch (err) {
-        console.error(`Failed to copy template: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
-    }
-    const updated = await reskinFunnel(outputPath, appName);
+    const result = await executeCreateFunnel({
+        templateSlug,
+        outputPath,
+        appName,
+    });
     console.log(`\nCreated funnel at ${outputDir}`);
-    if (updated.length > 0) {
-        console.log(`Updated ${updated.length} files with "${appName}" branding:`);
-        for (const file of updated) {
+    if (result.updatedFiles.length > 0) {
+        console.log(`Updated ${result.updatedFiles.length} files with "${appName}" branding:`);
+        for (const file of result.updatedFiles) {
             console.log(`  - ${file}`);
         }
     }