@amplitude/wizard 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/bin.js

@@ -142,11 +142,6 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     if (options.ci) {
         // Use LoggingUI for CI mode (no dependencies, no prompts)
         (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
-        if (!options.apiKey) {
-            (0, ui_1.getUI)().intro(chalk_1.default.inverse(`Amplitude Wizard`));
-            (0, ui_1.getUI)().log.error('CI mode requires --api-key (Amplitude project API key)');
-            process.exit(1);
-        }
         if (!options.installDir) {
             (0, ui_1.getUI)().intro(chalk_1.default.inverse(`Amplitude Wizard`));
             (0, ui_1.getUI)().log.error('CI mode requires --install-dir (directory to install Amplitude in)');
@@ -161,7 +156,8 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
             'It appears you are running in a non-interactive environment.\n' +
             'Please run the wizard in an interactive terminal.\n\n' +
             'For CI/CD environments, use --ci mode:\n' +
-            '  npx @amplitude/wizard --ci --api-key <your-key> --install-dir .');
+            '  npx @amplitude/wizard --ci --install-dir . [--api-key <your-key>]\n' +
+            '  (--api-key is optional when a key can be resolved from env or stored credentials.)');
         process.exit(1);
     }
     else {
@@ -205,12 +201,13 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     // returning users. This skips RegionSelect and Auth without requiring
                     // a persisted OAuth token.
                     const installDir = session.installDir;
-                    const [{ getStoredUser, getStoredToken }, { readAmpliConfig }, { getAPIKey }, { getHostFromRegion }, { logToFile },] = await Promise.all([
+                    const [{ getStoredUser, getStoredToken }, { readAmpliConfig }, { getAPIKey }, { getHostFromRegion }, { logToFile }, { fetchAmplitudeUser },] = await Promise.all([
                         import('./src/utils/ampli-settings.js'),
                         import('./src/lib/ampli-config.js'),
                         import('./src/utils/get-api-key.js'),
                         import('./src/utils/urls.js'),
                         import('./src/utils/debug.js'),
+                        import('./src/lib/api.js'),
                     ]);
                     // Zone: prefer a real (non-pending) stored user, fall back to
                     // the Zone field in the project-level ampli.json.
@@ -226,43 +223,108 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     }
                     // Skip Auth when we have a stored OAuth token — use it to fetch
                     // (or look up) the project API key, then pre-populate credentials.
+                    // When the workspace has multiple environments (projects), defer to
+                    // AuthScreen so the user can pick which project to instrument.
                     if (zone) {
                         const storedToken = realUser
                             ? getStoredToken(realUser.id, realUser.zone)
                             : getStoredToken(undefined, zone);
                         if (storedToken) {
-                            logToFile(`[bin] getAPIKey: zone=${zone} hasWorkspaceId=${!!session.selectedWorkspaceId}`);
-                            const projectApiKey = await getAPIKey({
-                                installDir,
-                                idToken: storedToken.idToken,
-                                zone,
-                                workspaceId: session.selectedWorkspaceId ?? undefined,
-                            });
-                            if (projectApiKey) {
-                                logToFile('[bin] getAPIKey: resolved project API key');
-                                (0, api_key_store_1.persistApiKey)(projectApiKey, installDir);
+                            // Check local storage first — if a key is already persisted
+                            // for this install dir, use it without fetching user data.
+                            const { readApiKeyWithSource } = await import('./src/utils/api-key-store.js');
+                            const localKey = readApiKeyWithSource(installDir);
+                            if (localKey) {
+                                logToFile('[bin] using locally stored API key');
                                 session.credentials = {
                                     accessToken: storedToken.idToken,
                                     idToken: storedToken.idToken,
-                                    projectApiKey,
+                                    projectApiKey: localKey.key,
                                     host: getHostFromRegion(zone),
                                     projectId: 0,
                                 };
-                                // Pre-populate activationLevel so DataSetup is also skipped,
-                                // giving a single wipe from Intro → Run/Setup.
-                                // DataSetup would set 'none' anyway (projectId=0 prevents the
-                                // real check), so this is equivalent — just earlier.
                                 session.activationLevel = 'none';
                                 session.projectHasData = false;
                             }
                             else {
-                                logToFile('[bin] getAPIKey: returned null — showing apiKeyNotice');
-                                // Region is already pre-populated above; prompt for the
-                                // key manually with a hint about org-admin permissions.
-                                session.apiKeyNotice =
-                                    "Your API key couldn't be fetched automatically. " +
-                                        'Only organization admins can access project API keys — ' +
-                                        'if you need one, ask an admin to share it with you.';
+                                // Fetch user data to check how many environments are available.
+                                const { fetchAmplitudeUser } = await import('./src/lib/api.js');
+                                try {
+                                    const userInfo = await fetchAmplitudeUser(storedToken.idToken, zone);
+                                    const workspaceId = session.selectedWorkspaceId ?? undefined;
+                                    // Find the relevant workspace and its environments
+                                    let envsWithKey = [];
+                                    for (const org of userInfo.orgs) {
+                                        const ws = workspaceId
+                                            ? org.workspaces.find((w) => w.id === workspaceId)
+                                            : org.workspaces[0];
+                                        if (ws?.environments) {
+                                            envsWithKey = ws.environments
+                                                .filter((env) => env.app?.apiKey)
+                                                .sort((a, b) => a.rank - b.rank);
+                                            break;
+                                        }
+                                    }
+                                    if (envsWithKey.length === 1) {
+                                        // Single environment — auto-select as before
+                                        const apiKey = envsWithKey[0].app.apiKey;
+                                        session.selectedProjectName = envsWithKey[0].name;
+                                        logToFile('[bin] single environment — auto-selecting API key');
+                                        (0, api_key_store_1.persistApiKey)(apiKey, installDir);
+                                        session.credentials = {
+                                            accessToken: storedToken.idToken,
+                                            idToken: storedToken.idToken,
+                                            projectApiKey: apiKey,
+                                            host: getHostFromRegion(zone),
+                                            projectId: 0,
+                                        };
+                                        session.activationLevel = 'none';
+                                        session.projectHasData = false;
+                                    }
+                                    else if (envsWithKey.length > 1) {
+                                        // Multiple environments — show the project picker via
+                                        // AuthScreen instead of auto-selecting.
+                                        logToFile(`[bin] ${envsWithKey.length} environments found — deferring to project picker`);
+                                        session.pendingOrgs = userInfo.orgs;
+                                        session.pendingAuthIdToken = storedToken.idToken;
+                                        session.pendingAuthAccessToken = storedToken.idToken;
+                                    }
+                                    else {
+                                        logToFile('[bin] no environments with API keys — showing apiKeyNotice');
+                                        session.apiKeyNotice =
+                                            "Your API key couldn't be fetched automatically. " +
+                                                'Only organization admins can access project API keys — ' +
+                                                'if you need one, ask an admin to share it with you.';
+                                    }
+                                }
+                                catch (err) {
+                                    logToFile(`[bin] fetchAmplitudeUser failed: ${err instanceof Error ? err.message : 'unknown'}`);
+                                    // Fall back to getAPIKey for backward compatibility
+                                    const projectApiKey = await getAPIKey({
+                                        installDir,
+                                        idToken: storedToken.idToken,
+                                        zone,
+                                        workspaceId: session.selectedWorkspaceId ?? undefined,
+                                    });
+                                    if (projectApiKey) {
+                                        (0, api_key_store_1.persistApiKey)(projectApiKey, installDir);
+                                        session.credentials = {
+                                            accessToken: storedToken.idToken,
+                                            idToken: storedToken.idToken,
+                                            projectApiKey,
+                                            host: getHostFromRegion(zone),
+                                            projectId: 0,
+                                        };
+                                        session.activationLevel = 'none';
+                                        session.projectHasData = false;
+                                    }
+                                    else {
+                                        session.apiKeyNotice =
+                                            "Your API key couldn't be fetched automatically. " +
+                                                'Only organization admins can access project API keys — ' +
+                                                'if you need one, ask an admin to share it with you.';
+                                    }
+                                }
                             }
                         }
                     }
@@ -275,8 +337,46 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     if (projectConfig.ok && projectConfig.config.WorkspaceId) {
                         session.selectedWorkspaceId = projectConfig.config.WorkspaceId;
                     }
+                    // Resolve org/workspace display names so /whoami shows them.
+                    // Uses the stored token to fetch user info — fire-and-forget so it
+                    // doesn't block startup.
+                    if (zone && session.selectedOrgId) {
+                        const storedToken = realUser
+                            ? getStoredToken(realUser.id, realUser.zone)
+                            : getStoredToken(undefined, zone);
+                        if (storedToken) {
+                            fetchAmplitudeUser(storedToken.idToken, zone)
+                                .then((userInfo) => {
+                                const org = userInfo.orgs.find((o) => o.id === session.selectedOrgId);
+                                if (org) {
+                                    session.selectedOrgName = org.name;
+                                    const ws = session.selectedWorkspaceId
+                                        ? org.workspaces.find((w) => w.id === session.selectedWorkspaceId)
+                                        : undefined;
+                                    if (ws) {
+                                        session.selectedWorkspaceName = ws.name;
+                                    }
+                                    // Update the store if it's already been assigned
+                                    if (tui.store.session === session) {
+                                        tui.store.emitChange();
+                                    }
+                                }
+                            })
+                                .catch(() => {
+                                // Non-fatal — /whoami will just show (none)
+                            });
+                        }
+                    }
                 }
                 tui.store.session = session;
+                // Initialize Amplitude Experiment feature flags (non-blocking).
+                const { initFeatureFlags } = await import('./src/lib/feature-flags.js');
+                await initFeatureFlags().catch(() => {
+                    // Flag init failure is non-fatal — all flags default to off
+                });
+                // Apply SDK-level opt-out based on feature flags
+                const { analytics } = await import('./src/utils/analytics.js');
+                analytics.applyOptOut();
                 const { FRAMEWORK_REGISTRY } = await import('./src/lib/registry.js');
                 const { detectIntegration } = await import('./src/run.js');
                 const installDir = session.installDir ?? process.cwd();
@@ -431,22 +531,27 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                             tui.store.addDiscoveredFeature(DiscoveredFeature.Stripe);
                         }
                         // LLM SDK detection — sourced from Amplitude LLM analytics skill
-                        const LLM_PACKAGES = [
-                            'openai',
-                            '@anthropic-ai/sdk',
-                            'ai',
-                            '@ai-sdk/openai',
-                            'langchain',
-                            '@langchain/openai',
-                            '@langchain/langgraph',
-                            '@google/generative-ai',
-                            '@google/genai',
-                            '@instructor-ai/instructor',
-                            '@mastra/core',
-                            'portkey-ai',
-                        ];
-                        if (depNames.some((d) => LLM_PACKAGES.includes(d))) {
-                            tui.store.addDiscoveredFeature(DiscoveredFeature.LLM);
+                        // Gated by the wizard-llm-analytics feature flag.
+                        const { isFlagEnabled } = await import('./src/lib/feature-flags.js');
+                        const { FLAG_LLM_ANALYTICS } = await import('./src/lib/feature-flags.js');
+                        if (isFlagEnabled(FLAG_LLM_ANALYTICS)) {
+                            const LLM_PACKAGES = [
+                                'openai',
+                                '@anthropic-ai/sdk',
+                                'ai',
+                                '@ai-sdk/openai',
+                                'langchain',
+                                '@langchain/openai',
+                                '@langchain/langgraph',
+                                '@google/generative-ai',
+                                '@google/genai',
+                                '@instructor-ai/instructor',
+                                '@mastra/core',
+                                'portkey-ai',
+                            ];
+                            if (depNames.some((d) => LLM_PACKAGES.includes(d))) {
+                                tui.store.addDiscoveredFeature(DiscoveredFeature.LLM);
+                            }
                         }
                     }
                     catch {
@@ -476,11 +581,19 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                 const localDetection = detectAmplitudeInProject(installDir);
                 if (localDetection.confidence !== 'none') {
                     const { logToFile: log } = await import('./src/utils/debug.js');
-                    log(`[bin] Amplitude already detected (${localDetection.reason ?? 'unknown'}) — skipping agent`);
+                    log(`[bin] Amplitude already detected (${localDetection.reason ?? 'unknown'}) — prompting on MCP screen (continue vs run wizard)`);
                     const { RunPhase, OutroKind } = await import('./src/lib/wizard-session.js');
                     tui.store.setAmplitudePreDetected();
-                    tui.store.setOutroData({ kind: OutroKind.Success });
                     tui.store.setRunPhase(RunPhase.Completed);
+                    const runWizardAnyway = await tui.store.waitForPreDetectedChoice();
+                    if (runWizardAnyway) {
+                        log('[bin] user chose to run setup wizard despite pre-detection');
+                        tui.store.resetForAgentAfterPreDetected();
+                        await (0, run_1.runWizard)(options, tui.store.session);
+                    }
+                    else {
+                        tui.store.setOutroData({ kind: OutroKind.Success });
+                    }
                 }
                 else {
                     await (0, run_1.runWizard)(options, tui.store.session);
@@ -589,6 +702,37 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
         }
         process.exit(0);
     })();
+})
+    .command('feedback', 'Send product feedback (Amplitude event: wizard: Feedback Submitted)', (yargs) => {
+    return yargs.options({
+        message: {
+            alias: 'm',
+            describe: 'Feedback message',
+            type: 'string',
+        },
+    });
+}, (argv) => {
+    void (async () => {
+        (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+        const fromFlag = typeof argv.message === 'string' ? argv.message.trim() : '';
+        const argvRest = argv._.slice(1).join(' ').trim();
+        const message = (fromFlag || argvRest).trim();
+        if (!message) {
+            (0, ui_1.getUI)().log.error('Usage: amplitude-wizard feedback <message>  or  feedback --message <message>');
+            process.exit(1);
+            return;
+        }
+        try {
+            const { trackWizardFeedback } = await import('./src/utils/track-wizard-feedback.js');
+            await trackWizardFeedback(message);
+            console.log(chalk_1.default.green('✔ Thanks — your feedback was sent.'));
+            process.exit(0);
+        }
+        catch (e) {
+            console.error(chalk_1.default.red(`Feedback failed: ${e instanceof Error ? e.message : String(e)}`));
+            process.exit(1);
+        }
+    })();
 })
     .command('slack', 'Set up Amplitude Slack integration', (y) => y, (argv) => {
     void (async () => {

package/dist/src/lib/agent-interface.js

@@ -153,7 +153,7 @@ function backupAndFixClaudeSettings(workingDirectory) {
     for (const name of ['settings.json', 'settings']) {
         const filePath = path_1.default.join(workingDirectory, '.claude', name);
         const backupPath = `${filePath}.wizard-backup`;
-        analytics_1.analytics.wizardCapture('backedup-claude-settings');
+        analytics_1.analytics.wizardCapture('Claude Settings Backed Up');
         try {
             fs.copyFileSync(filePath, backupPath);
             fs.unlinkSync(filePath);
@@ -182,7 +182,7 @@ function restoreClaudeSettings(workingDirectory) {
         const backup = path_1.default.join(workingDirectory, '.claude', `${name}.wizard-backup`);
         try {
             fs.copyFileSync(backup, path_1.default.join(workingDirectory, '.claude', name));
-            analytics_1.analytics.wizardCapture('restored-claude-settings');
+            analytics_1.analytics.wizardCapture('Claude Settings Restored');
             return;
         }
         catch (error) {
@@ -490,10 +490,7 @@ function wizardCanUseTool(toolName, input) {
     if (DANGEROUS_OPERATORS.test(command)) {
         (0, debug_1.logToFile)(`Denying bash command with dangerous operators: ${command}`);
         (0, debug_1.debug)(`Denying bash command with dangerous operators: ${command}`);
-        analytics_1.analytics.wizardCapture('bash denied', {
-            reason: 'dangerous operators',
-            command,
-        });
+        (0, analytics_1.captureWizardError)('Bash Policy', 'Dangerous shell operators are not permitted', 'wizardCanUseBash', { deny_reason: 'dangerous operators', command });
         return {
             behavior: 'deny',
             message: `Bash command not allowed. Shell operators like ; \` $ ( ) are not permitted.`,
@@ -509,10 +506,7 @@ function wizardCanUseTool(toolName, input) {
         if (/[|&]/.test(baseCommand)) {
             (0, debug_1.logToFile)(`Denying bash command with multiple pipes: ${command}`);
             (0, debug_1.debug)(`Denying bash command with multiple pipes: ${command}`);
-            analytics_1.analytics.wizardCapture('bash denied', {
-                reason: 'multiple pipes',
-                command,
-            });
+            (0, analytics_1.captureWizardError)('Bash Policy', 'Multiple pipes are not permitted', 'wizardCanUseBash', { deny_reason: 'multiple pipes', command });
             return {
                 behavior: 'deny',
                 message: `Bash command not allowed. Only single pipe to tail/head is permitted.`,
@@ -528,10 +522,7 @@ function wizardCanUseTool(toolName, input) {
     if (/[|&]/.test(normalized)) {
         (0, debug_1.logToFile)(`Denying bash command with pipe/&: ${command}`);
         (0, debug_1.debug)(`Denying bash command with pipe/&: ${command}`);
-        analytics_1.analytics.wizardCapture('bash denied', {
-            reason: 'disallowed pipe',
-            command,
-        });
+        (0, analytics_1.captureWizardError)('Bash Policy', 'Pipes are only allowed with tail/head', 'wizardCanUseBash', { deny_reason: 'disallowed pipe', command });
         return {
             behavior: 'deny',
             message: `Bash command not allowed. Pipes are only permitted with tail/head for output limiting.`,
@@ -545,10 +536,7 @@ function wizardCanUseTool(toolName, input) {
     }
     (0, debug_1.logToFile)(`Denying bash command: ${command}`);
     (0, debug_1.debug)(`Denying bash command: ${command}`);
-    analytics_1.analytics.wizardCapture('bash denied', {
-        reason: 'not in allowlist',
-        command,
-    });
+    (0, analytics_1.captureWizardError)('Bash Policy', 'Command not in allowlist', 'wizardCanUseBash', { deny_reason: 'not in allowlist', command });
     return {
         behavior: 'deny',
         message: `Bash command not allowed. Only install, build, typecheck, lint, and formatting commands are permitted.`,
@@ -783,10 +771,10 @@ async function runAgent(agentConfig, prompt, options, spinner, config, middlewar
         if (remarkMatch && remarkMatch[1]) {
             const remark = remarkMatch[1].trim();
             if (remark) {
-                analytics_1.analytics.capture(constants_1.WIZARD_REMARK_EVENT_NAME, { remark });
+                analytics_1.analytics.wizardCapture('Wizard Remark', { remark });
             }
         }
-        analytics_1.analytics.wizardCapture('agent completed', {
+        analytics_1.analytics.wizardCapture('Agent Completed', {
             duration_ms: durationMs,
             duration_seconds: durationSeconds,
         });
@@ -883,7 +871,7 @@ async function runAgent(agentConfig, prompt, options, spinner, config, middlewar
         for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
             if (attempt > 0) {
                 (0, debug_1.logToFile)(`Agent stall retry: attempt ${attempt + 1} of ${MAX_RETRIES + 1}`);
-                analytics_1.analytics.wizardCapture('agent stall retry', { attempt });
+                analytics_1.analytics.wizardCapture('Agent Stall Retry', { attempt });
                 // Clear per-attempt output so stale error markers don't affect the fresh run
                 collectedText.length = 0;
                 recentStatuses.length = 0;
@@ -910,7 +898,7 @@ async function runAgent(agentConfig, prompt, options, spinner, config, middlewar
                     clearTimeout(staleTimer);
                 staleTimer = setTimeout(() => {
                     (0, debug_1.logToFile)(`Agent stalled — no message for ${STALL_TIMEOUT_MS / 1000}s (attempt ${attempt + 1})`);
-                    analytics_1.analytics.wizardCapture('agent stall detected', {
+                    analytics_1.analytics.wizardCapture('Agent Stall Detected', {
                         attempt: attempt + 1,
                         stall_timeout_ms: STALL_TIMEOUT_MS,
                     });

package/dist/src/lib/agent-runner.js

@@ -140,7 +140,7 @@ async function runAgentWizard(config, session) {
         const versionBucket = config.detection.getVersionBucket(frameworkVersion);
         analytics_1.analytics.setTag(`${config.metadata.integration}-version`, versionBucket);
     }
-    analytics_1.analytics.wizardCapture('agent started', {
+    analytics_1.analytics.wizardCapture('Agent Started', {
         integration: config.metadata.integration,
     });
     // Credentials are pre-set by bin.ts (TUI mode) via the AuthScreen SUSI flow.
@@ -256,9 +256,7 @@ async function runAgentWizard(config, session) {
     }, middleware);
     // Handle error cases detected in agent output
     if (agentResult.error === agent_interface_1.AgentErrorType.AUTH_ERROR) {
-        analytics_1.analytics.wizardCapture('agent auth error', {
-            integration: config.metadata.integration,
-        });
+        (0, analytics_1.captureWizardError)('Agent Authentication', 'Session expired or invalid during agent run', 'agent-runner', { integration: config.metadata.integration });
         const authMessage = `Authentication failed\n\nYour Amplitude session has expired. Please run the wizard again to log in.`;
         session.credentials = null;
         session.outroData = {
@@ -297,10 +295,9 @@ async function runAgentWizard(config, session) {
     }
     if (agentResult.error === agent_interface_1.AgentErrorType.RATE_LIMIT ||
         agentResult.error === agent_interface_1.AgentErrorType.API_ERROR) {
-        analytics_1.analytics.wizardCapture('agent api error', {
+        (0, analytics_1.captureWizardError)('Agent API', agentResult.message ?? 'Unknown API error', 'agent-runner', {
             integration: config.metadata.integration,
             error_type: agentResult.error,
-            error_message: agentResult.message,
         });
         await (0, wizard_abort_1.wizardAbort)({
             message: `API Error\n\n${agentResult.message || 'Unknown error'}\n\nPlease report this error to: wizard@amplitude.com`,
@@ -401,6 +398,7 @@ STEP 5: Set up environment variables for Amplitude using the wizard-tools MCP se
    - Reference these environment variables in the code files you create instead of hardcoding the public token and host.
 
 STEP 6: Add event tracking to this project using the instrumentation skills.
+   - Call load_skill_menu with category "taxonomy" and install **amplitude-quickstart-taxonomy-agent** using install_skill. Load its SKILL.md and follow it when **naming events**, choosing **properties**, and scoping a **starter-kit taxonomy** (business-outcome events, property limits, funnel/linkage rules). Keep using this skill alongside instrumentation so names stay analysis-ready.
    - Call load_skill_menu with category "instrumentation" to see available instrumentation skills.
    - Install the "add-analytics-instrumentation" skill using install_skill.
    - Load the installed skill's SKILL.md file to understand the workflow.

package/dist/src/lib/commandments.js

@@ -13,7 +13,7 @@ const WIZARD_COMMANDMENTS = [
     'Always use the detect_package_manager tool from the wizard-tools MCP server to determine the package manager. Do not guess based on lockfiles or hard-code npm, yarn, pnpm, bun, pip, etc.',
     'When installing packages, start the installation as a background task and then continue with other work. Do not block waiting for installs to finish unless explicitly instructed.',
     'Before writing to any file, you MUST read that exact file immediately beforehand using the Read tool, even if you have already read it earlier in the run. This avoids tool failures and stale edits.',
-    'Treat feature flags, custom properties, and event names as part of an analytics contract. Prefer reusing existing names and patterns in the project. When you must introduce new ones, make them clear, descriptive, and consistent with existing conventions, and avoid scattering the same flag or property across many unrelated callsites.',
+    'Treat feature flags, custom properties, and event names as part of an analytics contract. Prefer reusing existing names and patterns in the project. When you must introduce new ones, make them clear, descriptive, and consistent with existing conventions, and avoid scattering the same flag or property across many unrelated callsites. For instrumentation runs, load the bundled **amplitude-quickstart-taxonomy-agent** skill (taxonomy category via wizard-tools) and align new event names and properties with its starter-kit rules (business-outcome naming, small property sets, no redundant pageview events, funnel-friendly linkage).',
     'Prefer minimal, targeted edits that achieve the requested behavior while preserving existing structure and style. Avoid large refactors, broad reformatting, or unrelated changes unless explicitly requested.',
     'Do not spawn subagents unless explicitly instructed to do so.',
     'Use the TodoWrite tool to track your progress. Create a todo list at the start describing the high-level areas of work, mark each as in_progress when you begin it, and completed when done.',

package/dist/src/lib/constants.d.ts

@@ -77,7 +77,7 @@ export declare const OUTBOUND_URLS: {
     /** New dashboard — opened from the Checklist screen. */
     newDashboard: (zone: AmplitudeZone, orgId?: string | null) => string;
     /** Slack integration settings — opened from the Slack screen. */
-    slackSettings: (zone: AmplitudeZone, orgName?: string | null) => string;
+    slackSettings: (zone: AmplitudeZone, orgId?: string | null, orgName?: string | null) => string;
     /** Products page — shown in the Outro for sign-up users. */
     products: (zone: AmplitudeZone) => string;
     /** SDK overview — opened from the Activation Options screen. */
@@ -105,11 +105,8 @@ export declare const OUTBOUND_URLS: {
     /** Bug reports and feedback. */
     githubIssues: string;
 };
-/** @deprecated Use OUTBOUND_URLS.githubIssues */
-export declare const ISSUES_URL: string;
 /** Placeholder embedded in generated code when the user skips key entry. */
 export declare const DUMMY_PROJECT_API_KEY = "_YOUR_AMPLITUDE_API_KEY_";
-export declare const WIZARD_REMARK_EVENT_NAME = "wizard remark";
 /** Feature flag key whose value selects a variant from WIZARD_VARIANTS. */
 export declare const WIZARD_VARIANT_FLAG_KEY = "wizard-variant";
 /** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */

package/dist/src/lib/constants.js

@@ -3,7 +3,7 @@
  * Shared constants for the Amplitude wizard.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DETECTION_TIMEOUT_MS = exports.AMPLITUDE_FLAG_HEADER_PREFIX = exports.AMPLITUDE_PROPERTY_HEADER_PREFIX = exports.WIZARD_USER_AGENT = exports.WIZARD_VARIANTS = exports.WIZARD_VARIANT_FLAG_KEY = exports.WIZARD_REMARK_EVENT_NAME = exports.DUMMY_PROJECT_API_KEY = exports.ISSUES_URL = exports.OUTBOUND_URLS = exports.DEFAULT_AMPLITUDE_ZONE = exports.AMPLITUDE_ZONE_SETTINGS = exports.OAUTH_PORT = exports.ANALYTICS_TEAM_TAG = exports.ANALYTICS_HOST_URL = exports.ANALYTICS_AMPLITUDE_PUBLIC_PROJECT_WRITE_KEY = exports.DEFAULT_HOST_URL = exports.DEFAULT_URL = exports.DEBUG = exports.IS_DEV = exports.Integration = void 0;
+exports.DETECTION_TIMEOUT_MS = exports.AMPLITUDE_FLAG_HEADER_PREFIX = exports.AMPLITUDE_PROPERTY_HEADER_PREFIX = exports.WIZARD_USER_AGENT = exports.WIZARD_VARIANTS = exports.WIZARD_VARIANT_FLAG_KEY = exports.DUMMY_PROJECT_API_KEY = exports.OUTBOUND_URLS = exports.DEFAULT_AMPLITUDE_ZONE = exports.AMPLITUDE_ZONE_SETTINGS = exports.OAUTH_PORT = exports.ANALYTICS_TEAM_TAG = exports.ANALYTICS_HOST_URL = exports.ANALYTICS_AMPLITUDE_PUBLIC_PROJECT_WRITE_KEY = exports.DEFAULT_HOST_URL = exports.DEFAULT_URL = exports.DEBUG = exports.IS_DEV = exports.Integration = void 0;
 const package_json_1 = require("../../package.json");
 // ── Integration / CLI ───────────────────────────────────────────────
 /**
@@ -108,11 +108,15 @@ exports.OUTBOUND_URLS = {
     },
     // ── Post-setup ────────────────────────────────────────────────────────────
     /** Slack integration settings — opened from the Slack screen. */
-    slackSettings: (zone, orgName) => {
+    slackSettings: (zone, orgId, orgName) => {
         const base = exports.OUTBOUND_URLS.overview[zone];
-        return orgName
-            ? `${base}/analytics/${encodeURIComponent(orgName)}/settings/profile`
-            : `${base}/settings/profile`;
+        if (orgName) {
+            return `${base}/analytics/${encodeURIComponent(orgName)}/settings/profile`;
+        }
+        if (orgId) {
+            return `${base}/${orgId}/settings/profile`;
+        }
+        return `${base}/settings/profile`;
     },
     /** Products page — shown in the Outro for sign-up users. */
     products: (zone) => `${exports.OUTBOUND_URLS.overview[zone]}/products?source=wizard`,
@@ -145,12 +149,9 @@ exports.OUTBOUND_URLS = {
     /** Bug reports and feedback. */
     githubIssues: 'https://github.com/amplitude/wizard/issues',
 };
-/** @deprecated Use OUTBOUND_URLS.githubIssues */
-exports.ISSUES_URL = exports.OUTBOUND_URLS.githubIssues;
 /** Placeholder embedded in generated code when the user skips key entry. */
 exports.DUMMY_PROJECT_API_KEY = '_YOUR_AMPLITUDE_API_KEY_';
 // ── Wizard run / variants ───────────────────────────────────────────
-exports.WIZARD_REMARK_EVENT_NAME = 'wizard remark';
 /** Feature flag key whose value selects a variant from WIZARD_VARIANTS. */
 exports.WIZARD_VARIANT_FLAG_KEY = 'wizard-variant';
 /** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */

package/dist/src/lib/feature-flags.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Feature flags powered by Amplitude Experiment (server-side local evaluation).
+ *
+ * Flags are fetched once at startup via `initFeatureFlags()` and evaluated
+ * synchronously thereafter — no per-check network calls.
+ */
+/** Gate for the LLM analytics additional-feature flow. */
+export declare const FLAG_LLM_ANALYTICS = "wizard-llm-analytics";
+/** Gate for agent-level analytics / telemetry instrumented by the wizard. */
+export declare const FLAG_AGENT_ANALYTICS = "wizard-agent-analytics";
+/**
+ * Initialize the Experiment local-evaluation client and pre-fetch flag configs.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ *
+ * @param userId  Optional user ID for targeted flag evaluation.
+ * @param deviceId  Optional device ID for targeted flag evaluation.
+ */
+export declare function initFeatureFlags(userId?: string, deviceId?: string): Promise<void>;
+/**
+ * Evaluate a single feature flag. Returns the string variant value,
+ * or `undefined` if the flag is not set / client not initialized.
+ */
+export declare function getFlag(flagKey: string): string | undefined;
+/**
+ * Check whether a flag is enabled (variant is `'on'` or `'true'`).
+ * Returns `false` when the flag is absent or the client is not initialized.
+ */
+export declare function isFlagEnabled(flagKey: string): boolean;
+/**
+ * Return a snapshot of all evaluated flags (key -> string value).
+ */
+export declare function getAllFlags(): Record<string, string>;
+/**
+ * Re-evaluate flags for a specific user (e.g. after login).
+ * Updates the cached flags in place.
+ */
+export declare function refreshFlags(userId?: string, deviceId?: string): Promise<void>;