@funnelsgrove/cli 0.1.263 → 0.1.265

package/README.md

@@ -123,6 +123,7 @@ Analytics workflow:
 fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11
 fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11
 fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11
+fgrove analytics versions --project claimbee --funnel claimbee-ios
 fgrove analytics cohort --project claimbee --date 2026-06-11
 ```
 
@@ -132,7 +133,16 @@ Each analytics command accepts `--format table|json`, `--out <path>`, `--workspa
 fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out conversions.json
 ```
 
-`conversions` downloads the one-day conversion totals, primary conversion metrics, full funnel path rows, and step transitions. `funnel-path` focuses on the ordered path report. `transitions` focuses on step-by-step advanced/drop-off counts. `cohort` downloads synced marketing cohort economics for the day. If the requested day has no synced data, or cohort source data is incomplete, the CLI exits non-zero with a human-readable explanation.
+`conversions` downloads conversion totals, primary conversion metrics, full funnel path rows, and step transitions. `funnel-path` focuses on the ordered path report. `transitions` focuses on step-by-step advanced/drop-off counts. `cohort` downloads synced marketing cohort economics for the day. If the requested period has no synced data, or cohort source data is incomplete, the CLI exits non-zero with a human-readable explanation.
+
+`conversions`, `funnel-path`, and `transitions` report one day with `--date`, or a range with `--from` and `--to` (inclusive, totals for the whole range). They report the current Journey Version by default, like Funnel Analytics in the console. Traffic from before the last structural change belongs to an older Journey Version: list the versions with `versions`, then pass `--journey-version <id>`:
+
+```bash
+fgrove analytics versions --project claimbee --funnel claimbee-ios
+fgrove analytics transitions --project claimbee --funnel claimbee-ios --from 2026-06-01 --to 2026-06-14 --journey-version <journey-version-id>
+```
+
+`versions` lists each Journey Version newest first with its id, start time, active days, and visitors on those days. Active days are dates in `--timezone` (the API default, America/Los_Angeles, when omitted); the day a version replaced its predecessor belongs to both, and each version counts only its own visitors. An explicit version reports its own metrics and its own step structure. `--journey-version all` counts every version and orders `funnel-path` by the current published flow, so steps that exist only in older versions appear in `transitions` but not in `funnel-path`. JSON reports include `from`, `to`, and a `journeyVersion` object (`id`, `seq`, `label`, `startedAt`, `isCurrent`); `date` is set only for a one-day report. Table titles end with the reported version, for example `Journey 2 (current)`. The `overview` block of `conversions` always covers all Journey Versions.
 
 The package also keeps the longer `funnelsgrove` command as a compatibility alias.
 

package/dist/analyticsOutput.d.ts

@@ -53,20 +53,8 @@ export type AnalyticsStepDropoffResponse = {
         slug: string;
     };
     version: {
-        selected: {
-            id: string;
-            seq: number;
-            message: string | null;
-            publishedAt: string | null;
-            isCurrent: boolean;
-        } | null;
-        options: Array<{
-            id: string;
-            seq: number;
-            message: string | null;
-            publishedAt: string | null;
-            isCurrent: boolean;
-        }>;
+        selected: AnalyticsJourneyVersionOption | null;
+        options: AnalyticsJourneyVersionOption[];
     };
     totals: Record<string, number>;
     metrics: Array<{
@@ -83,6 +71,30 @@ export type AnalyticsStepDropoffResponse = {
     steps: AnalyticsStepTransition[];
     flow: AnalyticsFunnelFlow | null;
 };
+export type AnalyticsJourneyVersionOption = {
+    id: string;
+    seq: number;
+    message: string | null;
+    publishedAt: string | null;
+    isCurrent: boolean;
+};
+export type AnalyticsReportJourneyVersion = {
+    id: string;
+    seq: number | null;
+    label: string;
+    startedAt: string | null;
+    isCurrent: boolean;
+};
+export type AnalyticsJourneyVersionRow = {
+    id: string;
+    seq: number;
+    label: string;
+    isCurrent: boolean;
+    startedAt: string | null;
+    activeFrom: string | null;
+    activeTo: string | null;
+    visitors: number | null;
+};
 export type AnalyticsStepTransition = {
     stepId: string;
     stepName: string | null;
@@ -153,11 +165,32 @@ type ReportContext = {
     workspaceId: string;
     project: AnalyticsProjectSummary;
 };
-export declare const parseAnalyticsDate: (value: string) => ParsedAnalyticsDate;
+type FunnelReportContext = {
+    period: AnalyticsPeriod;
+    journeyVersion: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    stepDropoff: AnalyticsStepDropoffResponse;
+};
+export declare const parseAnalyticsDate: (value: string, flag?: string) => ParsedAnalyticsDate;
+export type AnalyticsPeriod = {
+    date: string | null;
+    from: string;
+    to: string;
+    label: string;
+};
+export declare const parseAnalyticsPeriod: (input: {
+    date?: string;
+    from?: string;
+    to?: string;
+}) => AnalyticsPeriod & {
+    fromIso: string;
+    toIso: string;
+};
 export declare const normalizeAnalyticsOutputFormat: (value: string | undefined) => AnalyticsOutputFormat;
 export declare const assertHasConversionData: (date: string, overview: AnalyticsOverviewResponse, stepDropoff: AnalyticsStepDropoffResponse) => void;
 export declare const assertHasTransitionData: (date: string, stepDropoff: AnalyticsStepDropoffResponse) => void;
-export declare const assertHasFunnelPathData: (date: string, stepDropoff: AnalyticsStepDropoffResponse, publishedFunnelFlow: PublishedFunnelFlowResponse) => void;
+export declare const assertHasFunnelPathData: (date: string, stepDropoff: AnalyticsStepDropoffResponse, pathFlow: AnalyticsFunnelFlow | null) => void;
 export declare const assertHasCohortData: (date: string, report: MarketingCohortPerformanceReport) => void;
 export declare const buildTransitionRows: (stepDropoff: AnalyticsStepDropoffResponse) => {
     stepId: string;
@@ -168,7 +201,7 @@ export declare const buildTransitionRows: (stepDropoff: AnalyticsStepDropoffResp
     dropoffs: number;
     dropoffRate: number;
 }[];
-export declare const buildFunnelPathRows: (stepDropoff: AnalyticsStepDropoffResponse, publishedFunnelFlow: PublishedFunnelFlowResponse) => {
+export declare const buildFunnelPathRows: (stepDropoff: AnalyticsStepDropoffResponse, pathFlow: AnalyticsFunnelFlow | null) => {
     stepId: string;
     path: string;
     label: string;
@@ -178,20 +211,11 @@ export declare const buildFunnelPathRows: (stepDropoff: AnalyticsStepDropoffResp
     dropoffs: number;
     dropoffRate: number;
 }[];
-export declare const buildConversionReportPayload: (input: ReportContext & {
+export declare const journeyVersionLabel: (version: Pick<AnalyticsJourneyVersionOption, "seq">) => string;
+export declare const buildConversionReportPayload: (input: FunnelReportContext & {
     overview: AnalyticsOverviewResponse;
-    stepDropoff: AnalyticsStepDropoffResponse;
-    publishedFunnelFlow: PublishedFunnelFlowResponse;
+    pathFlow: AnalyticsFunnelFlow | null;
 }) => {
-    generatedAt: string;
-    date: string;
-    workspaceId: string;
-    project: AnalyticsProjectSummary;
-    funnel: {
-        id: string;
-        name: string;
-        slug: string;
-    };
     overview: AnalyticsOverviewResponse;
     totals: Record<string, number>;
     metrics: {
@@ -224,13 +248,10 @@ export declare const buildConversionReportPayload: (input: ReportContext & {
         dropoffs: number;
         dropoffRate: number;
     }[];
-};
-export declare const buildFunnelPathReportPayload: (input: ReportContext & {
-    stepDropoff: AnalyticsStepDropoffResponse;
-    publishedFunnelFlow: PublishedFunnelFlowResponse;
-}) => {
     generatedAt: string;
-    date: string;
+    date: string | null;
+    from: string;
+    to: string;
     workspaceId: string;
     project: AnalyticsProjectSummary;
     funnel: {
@@ -238,6 +259,11 @@ export declare const buildFunnelPathReportPayload: (input: ReportContext & {
         name: string;
         slug: string;
     };
+    journeyVersion: AnalyticsReportJourneyVersion | null;
+};
+export declare const buildFunnelPathReportPayload: (input: FunnelReportContext & {
+    pathFlow: AnalyticsFunnelFlow | null;
+}) => {
     funnelPath: {
         stepId: string;
         path: string;
@@ -248,12 +274,10 @@ export declare const buildFunnelPathReportPayload: (input: ReportContext & {
         dropoffs: number;
         dropoffRate: number;
     }[];
-};
-export declare const buildTransitionReportPayload: (input: ReportContext & {
-    stepDropoff: AnalyticsStepDropoffResponse;
-}) => {
     generatedAt: string;
-    date: string;
+    date: string | null;
+    from: string;
+    to: string;
     workspaceId: string;
     project: AnalyticsProjectSummary;
     funnel: {
@@ -261,6 +285,9 @@ export declare const buildTransitionReportPayload: (input: ReportContext & {
         name: string;
         slug: string;
     };
+    journeyVersion: AnalyticsReportJourneyVersion | null;
+};
+export declare const buildTransitionReportPayload: (input: FunnelReportContext) => {
     transitions: {
         stepId: string;
         step: string;
@@ -270,6 +297,18 @@ export declare const buildTransitionReportPayload: (input: ReportContext & {
         dropoffs: number;
         dropoffRate: number;
     }[];
+    generatedAt: string;
+    date: string | null;
+    from: string;
+    to: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    funnel: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    journeyVersion: AnalyticsReportJourneyVersion | null;
 };
 export declare const buildCohortReportPayload: (input: ReportContext & {
     cohort: MarketingCohortPerformanceReport;
@@ -285,21 +324,34 @@ export declare const buildCohortReportPayload: (input: ReportContext & {
     } | null;
 };
 export declare const formatAnalyticsJson: (payload: unknown) => string;
-export declare const formatTransitionsTable: (input: {
-    date: string;
-    stepDropoff: AnalyticsStepDropoffResponse;
+type FunnelReportTableInput = Pick<FunnelReportContext, 'period' | 'journeyVersion' | 'stepDropoff'>;
+export declare const formatTransitionsTable: (input: FunnelReportTableInput) => string;
+export declare const formatFunnelPathTable: (input: FunnelReportTableInput & {
+    pathFlow: AnalyticsFunnelFlow | null;
 }) => string;
-export declare const formatFunnelPathTable: (input: {
-    date: string;
-    stepDropoff: AnalyticsStepDropoffResponse;
-    publishedFunnelFlow: PublishedFunnelFlowResponse;
-}) => string;
-export declare const formatConversionsTable: (input: {
-    date: string;
+export declare const formatConversionsTable: (input: FunnelReportTableInput & {
     overview: AnalyticsOverviewResponse;
-    stepDropoff: AnalyticsStepDropoffResponse;
-    publishedFunnelFlow: PublishedFunnelFlowResponse;
+    pathFlow: AnalyticsFunnelFlow | null;
 }) => string;
+type JourneyVersionsReport = {
+    funnel: AnalyticsStepDropoffResponse['funnel'];
+    versions: AnalyticsJourneyVersionRow[];
+};
+export declare const buildJourneyVersionsReportPayload: (input: JourneyVersionsReport & {
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+}) => {
+    generatedAt: string;
+    workspaceId: string;
+    project: AnalyticsProjectSummary;
+    funnel: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    versions: AnalyticsJourneyVersionRow[];
+};
+export declare const formatJourneyVersionsTable: (input: JourneyVersionsReport) => string;
 export declare const formatCohortTable: (input: {
     date: string;
     cohort: MarketingCohortPerformanceReport;

package/dist/analyticsOutput.js

@@ -1,8 +1,8 @@
-export const parseAnalyticsDate = (value) => {
+export const parseAnalyticsDate = (value, flag = '--date') => {
     const trimmed = value.trim();
     const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
     if (!match) {
-        throw new Error('Expected --date in YYYY-MM-DD format.');
+        throw new Error(`Expected ${flag} in YYYY-MM-DD format.`);
     }
     const year = Number(match[1]);
     const month = Number(match[2]);
@@ -13,7 +13,7 @@ export const parseAnalyticsDate = (value) => {
         parsed.getUTCMonth() + 1 === month &&
         parsed.getUTCDate() === day;
     if (!isRealDate) {
-        throw new Error('Expected --date to be a real calendar date.');
+        throw new Error(`Expected ${flag} to be a real calendar date.`);
     }
     return {
         date: trimmed,
@@ -21,6 +21,32 @@ export const parseAnalyticsDate = (value) => {
         toIso: `${trimmed}T23:59:59.999Z`,
     };
 };
+export const parseAnalyticsPeriod = (input) => {
+    if (input.date !== undefined) {
+        if (input.from !== undefined || input.to !== undefined) {
+            throw new Error('Use either --date or --from with --to, not both.');
+        }
+        const day = parseAnalyticsDate(input.date);
+        return { date: day.date, from: day.date, to: day.date, label: day.date, fromIso: day.fromIso, toIso: day.toIso };
+    }
+    if (input.from === undefined || input.to === undefined) {
+        throw new Error('Pass --date, or --from together with --to.');
+    }
+    const from = parseAnalyticsDate(input.from, '--from');
+    const to = parseAnalyticsDate(input.to, '--to');
+    if (from.date > to.date) {
+        throw new Error('--from must be on or before --to.');
+    }
+    const date = from.date === to.date ? from.date : null;
+    return {
+        date,
+        from: from.date,
+        to: to.date,
+        label: date ?? `${from.date}..${to.date}`,
+        fromIso: from.fromIso,
+        toIso: to.toIso,
+    };
+};
 export const normalizeAnalyticsOutputFormat = (value) => {
     const normalized = (value || 'table').trim().toLowerCase();
     if (normalized === 'table' || normalized === 'json') {
@@ -40,6 +66,9 @@ const hasPositiveNumber = (value) => {
     }
     return false;
 };
+const olderJourneyVersionHint = (stepDropoff) => (stepDropoff.version.selected?.isCurrent && stepDropoff.version.options.length > 1
+    ? ' Traffic on these dates may belong to an older journey version: list them with `fgrove analytics versions` and pass --journey-version.'
+    : '');
 export const assertHasConversionData = (date, overview, stepDropoff) => {
     if (hasPositiveNumber(overview.totals) ||
         hasPositiveNumber(overview.byDay) ||
@@ -47,19 +76,19 @@ export const assertHasConversionData = (date, overview, stepDropoff) => {
         hasPositiveNumber(stepDropoff.steps)) {
         return;
     }
-    throw new Error(`No synced conversion data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked traffic that day.`);
+    throw new Error(`No synced conversion data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked traffic in that period.${olderJourneyVersionHint(stepDropoff)}`);
 };
 export const assertHasTransitionData = (date, stepDropoff) => {
     if (stepDropoff.steps.length > 0 && hasPositiveNumber(stepDropoff.steps)) {
         return;
     }
-    throw new Error(`No synced step transition data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked step traffic that day.`);
+    throw new Error(`No synced step transition data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked step traffic in that period.${olderJourneyVersionHint(stepDropoff)}`);
 };
-export const assertHasFunnelPathData = (date, stepDropoff, publishedFunnelFlow) => {
-    if (buildFunnelPathRows(stepDropoff, publishedFunnelFlow).length > 0) {
+export const assertHasFunnelPathData = (date, stepDropoff, pathFlow) => {
+    if (buildFunnelPathRows(stepDropoff, pathFlow).length > 0) {
         return;
     }
-    throw new Error(`No synced full funnel path data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked path traffic that day.`);
+    throw new Error(`No synced full funnel path data found for ${date}. Analytics may not have synced yet, or the funnel had no tracked path traffic in that period.${olderJourneyVersionHint(stepDropoff)}`);
 };
 export const assertHasCohortData = (date, report) => {
     if (report.sourceHealth && !report.sourceHealth.complete) {
@@ -96,12 +125,12 @@ export const buildTransitionRows = (stepDropoff) => [...stepDropoff.steps]
     dropoffs: step.dropoffs,
     dropoffRate: step.dropoffRate,
 }));
-export const buildFunnelPathRows = (stepDropoff, publishedFunnelFlow) => {
-    if (publishedFunnelFlow.status !== 'ready' || !publishedFunnelFlow.flow) {
+export const buildFunnelPathRows = (stepDropoff, pathFlow) => {
+    if (!pathFlow) {
         return [];
     }
     const transitionsByStepId = new Map(stepDropoff.steps.map((step) => [step.stepId, step]));
-    return [...publishedFunnelFlow.flow.steps]
+    return [...pathFlow.steps]
         .sort((left, right) => left.stepOrder - right.stepOrder || left.stepId.localeCompare(right.stepId))
         .map((flowStep) => {
         const step = transitionsByStepId.get(flowStep.stepId);
@@ -118,32 +147,55 @@ export const buildFunnelPathRows = (stepDropoff, publishedFunnelFlow) => {
         };
     });
 };
-export const buildConversionReportPayload = (input) => ({
+export const journeyVersionLabel = (version) => `Journey ${version.seq}`;
+const describeReportJourneyVersion = (input) => {
+    if (input.journeyVersion === 'all') {
+        return { id: 'all', seq: null, label: 'All journey versions', startedAt: null, isCurrent: false };
+    }
+    const selected = input.stepDropoff.version.selected;
+    return selected
+        ? {
+            id: selected.id,
+            seq: selected.seq,
+            label: journeyVersionLabel(selected),
+            startedAt: selected.publishedAt,
+            isCurrent: selected.isCurrent,
+        }
+        : null;
+};
+const buildFunnelReportHeader = (input) => ({
     generatedAt: new Date().toISOString(),
-    date: input.date,
+    date: input.period.date,
+    from: input.period.from,
+    to: input.period.to,
     workspaceId: input.workspaceId,
     project: input.project,
     funnel: input.stepDropoff.funnel,
+    journeyVersion: describeReportJourneyVersion(input),
+});
+const formatFunnelReportTitle = (title, input) => {
+    const version = describeReportJourneyVersion(input);
+    return [
+        title,
+        input.period.label,
+        input.stepDropoff.funnel.name,
+        ...(version ? [version.isCurrent ? `${version.label} (current)` : version.label] : []),
+    ].join('\t');
+};
+export const buildConversionReportPayload = (input) => ({
+    ...buildFunnelReportHeader(input),
     overview: input.overview,
     totals: input.stepDropoff.totals,
     metrics: input.stepDropoff.metrics,
-    funnelPath: buildFunnelPathRows(input.stepDropoff, input.publishedFunnelFlow),
+    funnelPath: buildFunnelPathRows(input.stepDropoff, input.pathFlow),
     transitions: buildTransitionRows(input.stepDropoff),
 });
 export const buildFunnelPathReportPayload = (input) => ({
-    generatedAt: new Date().toISOString(),
-    date: input.date,
-    workspaceId: input.workspaceId,
-    project: input.project,
-    funnel: input.stepDropoff.funnel,
-    funnelPath: buildFunnelPathRows(input.stepDropoff, input.publishedFunnelFlow),
+    ...buildFunnelReportHeader(input),
+    funnelPath: buildFunnelPathRows(input.stepDropoff, input.pathFlow),
 });
 export const buildTransitionReportPayload = (input) => ({
-    generatedAt: new Date().toISOString(),
-    date: input.date,
-    workspaceId: input.workspaceId,
-    project: input.project,
-    funnel: input.stepDropoff.funnel,
+    ...buildFunnelReportHeader(input),
     transitions: buildTransitionRows(input.stepDropoff),
 });
 export const buildCohortReportPayload = (input) => ({
@@ -157,7 +209,7 @@ export const buildCohortReportPayload = (input) => ({
 export const formatAnalyticsJson = (payload) => `${JSON.stringify(payload, null, 2)}\n`;
 export const formatTransitionsTable = (input) => {
     const lines = [
-        `Step transitions\t${input.date}\t${input.stepDropoff.funnel.name}`,
+        formatFunnelReportTitle('Step transitions', input),
         'step\tnextStep\tentrants\tadvanced\tdropoffs\tdropoffRate',
     ];
     for (const row of buildTransitionRows(input.stepDropoff)) {
@@ -174,10 +226,10 @@ export const formatTransitionsTable = (input) => {
 };
 export const formatFunnelPathTable = (input) => {
     const lines = [
-        `Full funnel path\t${input.date}\t${input.stepDropoff.funnel.name}`,
+        formatFunnelReportTitle('Full funnel path', input),
         'step\tpath\tusers\tadvanced\tconversionToNext\tdropoffs\tdropoffRate',
     ];
-    for (const row of buildFunnelPathRows(input.stepDropoff, input.publishedFunnelFlow)) {
+    for (const row of buildFunnelPathRows(input.stepDropoff, input.pathFlow)) {
         lines.push([
             row.label,
             row.path,
@@ -194,7 +246,7 @@ export const formatConversionsTable = (input) => {
     const totals = input.stepDropoff.totals;
     const overviewTotals = input.overview.totals;
     const lines = [
-        `Conversions\t${input.date}\t${input.stepDropoff.funnel.name}`,
+        formatFunnelReportTitle('Conversions', input),
         'metric\tvalue',
         ['visitors', formatNumber(totals.visitors ?? overviewTotals.visitors ?? 0)].join('\t'),
         ['quizEntries', formatNumber(totals.quizEntries ?? 0)].join('\t'),
@@ -217,11 +269,31 @@ export const formatConversionsTable = (input) => {
             formatPercent(metric.rate),
         ].join('\t'));
     }
-    lines.push('', formatFunnelPathTable({
-        date: input.date,
-        stepDropoff: input.stepDropoff,
-        publishedFunnelFlow: input.publishedFunnelFlow,
-    }).trimEnd());
+    lines.push('', formatFunnelPathTable(input).trimEnd());
+    return `${lines.join('\n')}\n`;
+};
+export const buildJourneyVersionsReportPayload = (input) => ({
+    generatedAt: new Date().toISOString(),
+    workspaceId: input.workspaceId,
+    project: input.project,
+    funnel: input.funnel,
+    versions: input.versions,
+});
+export const formatJourneyVersionsTable = (input) => {
+    const lines = [
+        `Journey versions\t${input.funnel.name}`,
+        'version\tid\tstartedAt\tactiveFrom\tactiveTo\tvisitors',
+    ];
+    for (const version of input.versions) {
+        lines.push([
+            version.isCurrent ? `${version.label} (current)` : version.label,
+            version.id,
+            version.startedAt || '',
+            version.activeFrom || '',
+            version.activeTo || '',
+            version.visitors === null ? '' : formatNumber(version.visitors),
+        ].join('\t'));
+    }
     return `${lines.join('\n')}\n`;
 };
 const flattenCohortRows = (rows) => rows.flatMap((row) => [row, ...(row.segments || []), ...(row.children || [])]);

package/dist/cli.d.ts

@@ -8,7 +8,7 @@ import { type DocsExitCode } from './docsOutput.js';
 import { type DocsDiagnostic, type DocsStatus } from './docsTransaction.js';
 import { type FunnelValidationExitCode, type FunnelValidationResult } from './diagnosticOutput.js';
 import { type StepContractMigrationApplyResult, type StepContractMigrationCheckResult, type StepContractMigrationTargetVersion, type StepContractMigrationValidationResult } from './stepContractMigration.js';
-import { type AnalyticsOutputFormat, type AnalyticsStepDropoffResponse, type PublishedFunnelFlowResponse } from './analyticsOutput.js';
+import { type AnalyticsFunnelFlow, type AnalyticsJourneyVersionRow, type AnalyticsPeriod, type AnalyticsOutputFormat, type AnalyticsStepDropoffResponse } from './analyticsOutput.js';
 export declare const CANONICAL_CREATE_TEMPLATE_SLUG = "template";
 export declare const SCAFFOLD_TRANSIENT_PATHS: readonly ["node_modules", ".next", "out", "tsconfig.tsbuildinfo", ".funnelsgrove-scaffold.json"];
 export declare class CliContractError extends Error {
@@ -142,6 +142,15 @@ type AnalyticsCommandInput = {
     format: AnalyticsOutputFormat;
     timezone?: string;
 };
+type FunnelAnalyticsCommandInput = {
+    period: AnalyticsPeriod & {
+        fromIso: string;
+        toIso: string;
+    };
+    format: AnalyticsOutputFormat;
+    timezone?: string;
+    journeyVersion: string;
+};
 type SyncTargetIdInput = {
     explicitWorkspaceId?: string;
     explicitFunnelId?: string;
@@ -161,6 +170,14 @@ export declare function buildAnalyticsCommandInput(options: {
     format?: string;
     timezone?: string;
 }): AnalyticsCommandInput;
+export declare function buildFunnelAnalyticsCommandInput(options: {
+    date?: string;
+    from?: string;
+    to?: string;
+    journeyVersion?: string;
+    format?: string;
+    timezone?: string;
+}): FunnelAnalyticsCommandInput;
 export declare function buildPatchSourceInput(input: {
     workspaceId: string;
     funnelId: string;
@@ -289,10 +306,18 @@ type FunnelPathAnalyticsInput = {
     workspaceId: string;
     projectId: string;
     funnelId: string;
-    commandInput: AnalyticsCommandInput;
+    commandInput: FunnelAnalyticsCommandInput;
 };
 export declare const fetchFunnelPathAnalytics: (input: FunnelPathAnalyticsInput, apiCall?: AnalyticsApiCall) => Promise<{
     stepDropoff: AnalyticsStepDropoffResponse;
-    publishedFunnelFlow: PublishedFunnelFlowResponse;
+    pathFlow: AnalyticsFunnelFlow | null;
+}>;
+type JourneyVersionsInput = Pick<FunnelPathAnalyticsInput, 'token' | 'workspaceId' | 'projectId' | 'funnelId'> & {
+    timezone?: string;
+    today: string;
+};
+export declare const fetchJourneyVersions: (input: JourneyVersionsInput, apiCall?: AnalyticsApiCall) => Promise<{
+    funnel: AnalyticsStepDropoffResponse["funnel"];
+    versions: AnalyticsJourneyVersionRow[];
 }>;
 export {};

package/dist/cli.js

@@ -29,7 +29,7 @@ import { applyTemplateDocsUpdate, inspectTemplateDocs, loadBundledDocs, planTemp
 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';
+import { assertHasCohortData, assertHasConversionData, assertHasFunnelPathData, assertHasTransitionData, buildCohortReportPayload, buildConversionReportPayload, buildFunnelPathReportPayload, buildJourneyVersionsReportPayload, buildTransitionReportPayload, formatAnalyticsJson, formatCohortTable, formatConversionsTable, formatFunnelPathTable, formatJourneyVersionsTable, formatTransitionsTable, journeyVersionLabel, normalizeAnalyticsOutputFormat, parseAnalyticsDate, parseAnalyticsPeriod, } from './analyticsOutput.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const toKebabCase = (value) => value
     .trim()
@@ -1115,6 +1115,21 @@ export function buildAnalyticsCommandInput(options) {
         timezone,
     };
 }
+const parseAnalyticsJourneyVersion = (value) => {
+    const normalized = (value || 'current').trim().toLowerCase();
+    if (normalized === 'current' || normalized === 'all' || UUID_PATTERN.test(normalized)) {
+        return normalized;
+    }
+    throw new Error('--journey-version must be current, all, or a journey version id from `fgrove analytics versions`.');
+};
+export function buildFunnelAnalyticsCommandInput(options) {
+    return {
+        period: parseAnalyticsPeriod(options),
+        format: normalizeAnalyticsOutputFormat(options.format),
+        timezone: options.timezone?.trim() || undefined,
+        journeyVersion: parseAnalyticsJourneyVersion(options.journeyVersion),
+    };
+}
 export function buildPatchSourceInput(input) {
     return {
         workspaceId: input.workspaceId,
@@ -2169,9 +2184,10 @@ const analyticsCommand = addExamples(program.command('analytics').description('D
     'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out analytics.json',
     'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11',
     'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11',
+    'fgrove analytics versions --project claimbee --funnel claimbee-ios',
     'fgrove analytics cohort --project claimbee --date 2026-06-11 --format json',
 ]);
-const loadFunnelAnalyticsContext = async (options) => {
+const resolveFunnelAnalyticsTarget = async (options) => {
     const token = await readAuthToken();
     const workspace = await resolveWorkspace(token, options.workspace);
     const project = await resolveAnalyticsProject({
@@ -2189,7 +2205,13 @@ const loadFunnelAnalyticsContext = async (options) => {
         workspace,
         project,
         funnel,
-        commandInput: buildAnalyticsCommandInput(options),
+    };
+};
+const loadFunnelAnalyticsContext = async (options) => {
+    const commandInput = buildFunnelAnalyticsCommandInput(options);
+    return {
+        ...await resolveFunnelAnalyticsTarget(options),
+        commandInput,
     };
 };
 const loadProjectAnalyticsContext = async (options) => {
@@ -2216,8 +2238,9 @@ const fetchStepDropoffAnalytics = async (input, apiCall = callApi) => {
             workspaceId: input.workspaceId,
             projectId: input.projectId,
             funnelId: input.funnelId,
-            from: input.commandInput.from,
-            to: input.commandInput.to,
+            ...(input.commandInput.journeyVersion === 'current' ? {} : { versionId: input.commandInput.journeyVersion }),
+            from: input.commandInput.period.fromIso,
+            to: input.commandInput.period.toIso,
             timezone: input.commandInput.timezone,
         },
     });
@@ -2235,24 +2258,79 @@ const fetchPublishedFunnelFlow = async (input, apiCall = callApi) => {
     });
 };
 export const fetchFunnelPathAnalytics = async (input, apiCall = callApi) => {
+    const { journeyVersion } = input.commandInput;
+    if (journeyVersion !== 'current' && journeyVersion !== 'all') {
+        // An explicit Journey Version reports its own structure and is never
+        // paired with the current published path.
+        const stepDropoff = await fetchStepDropoffAnalytics(input, apiCall);
+        return { stepDropoff, pathFlow: stepDropoff.flow };
+    }
     const [stepDropoff, publishedFunnelFlow] = await Promise.all([
         fetchStepDropoffAnalytics(input, apiCall),
         fetchPublishedFunnelFlow(input, apiCall),
     ]);
-    return { stepDropoff, publishedFunnelFlow };
+    return {
+        stepDropoff,
+        pathFlow: publishedFunnelFlow.status === 'ready' ? publishedFunnelFlow.flow : null,
+    };
 };
-addExamples(analyticsCommand
-    .command('conversions')
-    .description('Download one-day conversion data, full funnel path, and step transitions')
+// The API reads analytics dates in this timezone when a request names none.
+const DEFAULT_ANALYTICS_TIMEZONE = 'America/Los_Angeles';
+const toAnalyticsDate = (value, timezone) => new Intl.DateTimeFormat('en-CA', { timeZone: timezone || DEFAULT_ANALYTICS_TIMEZONE }).format(value);
+export const fetchJourneyVersions = async (input, apiCall = callApi) => {
+    const { today, timezone, ...target } = input;
+    const current = await fetchStepDropoffAnalytics({
+        ...target,
+        commandInput: buildFunnelAnalyticsCommandInput({ date: today, timezone }),
+    }, apiCall);
+    const newestFirst = [...current.version.options].sort((left, right) => right.seq - left.seq);
+    // A version is active from its start day until the next version starts;
+    // version-scoped counts make the shared switch day safe to include in both.
+    const startDate = (startedAt) => (startedAt ? toAnalyticsDate(new Date(startedAt), timezone) : null);
+    const versions = await Promise.all(newestFirst.map(async (version, index) => {
+        const activeFrom = startDate(version.publishedAt);
+        const activeTo = index === 0 ? null : startDate(newestFirst[index - 1].publishedAt);
+        const report = activeFrom
+            ? await fetchStepDropoffAnalytics({
+                ...target,
+                commandInput: buildFunnelAnalyticsCommandInput({
+                    from: activeFrom,
+                    to: activeTo ?? today,
+                    journeyVersion: version.id,
+                    timezone,
+                }),
+            }, apiCall)
+            : null;
+        return {
+            id: version.id,
+            seq: version.seq,
+            label: journeyVersionLabel(version),
+            isCurrent: version.isCurrent,
+            startedAt: version.publishedAt,
+            activeFrom,
+            activeTo,
+            visitors: report ? report.totals.visitors ?? 0 : null,
+        };
+    }));
+    return { funnel: current.funnel, versions };
+};
+const addFunnelReportOptions = (command) => command
     .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
     .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
     .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
-    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
+    .option('--date <yyyy-mm-dd>', 'Analytics date; use instead of --from/--to for one day')
+    .option('--from <yyyy-mm-dd>', 'First analytics date of a range, used with --to')
+    .option('--to <yyyy-mm-dd>', 'Last analytics date of a range, used with --from')
+    .option('--journey-version <id|current|all>', 'Journey version: current, all, or an id from `fgrove analytics versions`', 'current')
     .option('--format <table-or-json>', 'Output format: table or json', 'table')
     .option('--out <path>', 'Write output to a file')
-    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles');
+addExamples(addFunnelReportOptions(analyticsCommand
+    .command('conversions')
+    .description('Download conversion data, full funnel path, and step transitions for a day or date range')), [
     'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11',
     'fgrove analytics conversions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json --out analytics.json',
+    'fgrove analytics conversions --project claimbee --funnel claimbee-ios --from 2026-06-01 --to 2026-06-14 --journey-version all',
 ])
     .action(async (options) => {
     const context = await loadFunnelAnalyticsContext(options);
@@ -2265,8 +2343,8 @@ addExamples(analyticsCommand
                 workspaceId: context.workspace.id,
                 projectId: context.project.id,
                 funnelId: context.funnel.id,
-                from: context.commandInput.from,
-                to: context.commandInput.to,
+                from: context.commandInput.period.fromIso,
+                to: context.commandInput.period.toIso,
                 timezone: context.commandInput.timezone,
                 limit: 20_000,
             },
@@ -2279,81 +2357,66 @@ addExamples(analyticsCommand
             commandInput: context.commandInput,
         }),
     ]);
-    const { stepDropoff, publishedFunnelFlow } = pathAnalytics;
-    assertHasConversionData(context.commandInput.date, overview, stepDropoff);
-    const payload = buildConversionReportPayload({
-        date: context.commandInput.date,
-        workspaceId: context.workspace.id,
-        project: context.project,
-        overview,
+    const { stepDropoff, pathFlow } = pathAnalytics;
+    assertHasConversionData(context.commandInput.period.label, overview, stepDropoff);
+    const report = {
+        period: context.commandInput.period,
+        journeyVersion: context.commandInput.journeyVersion,
         stepDropoff,
-        publishedFunnelFlow,
-    });
+        overview,
+        pathFlow,
+    };
     await writeOrPrintAnalyticsOutput({
         format: context.commandInput.format,
-        payload,
-        table: formatConversionsTable({
-            date: context.commandInput.date,
-            overview,
-            stepDropoff,
-            publishedFunnelFlow,
+        payload: buildConversionReportPayload({
+            ...report,
+            workspaceId: context.workspace.id,
+            project: context.project,
         }),
+        table: formatConversionsTable(report),
         out: options.out,
     });
 });
-addExamples(analyticsCommand
+addExamples(addFunnelReportOptions(analyticsCommand
     .command('funnel-path')
-    .description('Download the full one-day funnel path report')
-    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
-    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
-    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
-    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
-    .option('--format <table-or-json>', 'Output format: table or json', 'table')
-    .option('--out <path>', 'Write output to a file')
-    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    .description('Download the full funnel path report for a day or date range')), [
     'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11',
     'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json',
+    'fgrove analytics funnel-path --project claimbee --funnel claimbee-ios --from 2026-06-01 --to 2026-06-14 --journey-version <journey-version-id>',
 ])
     .action(async (options) => {
     const context = await loadFunnelAnalyticsContext(options);
-    const { stepDropoff, publishedFunnelFlow } = await fetchFunnelPathAnalytics({
+    const { stepDropoff, pathFlow } = 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, publishedFunnelFlow);
-    const payload = buildFunnelPathReportPayload({
-        date: context.commandInput.date,
-        workspaceId: context.workspace.id,
-        project: context.project,
+    assertHasFunnelPathData(context.commandInput.period.label, stepDropoff, pathFlow);
+    const report = {
+        period: context.commandInput.period,
+        journeyVersion: context.commandInput.journeyVersion,
         stepDropoff,
-        publishedFunnelFlow,
-    });
+        pathFlow,
+    };
     await writeOrPrintAnalyticsOutput({
         format: context.commandInput.format,
-        payload,
-        table: formatFunnelPathTable({
-            date: context.commandInput.date,
-            stepDropoff,
-            publishedFunnelFlow,
+        payload: buildFunnelPathReportPayload({
+            ...report,
+            workspaceId: context.workspace.id,
+            project: context.project,
         }),
+        table: formatFunnelPathTable(report),
         out: options.out,
     });
 });
-addExamples(analyticsCommand
+addExamples(addFunnelReportOptions(analyticsCommand
     .command('transitions')
-    .description('Download one-day step transitions and drop-offs')
-    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
-    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
-    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
-    .requiredOption('--date <yyyy-mm-dd>', 'Analytics date')
-    .option('--format <table-or-json>', 'Output format: table or json', 'table')
-    .option('--out <path>', 'Write output to a file')
-    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    .description('Download step transitions and drop-offs for a day or date range')), [
     'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11',
     'fgrove analytics transitions --project claimbee --funnel claimbee-ios --date 2026-06-11 --format json',
+    'fgrove analytics transitions --project claimbee --funnel claimbee-ios --from 2026-06-01 --to 2026-06-14 --journey-version <journey-version-id>',
 ])
     .action(async (options) => {
     const context = await loadFunnelAnalyticsContext(options);
@@ -2364,20 +2427,55 @@ addExamples(analyticsCommand
         funnelId: context.funnel.id,
         commandInput: context.commandInput,
     });
-    assertHasTransitionData(context.commandInput.date, stepDropoff);
-    const payload = buildTransitionReportPayload({
-        date: context.commandInput.date,
-        workspaceId: context.workspace.id,
-        project: context.project,
+    assertHasTransitionData(context.commandInput.period.label, stepDropoff);
+    const report = {
+        period: context.commandInput.period,
+        journeyVersion: context.commandInput.journeyVersion,
         stepDropoff,
-    });
+    };
     await writeOrPrintAnalyticsOutput({
         format: context.commandInput.format,
-        payload,
-        table: formatTransitionsTable({
-            date: context.commandInput.date,
-            stepDropoff,
+        payload: buildTransitionReportPayload({
+            ...report,
+            workspaceId: context.workspace.id,
+            project: context.project,
+        }),
+        table: formatTransitionsTable(report),
+        out: options.out,
+    });
+});
+addExamples(analyticsCommand
+    .command('versions')
+    .description('List journey versions with their active days and visitors')
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--funnel <id-or-slug-or-name>', 'Funnel id, slug, or name')
+    .option('--format <table-or-json>', 'Output format: table or json', 'table')
+    .option('--out <path>', 'Write output to a file')
+    .option('--timezone <iana-timezone>', 'Analytics timezone, for example America/Los_Angeles'), [
+    'fgrove analytics versions --project claimbee --funnel claimbee-ios',
+    'fgrove analytics versions --project claimbee --funnel claimbee-ios --format json',
+])
+    .action(async (options) => {
+    const format = normalizeAnalyticsOutputFormat(options.format);
+    const timezone = options.timezone?.trim() || undefined;
+    const target = await resolveFunnelAnalyticsTarget(options);
+    const report = await fetchJourneyVersions({
+        token: target.token,
+        workspaceId: target.workspace.id,
+        projectId: target.project.id,
+        funnelId: target.funnel.id,
+        timezone,
+        today: toAnalyticsDate(new Date(), timezone),
+    });
+    await writeOrPrintAnalyticsOutput({
+        format,
+        payload: buildJourneyVersionsReportPayload({
+            ...report,
+            workspaceId: target.workspace.id,
+            project: target.project,
         }),
+        table: formatJourneyVersionsTable(report),
         out: options.out,
     });
 });

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.263",
+      "repositoryCliVersion": "0.1.265",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.256",
+        "bundleVersion": "2.0.258",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "afba67a5679827efbd37d706d290e393558d4abf13271b5606e069b1694960e8"
+            "sha256": "e529cbfc0ab172d5168301efcb09e2f7ed7459d3c8c7f27db9198b4ccce069ba"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ac03af2c7446ffefd0acd9e28db1c4d6fa7a04848b1c2a562a3e722d16f9a98a"
+            "sha256": "4cc4c05d6f0048162c5fc0a534050e11a8c14585783a7fae61a98462e880cc65"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.262",
+      "repositoryCliVersion": "0.1.264",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.255",
+        "bundleVersion": "2.0.257",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "d733607091b48f87b667e43c68984116b4f5c82cdc5ca04af688ccc7160c0e36"
+            "sha256": "a299775572c2aac26afb8905d770417e1dd2f5a0ff1026d5212ba080ef1d5e82"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "3bb975a7ced201ae60030e863b150e51fc8b5d496e0d0fb93fc92c48953e0c39"
+            "sha256": "693f0649aedbb45a62b88661d482cbafeb01eb3fdb5279b473732b1a0c83e8ac"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.261",
+      "repositoryCliVersion": "0.1.263",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.254",
+        "bundleVersion": "2.0.256",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "92a56af5007b51ced39aec37795aeab3a94552e1d242c13f3dbd056a353ebdef"
+            "sha256": "afba67a5679827efbd37d706d290e393558d4abf13271b5606e069b1694960e8"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "68a262476d89d22cf3206316ccbf935ae3cf1686a7d951f2024cfffc9e93384d"
+            "sha256": "ac03af2c7446ffefd0acd9e28db1c4d6fa7a04848b1c2a562a3e722d16f9a98a"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.260",
+      "repositoryCliVersion": "0.1.262",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.253",
+        "bundleVersion": "2.0.255",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "3f4c093fce58c01bd66604a5dd371bdd1f3cf3743bc7e556e2a1e871e0b24866"
+            "sha256": "d733607091b48f87b667e43c68984116b4f5c82cdc5ca04af688ccc7160c0e36"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "dea21f974e2601112ec12aac3493ece0c0955eb612c6eb790874add999a11822"
+            "sha256": "3bb975a7ced201ae60030e863b150e51fc8b5d496e0d0fb93fc92c48953e0c39"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.259",
+      "repositoryCliVersion": "0.1.261",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.252",
+        "bundleVersion": "2.0.254",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "d1ca070960305b60bc78dae50355a59c8c068b59ea161b4acc9403ec1848b04c"
+            "sha256": "92a56af5007b51ced39aec37795aeab3a94552e1d242c13f3dbd056a353ebdef"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "b683d23440209016d94de8319f46040e4e174567d3cc0a1f8ede194c29cc3e76"
+            "sha256": "68a262476d89d22cf3206316ccbf935ae3cf1686a7d951f2024cfffc9e93384d"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.258",
+      "repositoryCliVersion": "0.1.260",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.251",
+        "bundleVersion": "2.0.253",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "871dd4aa34ed91d4bf366e8ca7f0882f78d9ae1098ee2c587064743ecd81feba"
+            "sha256": "3f4c093fce58c01bd66604a5dd371bdd1f3cf3743bc7e556e2a1e871e0b24866"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "c41f35a830e5a58e5896f76afb97d4313308734ad93c0cc3636b4495927d170e"
+            "sha256": "dea21f974e2601112ec12aac3493ece0c0955eb612c6eb790874add999a11822"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.256",
+      "repositoryCliVersion": "0.1.259",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.249",
+        "bundleVersion": "2.0.252",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "800853d3acaf8ccb9f56891b7d83a1a17c8fe8e63f40bc46029bc7b76cdb2ddd"
+            "sha256": "d1ca070960305b60bc78dae50355a59c8c068b59ea161b4acc9403ec1848b04c"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -935,7 +935,7 @@
           },
           {
             "path": "docs/funnelsgrove/qa/local.md",
-            "sha256": "97da7e26c5dbe8f63e654e4e0a035a4ecfbb9bcfd80db67d45c627141d6a2756"
+            "sha256": "c8a83c33cd33bea6d5efde91d7c479505f77077f16de8073064baacbfad98e5f"
           },
           {
             "path": "docs/funnelsgrove/qa/paywall-checkout.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "5358d40a9accbc34e79924d07053d17f74915bb90db963756c208c00e90541e8"
+            "sha256": "b683d23440209016d94de8319f46040e4e174567d3cc0a1f8ede194c29cc3e76"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.263",
+  "version": "0.1.265",
   "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.256",
+  "bundleVersion": "2.0.258",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "afba67a5679827efbd37d706d290e393558d4abf13271b5606e069b1694960e8"
+      "sha256": "e529cbfc0ab172d5168301efcb09e2f7ed7459d3c8c7f27db9198b4ccce069ba"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "ac03af2c7446ffefd0acd9e28db1c4d6fa7a04848b1c2a562a3e722d16f9a98a"
+      "sha256": "4cc4c05d6f0048162c5fc0a534050e11a8c14585783a7fae61a98462e880cc65"
     }
   ]
 }

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/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.25.0`, then `@funnelsgrove/analytics` `0.7.0`, then `@funnelsgrove/payments` `0.27.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.263`, 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.25.0`, then `@funnelsgrove/analytics` `0.7.0`, then `@funnelsgrove/payments` `0.28.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.265`, 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.256",
+  "bundleVersion": "2.0.258",
   "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.256",
+  "bundleVersion": "2.0.258",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "afba67a5679827efbd37d706d290e393558d4abf13271b5606e069b1694960e8"
+      "sha256": "e529cbfc0ab172d5168301efcb09e2f7ed7459d3c8c7f27db9198b4ccce069ba"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "ac03af2c7446ffefd0acd9e28db1c4d6fa7a04848b1c2a562a3e722d16f9a98a"
+      "sha256": "4cc4c05d6f0048162c5fc0a534050e11a8c14585783a7fae61a98462e880cc65"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "cc9cf76017a4288e36972c5c59d4790e3f13ad4efac0f26cbaa4af32a39ec8d7",
+  "sourceTreeHash": "c027378d488e07eb04386f9f4111db2be90090aa72d368bee4862ba1fd27cfd3",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.256",
+  "docsBundleVersion": "2.0.258",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "6c690361e365dba0a530899a8d977a7bd60b51a2d5351a4e2cf490fbc48b7e5d",
+      "sha256": "9e51428cc1e4241c2ce35a2240051e453e0c021297a093e300ff01a911eb8acf",
       "mode": "100644"
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "afba67a5679827efbd37d706d290e393558d4abf13271b5606e069b1694960e8",
+      "sha256": "e529cbfc0ab172d5168301efcb09e2f7ed7459d3c8c7f27db9198b4ccce069ba",
       "mode": "100644"
     },
     {
@@ -206,7 +206,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "ac03af2c7446ffefd0acd9e28db1c4d6fa7a04848b1c2a562a3e722d16f9a98a",
+      "sha256": "4cc4c05d6f0048162c5fc0a534050e11a8c14585783a7fae61a98462e880cc65",
       "mode": "100644"
     },
     {

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/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.25.0`, then `@funnelsgrove/analytics` `0.7.0`, then `@funnelsgrove/payments` `0.27.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.263`, 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.25.0`, then `@funnelsgrove/analytics` `0.7.0`, then `@funnelsgrove/payments` `0.28.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.265`, 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.256",
+  "bundleVersion": "2.0.258",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",