@tenderprompt/cli 0.1.24 → 0.1.25

package/README.md

@@ -43,6 +43,7 @@ session:
   analytics history, app database rows, secrets, or release history
 - run server-validated chart specs and export aggregate rows
 - generate starter analytics suggestions
+- print a non-mutating default analytics provisioning plan for generated apps
 - create, list, update, and delete saved analytics dashboards and charts, with
   `--dry-run` available for write previews
 
@@ -79,6 +80,13 @@ For agents, keep the pattern simple:
 6. call `preview`, `publish --dry-run`, then `publish --confirm publish` only
    when the user asked to publish
 
+For replacement work, run `tender app analytics authoring --json` before adding
+or repairing instrumentation. Its agent guidance tells agents to inspect the
+existing shopper surface before source edits, keep operator analytics out of
+shopper UI, and treat default analytics plus saved starter dashboard charts as
+part of generated-app delivery unless the user opts out or there is a concrete
+blocker.
+
 ## Auth
 
 Use the device login flow to mint a local token:
@@ -185,6 +193,7 @@ agents:
 
 ```bash
 tender app analytics capabilities artifact_123 --include-catalog --range 30d --json
+tender app analytics provision artifact_123 --from-app --json
 ```
 
 That response tells the agent:
@@ -201,6 +210,8 @@ Common read-only commands:
 ```bash
 tender app analytics summary artifact_123 --range 30d --json
 
+tender app analytics provision artifact_123 --from-app --json
+
 tender app analytics query artifact_123 --spec chart.json --json
 
 tender app analytics query artifact_123 --spec - --json < chart.json
@@ -256,6 +267,10 @@ explicit:
 tender app analytics charts list artifact_123 --dashboard analytics_dashboard_123 --json
 ```
 
+`analytics provision --from-app` is a guided plan in this release, not a hidden
+write. It returns starter chart specs, write-preview commands, write commands,
+blockers, and the chart-list completion proof an external agent should report.
+
 Agents should combine `capabilities --include-catalog` with local source-code
 inspection. For example, inspect where the app calls
 `__TP_ANALYTICS.invoke(...)`, propose a chart spec, validate it with

package/dist/artifact-memory.js

@@ -100,7 +100,8 @@ function assertUsefulMemoryText(input) {
     if (lineCount > 240 || byteLength(total) > ARTIFACT_MEMORY_ENTRY_MAX_BYTES) {
         throw new Error(`Memory entries are limited to ${ARTIFACT_MEMORY_ENTRY_MAX_BYTES} bytes. Summarize the relevant context instead.\nNext: tender memory handoff --reason "Need Tender support" --summary "Current blocker and what was tried"`);
     }
-    if (lineCount > 40 && !/^summary|support_handoff|reflection$/i.test(input.summary)) {
+    const allowsLongBody = input.kind === 'summary' || input.kind === 'support_handoff' || input.kind === 'reflection';
+    if (lineCount > 40 && !allowsLongBody) {
         throw new Error('Memory entries should be bounded summaries, not raw transcript dumps.\nNext: tender memory add --kind summary --summary "Compact the useful context" --body "Goal, changes, failures, and next step"');
     }
 }
@@ -162,14 +163,14 @@ async function readExistingNote(input) {
     return result.exitCode === 0 ? result.stdout : '';
 }
 export async function appendArtifactMemoryNote(input) {
-    assertUsefulMemoryText(input);
+    const normalizedKind = normalizeArtifactMemoryKind(input.kind);
+    assertUsefulMemoryText({ ...input, kind: normalizedKind.kind });
     const commitSha = input.commitSha ?? (await readArtifactMemoryHead(input));
     const artifactId = input.artifactId ?? (await inferArtifactIdFromRemote(input));
     if (!artifactId) {
         throw new Error('Artifact memory requires an artifact id. Pass --artifact or run inside a checkout with a Tender artifact remote.\nNext: tender app git setup <app-id> --dir .');
     }
     const sessionId = await readArtifactMemorySessionId(input);
-    const normalizedKind = normalizeArtifactMemoryKind(input.kind);
     const redactedSummary = redactArtifactMemoryText(input.summary.trim());
     const redactedBody = input.body?.trim() ? redactArtifactMemoryText(input.body.trim()) : null;
     const warnings = [

package/dist/index.js

@@ -34,6 +34,61 @@ 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`;
+const ANALYTICS_AGENT_GUIDANCE = {
+    generatedAppDelivery: {
+        defaultAnalytics: 'Generated apps should emit useful Tender analytics events and provision saved starter dashboard charts by default unless the user opts out or a concrete blocker is recorded.',
+        skipOnlyWhen: ['The user explicitly opts out.', 'A concrete platform or data blocker is reported.'],
+    },
+    replacementBaseline: {
+        requiredBeforeSourceEdits: true,
+        guidance: 'Replacement work must inspect and interact with the existing customer-facing surface before source edits, or record the concrete blocker.',
+        browserToolPriority: [
+            'Codex in-app browser:browser skill',
+            'agent-browser',
+            'Chrome DevTools MCP',
+            'Playwright',
+            'another browser-capable tool',
+        ],
+    },
+    shopperOperatorBoundary: {
+        guidance: 'Tender analytics dashboards, A/B reports, sessions, and internal counters are operator-facing Tender surfaces, not shopper-facing app UI.',
+        shopperUiMustNotInclude: [
+            'analytics dashboards',
+            'A/B reports',
+            'sessions tables',
+            'internal counters',
+            'dashboard controls',
+            'shopper-callable analytics summary routes',
+        ],
+        adminSurfaceException: 'Only build an admin or operator surface when the user explicitly asks for one, and secure it so shopper traffic cannot read internal analytics.',
+    },
+    dashboardCompletion: {
+        completeWhen: [
+            'A Tender dashboard exists or is reused.',
+            'Required queryable properties are active, already queryable, or blocked with an actionable reason.',
+            'Saved starter charts exist for the app journey.',
+            'The saved chart list has been queried and returns the chart names or ids.',
+        ],
+        notCompleteWhen: ['Only an empty dashboard shell exists.'],
+        proofCommand: 'tender app analytics charts list <app-id> --dashboard <dashboard-id> --json',
+    },
+    starterDashboardCommands: [
+        'tender app analytics authoring --json',
+        'tender playbooks get analytics-event-authoring --json',
+        'tender app analytics charts templates --json',
+        'tender app analytics properties activate <app-id> --event <event-name> --property <property-key> --type dimension --dry-run --json',
+        'tender app analytics dashboards <app-id> --create "Agent dashboard" --dry-run --json',
+        'tender app analytics charts create <app-id> --dashboard <dashboard-id> --title <title> --spec chart.json --dry-run --json',
+        'tender app analytics charts list <app-id> --dashboard <dashboard-id> --json',
+    ],
+    finalAnswerEvidence: [
+        'baseline inspection scope or blocker',
+        'published URL or preview status',
+        'Tender dashboard id',
+        'saved chart names or ids from charts list',
+        'clear split between shopper-facing UI and operator-facing analytics',
+    ],
+};
 class TenderCliUsageError extends Error {
     constructor(message) {
         super(message);
@@ -350,12 +405,12 @@ Commands:
                              Rebuild the preview and optionally stream lifecycle events
   tender app preview status <app-id>
                              Show preview job status by latest, commit, or job id
-  tender app preview watch <app-id>
-                             Replay lifecycle events by latest, commit, or job id
-  tender app agent heartbeat <app-id>
-                             Send a concise agent status update to the workspace
-  tender app publish <app-id>
-                             Publish after dry-run or explicit confirmation
+	  tender app preview watch <app-id>
+	                             Replay lifecycle events by latest, commit, or job id
+	  tender app agent heartbeat <app-id>
+	                             Send a concise agent status update to the workspace
+	  tender app publish <app-id>
+	                             Publish after dry-run or explicit confirmation
   tender app publish status <app-id>
                              Show publish job status by job id
   tender app publish watch <app-id>
@@ -372,6 +427,8 @@ Commands:
                              Run a server-validated chart spec
   tender app analytics suggestions <app-id>
                              Generate useful starter chart suggestions
+  tender app analytics provision <app-id>
+                             Print a starter dashboard provisioning plan
   tender app analytics dashboards <app-id>
                              List or create saved dashboards
   tender app analytics charts create <app-id>
@@ -537,6 +594,7 @@ Commands:
   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 provision <app-id>     Print a starter dashboard provisioning plan
   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
@@ -557,6 +615,7 @@ Examples:
   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 provision artifact_123 --from-app --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 unit-funnel.json --json
@@ -572,6 +631,10 @@ function analyticsAuthoringHelp() {
 Prints the current generated-app analytics event authoring contract. This command
 does not require an app id, checkout, API token, or installed skill.
 
+Agent guidance includes default generated-app analytics, replacement baseline
+inspection, shopper/operator surface separation, and dashboard chart-list
+completion criteria.
+
 Examples:
   tender app analytics authoring --json`;
 }
@@ -638,6 +701,18 @@ dashboard page loads.
 Examples:
   tender app analytics exact-funnel artifact_123 --flow checkout_flow --steps started,completed --range 30d --json`;
 }
+function analyticsProvisionHelp() {
+    return `Usage: tender app analytics provision <app-id> --from-app [--dashboard-name <name>] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
+
+Prints a machine-readable provisioning plan for the default generated-app
+analytics delivery contract. This command does not mutate dashboards yet; it
+returns the exact commands, starter chart specs, completion criteria, and
+blockers an external coding agent should follow.
+
+Examples:
+  tender app analytics provision artifact_123 --from-app --json
+  tender app analytics provision artifact_123 --from-app --dashboard-name "Recommendation dashboard" --json`;
+}
 function analyticsDashboardsHelp() {
     return `Usage: tender app analytics dashboards <app-id> [--create <name>] [--dry-run] [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
@@ -1097,6 +1172,15 @@ Examples:
   tender app agent heartbeat artifact_123 --source claude-code --status needs_attention --summary "Waiting for an API key decision" --requested-action answer_question --json
   tender app agent heartbeat artifact_123 --input - --json < heartbeat.json`;
 }
+function appAgentHelp() {
+    return `Usage: tender app agent <command>
+
+Commands:
+  heartbeat <app-id>    Send a concise agent status update to the workspace.
+
+Examples:
+  tender app agent heartbeat artifact_123 --source codex --status working --summary "Reading files" --json`;
+}
 function publishStatusHelp() {
     return `Usage: tender app publish status <app-id> --job <job-id> [--base-url <url>] [--token <token>] [--profile <name>] [--json]
 
@@ -1174,6 +1258,7 @@ function tenderCliCapabilities() {
             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.',
+            guidance: ANALYTICS_AGENT_GUIDANCE,
         },
         description: 'Agent-safe Tender App source, lifecycle, analytics, and local scaffold controls.',
         discovery: {
@@ -1185,6 +1270,7 @@ function tenderCliCapabilities() {
                 'tender memory --help',
                 'tender playbooks --help',
                 'tender app --help',
+                'tender app agent --help',
                 'tender app agent heartbeat --help',
                 'tender app share --help',
                 'tender app claim --help',
@@ -1286,6 +1372,7 @@ function tenderCliCapabilities() {
                 commands: [
                     ANALYTICS_AUTHORING_COMMAND,
                     ANALYTICS_AUTHORING_PLAYBOOK_COMMAND,
+                    'tender app analytics provision <artifact-id> --from-app --json',
                     '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',
@@ -1300,10 +1387,14 @@ function tenderCliCapabilities() {
                 ],
                 notes: [
                     'Run authoring before adding or repairing analytics instrumentation; use capabilities for artifact-scoped read/query details.',
+                    'Generated apps should get useful Tender analytics events and saved starter dashboard charts by default unless the user opts out or a concrete blocker is recorded.',
+                    'For replacement work, inspect the baseline customer-facing page or widget before source edits; Codex should prefer browser:browser when available.',
+                    'Tender analytics dashboards are operator-facing surfaces; do not render dashboards, A/B reports, sessions, or internal counters in shopper UI unless the user explicitly requests a secured admin surface.',
                     '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.',
                     'Ad hoc query is read-only; if it reports a missing dashboard-query property, activate the property first or save the chart through charts create/update.',
+                    'Dashboard setup is not complete until saved charts exist and tender app analytics charts list returns chart names or ids.',
                     'Use list before writes so agents can avoid duplicates and explain the exact chart they are changing.',
                 ],
             },
@@ -1450,6 +1541,12 @@ function tenderCliCapabilities() {
                 requiresAuth: false,
                 writes: false,
             },
+            {
+                command: 'tender app analytics provision <artifact-id> --from-app --json',
+                purpose: 'Print a guided starter dashboard provisioning plan with chart-list completion proof.',
+                requiresAuth: false,
+                writes: false,
+            },
             {
                 command: 'tender app analytics properties list <artifact-id> --json',
                 purpose: 'List custom event properties available to dashboard queries.',
@@ -4103,6 +4200,35 @@ function parseAnalyticsDashboardsArgs(args) {
     }
     return { command: 'app analytics dashboards', artifactId, name, dryRun, ...parsed };
 }
+function parseAnalyticsProvisionArgs(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        return { command: 'help', topic: 'app analytics provision' };
+    }
+    const artifactId = args[0];
+    if (!artifactId || artifactId.startsWith('-')) {
+        throw new TenderCliUsageError('app id is required. Example: tender app analytics provision <app-id> --from-app --json');
+    }
+    const parsed = parseAnalyticsCommonArgs(args, 1);
+    let fromApp = false;
+    let dashboardName = 'Agent dashboard';
+    for (let index = 0; index < parsed.remaining.length; index += 1) {
+        const arg = parsed.remaining[index];
+        if (arg === '--from-app') {
+            fromApp = true;
+            continue;
+        }
+        if (arg === '--dashboard-name') {
+            dashboardName = parseRequiredFlagValue(parsed.remaining[index + 1], '--dashboard-name');
+            index += 1;
+            continue;
+        }
+        throw new TenderCliUsageError(`Unknown analytics provision option: ${arg}`);
+    }
+    if (!fromApp) {
+        throw new TenderCliUsageError('--from-app is required. Example: tender app analytics provision artifact_123 --from-app --json');
+    }
+    return { command: 'app analytics provision', artifactId, fromApp, dashboardName, ...parsed };
+}
 function parseAnalyticsChartsTemplatesArgs(args) {
     if (args.includes('--help') || args.includes('-h')) {
         return { command: 'help', topic: 'app analytics charts templates' };
@@ -4222,6 +4348,7 @@ function analyticsAuthoringContract() {
                 'analytics_unstable_unit_id',
             ],
         },
+        agentGuidance: ANALYTICS_AGENT_GUIDANCE,
         analyticsAuthoring: {
             payloadShape: {
                 event: 'custom_event_name',
@@ -4293,6 +4420,8 @@ function analyticsAuthoringContract() {
             },
         ],
         charting: {
+            starterDashboardCommands: ANALYTICS_AGENT_GUIDANCE.starterDashboardCommands,
+            completionProof: ANALYTICS_AGENT_GUIDANCE.dashboardCompletion.proofCommand,
             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.',
         },
@@ -4648,6 +4777,100 @@ function runAnalyticsChartsTemplates(command, io) {
     }
     return 0;
 }
+function quoteCliArgument(value) {
+    return JSON.stringify(value);
+}
+function buildAnalyticsProvisionPayload(command) {
+    const starterTemplateIds = new Set(['daily_custom_events', 'top_custom_events']);
+    const starterCharts = analyticsChartTemplates()
+        .filter((template) => starterTemplateIds.has(template.id))
+        .map((template) => ({
+        templateId: template.id,
+        title: template.title,
+        purpose: template.purpose,
+        spec: template.spec,
+    }));
+    const dashboardName = quoteCliArgument(command.dashboardName);
+    return {
+        ok: true,
+        command: command.command,
+        version: 1,
+        artifactId: command.artifactId,
+        mode: 'guided_provisioning_plan',
+        writes: false,
+        fromApp: command.fromApp,
+        dashboardName: command.dashboardName,
+        description: 'Machine-readable starter dashboard provisioning plan for external coding agents. This command does not mutate dashboards yet.',
+        agentGuidance: ANALYTICS_AGENT_GUIDANCE,
+        starterCharts,
+        steps: [
+            {
+                id: 'read_authoring_contract',
+                command: ANALYTICS_AUTHORING_COMMAND,
+                completion: 'Generated app analytics payload contract and surface boundary are loaded.',
+            },
+            {
+                id: 'inspect_app_analytics',
+                commands: [
+                    `tender app analytics capabilities ${command.artifactId} --include-catalog --range 30d --json`,
+                    'tender app doctor --dir . --json',
+                ],
+                completion: 'Observed events, unit/flow metadata, existing dashboards, and local analytics diagnostics are known.',
+            },
+            {
+                id: 'choose_starter_charts',
+                command: 'tender app analytics charts templates --json',
+                defaultTemplates: ['daily_custom_events', 'top_custom_events'],
+                completion: 'Starter chart specs are adapted to observed events or accepted as generic app-owned event charts.',
+            },
+            {
+                id: 'create_or_reuse_dashboard',
+                dryRunCommand: `tender app analytics dashboards ${command.artifactId} --create ${dashboardName} --dry-run --json`,
+                writeCommand: `tender app analytics dashboards ${command.artifactId} --create ${dashboardName} --json`,
+                completion: 'A dashboard id is available, either reused from capabilities or returned by the create command.',
+            },
+            {
+                id: 'validate_chart_specs',
+                command: `tender app analytics query ${command.artifactId} --spec chart.json --json`,
+                completion: 'Each chart spec is server-validated before it is saved.',
+            },
+            {
+                id: 'create_saved_charts',
+                dryRunCommand: `tender app analytics charts create ${command.artifactId} --dashboard <dashboard-id> --title <title> --spec chart.json --dry-run --json`,
+                writeCommand: `tender app analytics charts create ${command.artifactId} --dashboard <dashboard-id> --title <title> --spec chart.json --json`,
+                completion: 'Saved chart ids exist for starter charts, or a concrete blocker is reported.',
+            },
+            {
+                id: 'prove_completion',
+                command: `tender app analytics charts list ${command.artifactId} --dashboard <dashboard-id> --json`,
+                completion: 'The chart list returns saved chart names or ids; an empty dashboard shell is not complete.',
+            },
+        ],
+        completionCriteria: ANALYTICS_AGENT_GUIDANCE.dashboardCompletion.completeWhen,
+        blockers: [
+            'User explicitly opted out of analytics.',
+            'No meaningful generated-app journey exists to instrument yet.',
+            'App source cannot be inspected from the current checkout.',
+            'Dashboard/chart API returns an actionable auth, validation, or property activation error.',
+        ],
+        finalAnswerEvidence: ANALYTICS_AGENT_GUIDANCE.finalAnswerEvidence,
+    };
+}
+function runAnalyticsProvision(command, io) {
+    const payload = buildAnalyticsProvisionPayload(command);
+    if (command.json) {
+        io.stdout(JSON.stringify(payload, null, 2));
+    }
+    else {
+        io.stdout([
+            `app_id: ${command.artifactId}`,
+            'mode: guided_provisioning_plan',
+            `dashboard: ${command.dashboardName}`,
+            `proof: ${ANALYTICS_AGENT_GUIDANCE.dashboardCompletion.proofCommand}`,
+        ].join('\n'));
+    }
+    return 0;
+}
 function parseAnalyticsChartsCreateArgs(args) {
     if (args.includes('--help') || args.includes('-h')) {
         return { command: 'help', topic: 'app analytics charts create' };
@@ -5526,7 +5749,7 @@ function parseTenderArgs(args) {
             return parseContextRefreshArgs(resourceArgs.slice(3));
         }
         if (resourceArgs[1] === 'agent' && (resourceArgs[2] === undefined || resourceArgs[2] === '--help' || resourceArgs[2] === '-h')) {
-            return { command: 'help', topic: 'app agent heartbeat' };
+            return { command: 'help', topic: 'app agent' };
         }
         if (resourceArgs[1] === 'agent' && resourceArgs[2] === 'heartbeat') {
             return parseAgentHeartbeatArgs(resourceArgs.slice(3));
@@ -5576,6 +5799,9 @@ function parseTenderArgs(args) {
         if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'dashboards') {
             return parseAnalyticsDashboardsArgs(resourceArgs.slice(3));
         }
+        if (resourceArgs[1] === 'analytics' && resourceArgs[2] === 'provision') {
+            return parseAnalyticsProvisionArgs(resourceArgs.slice(3));
+        }
         if (resourceArgs[1] === 'analytics' &&
             resourceArgs[2] === 'properties' &&
             (resourceArgs[3] === undefined || resourceArgs[3] === '--help' || resourceArgs[3] === '-h')) {
@@ -10150,6 +10376,9 @@ export async function runTenderCli(args, io = {
             else if (command.topic === 'app preview watch') {
                 io.stdout(previewWatchHelp());
             }
+            else if (command.topic === 'app agent') {
+                io.stdout(appAgentHelp());
+            }
             else if (command.topic === 'app agent heartbeat') {
                 io.stdout(agentHeartbeatHelp());
             }
@@ -10189,6 +10418,9 @@ export async function runTenderCli(args, io = {
             else if (command.topic === 'app analytics dashboards') {
                 io.stdout(analyticsDashboardsHelp());
             }
+            else if (command.topic === 'app analytics provision') {
+                io.stdout(analyticsProvisionHelp());
+            }
             else if (command.topic === 'app analytics export') {
                 io.stdout(analyticsExportHelp());
             }
@@ -10383,6 +10615,9 @@ export async function runTenderCli(args, io = {
         if (command.command === 'app analytics dashboards') {
             return await runAnalyticsDashboards(command, io, runtime);
         }
+        if (command.command === 'app analytics provision') {
+            return runAnalyticsProvision(command, io);
+        }
         if (command.command === 'app analytics export catalog') {
             return await runAnalyticsExportCatalog(command, io, runtime);
         }

package/package.json

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