@funnelsgrove/cli 0.1.306 → 0.1.307

package/README.md

@@ -224,6 +224,25 @@ last pull. Item `paymentProfileBindings` (for example a PayPal binding) are not
 in the file; existing ones are kept, and a new set copied from another starts
 without them.
 
+Read chargeback alert and Prevent transaction search history for one UTC month
+without customer or card data:
+
+```bash
+fgrove alerts list --project claimbee --month 2026-10          # every alert: ids, dates, service, amount, status, outcome
+fgrove alerts stats --project claimbee --month 2026-10 --json  # counts by service, refund/cancellation shares, FunnelsGrove cost
+fgrove prevent list --project claimbee --month 2026-10         # every transaction search / inquiry: date, program, outcome, amount, scheme, status
+fgrove prevent stats --project claimbee --month 2026-10        # searches, found rate, Prevent deflection rate
+```
+
+`--month` defaults to the current month. List commands download every page
+before printing. Outcomes are `refunded automatically`, `refunded manually`,
+`needs review / pending`, `closed without refund` or `informational`, plus the
+subscription cancellation state; percentages in `alerts stats` are shares of all
+alerts received in the month. Merchanto alerts are counted but billed directly
+by Merchanto; the cost lines cover FunnelsGrove alerts for the whole project.
+The output never includes customer emails, names, phone numbers, IP addresses,
+card digits, network references or Stripe identifiers.
+
 Use `--api-url` or `FUNNELSGROVE_API_URL` for non-production APIs.
 Use `--config` or `FUNNELSGROVE_CONFIG` to keep test credentials separate from the default `~/.funnelsgrove/config.json`.
 

package/dist/alertCommands.d.ts

@@ -0,0 +1,166 @@
+type CallApi = <T>(input: {
+    path: string;
+    type: 'query' | 'mutation';
+    data?: unknown;
+    token?: string | null;
+}) => Promise<T>;
+export type AlertCommandScope = {
+    callApi: CallApi;
+    token: string;
+    workspaceId: string;
+    projectId: string;
+};
+export type AlertMonth = {
+    month: string;
+    from: string;
+    to: string;
+};
+type Provider = 'chargebackhit' | 'merchanto';
+type OutcomeBucket = 'refundedAutomatically' | 'refundedManually' | 'needsReview' | 'resolvedWithoutRefund' | 'informational';
+type OutcomeCounts = Record<OutcomeBucket | 'subscriptionCanceled', number>;
+/** API export row; identifiers, money, dates and outcome only. */
+export type AlertExportRow = {
+    id: string;
+    provider: Provider;
+    providerAlertId: string;
+    paymentProfileId: string | null;
+    service: string;
+    alertType: 'chargeback' | 'notification';
+    status: string;
+    receivedAt: string;
+    transactionDate: string;
+    amountMinor: number;
+    currency: string;
+    outcome: OutcomeBucket;
+    refund: {
+        kind: 'refunded' | 'already_refunded';
+        actor: 'automatic' | 'manual';
+    } | null;
+    cancellationStatus: string | null;
+    needsReview: boolean;
+};
+export type AlertStatisticsResponse = {
+    period: {
+        from: string;
+        to: string;
+    };
+    paymentProfileId: string | null;
+    providers: Array<{
+        provider: Provider;
+        total: number;
+        services: Array<{
+            service: string;
+            count: number;
+        }>;
+        outcomes: OutcomeCounts;
+    }>;
+    billing: {
+        currency: 'USD';
+        lines: Array<{
+            serviceId: string;
+            label: string;
+            quantity: number;
+            billableQuantity: number;
+            unitPriceMinor: number;
+            estimatedChargeMinor: number;
+        }>;
+        totalChargeMinor: number;
+    } | null;
+};
+export type PreventExportRow = {
+    id: string;
+    createdAt: string;
+    environment: 'test' | 'live';
+    requestMode: 'primary' | 'shadow';
+    program: string | null;
+    scheme: 'visa' | 'mastercard' | null;
+    outcome: 'found' | 'not_found';
+    amountMinor: number | null;
+    currency: string | null;
+    statusCode: number;
+    preventCaseStatus: 'new' | 'failed' | 'delete' | 'timeout' | null;
+};
+export type PreventSummary = {
+    totalCount: number;
+    foundCount: number;
+    notFoundCount: number;
+    foundRatePercent: number | null;
+    preventTotalCount: number;
+    preventDeflectedCount: number;
+    preventSuccessRatePercent: number | null;
+};
+/** The vendor behind FunnelsGrove alerts is never named in client output. */
+export declare const alertProviderLabel: (provider: Provider) => string;
+export declare const EXPORT_PAGE_SIZE = 500;
+/** Parses `YYYY-MM` into an inclusive UTC day range; defaults to the current UTC month. */
+export declare const parseAlertMonth: (value: string | undefined, now?: Date) => AlertMonth;
+/** Minor units follow the currency's Intl fraction digits, matching how the API stores amounts. */
+export declare const formatMinor: (amountMinor: number | null, currency: string | null) => string;
+export declare const listAlerts: (scope: AlertCommandScope, month: AlertMonth) => Promise<AlertExportRow[]>;
+export declare const fetchAlertStatistics: (scope: AlertCommandScope, month: AlertMonth) => Promise<AlertStatisticsResponse>;
+export declare const listPreventSearches: (scope: AlertCommandScope, month: AlertMonth) => Promise<PreventExportRow[]>;
+export declare const fetchPreventSummary: (scope: AlertCommandScope, month: AlertMonth) => Promise<PreventSummary>;
+export declare const alertOutcomeLabel: (row: AlertExportRow) => string;
+/** JSON row: the API export fields plus the client-facing provider label. */
+export declare const toAlertJsonRow: (row: AlertExportRow) => {
+    provider: string;
+    id: string;
+    providerAlertId: string;
+    paymentProfileId: string | null;
+    service: string;
+    alertType: "chargeback" | "notification";
+    status: string;
+    receivedAt: string;
+    transactionDate: string;
+    amountMinor: number;
+    currency: string;
+    outcome: OutcomeBucket;
+    refund: {
+        kind: "refunded" | "already_refunded";
+        actor: "automatic" | "manual";
+    } | null;
+    cancellationStatus: string | null;
+    needsReview: boolean;
+};
+export declare const formatAlertRows: (rows: AlertExportRow[]) => string[];
+export declare const buildAlertStatisticsReport: (month: AlertMonth, statistics: AlertStatisticsResponse) => {
+    month: string;
+    period: {
+        from: string;
+        to: string;
+    };
+    totalAlerts: number;
+    providers: {
+        provider: string;
+        total: number;
+        services: {
+            service: string;
+            count: number;
+        }[];
+        outcomes: OutcomeCounts;
+        billing: string;
+    }[];
+    outcomes: {
+        [k: string]: {
+            count: number;
+            percentOfAlerts: number | null;
+        };
+    };
+    billing: {
+        currency: "USD";
+        lines: Array<{
+            serviceId: string;
+            label: string;
+            quantity: number;
+            billableQuantity: number;
+            unitPriceMinor: number;
+            estimatedChargeMinor: number;
+        }>;
+        totalChargeMinor: number;
+    } | null;
+};
+export declare const formatAlertStatistics: (month: AlertMonth, statistics: AlertStatisticsResponse) => string[];
+export declare const preventOutcomeLabel: (row: PreventExportRow) => string;
+export declare const formatPreventRows: (rows: PreventExportRow[]) => string[];
+export declare const formatPreventSummary: (month: AlertMonth, summary: PreventSummary) => string[];
+export {};

package/dist/alertCommands.js

@@ -0,0 +1,160 @@
+/** The vendor behind FunnelsGrove alerts is never named in client output. */
+export const alertProviderLabel = (provider) => (provider === 'chargebackhit' ? 'FunnelsGrove' : 'Merchanto');
+const OUTCOME_LABELS = {
+    refundedAutomatically: 'refunded automatically',
+    refundedManually: 'refunded manually',
+    needsReview: 'needs review / pending',
+    resolvedWithoutRefund: 'closed without refund',
+    informational: 'informational',
+};
+const OUTCOME_ORDER = ['refundedAutomatically', 'refundedManually', 'needsReview', 'resolvedWithoutRefund', 'informational'];
+export const EXPORT_PAGE_SIZE = 500;
+const pad = (value) => String(value).padStart(2, '0');
+/** Parses `YYYY-MM` into an inclusive UTC day range; defaults to the current UTC month. */
+export const parseAlertMonth = (value, now = new Date()) => {
+    const month = value ?? `${now.getUTCFullYear()}-${pad(now.getUTCMonth() + 1)}`;
+    const match = /^(\d{4})-(\d{2})$/.exec(month);
+    const year = match ? Number(match[1]) : NaN;
+    const monthNumber = match ? Number(match[2]) : NaN;
+    if (!match || monthNumber < 1 || monthNumber > 12) {
+        throw new Error(`Invalid month "${value}". Use YYYY-MM, for example 2026-10.`);
+    }
+    const lastDay = new Date(Date.UTC(year, monthNumber, 0)).getUTCDate();
+    return { month, from: `${month}-01`, to: `${month}-${pad(lastDay)}` };
+};
+/** Minor units follow the currency's Intl fraction digits, matching how the API stores amounts. */
+export const formatMinor = (amountMinor, currency) => {
+    if (amountMinor === null || !currency)
+        return '';
+    const code = currency.toUpperCase();
+    let digits = 2;
+    try {
+        digits = new Intl.NumberFormat('en', { style: 'currency', currency: code }).resolvedOptions().maximumFractionDigits ?? 2;
+    }
+    catch { /* unknown code: assume two decimals */ }
+    return `${(amountMinor / 10 ** digits).toFixed(digits)} ${code}`;
+};
+const percent = (count, total) => (total > 0 ? `${((count / total) * 100).toFixed(1)}%` : '-');
+const money = (minor) => `$${(minor / 100).toFixed(2)}`;
+const fetchAllPages = async (fetchPage) => {
+    const rows = [];
+    for (let offset = 0; offset !== null;) {
+        const page = await fetchPage(offset);
+        rows.push(...page.rows);
+        if (page.nextOffset !== null && page.nextOffset <= offset)
+            throw new Error('Export paging did not advance.');
+        offset = page.rows.length === 0 ? null : page.nextOffset;
+    }
+    return rows;
+};
+export const listAlerts = async (scope, month) => {
+    const providers = ['chargebackhit', 'merchanto'];
+    const pages = await Promise.all(providers.map((provider) => fetchAllPages((offset) => scope.callApi({
+        path: 'transactionAlerts.exportAlerts',
+        type: 'query',
+        token: scope.token,
+        data: { workspaceId: scope.workspaceId, projectId: scope.projectId, provider, from: month.from, to: month.to, offset, limit: EXPORT_PAGE_SIZE },
+    }))));
+    return pages.flat().sort((left, right) => right.receivedAt.localeCompare(left.receivedAt) || left.id.localeCompare(right.id));
+};
+export const fetchAlertStatistics = (scope, month) => scope.callApi({
+    path: 'transactionAlerts.statistics',
+    type: 'query',
+    token: scope.token,
+    data: { workspaceId: scope.workspaceId, projectId: scope.projectId, from: month.from, to: month.to },
+});
+export const listPreventSearches = (scope, month) => fetchAllPages((offset) => scope.callApi({
+    path: 'projects.exportTransactionSearchAudits',
+    type: 'query',
+    token: scope.token,
+    data: { workspaceId: scope.workspaceId, projectId: scope.projectId, from: month.from, to: month.to, offset, limit: EXPORT_PAGE_SIZE },
+}));
+export const fetchPreventSummary = (scope, month) => scope.callApi({
+    path: 'projects.transactionSearchAuditSummary',
+    type: 'query',
+    token: scope.token,
+    data: { workspaceId: scope.workspaceId, projectId: scope.projectId, from: month.from, to: month.to },
+});
+export const alertOutcomeLabel = (row) => {
+    const parts = [row.refund ? `${row.refund.kind === 'already_refunded' ? 'already refunded' : 'refunded'} (${row.refund.actor})` : OUTCOME_LABELS[row.outcome]];
+    if (row.cancellationStatus)
+        parts.push(`subscription ${row.cancellationStatus.replaceAll('_', ' ')}`);
+    if (row.needsReview && row.outcome !== 'needsReview')
+        parts.push('needs review');
+    return parts.join('; ');
+};
+/** JSON row: the API export fields plus the client-facing provider label. */
+export const toAlertJsonRow = (row) => ({ ...row, provider: alertProviderLabel(row.provider) });
+export const formatAlertRows = (rows) => [
+    ['received_at', 'provider', 'service', 'id', 'status', 'amount', 'outcome'].join('\t'),
+    ...rows.map((row) => [row.receivedAt, alertProviderLabel(row.provider), row.service, row.providerAlertId, row.status, formatMinor(row.amountMinor, row.currency), alertOutcomeLabel(row)].join('\t')),
+];
+export const buildAlertStatisticsReport = (month, statistics) => {
+    const total = statistics.providers.reduce((sum, provider) => sum + provider.total, 0);
+    const sum = (key) => statistics.providers.reduce((count, provider) => count + provider.outcomes[key], 0);
+    return {
+        month: month.month,
+        period: statistics.period,
+        totalAlerts: total,
+        providers: statistics.providers.map((provider) => ({
+            provider: alertProviderLabel(provider.provider),
+            total: provider.total,
+            services: provider.services,
+            outcomes: provider.outcomes,
+            billing: provider.provider === 'merchanto' ? 'Billed directly by Merchanto' : 'FunnelsGrove usage',
+        })),
+        outcomes: Object.fromEntries([...OUTCOME_ORDER, 'subscriptionCanceled'].map((key) => [key, { count: sum(key), percentOfAlerts: total > 0 ? Number(((sum(key) / total) * 100).toFixed(1)) : null }])),
+        billing: statistics.billing,
+    };
+};
+export const formatAlertStatistics = (month, statistics) => {
+    const report = buildAlertStatisticsReport(month, statistics);
+    const lines = [`Alerts ${month.month} (${statistics.period.from} to ${statistics.period.to}, UTC)`, `Total alerts\t${report.totalAlerts}`];
+    for (const provider of report.providers) {
+        if (provider.total === 0)
+            continue;
+        lines.push(`${provider.provider}\t${provider.total}`);
+        for (const service of provider.services)
+            lines.push(`  ${service.service}\t${service.count}`);
+    }
+    lines.push('Outcomes (percent of total alerts; cancellation overlaps refunds)');
+    for (const key of OUTCOME_ORDER)
+        lines.push(`  ${OUTCOME_LABELS[key]}\t${report.outcomes[key].count}\t${percent(report.outcomes[key].count, report.totalAlerts)}`);
+    lines.push(`  subscription canceled\t${report.outcomes.subscriptionCanceled.count}\t${percent(report.outcomes.subscriptionCanceled.count, report.totalAlerts)}`);
+    if (statistics.billing) {
+        lines.push('Estimated FunnelsGrove alert cost (whole project, before billing reconciliation)');
+        for (const line of statistics.billing.lines)
+            lines.push(`  ${line.label}\t${line.quantity} x ${money(line.unitPriceMinor)}\t${money(line.estimatedChargeMinor)}`);
+        lines.push(`  Total\t${money(statistics.billing.totalChargeMinor)}`);
+    }
+    else {
+        lines.push('Estimated FunnelsGrove alert cost\tno usage recorded');
+    }
+    const merchanto = report.providers.find((provider) => provider.provider === 'Merchanto');
+    if (merchanto && merchanto.total > 0)
+        lines.push(`Merchanto alerts (${merchanto.total}) are billed directly by Merchanto.`);
+    return lines;
+};
+export const preventOutcomeLabel = (row) => {
+    if (row.preventCaseStatus === 'new')
+        return 'deflected';
+    if (row.preventCaseStatus === 'failed')
+        return 'escalated';
+    if (row.preventCaseStatus === 'delete')
+        return 'reopened';
+    if (row.preventCaseStatus === 'timeout')
+        return 'timed out';
+    return row.outcome;
+};
+export const formatPreventRows = (rows) => [
+    ['created_at', 'program', 'scheme', 'environment', 'id', 'outcome', 'amount', 'status'].join('\t'),
+    ...rows.map((row) => [row.createdAt, row.program ?? 'Transaction search', row.scheme ?? '', row.environment, row.id, preventOutcomeLabel(row), formatMinor(row.amountMinor, row.currency), String(row.statusCode)].join('\t')),
+];
+export const formatPreventSummary = (month, summary) => [
+    `Prevent ${month.month} (${month.from} to ${month.to}, UTC)`,
+    `Searches\t${summary.totalCount}`,
+    `Found\t${summary.foundCount}\t${summary.foundRatePercent === null ? '-' : `${summary.foundRatePercent.toFixed(1)}%`}`,
+    `Not found\t${summary.notFoundCount}`,
+    `Prevent cases\t${summary.preventTotalCount}`,
+    `Deflected\t${summary.preventDeflectedCount}\t${summary.preventSuccessRatePercent === null ? '-' : `${summary.preventSuccessRatePercent.toFixed(1)}%`}`,
+];

package/dist/cli.js

@@ -19,6 +19,7 @@ import { pullEnvFile } from './envSync.js';
 import { executeFastDraftPatchSync, uploadDirectAssetWithFetch } from './draftPatchSync.js';
 import { updateCliInstallations } from './selfUpdate.js';
 import { executeExpensePublish, executeExpensePull } from './expenseCommands.js';
+import { buildAlertStatisticsReport, fetchAlertStatistics, fetchPreventSummary, formatAlertRows, formatAlertStatistics, formatPreventRows, formatPreventSummary, listAlerts, listPreventSearches, parseAlertMonth, toAlertJsonRow, } from './alertCommands.js';
 import { executeOfferSetPrices, executeOfferSetPublish, executeOfferSetPull, formatOfferSetPriceCatalogs, } from './offerSetCommands.js';
 import { executeEmailPull, executeEmailPush, executeEmailSend, executeEmailUpdateVariables, executeEmailSequenceAddStep, executeEmailSequenceCancel, executeEmailSequenceCreate, executeEmailSequencePublish, executeEmailSequenceSetActive, executeEmailLibraryAdd, executeEmailLibraryList, executeEmailTemplatePublish, executeEmailValidate, parseEmailVariablesJson, } from './emailCommands.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
@@ -2066,18 +2067,17 @@ const addExpenseScopeOptions = (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('--file <path>', 'Expense JSON file', 'expenses.json');
-const resolveExpenseCommandScope = async (options) => {
+/** Token, workspace and project for commands that read or edit one project (`--project`, else `fgrove use`). */
+const resolveProjectCommandScope = async (options) => {
     const token = await readAuthToken();
     const workspaceId = await resolveWorkspaceId(token, options.workspace);
     const project = await resolveAnalyticsProject({ token, workspaceId, project: options.project });
-    return {
-        callApi,
-        token,
-        workspaceId,
-        projectId: project.id,
-        filePath: path.resolve(process.cwd(), options.file),
-    };
+    return { callApi, token, workspaceId, projectId: project.id };
 };
+const resolveExpenseCommandScope = async (options) => ({
+    ...await resolveProjectCommandScope(options),
+    filePath: path.resolve(process.cwd(), options.file),
+});
 const expensesCommand = addExamples(program.command('expenses').description('Edit project profitability expenses'), [
     'fgrove expenses pull --project claimbee',
     'fgrove expenses publish --project claimbee',
@@ -2213,6 +2213,71 @@ offerSetsCommand
     });
     console.log(options.json ? JSON.stringify({ catalogs }, null, 2) : formatOfferSetPriceCatalogs(catalogs).join('\n'));
 });
+const addAlertScopeOptions = (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('--month <YYYY-MM>', 'UTC calendar month (default: current month)')
+    .option('--json', 'Print machine-readable JSON');
+const resolveAlertCommandScope = async (options) => ({
+    scope: await resolveProjectCommandScope(options),
+    month: parseAlertMonth(options.month),
+});
+const alertsCommand = addExamples(program.command('alerts').description('Read chargeback alert history and statistics without customer or card data'), [
+    'fgrove alerts list --project claimbee --month 2026-10',
+    'fgrove alerts stats --project claimbee --month 2026-10 --json',
+]);
+addAlertScopeOptions(alertsCommand
+    .command('list')
+    .description('List every chargeback alert received in a month: ids, dates, service, amount, status and outcome'))
+    .action(async (options) => {
+    const { scope, month } = await resolveAlertCommandScope(options);
+    const rows = await listAlerts(scope, month);
+    if (options.json) {
+        console.log(JSON.stringify({ month: month.month, period: { from: month.from, to: month.to }, alerts: rows.map(toAlertJsonRow) }, null, 2));
+        return;
+    }
+    printValueRows(formatAlertRows(rows).map((line) => [line]));
+});
+addAlertScopeOptions(alertsCommand
+    .command('stats')
+    .description('Monthly alert counts by service, refund and cancellation outcomes, and the estimated FunnelsGrove alert cost'))
+    .action(async (options) => {
+    const { scope, month } = await resolveAlertCommandScope(options);
+    const statistics = await fetchAlertStatistics(scope, month);
+    if (options.json) {
+        console.log(JSON.stringify(buildAlertStatisticsReport(month, statistics), null, 2));
+        return;
+    }
+    printValueRows(formatAlertStatistics(month, statistics).map((line) => [line]));
+});
+const preventCommand = addExamples(program.command('prevent').description('Read Prevent transaction search history and statistics without customer or card data'), [
+    'fgrove prevent list --project claimbee --month 2026-10',
+    'fgrove prevent stats --project claimbee --month 2026-10 --json',
+]);
+addAlertScopeOptions(preventCommand
+    .command('list')
+    .description('List every transaction search and inquiry in a month: date, program, outcome, amount, scheme and status'))
+    .action(async (options) => {
+    const { scope, month } = await resolveAlertCommandScope(options);
+    const rows = await listPreventSearches(scope, month);
+    if (options.json) {
+        console.log(JSON.stringify({ month: month.month, period: { from: month.from, to: month.to }, searches: rows }, null, 2));
+        return;
+    }
+    printValueRows(formatPreventRows(rows).map((line) => [line]));
+});
+addAlertScopeOptions(preventCommand
+    .command('stats')
+    .description('Monthly transaction search totals, found rate and Prevent deflection rate'))
+    .action(async (options) => {
+    const { scope, month } = await resolveAlertCommandScope(options);
+    const summary = await fetchPreventSummary(scope, month);
+    if (options.json) {
+        console.log(JSON.stringify({ month: month.month, period: { from: month.from, to: month.to }, summary }, null, 2));
+        return;
+    }
+    printValueRows(formatPreventSummary(month, summary).map((line) => [line]));
+});
 const funnelsCommand = addExamples(program.command('funnels').description('Manage funnels'), [
     'fgrove funnels list',
     'fgrove funnels clone --funnel claimbee --name claimbee-ios',

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.306",
+      "repositoryCliVersion": "0.1.307",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.299",
+        "bundleVersion": "2.0.300",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4"
+            "sha256": "5c85ab989a7c1675ef36fda22779d50977a926b6cc417880ae1e08bd35380135"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af"
+            "sha256": "451b21e025b31e38404784ba88d0a409958e8ed2cf25da163b0a7dd291bb471c"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.305",
+      "repositoryCliVersion": "0.1.306",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.298",
+        "bundleVersion": "2.0.299",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -180,7 +180,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
-            "sha256": "fd81ec6c973f4c3a9c26db813bf44c6cfce3c8bbe17287cdaec330fa566ee78c"
+            "sha256": "050564846bf7d44afb267e1321d6fe277f032fe7b6237441741570c723543d0e"
           },
           {
             "path": "docs/funnelsgrove/contracts/payments.md",
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "6a7df14c1aad5de56a90931928a2ed3f0ac08cf1e04c34f9a4da77ad65cec8b3"
+            "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "0009f06c828f9441ff7a9a8a36ca4fe799fc70236b0338506a2e8fb9325092ca"
+            "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.304",
+      "repositoryCliVersion": "0.1.305",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.297",
+        "bundleVersion": "2.0.298",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -327,7 +327,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/flow-routing.md",
-            "sha256": "050564846bf7d44afb267e1321d6fe277f032fe7b6237441741570c723543d0e"
+            "sha256": "fd81ec6c973f4c3a9c26db813bf44c6cfce3c8bbe17287cdaec330fa566ee78c"
           },
           {
             "path": "docs/funnelsgrove/contracts/payments.md",
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "6b5546c6bfabf6c03b3d576bf945de4350a0d8f465a4159a3fb7cae40ba6142a"
+            "sha256": "6a7df14c1aad5de56a90931928a2ed3f0ac08cf1e04c34f9a4da77ad65cec8b3"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ba7cf49d4b85969994262ae8ca59989cc5ef6a7db7272820556a99887bc5c408"
+            "sha256": "0009f06c828f9441ff7a9a8a36ca4fe799fc70236b0338506a2e8fb9325092ca"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.303",
+      "repositoryCliVersion": "0.1.304",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.296",
+        "bundleVersion": "2.0.297",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "b54e093d99f163b399ca52788beabc94530accea7b3c7d60caaf9f067a5aeb04"
+            "sha256": "6b5546c6bfabf6c03b3d576bf945de4350a0d8f465a4159a3fb7cae40ba6142a"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "51ad1bfe95afe002bc2fabefe00655881cc41ab34cfb1d13a0dbf92b31ab0c7e"
+            "sha256": "ba7cf49d4b85969994262ae8ca59989cc5ef6a7db7272820556a99887bc5c408"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.302",
+      "repositoryCliVersion": "0.1.303",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.295",
+        "bundleVersion": "2.0.296",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -613,7 +613,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
-            "sha256": "482b159a6b88a86009b9d2bec643d3e6dc4389c7693e1ab26c8df60b1eeb1f19"
+            "sha256": "11c79bd21570374ae591f21594c7235cc2bb015067ad901eddc1420a9998cd25"
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "373b181e673ad2fffcbcb68a11fa43186a57cac67493a746aafec03bd0a0ab94"
+            "sha256": "b54e093d99f163b399ca52788beabc94530accea7b3c7d60caaf9f067a5aeb04"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "df1b6615d35d8d2385038e26580604bae5921075126dd01159bf7300ba675bf9"
+            "sha256": "51ad1bfe95afe002bc2fabefe00655881cc41ab34cfb1d13a0dbf92b31ab0c7e"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.301",
+      "repositoryCliVersion": "0.1.302",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.294",
+        "bundleVersion": "2.0.295",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -760,7 +760,7 @@
           },
           {
             "path": "docs/funnelsgrove/contracts/analytics-events.md",
-            "sha256": "30a445a2042549fe4bc87e0635785b5ff7876cbba0c8c27db2fcb04de3976f47"
+            "sha256": "482b159a6b88a86009b9d2bec643d3e6dc4389c7693e1ab26c8df60b1eeb1f19"
           },
           {
             "path": "docs/funnelsgrove/contracts/content-answers.md",
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "39d41b41132bf4ecbae9f2e98500cea9045c66889bd4b6daf67673a566f282d3"
+            "sha256": "373b181e673ad2fffcbcb68a11fa43186a57cac67493a746aafec03bd0a0ab94"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -796,7 +796,7 @@
           },
           {
             "path": "docs/funnelsgrove/qa/publish.md",
-            "sha256": "67391a8bf5e1ddeab2e7430f48a589c28ce5fb986f06fee74f78f09649086603"
+            "sha256": "dd1584f08ffd779375b4ffec6890d6ef731734925d7abb2d021f7f0ad15d11f6"
           },
           {
             "path": "docs/funnelsgrove/recipes/add-experiment.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "69f6150b16fa1293a238fdc56d2f097dec4f626f3cdf32dc51f75b0f5cb06485"
+            "sha256": "df1b6615d35d8d2385038e26580604bae5921075126dd01159bf7300ba675bf9"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.300",
+      "repositoryCliVersion": "0.1.301",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.293",
+        "bundleVersion": "2.0.294",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "24c93bea6e2b118908401b7ef82d36ae846669f7cf62d0b4cc18674caf531866"
+            "sha256": "39d41b41132bf4ecbae9f2e98500cea9045c66889bd4b6daf67673a566f282d3"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "ec0d3caed99d53b09e28ecf2e59fd3100caf0d32c08c507651611a05c7019b6d"
+            "sha256": "69f6150b16fa1293a238fdc56d2f097dec4f626f3cdf32dc51f75b0f5cb06485"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.306",
+  "version": "0.1.307",
   "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.299",
+  "bundleVersion": "2.0.300",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4"
+      "sha256": "5c85ab989a7c1675ef36fda22779d50977a926b6cc417880ae1e08bd35380135"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af"
+      "sha256": "451b21e025b31e38404784ba88d0a409958e8ed2cf25da163b0a7dd291bb471c"
     }
   ]
 }

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.38.0`, then `@funnelsgrove/analytics` `0.20.0`, then `@funnelsgrove/payments` `0.51.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.306`, 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.38.0`, then `@funnelsgrove/analytics` `0.20.0`, then `@funnelsgrove/payments` `0.51.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.307`, 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.299",
+  "bundleVersion": "2.0.300",
   "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.299",
+  "bundleVersion": "2.0.300",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4"
+      "sha256": "5c85ab989a7c1675ef36fda22779d50977a926b6cc417880ae1e08bd35380135"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af"
+      "sha256": "451b21e025b31e38404784ba88d0a409958e8ed2cf25da163b0a7dd291bb471c"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "7cd61f5572c1da3d31e58b6c2dc13753665bfcedf88e8499fdcc74462fcb7a8a",
+  "sourceTreeHash": "fbde2c5222561ac78d7d640bca5665b4d8f1aad18fcff17a178d05a9ad062149",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.299",
+  "docsBundleVersion": "2.0.300",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "181374fd6ca6aff24e73b6ad33eb2a12f0d8b4b1ca4d57d3285b08404ee32c04",
+      "sha256": "8acc548cb6916fc1a127068a4621f4206c3018f1bc0e163bb2e91c9665e89c62",
       "mode": "100644"
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "e28376a9ab3d97ba9da5380d8c424dd4ace9f8bd7f83b21c1e87de55c14636b4",
+      "sha256": "5c85ab989a7c1675ef36fda22779d50977a926b6cc417880ae1e08bd35380135",
       "mode": "100644"
     },
     {
@@ -206,7 +206,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "3bcbc5df69c1d4ef7e25430a5d48fb0af48919a6b5844f73d77b14478df7e6af",
+      "sha256": "451b21e025b31e38404784ba88d0a409958e8ed2cf25da163b0a7dd291bb471c",
       "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.38.0`, then `@funnelsgrove/analytics` `0.20.0`, then `@funnelsgrove/payments` `0.51.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.306`, 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.38.0`, then `@funnelsgrove/analytics` `0.20.0`, then `@funnelsgrove/payments` `0.51.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.307`, 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.299",
+  "bundleVersion": "2.0.300",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",