@tenderprompt/cli 0.1.23 → 0.1.24

package/dist/index.js

@@ -31,6 +31,9 @@ function readCliPackageVersion() {
     return UNKNOWN_CLI_VERSION;
 }
 const CLI_PACKAGE_VERSION = readCliPackageVersion();
+const ANALYTICS_AUTHORING_PLAYBOOK_ID = 'analytics-event-authoring';
+const ANALYTICS_AUTHORING_COMMAND = 'tender app analytics authoring --json';
+const ANALYTICS_AUTHORING_PLAYBOOK_COMMAND = `tender playbooks get ${ANALYTICS_AUTHORING_PLAYBOOK_ID} --json`;
 class TenderCliUsageError extends Error {
     constructor(message) {
         super(message);
@@ -121,7 +124,9 @@ Commands:
                              Approve manifest-declared outbound auth grants
   tender app analytics summary <app-id>
                              Read artifact analytics totals and trend points
-  tender app analytics query <app-id> --spec <file|-> 
+  tender app analytics authoring
+                             Print the current analytics event authoring contract
+  tender app analytics query <app-id> --spec <file|->
                              Run a server-validated chart spec
   tender app analytics suggestions <app-id>
                              Generate useful starter chart suggestions
@@ -171,6 +176,7 @@ Examples:
   tender app outbound-auth list artifact_123 --json
   tender app outbound-auth approve artifact_123 --all --confirm approve --json
   tender app analytics summary artifact_123 --range 30d --json
+  tender app analytics authoring --json
   tender app analytics query artifact_123 --spec chart.json --json
   tender app analytics suggestions artifact_123 --range 30d --json
   tender app db capabilities artifact_123 --json
@@ -360,6 +366,8 @@ Commands:
                              Approve manifest-declared outbound auth grants
   tender app analytics summary <app-id>
                              Read artifact analytics totals and trend points
+  tender app analytics authoring
+                             Print the current analytics event authoring contract
   tender app analytics query <app-id> --spec <file|->
                              Run a server-validated chart spec
   tender app analytics suggestions <app-id>
@@ -423,13 +431,14 @@ Examples:
   tender app outbound-auth list artifact_123 --json
   tender app outbound-auth approve artifact_123 --all --confirm approve --json
   tender app analytics summary artifact_123 --range 30d --json
+  tender app analytics authoring --json
   tender app analytics query artifact_123 --spec chart.json --json
   tender app analytics suggestions artifact_123 --range 30d --json
   tender app analytics dashboards artifact_123 --json
   tender app analytics dashboards artifact_123 --create "Agent dashboard" --json
-  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec funnel.json --json
+  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec unit-funnel.json --json
   tender app analytics charts list artifact_123 --dashboard analytics_dashboard_123 --json
-  tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --spec funnel.json --dry-run --json
+  tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --spec unit-funnel.json --dry-run --json
   tender app analytics charts delete artifact_123 --chart analytics_chart_123 --dry-run --json
   tender app analytics properties list artifact_123 --json
   tender app analytics properties activate artifact_123 --event signup_started --property plan --type dimension --dry-run --json
@@ -515,16 +524,19 @@ Examples:
   tender version --json`;
 }
 function analyticsHelp() {
-    return `Usage: tender app analytics <command> <app-id> [options]
+    return `Usage: tender app analytics <command> [<app-id>] [options]
 
 Start here for agents:
+  tender app analytics authoring --json
   tender app analytics capabilities <app-id> --include-catalog --range 30d --json
 
 Commands:
+  tender app analytics authoring              Print the current event authoring contract
   tender app analytics summary <app-id>       Read totals and trend points
   tender app analytics query <app-id>         Run one chart spec
   tender app analytics capabilities <app-id>  Describe agent-safe analytics capabilities
   tender app analytics suggestions <app-id>   Generate starter chart suggestions
+  tender app analytics exact-funnel <app-id>  Run exact unit funnel analysis
   tender app analytics dashboards <app-id>    List or create dashboards
   tender app analytics export <kind> <app-id> Export catalog metadata or query rows
   tender app analytics charts templates       Print reusable chart spec templates
@@ -536,22 +548,33 @@ Commands:
   tender app analytics properties activate <app-id>  Make a property queryable
 
 Examples:
+  tender app analytics authoring --json
   tender app analytics summary artifact_123 --range 30d --json
   tender app analytics capabilities artifact_123 --include-catalog --json
   tender app analytics query artifact_123 --spec chart.json --json
   tender app analytics query artifact_123 --spec - --json < chart.json
+  tender app analytics exact-funnel artifact_123 --flow checkout_flow --steps started,completed --range 30d --json
   tender app analytics export catalog artifact_123 --range 30d --json
   tender app analytics export query artifact_123 --spec chart.json --format csv
   tender app analytics suggestions artifact_123 --range 2026-04-01..2026-04-30 --json
   tender app analytics dashboards artifact_123 --create "Agent dashboard" --json
   tender app analytics charts templates --json
-  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec funnel.json --json
+  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec unit-funnel.json --json
   tender app analytics charts list artifact_123 --dashboard analytics_dashboard_123 --json
-  tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --spec funnel.json --dry-run --json
+  tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --spec unit-funnel.json --dry-run --json
   tender app analytics charts delete artifact_123 --chart analytics_chart_123 --dry-run --json
   tender app analytics properties list artifact_123 --json
   tender app analytics properties activate artifact_123 --event signup_started --property plan --type dimension --dry-run --json`;
 }
+function analyticsAuthoringHelp() {
+    return `Usage: tender app analytics authoring [--json]
+
+Prints the current generated-app analytics event authoring contract. This command
+does not require an app id, checkout, API token, or installed skill.
+
+Examples:
+  tender app analytics authoring --json`;
+}
 function analyticsSummaryHelp() {
     return `Usage: tender app analytics summary <app-id> [--range <7d|30d|90d|YYYY-MM-DD..YYYY-MM-DD>] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
@@ -605,6 +628,16 @@ function analyticsSuggestionsHelp() {
 Examples:
   tender app analytics suggestions artifact_123 --range 30d --json`;
 }
+function analyticsExactFunnelHelp() {
+    return `Usage: tender app analytics exact-funnel <app-id> --flow <flow-id> --steps <step-a,step-b> [--range <7d|30d|90d|YYYY-MM-DD..YYYY-MM-DD>] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+
+Runs an explicit raw-event unit funnel audit. This path dedupes by unit id and
+flow step from artifact-scoped raw analytics rows; it is not used for normal
+dashboard page loads.
+
+Examples:
+  tender app analytics exact-funnel artifact_123 --flow checkout_flow --steps started,completed --range 30d --json`;
+}
 function analyticsDashboardsHelp() {
     return `Usage: tender app analytics dashboards <app-id> [--create <name>] [--dry-run] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
@@ -630,8 +663,8 @@ Property charts automatically make required custom event properties queryable be
 saving when the spec has an event_name = filter.
 
 Examples:
-  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec funnel.json --dry-run --json
-  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec funnel.json --json`;
+  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec unit-funnel.json --dry-run --json
+  tender app analytics charts create artifact_123 --dashboard analytics_dashboard_123 --title "Signup funnel" --spec unit-funnel.json --json`;
 }
 function analyticsChartsListHelp() {
     return `Usage: tender app analytics charts list <app-id> --dashboard <dashboard-id> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
@@ -649,8 +682,8 @@ saving when the spec has an event_name = filter.
 
 Examples:
   tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --dry-run --json
-  tender app analytics charts update artifact_123 --chart analytics_chart_123 --spec funnel.json --dry-run --json
-  tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --spec - --json < funnel.json`;
+  tender app analytics charts update artifact_123 --chart analytics_chart_123 --spec unit-funnel.json --dry-run --json
+  tender app analytics charts update artifact_123 --chart analytics_chart_123 --title "Signup funnel" --spec - --json < unit-funnel.json`;
 }
 function analyticsChartsDeleteHelp() {
     return `Usage: tender app analytics charts delete <app-id> --chart <chart-id> [--dry-run] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
@@ -1135,6 +1168,13 @@ function tenderCliCapabilities() {
             persistence: 'session_only',
             writesToCheckout: false,
         },
+        analyticsAuthoring: {
+            command: ANALYTICS_AUTHORING_COMMAND,
+            playbookId: ANALYTICS_AUTHORING_PLAYBOOK_ID,
+            playbookCommand: ANALYTICS_AUTHORING_PLAYBOOK_COMMAND,
+            doctorCommand: 'tender app doctor --dir <dir> --json',
+            purpose: 'Keep generated app analytics events compatible with Tender dashboards and unit funnels.',
+        },
         description: 'Agent-safe Tender App source, lifecycle, analytics, and local scaffold controls.',
         discovery: {
             primary: 'npm exec --yes @tenderprompt/cli@latest -- capabilities --json',
@@ -1244,6 +1284,8 @@ function tenderCliCapabilities() {
                 name: 'analytics_agent_loop',
                 when: 'When understanding app analytics or creating saved charts.',
                 commands: [
+                    ANALYTICS_AUTHORING_COMMAND,
+                    ANALYTICS_AUTHORING_PLAYBOOK_COMMAND,
                     'tender app analytics capabilities <artifact-id> --include-catalog --range 30d --json',
                     'tender app analytics charts templates --json',
                     'tender app analytics query <artifact-id> --spec chart.json --json',
@@ -1257,6 +1299,7 @@ function tenderCliCapabilities() {
                     'tender app analytics charts delete <artifact-id> --chart <chart-id> --dry-run --json',
                 ],
                 notes: [
+                    'Run authoring before adding or repairing analytics instrumentation; use capabilities for artifact-scoped read/query details.',
                     'Combine CLI capabilities with local source inspection of analytics calls.',
                     'Validate chart specs with query before creating or updating saved charts.',
                     'Property chart create/update commands automatically make missing custom event properties queryable when the spec has an event_name = filter.',
@@ -1383,6 +1426,18 @@ function tenderCliCapabilities() {
                 requiresAuth: false,
                 writes: false,
             },
+            {
+                command: ANALYTICS_AUTHORING_COMMAND,
+                purpose: 'Print the generated-app analytics event payload contract for unit funnels and dashboard-ready events.',
+                requiresAuth: false,
+                writes: false,
+            },
+            {
+                command: ANALYTICS_AUTHORING_PLAYBOOK_COMMAND,
+                purpose: 'Fetch the remote analytics authoring playbook for examples and repair patterns.',
+                requiresAuth: true,
+                writes: false,
+            },
             {
                 command: 'tender app analytics capabilities <artifact-id> --include-catalog --range 30d --json',
                 purpose: 'Discover artifact-scoped analytics commands, chart specs, saved dashboards, and bounded observed catalog.',
@@ -3937,6 +3992,20 @@ function parseAnalyticsCapabilitiesArgs(args) {
         ...parsed,
     };
 }
+function parseAnalyticsAuthoringArgs(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        return { command: 'help', topic: 'app analytics authoring' };
+    }
+    let json = false;
+    for (const arg of args) {
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        throw new TenderCliUsageError(`Unknown analytics authoring option: ${arg}`);
+    }
+    return { command: 'app analytics authoring', json };
+}
 function parseAnalyticsSuggestionsArgs(args) {
     if (args.includes('--help') || args.includes('-h')) {
         return { command: 'help', topic: 'app analytics suggestions' };
@@ -3958,6 +4027,53 @@ function parseAnalyticsSuggestionsArgs(args) {
     }
     return { command: 'app analytics suggestions', artifactId, range, ...parsed };
 }
+function parseAnalyticsSteps(value) {
+    const raw = parseRequiredFlagValue(value, '--steps');
+    const steps = raw
+        .split(',')
+        .map((step) => step.trim())
+        .filter((step) => step.length > 0);
+    if (steps.length < 2 || steps.length > 25 || new Set(steps).size !== steps.length) {
+        throw new TenderCliUsageError('--steps must contain 2-25 unique comma-separated flow steps.');
+    }
+    return steps;
+}
+function parseAnalyticsExactFunnelArgs(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        return { command: 'help', topic: 'app analytics exact-funnel' };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith('-')) {
+        throw new TenderCliUsageError('app id is required. Example: tender app analytics exact-funnel <app-id> --flow checkout_flow --steps started,completed --range 30d --json');
+    }
+    const parsed = parseAnalyticsCommonArgs(args, 1);
+    let range = '7d';
+    let flowId = null;
+    let steps = null;
+    for (let index = 0; index < parsed.remaining.length; index += 1) {
+        const arg = parsed.remaining[index];
+        if (arg === '--range') {
+            range = parseAnalyticsRange(parsed.remaining[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg === '--flow') {
+            flowId = parseRequiredFlagValue(parsed.remaining[index + 1], '--flow');
+            index += 1;
+            continue;
+        }
+        if (arg === '--steps') {
+            steps = parseAnalyticsSteps(parsed.remaining[index + 1]);
+            index += 1;
+            continue;
+        }
+        throw new TenderCliUsageError(`Unknown analytics exact-funnel option: ${arg}`);
+    }
+    if (!flowId || !steps) {
+        throw new TenderCliUsageError('--flow and --steps are required. Example: tender app analytics exact-funnel artifact_123 --flow checkout_flow --steps started,completed --range 30d --json');
+    }
+    return { command: 'app analytics exact-funnel', artifactId, flowId, steps, range, ...parsed };
+}
 function parseAnalyticsDashboardsArgs(args) {
     if (args.includes('--help') || args.includes('-h')) {
         return { command: 'help', topic: 'app analytics dashboards' };
@@ -4079,6 +4195,121 @@ function parseAnalyticsExportQueryArgs(args) {
         ...parsed,
     };
 }
+function analyticsAuthoringContract() {
+    return {
+        ok: true,
+        surface: 'analytics_authoring',
+        command: 'app analytics authoring',
+        version: 1,
+        playbook: {
+            id: ANALYTICS_AUTHORING_PLAYBOOK_ID,
+            command: ANALYTICS_AUTHORING_PLAYBOOK_COMMAND,
+            useWhen: [
+                'Creating a generated app with custom analytics.',
+                'Repairing dashboards or funnels that cannot dedupe a shopper journey.',
+                'Retrofitting an existing app before saving unit funnel charts.',
+                'Publishing Shopify Customer Events while keeping Tender dashboards complete.',
+            ],
+        },
+        doctor: {
+            command: 'tender app doctor --dir <dir> --json',
+            diagnosticCodes: [
+                'analytics_reserved_unit_step_event',
+                'analytics_reserved_event_type_field',
+                'analytics_metadata_nested_in_properties',
+                'analytics_missing_unit_flow_metadata',
+                'analytics_tender_tracking_skipped_after_shopify_publish',
+                'analytics_unstable_unit_id',
+            ],
+        },
+        analyticsAuthoring: {
+            payloadShape: {
+                event: 'custom_event_name',
+                unit: { type: 'quiz_attempt', id: 'stable-attempt-id' },
+                flow: {
+                    id: 'recommendation_quiz',
+                    step: 'quiz_completed',
+                    order: 3,
+                    role: 'outcome',
+                },
+                properties: {
+                    experiment_id: 'quiz_copy_v1',
+                    experiment_variant: 'guided',
+                    score: 84,
+                },
+            },
+            rules: [
+                'Keep event names business-specific and do not use platform-reserved names such as unit_step.',
+                'Put unit and flow metadata at the top level of the analytics payload, not inside properties.',
+                'Use one stable unit.id for the user journey being measured; do not regenerate it for each click.',
+                'Use flow.role values start, milestone, activity, outcome, or error.',
+                'Do not emit event_type from generated app code; the platform derives it.',
+                'When also publishing Shopify Customer Events, still send Tender analytics for Tender dashboards.',
+                'Keep properties low-cardinality and dashboard-safe; avoid PII, secrets, free text, ids, and URLs unless explicitly approved.',
+            ],
+            propertyStates: ['tracked', 'observed', 'queryable'],
+            queryablePropertyCommand: 'tender app analytics properties activate <app-id> --event <event-name> --property <property-key> --type <dimension|metric> --dry-run --json',
+        },
+        examples: [
+            {
+                scenario: 'game attempt',
+                payload: {
+                    event: 'level_completed',
+                    unit: { type: 'game_attempt', id: 'attempt-01HXYZ' },
+                    flow: { id: 'pasta_game', step: 'level_completed', order: 3, role: 'milestone' },
+                    properties: { level: 2, score: 1270, experiment_variant: 'timer_v2' },
+                },
+            },
+            {
+                scenario: 'recommendation quiz',
+                payload: {
+                    event: 'quiz_completed',
+                    unit: { type: 'quiz_attempt', id: 'quiz-session-42' },
+                    flow: { id: 'recommendation_quiz', step: 'quiz_completed', order: 4, role: 'outcome' },
+                    properties: { result: 'starter_bundle', score: 84 },
+                },
+            },
+            {
+                scenario: 'bundle builder',
+                payload: {
+                    event: 'bundle_checkout_clicked',
+                    unit: { type: 'bundle_build', id: 'bundle-build-42' },
+                    flow: { id: 'bundle_builder', step: 'checkout_clicked', order: 5, role: 'outcome' },
+                    properties: { selected_items: 6, cadence: 'monthly', variant: 'guided' },
+                },
+            },
+            {
+                scenario: 'Shopify Customer Events duplication',
+                notes: [
+                    'Publish consent-aware Shopify Customer Events when the embed runs in Shopify.',
+                    'Do not return before sending the Tender analytics event needed by Tender dashboards.',
+                ],
+                payload: {
+                    event: 'product_match_submitted',
+                    unit: { type: 'quiz_attempt', id: 'quiz-session-42' },
+                    flow: { id: 'recommendation_quiz', step: 'submitted', order: 3, role: 'milestone' },
+                    properties: { shopify_customer_event: 'product_match_submitted' },
+                },
+            },
+        ],
+        charting: {
+            unitFunnel: 'After traffic exists, use tender app analytics capabilities <app-id> --include-catalog --json and create version 2 unit_step_count funnel specs from observedFlows and observedUnitTypes.',
+            exactAudit: 'Use tender app analytics exact-funnel <app-id> --flow <flow-id> --steps <step-a,step-b> --json for repair and low-volume audits.',
+        },
+    };
+}
+function runAnalyticsAuthoring(command, io) {
+    const payload = analyticsAuthoringContract();
+    printAnalyticsPayload(command, io, payload, [
+        'Analytics authoring contract',
+        '',
+        `command: ${ANALYTICS_AUTHORING_COMMAND}`,
+        `playbook: ${ANALYTICS_AUTHORING_PLAYBOOK_COMMAND}`,
+        'payload: event plus top-level unit, flow, and properties',
+        'doctor: tender app doctor --dir <dir> --json',
+    ]);
+    return 0;
+}
 function analyticsChartTemplates() {
     return [
         {
@@ -4145,30 +4376,30 @@ function analyticsChartTemplates() {
             },
         },
         {
-            id: 'event_funnel_by_name',
-            title: 'Event funnel',
-            visualization: 'funnel',
-            purpose: 'Measure ordered conversion through observed custom event names.',
+            id: 'milestone_event_totals',
+            title: 'Milestone event totals',
+            visualization: 'table',
+            purpose: 'Compare ordered milestone event totals without treating them as conversion rates.',
             usableAsIs: false,
             placeholders: {
-                eventNames: ['<start_event>', '<middle_event>', '<conversion_event>'],
+                eventNames: ['<start_event>', '<middle_event>', '<outcome_event>'],
             },
             adaptWith: [
-                'Replace placeholders with ordered event names from catalog classification or observed events.',
+                'Replace placeholders with observed event names from catalog classification or source order.',
                 'Use only event names observed for the selected app.',
-                'Validate with analytics query before saving because funnel order changes the meaning.',
+                'Use unit_funnel instead when the app emits unit and flow metadata.',
             ],
             spec: {
                 version: 1,
                 dataset: 'events',
-                visualization: 'funnel',
+                visualization: 'table',
                 metric: { name: 'custom_event_count' },
                 groupBy: [{ field: 'event_name' }],
                 filters: [
                     {
                         field: 'event_name',
                         op: 'in',
-                        value: ['<start_event>', '<middle_event>', '<conversion_event>'],
+                        value: ['<start_event>', '<middle_event>', '<outcome_event>'],
                     },
                 ],
                 range: { preset: '30d' },
@@ -4177,30 +4408,65 @@ function analyticsChartTemplates() {
             },
         },
         {
-            id: 'request_path_funnel',
-            title: 'Request path funnel',
+            id: 'unit_funnel',
+            title: 'Unit funnel',
             visualization: 'funnel',
-            purpose: 'Measure ordered conversion through observed request paths.',
+            purpose: 'Measure ordered progression with one reach per unit and step.',
             usableAsIs: false,
             placeholders: {
-                paths: ['/<start_path>', '/<middle_path>', '/<conversion_path>'],
+                flowId: '<flow_id>',
+                unitType: '<unit_type>',
+                steps: ['<start_step>', '<middle_step>', '<outcome_step>'],
             },
             adaptWith: [
-                'Use when catalog classification includes a path-based funnel or the source code shows ordered route milestones.',
+                'Use only when the app emits unit and flow metadata and capabilities show unit-step rows.',
+                'Replace placeholders with ordered flow steps, usually matching event names.',
+                'Use activity charts for repeated actions instead of adding raw activity to this funnel.',
+            ],
+            spec: {
+                version: 2,
+                dataset: 'events',
+                visualization: 'funnel',
+                metric: { name: 'unit_step_count' },
+                funnel: {
+                    flowId: '<flow_id>',
+                    unit: { source: 'unit_id', type: '<unit_type>' },
+                    steps: [
+                        { event: '<start_step>', label: 'Started' },
+                        { event: '<middle_step>', label: 'Reached milestone' },
+                        { event: '<outcome_step>', label: 'Completed' },
+                    ],
+                },
+                filters: [],
+                range: { preset: '30d' },
+                limit: 3,
+            },
+        },
+        {
+            id: 'route_request_totals',
+            title: 'Route request totals',
+            visualization: 'table',
+            purpose: 'Compare observed request path totals without treating them as conversion rates.',
+            usableAsIs: false,
+            placeholders: {
+                paths: ['/<start_path>', '/<middle_path>', '/<outcome_path>'],
+            },
+            adaptWith: [
+                'Use when the source code shows ordered route milestones but custom events are unavailable.',
                 'Replace placeholders with exact observed paths from the selected app.',
-                'Do not include repeated activity routes unless source context says they are milestones.',
+                'Use custom events with unit and flow metadata for conversion funnels.',
             ],
             spec: {
                 version: 1,
                 dataset: 'events',
-                visualization: 'funnel',
+                visualization: 'table',
                 metric: { name: 'request_count' },
                 groupBy: [{ field: 'path' }],
                 filters: [
                     {
                         field: 'path',
                         op: 'in',
-                        value: ['/<start_path>', '/<middle_path>', '/<conversion_path>'],
+                        value: ['/<start_path>', '/<middle_path>', '/<outcome_path>'],
                     },
                 ],
                 range: { preset: '30d' },
@@ -4208,6 +4474,33 @@ function analyticsChartTemplates() {
                 limit: 3,
             },
         },
+        {
+            id: 'activity_rate',
+            title: 'Activity rate',
+            visualization: 'number',
+            purpose: 'Show an average repeated-activity total recorded on an outcome event.',
+            usableAsIs: false,
+            placeholders: {
+                eventName: '<outcome_event>',
+                metric: 'avg:<queryable_metric_property>',
+            },
+            adaptWith: [
+                'Use when the outcome event records a numeric total such as throws, answers, edits, duration_ms, or attempts.',
+                'Activate the metric property for the selected outcome event before dashboard queries.',
+                'Use raw activity volume charts when the app only emits repeated activity events and no per-unit total.',
+            ],
+            spec: {
+                version: 1,
+                dataset: 'events',
+                visualization: 'number',
+                metric: { name: 'avg:<queryable_metric_property>' },
+                groupBy: [],
+                filters: [{ field: 'event_name', op: '=', value: '<outcome_event>' }],
+                range: { preset: '30d' },
+                sort: [],
+                limit: 1,
+            },
+        },
         {
             id: 'property_breakdown',
             title: 'Property breakdown',
@@ -4235,6 +4528,42 @@ function analyticsChartTemplates() {
                 limit: 10,
             },
         },
+        {
+            id: 'experiment_readout',
+            title: 'Experiment readout',
+            visualization: 'table',
+            purpose: 'Compare selected milestones by experiment variant in one table.',
+            usableAsIs: false,
+            placeholders: {
+                eventNames: ['<exposure_event>', '<started_event>', '<outcome_event>'],
+                property: 'experiment_variant',
+            },
+            adaptWith: [
+                'Use when each selected event has an active low-cardinality experiment_variant property mapping.',
+                'Keep this as a table; do not render raw event totals as conversion percentages.',
+                'Use exact analysis for low-volume winner decisions.',
+            ],
+            spec: {
+                version: 1,
+                dataset: 'events',
+                visualization: 'table',
+                metric: { name: 'custom_event_count' },
+                groupBy: [
+                    { field: 'event_name' },
+                    { field: 'property:experiment_variant' },
+                ],
+                filters: [
+                    {
+                        field: 'event_name',
+                        op: 'in',
+                        value: ['<exposure_event>', '<started_event>', '<outcome_event>'],
+                    },
+                ],
+                range: { preset: '30d' },
+                sort: [{ field: 'event_name', direction: 'asc' }],
+                limit: 50,
+            },
+        },
         {
             id: 'average_metric_property',
             title: 'Average metric property',
@@ -5235,9 +5564,15 @@ function parseTenderArgs(args) {
         if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'capabilities') {
             return parseAnalyticsCapabilitiesArgs(resourceArgs.slice(3));
         }
+        if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'authoring') {
+            return parseAnalyticsAuthoringArgs(resourceArgs.slice(3));
+        }
         if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'suggestions') {
             return parseAnalyticsSuggestionsArgs(resourceArgs.slice(3));
         }
+        if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'exact-funnel') {
+            return parseAnalyticsExactFunnelArgs(resourceArgs.slice(3));
+        }
         if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'dashboards') {
             return parseAnalyticsDashboardsArgs(resourceArgs.slice(3));
         }
@@ -5790,6 +6125,9 @@ function analyticsCorrectedExample(artifactId, analyticsPath) {
     if (analyticsPath === 'suggestions') {
         return `tender app analytics suggestions ${artifactId} --range 30d --json`;
     }
+    if (analyticsPath === 'exact-funnel') {
+        return `tender app analytics exact-funnel ${artifactId} --flow <flow-id> --steps started,completed --range 30d --json`;
+    }
     if (analyticsPath === 'properties') {
         return `tender app analytics properties list ${artifactId} --json`;
     }
@@ -9268,6 +9606,31 @@ async function runAnalyticsSuggestions(command, io, runtime) {
     printAnalyticsPayload(command, io, payload, [`app_id: ${command.artifactId}`, `suggestions: ${suggestions.length}`]);
     return 0;
 }
+async function runAnalyticsExactFunnel(command, io, runtime) {
+    const credentials = await resolveAnalyticsCredentials(command, runtime);
+    const payload = await requestAnalyticsApi({
+        artifactId: command.artifactId,
+        analyticsPath: 'exact-funnel',
+        method: 'POST',
+        baseUrl: credentials.baseUrl,
+        token: credentials.token,
+        fetcher: runtime.fetcher ?? fetch,
+        range: command.range,
+        body: {
+            flowId: command.flowId,
+            steps: command.steps,
+        },
+    });
+    const rows = Array.isArray(payload.rows) ? payload.rows : [];
+    printAnalyticsPayload(command, io, payload, [
+        `app_id: ${command.artifactId}`,
+        `source: ${String(payload.source ?? 'unknown')}`,
+        `flow_id: ${command.flowId}`,
+        `steps: ${rows.length}`,
+        `exact: ${String(payload.exact ?? false)}`,
+    ]);
+    return 0;
+}
 async function runAnalyticsDashboards(command, io, runtime) {
     if (command.name && command.dryRun) {
         const payload = {
@@ -9814,9 +10177,15 @@ export async function runTenderCli(args, io = {
             else if (command.topic === 'app analytics capabilities') {
                 io.stdout(analyticsCapabilitiesHelp());
             }
+            else if (command.topic === 'app analytics authoring') {
+                io.stdout(analyticsAuthoringHelp());
+            }
             else if (command.topic === 'app analytics suggestions') {
                 io.stdout(analyticsSuggestionsHelp());
             }
+            else if (command.topic === 'app analytics exact-funnel') {
+                io.stdout(analyticsExactFunnelHelp());
+            }
             else if (command.topic === 'app analytics dashboards') {
                 io.stdout(analyticsDashboardsHelp());
             }
@@ -10002,9 +10371,15 @@ export async function runTenderCli(args, io = {
         if (command.command === 'app analytics capabilities') {
             return await runAnalyticsCapabilities(command, io, runtime);
         }
+        if (command.command === 'app analytics authoring') {
+            return runAnalyticsAuthoring(command, io);
+        }
         if (command.command === 'app analytics suggestions') {
             return await runAnalyticsSuggestions(command, io, runtime);
         }
+        if (command.command === 'app analytics exact-funnel') {
+            return await runAnalyticsExactFunnel(command, io, runtime);
+        }
         if (command.command === 'app analytics dashboards') {
             return await runAnalyticsDashboards(command, io, runtime);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tenderprompt/cli",
-	"version": "0.1.23",
+	"version": "0.1.24",
 	"type": "module",
 	"bin": {
 		"tender": "bin/tender.js"