diff --git a/bin.ts b/bin.ts
index a61e4cc..803fdf0 100644
--- a/bin.ts
+++ b/bin.ts
@@ -504,6 +504,49 @@ yargs(hideBin(process.argv))
       .demandCommand(1, 'You must specify a subcommand (add or remove)')
       .help();
   })
+  .command(
+    'setup-revenue-analytics',
+    'Set up Stripe revenue analytics with PostHog',
+    (yargs) => {
+      return yargs.options({
+        'install-dir': {
+          describe:
+            'Directory of the project to set up\nenv: POSTHOG_WIZARD_INSTALL_DIR',
+          type: 'string',
+        },
+      });
+    },
+    (argv) => {
+      const options = { ...argv };
+
+      void (async () => {
+        // Always use LoggingUI for this subcommand (simple linear flow)
+        setUI(new LoggingUI());
+
+        const { readApiKeyFromEnv } = await import(
+          './src/utils/env-api-key.js'
+        );
+        const { buildSession } = await import('./src/lib/wizard-session.js');
+        const { runSetupRevenueAnalytics } = await import(
+          './src/setup-revenue-analytics/index.js'
+        );
+
+        const apiKey =
+          (options.apiKey as string | undefined) || readApiKeyFromEnv();
+
+        const session = buildSession({
+          debug: options.debug as boolean | undefined,
+          installDir: options.installDir as string | undefined,
+          ci: options.ci as boolean | undefined,
+          localMcp: options.localMcp as boolean | undefined,
+          apiKey,
+          projectId: options.projectId as string | undefined,
+        });
+
+        await runSetupRevenueAnalytics(session);
+      })();
+    },
+  )
   .help()
   .alias('help', 'h')
   .version()
diff --git a/src/lib/agent-interface.ts b/src/lib/agent-interface.ts
index 1dca0cc..860b880 100644
--- a/src/lib/agent-interface.ts
+++ b/src/lib/agent-interface.ts
@@ -1188,7 +1188,6 @@ function handleSDKMessage(
             const statusMatch = block.text.match(statusRegex);
             if (statusMatch) {
               const statusText = statusMatch[1].trim();
-              getUI().pushStatus(statusText);
               spinner.message(statusText);
             }
           }
diff --git a/src/setup-revenue-analytics/__tests__/language-detection.test.ts b/src/setup-revenue-analytics/__tests__/language-detection.test.ts
new file mode 100644
index 0000000..c770fbd
--- /dev/null
+++ b/src/setup-revenue-analytics/__tests__/language-detection.test.ts
@@ -0,0 +1,151 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+import {
+  detectLanguageFromFiles,
+  languageFromIntegration,
+} from '../language-detection';
+import { Integration } from '../../lib/constants';
+
+describe('languageFromIntegration', () => {
+  const cases: [Integration, string | null][] = [
+    [Integration.nextjs, 'node'],
+    [Integration.nuxt, 'node'],
+    [Integration.vue, 'node'],
+    [Integration.reactRouter, 'node'],
+    [Integration.tanstackStart, 'node'],
+    [Integration.tanstackRouter, 'node'],
+    [Integration.reactNative, 'node'],
+    [Integration.angular, 'node'],
+    [Integration.astro, 'node'],
+    [Integration.sveltekit, 'node'],
+    [Integration.javascript_web, 'node'],
+    [Integration.javascriptNode, 'node'],
+    [Integration.django, 'python'],
+    [Integration.flask, 'python'],
+    [Integration.fastapi, 'python'],
+    [Integration.python, 'python'],
+    [Integration.laravel, 'php'],
+    [Integration.rails, 'ruby'],
+    [Integration.ruby, 'ruby'],
+    [Integration.swift, null],
+    [Integration.android, null],
+  ];
+
+  test.each(cases)('%s → %s', (integration, expected) => {
+    expect(languageFromIntegration(integration)).toBe(expected);
+  });
+});
+
+describe('detectLanguageFromFiles', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wizard-lang-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('detects node from package.json', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('node');
+  });
+
+  test('detects python from requirements.txt', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'requirements.txt'), 'stripe==5.0.0');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('python');
+  });
+
+  test('detects python from pyproject.toml', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'pyproject.toml'), '[project]');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('python');
+  });
+
+  test('detects ruby from Gemfile', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'Gemfile'),
+      "source 'https://rubygems.org'",
+    );
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('ruby');
+  });
+
+  test('detects php from composer.json', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'composer.json'), '{}');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('php');
+  });
+
+  test('detects go from go.mod', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'go.mod'), 'module myapp');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('go');
+  });
+
+  test('detects java from build.gradle', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'build.gradle'), 'plugins {}');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('java');
+  });
+
+  test('detects java from pom.xml', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'pom.xml'), '<project></project>');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('java');
+  });
+
+  test('detects dotnet from .csproj', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'MyApp.csproj'), '<Project></Project>');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('dotnet');
+  });
+
+  test('detects dotnet from .sln', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'MyApp.sln'),
+      'Microsoft Visual Studio Solution',
+    );
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('dotnet');
+  });
+
+  test('returns null for empty directory', async () => {
+    expect(await detectLanguageFromFiles(tmpDir)).toBeNull();
+  });
+
+  test('returns first match when multiple indicators present', async () => {
+    // node (package.json) comes before python in indicator order
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{}');
+    fs.writeFileSync(path.join(tmpDir, 'requirements.txt'), 'stripe');
+    expect(await detectLanguageFromFiles(tmpDir)).toBe('node');
+  });
+
+  describe('monorepo support', () => {
+    test('detects node from subdirectory package.json', async () => {
+      fs.mkdirSync(path.join(tmpDir, 'backend'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'backend', 'package.json'), '{}');
+      expect(await detectLanguageFromFiles(tmpDir)).toBe('node');
+    });
+
+    test('detects python from subdirectory requirements.txt', async () => {
+      fs.mkdirSync(path.join(tmpDir, 'server'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, 'server', 'requirements.txt'),
+        'django',
+      );
+      expect(await detectLanguageFromFiles(tmpDir)).toBe('python');
+    });
+
+    test('detects ruby from nested Gemfile', async () => {
+      fs.mkdirSync(path.join(tmpDir, 'api'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'api', 'Gemfile'), "gem 'rails'");
+      expect(await detectLanguageFromFiles(tmpDir)).toBe('ruby');
+    });
+
+    test('ignores node_modules subdirectories', async () => {
+      fs.mkdirSync(path.join(tmpDir, 'node_modules', 'stripe'), {
+        recursive: true,
+      });
+      fs.writeFileSync(
+        path.join(tmpDir, 'node_modules', 'stripe', 'package.json'),
+        '{}',
+      );
+      expect(await detectLanguageFromFiles(tmpDir)).toBeNull();
+    });
+  });
+});
diff --git a/src/setup-revenue-analytics/__tests__/posthog-detection.test.ts b/src/setup-revenue-analytics/__tests__/posthog-detection.test.ts
new file mode 100644
index 0000000..c983d8e
--- /dev/null
+++ b/src/setup-revenue-analytics/__tests__/posthog-detection.test.ts
@@ -0,0 +1,400 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+import { detectPostHogDistinctId } from '../posthog-detection';
+
+function createFixture(files: Record<string, string>): {
+  dir: string;
+  cleanup: () => void;
+} {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wizard-posthog-'));
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(dir, filePath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, content);
+  }
+  return {
+    dir,
+    cleanup: () => fs.rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+describe('detectPostHogDistinctId', () => {
+  describe('Node.js / JavaScript', () => {
+    test('finds distinct_id from posthog.identify() — frontend SDK', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/analytics.ts': `import posthog from 'posthog-js';
+posthog.identify(user.id, { name: user.name });`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBe('user.id');
+        expect(result.sourceFile).toBe('src/analytics.ts');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from client.capture() — backend Node SDK', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/events.ts': `client.capture({
+  distinctId: req.user.id,
+  event: 'purchase',
+});`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBe('req.user.id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from client.alias() — backend Node SDK', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/auth.ts': `client.alias({
+  distinctId: user.frontendId,
+  alias: user.backendId,
+});`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBe('user.frontendId');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from variable assignment', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/posthog.ts': `const distinctId = session.user.id;`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBe('session.user.id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from get_distinct_id() assignment', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/tracking.ts': `const userId = posthog.get_distinct_id();`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBe('userId');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('returns null when no PostHog usage found', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/app.ts': `console.log('hello');`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBeNull();
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Python', () => {
+    test('finds distinct_id from posthog.identify()', async () => {
+      const { dir, cleanup } = createFixture({
+        'analytics.py': `import posthog
+posthog.identify(request.user.pk)`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'python');
+        expect(result.distinctIdExpression).toBe('request.user.pk');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from posthog.capture() — positional arg', async () => {
+      const { dir, cleanup } = createFixture({
+        'events.py': `posthog.capture(user.id, 'purchase')`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'python');
+        expect(result.distinctIdExpression).toBe('user.id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from keyword argument', async () => {
+      const { dir, cleanup } = createFixture({
+        'track.py': `posthog.capture(distinct_id=user.email, event='sign_up')`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'python');
+        expect(result.distinctIdExpression).toBe('user.email');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from posthog.alias()', async () => {
+      const { dir, cleanup } = createFixture({
+        'alias.py': `posthog.alias(previous_id=old_id, distinct_id=user.uuid)`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'python');
+        expect(result.distinctIdExpression).toBe('user.uuid');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Ruby', () => {
+    test('finds distinct_id from capture() hash', async () => {
+      const { dir, cleanup } = createFixture({
+        'app/services/tracking.rb': `posthog.capture({
+  distinct_id: current_user.id,
+  event: 'purchase'
+})`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'ruby');
+        expect(result.distinctIdExpression).toBe('current_user.id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from identify() hash', async () => {
+      const { dir, cleanup } = createFixture({
+        'app/controllers/sessions_controller.rb': `posthog.identify({
+  distinct_id: @user.id,
+  properties: { email: @user.email }
+})`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'ruby');
+        expect(result.distinctIdExpression).toBe('@user.id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from alias() hash', async () => {
+      const { dir, cleanup } = createFixture({
+        'app/services/alias.rb': `posthog.alias({
+  distinct_id: user.frontend_id,
+  alias: user.backend_id,
+})`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'ruby');
+        expect(result.distinctIdExpression).toBe('user.frontend_id');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('PHP', () => {
+    test('finds distinct_id from PostHog::capture()', async () => {
+      const { dir, cleanup } = createFixture({
+        'app/Http/Controllers/EventController.php': `PostHog::capture([
+  'distinctId' => $user->id,
+  'event' => 'purchase',
+]);`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'php');
+        expect(result.distinctIdExpression).toBe('$user->id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from PostHog::identify()', async () => {
+      const { dir, cleanup } = createFixture({
+        'app/Listeners/LoginListener.php': `PostHog::identify([
+  'distinctId' => Auth::id(),
+]);`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'php');
+        expect(result.distinctIdExpression).toBe('Auth::id()');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Go', () => {
+    test('finds DistinctId from posthog.Capture struct', async () => {
+      const { dir, cleanup } = createFixture({
+        'analytics/track.go': `client.Enqueue(posthog.Capture{
+  DistinctId: user.ID,
+  Event: "purchase",
+})`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'go');
+        expect(result.distinctIdExpression).toBe('user.ID');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds DistinctId from posthog.Identify struct', async () => {
+      const { dir, cleanup } = createFixture({
+        'analytics/identify.go': `client.Enqueue(posthog.Identify{
+  DistinctId: req.UserID,
+})`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'go');
+        expect(result.distinctIdExpression).toBe('req.UserID');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds DistinctId from posthog.Alias struct', async () => {
+      const { dir, cleanup } = createFixture({
+        'analytics/alias.go': `client.Enqueue(posthog.Alias{
+  DistinctId: user.FrontendID,
+  Alias: user.BackendID,
+})`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'go');
+        expect(result.distinctIdExpression).toBe('user.FrontendID');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Java / Kotlin', () => {
+    test('finds distinct_id from posthog.capture() — Java', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/main/java/Analytics.java': `posthog.capture(user.getId(), "purchase");`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'java');
+        expect(result.distinctIdExpression).toBe('user.getId()');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from posthog.identify() — Java', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/main/java/Auth.java': `posthog.identify(session.getUserId());`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'java');
+        expect(result.distinctIdExpression).toBe('session.getUserId()');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinctId from PostHog.identify() — Kotlin/Android SDK', async () => {
+      const { dir, cleanup } = createFixture({
+        'app/src/main/kotlin/Analytics.kt': `PostHog.identify(distinctId = currentUser.uid)`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'java');
+        expect(result.distinctIdExpression).toBe('currentUser.uid');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('.NET', () => {
+    test('finds DistinctId from property assignment', async () => {
+      const { dir, cleanup } = createFixture({
+        'Services/Analytics.cs': `var options = new CaptureOptions
+{
+    DistinctId = user.Id,
+    Event = "purchase",
+};`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'dotnet');
+        expect(result.distinctIdExpression).toBe('user.Id');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds distinct_id from Capture() call', async () => {
+      const { dir, cleanup } = createFixture({
+        'Services/Tracking.cs': `await posthog.CaptureAsync(userId, "purchase");`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'dotnet');
+        expect(result.distinctIdExpression).toBe('userId');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('filtering', () => {
+    test('ignores string literal distinct_ids', async () => {
+      const { dir, cleanup } = createFixture({
+        'test.ts': `posthog.identify("hardcoded-id");`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBeNull();
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('ignores placeholder values from docs examples', async () => {
+      const { dir, cleanup } = createFixture({
+        'example.ts': `posthog.identify(distinct_id, { email: 'test@test.com' });`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        // "distinct_id" is a placeholder, should be skipped
+        expect(result.distinctIdExpression).toBeNull();
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('ignores test files', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/__tests__/analytics.test.ts': `posthog.identify(testUser.id);`,
+        'src/analytics.spec.ts': `posthog.identify(mockUser.id);`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBeNull();
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('prefers identify() over capture() when both present', async () => {
+      const { dir, cleanup } = createFixture({
+        'src/posthog.ts': `posthog.identify(auth.user.id, { name: user.name });
+posthog.capture('page_view', { url: window.location.href });`,
+      });
+      try {
+        const result = await detectPostHogDistinctId(dir, 'node');
+        expect(result.distinctIdExpression).toBe('auth.user.id');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+});
diff --git a/src/setup-revenue-analytics/__tests__/prompt-builder.test.ts b/src/setup-revenue-analytics/__tests__/prompt-builder.test.ts
new file mode 100644
index 0000000..8fe5183
--- /dev/null
+++ b/src/setup-revenue-analytics/__tests__/prompt-builder.test.ts
@@ -0,0 +1,177 @@
+import { buildRevenueAnalyticsPrompt } from '../prompt-builder';
+import type { StripeDetectionResult, PostHogDistinctIdResult } from '../types';
+import { STRIPE_DOCS_FALLBACK } from '../stripe-docs-fallback';
+
+function makeContext(overrides?: {
+  language?: StripeDetectionResult['language'];
+  customerCalls?: StripeDetectionResult['customerCreationCalls'];
+  chargeCalls?: StripeDetectionResult['chargeCalls'];
+  distinctId?: string | null;
+  usesCheckout?: boolean;
+}) {
+  const language = overrides?.language ?? 'node';
+  return {
+    language,
+    stripeDetection: {
+      sdkPackage: 'package.json',
+      sdkVersion: '14.21.0',
+      language,
+      customerCreationCalls: overrides?.customerCalls ?? [
+        {
+          file: 'src/billing.ts',
+          line: 10,
+          snippet: 'stripe.customers.create({',
+        },
+      ],
+      chargeCalls: overrides?.chargeCalls ?? [
+        {
+          file: 'src/payments.ts',
+          line: 20,
+          snippet: 'stripe.paymentIntents.create({',
+          type: 'payment_intent' as const,
+        },
+      ],
+      usesCheckoutSessions: overrides?.usesCheckout ?? false,
+    } satisfies StripeDetectionResult,
+    posthogDetection: {
+      distinctIdExpression:
+        overrides && 'distinctId' in overrides
+          ? overrides.distinctId ?? null
+          : 'user.id',
+      sourceFile: overrides?.distinctId === null ? null : 'src/analytics.ts',
+      sourceLine:
+        overrides?.distinctId === null ? null : 'posthog.identify(user.id)',
+    } satisfies PostHogDistinctIdResult,
+    stripeDocs: STRIPE_DOCS_FALLBACK[language],
+  };
+}
+
+describe('buildRevenueAnalyticsPrompt', () => {
+  test('includes language and Stripe SDK info', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('node');
+    expect(prompt).toContain('v14.21.0');
+  });
+
+  test('includes detected distinct_id expression and source line', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('`user.id`');
+    expect(prompt).toContain('src/analytics.ts');
+    expect(prompt).toContain('posthog.identify(user.id)');
+  });
+
+  test('instructs agent to search codebase when distinct_id not detected', () => {
+    const prompt = buildRevenueAnalyticsPrompt(
+      makeContext({ distinctId: null }),
+    );
+    expect(prompt).toContain('Not automatically detected');
+    expect(prompt).toContain('Search the codebase');
+  });
+
+  test('explains how to find distinct_id from posthog.identify', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('posthog.identify(');
+    expect(prompt).toContain('FIRST ARGUMENT is the distinct_id');
+  });
+
+  test('uses <POSTHOG_DISTINCT_ID> placeholder in code examples', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('<POSTHOG_DISTINCT_ID>');
+    expect(prompt).toContain('Replace `<POSTHOG_DISTINCT_ID>` with the actual');
+  });
+
+  describe('guiding tenets', () => {
+    test('includes never-fabricate tenet', () => {
+      const prompt = buildRevenueAnalyticsPrompt(makeContext());
+      expect(prompt).toContain('Never fabricate the value');
+      expect(prompt).toContain('A wrong value is worse than no value');
+    });
+
+    test('includes thread-the-value tenet', () => {
+      const prompt = buildRevenueAnalyticsPrompt(makeContext());
+      expect(prompt).toContain("Thread the value, don't invent it");
+      expect(prompt).toContain('optional parameter');
+    });
+
+    test('includes minimize-api-calls tenet', () => {
+      const prompt = buildRevenueAnalyticsPrompt(makeContext());
+      expect(prompt).toContain('Minimize extra API calls');
+      expect(prompt).toContain('network round-trip');
+    });
+
+    test('includes follow-abstractions tenet', () => {
+      const prompt = buildRevenueAnalyticsPrompt(makeContext());
+      expect(prompt).toContain('Follow existing Stripe abstraction patterns');
+      expect(prompt).toContain('utility/service layer');
+    });
+
+    test('warns against fabricating user.posthogDistinctId', () => {
+      const prompt = buildRevenueAnalyticsPrompt(makeContext());
+      expect(prompt).toContain('user.posthogDistinctId');
+      expect(prompt).toContain('does not exist');
+    });
+  });
+
+  test('includes customer creation locations', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('src/billing.ts:10');
+  });
+
+  test('includes charge call locations with types', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('src/payments.ts:20 [payment_intent]');
+  });
+
+  test('handles no customer creation calls found', () => {
+    const prompt = buildRevenueAnalyticsPrompt(
+      makeContext({ customerCalls: [] }),
+    );
+    expect(prompt).toContain('none found');
+    expect(prompt).toContain('search the codebase yourself');
+  });
+
+  test('includes checkout session note when detected', () => {
+    const prompt = buildRevenueAnalyticsPrompt(
+      makeContext({
+        usesCheckout: true,
+        chargeCalls: [
+          {
+            file: 'src/checkout.ts',
+            line: 5,
+            snippet: 'stripe.checkout.sessions.create({',
+            type: 'checkout_session',
+          },
+        ],
+      }),
+    );
+    expect(prompt).toContain('Stripe Checkout detected');
+    expect(prompt).toContain('checkout.session.completed webhook');
+  });
+
+  test('does not include checkout note when not using checkout', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).not.toContain('Stripe Checkout detected');
+  });
+
+  test('includes Stripe docs code examples', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('stripe.customers.create');
+    expect(prompt).toContain('stripe.customers.update');
+    expect(prompt).toContain('posthog_person_distinct_id');
+  });
+
+  test('includes constraints section', () => {
+    const prompt = buildRevenueAnalyticsPrompt(makeContext());
+    expect(prompt).toContain('Do NOT modify charge/payment logic');
+    expect(prompt).toContain('Do NOT remove any existing code');
+  });
+
+  test.each(['python', 'ruby', 'php', 'go', 'java', 'dotnet'] as const)(
+    'generates prompt for %s',
+    (language) => {
+      const prompt = buildRevenueAnalyticsPrompt(makeContext({ language }));
+      expect(prompt).toContain(language);
+      expect(prompt).toContain('posthog_person_distinct_id');
+    },
+  );
+});
diff --git a/src/setup-revenue-analytics/__tests__/stripe-detection.test.ts b/src/setup-revenue-analytics/__tests__/stripe-detection.test.ts
new file mode 100644
index 0000000..bb8e183
--- /dev/null
+++ b/src/setup-revenue-analytics/__tests__/stripe-detection.test.ts
@@ -0,0 +1,383 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+import { detectStripe } from '../stripe-detection';
+
+function createFixture(files: Record<string, string>): {
+  dir: string;
+  cleanup: () => void;
+} {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wizard-stripe-'));
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(dir, filePath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, content);
+  }
+  return {
+    dir,
+    cleanup: () => fs.rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+describe('detectStripe', () => {
+  describe('Node.js', () => {
+    test('detects Stripe from package.json', () => {
+      const { dir, cleanup } = createFixture({
+        'package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('package.json');
+        expect(result!.language).toBe('node');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('extracts version from package-lock.json', () => {
+      const { dir, cleanup } = createFixture({
+        'package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+        'package-lock.json': JSON.stringify({
+          packages: { 'node_modules/stripe': { version: '14.21.0' } },
+        }),
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.sdkVersion).toBe('14.21.0');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds customer creation calls', () => {
+      const { dir, cleanup } = createFixture({
+        'package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+        'src/billing.ts': `import Stripe from 'stripe';
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
+
+const customer = await stripe.customers.create({
+  email: user.email,
+});`,
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.customerCreationCalls).toHaveLength(1);
+        expect(result!.customerCreationCalls[0].file).toBe('src/billing.ts');
+        expect(result!.customerCreationCalls[0].line).toBe(4);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds charge patterns', () => {
+      const { dir, cleanup } = createFixture({
+        'package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+        'src/payments.ts': `const intent = await stripe.paymentIntents.create({
+  amount: 1000,
+  currency: 'usd',
+});
+
+const sub = await stripe.subscriptions.create({
+  customer: customerId,
+});
+
+const session = await stripe.checkout.sessions.create({
+  mode: 'payment',
+});`,
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.chargeCalls).toHaveLength(3);
+        expect(result!.chargeCalls.map((c) => c.type)).toEqual([
+          'payment_intent',
+          'subscription',
+          'checkout_session',
+        ]);
+        expect(result!.usesCheckoutSessions).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('returns null when Stripe is not installed', () => {
+      const { dir, cleanup } = createFixture({
+        'package.json': JSON.stringify({
+          dependencies: { express: '^4.0.0' },
+        }),
+      });
+      try {
+        expect(detectStripe(dir, 'node')).toBeNull();
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Python', () => {
+    test('detects Stripe from requirements.txt', () => {
+      const { dir, cleanup } = createFixture({
+        'requirements.txt': 'stripe>=5.0.0\nflask',
+      });
+      try {
+        const result = detectStripe(dir, 'python');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('requirements.txt');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('detects Stripe from uv.lock', () => {
+      const { dir, cleanup } = createFixture({
+        'uv.lock': `[[package]]
+name = "stripe"
+version = "11.4.1"
+source = { registry = "https://pypi.org/simple" }`,
+      });
+      try {
+        const result = detectStripe(dir, 'python');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('uv.lock');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('detects Stripe from poetry.lock', () => {
+      const { dir, cleanup } = createFixture({
+        'poetry.lock': `[[package]]
+name = "stripe"
+version = "11.4.1"`,
+      });
+      try {
+        const result = detectStripe(dir, 'python');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('poetry.lock');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds Python customer creation', () => {
+      const { dir, cleanup } = createFixture({
+        'requirements.txt': 'stripe>=5.0.0',
+        'billing.py': `import stripe
+
+customer = stripe.Customer.create(
+    email=user.email,
+)`,
+      });
+      try {
+        const result = detectStripe(dir, 'python');
+        expect(result).not.toBeNull();
+        expect(result!.customerCreationCalls).toHaveLength(1);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds Python charge patterns', () => {
+      const { dir, cleanup } = createFixture({
+        'requirements.txt': 'stripe>=5.0.0',
+        'payments.py': `import stripe
+
+intent = stripe.PaymentIntent.create(
+    amount=1000,
+    currency="usd",
+)
+
+sub = stripe.Subscription.create(
+    customer=customer_id,
+)`,
+      });
+      try {
+        const result = detectStripe(dir, 'python');
+        expect(result).not.toBeNull();
+        expect(result!.chargeCalls).toHaveLength(2);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Ruby', () => {
+    test('detects Stripe from Gemfile', () => {
+      const { dir, cleanup } = createFixture({
+        Gemfile: "gem 'stripe'",
+      });
+      try {
+        const result = detectStripe(dir, 'ruby');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('Gemfile');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds Ruby customer creation', () => {
+      const { dir, cleanup } = createFixture({
+        Gemfile: "gem 'stripe'",
+        'app/services/billing.rb': `Stripe::Customer.create({
+  email: user.email,
+})`,
+      });
+      try {
+        const result = detectStripe(dir, 'ruby');
+        expect(result!.customerCreationCalls).toHaveLength(1);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('PHP', () => {
+    test('detects Stripe from composer.json', () => {
+      const { dir, cleanup } = createFixture({
+        'composer.json': JSON.stringify({
+          require: { 'stripe/stripe-php': '^12.0' },
+        }),
+      });
+      try {
+        const result = detectStripe(dir, 'php');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('composer.json');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Go', () => {
+    test('detects Stripe from go.mod', () => {
+      const { dir, cleanup } = createFixture({
+        'go.mod': `module myapp
+
+require github.com/stripe/stripe-go/v76 v76.0.0`,
+      });
+      try {
+        const result = detectStripe(dir, 'go');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('go.mod');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('Java', () => {
+    test('detects Stripe from build.gradle', () => {
+      const { dir, cleanup } = createFixture({
+        'build.gradle': `dependencies {
+    implementation 'com.stripe:stripe-java:24.0.0'
+}`,
+      });
+      try {
+        const result = detectStripe(dir, 'java');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('build.gradle');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('.NET', () => {
+    test('detects Stripe from .csproj', () => {
+      const { dir, cleanup } = createFixture({
+        'MyApp.csproj': `<Project>
+  <ItemGroup>
+    <PackageReference Include="Stripe.net" Version="43.0.0" />
+  </ItemGroup>
+</Project>`,
+      });
+      try {
+        const result = detectStripe(dir, 'dotnet');
+        expect(result).not.toBeNull();
+        expect(result!.sdkVersion).toBe('43.0.0');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
+  describe('monorepo support', () => {
+    test('detects Stripe from subdirectory package.json', () => {
+      const { dir, cleanup } = createFixture({
+        'backend/package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('backend/package.json');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('extracts version from subdirectory lockfile', () => {
+      const { dir, cleanup } = createFixture({
+        'backend/package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+        'backend/package-lock.json': JSON.stringify({
+          packages: { 'node_modules/stripe': { version: '14.21.0' } },
+        }),
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.sdkVersion).toBe('14.21.0');
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('finds customer creation calls in subdirectory', () => {
+      const { dir, cleanup } = createFixture({
+        'backend/package.json': JSON.stringify({
+          dependencies: { stripe: '^14.0.0' },
+        }),
+        'backend/src/billing.ts': `const customer = await stripe.customers.create({
+  email: user.email,
+});`,
+      });
+      try {
+        const result = detectStripe(dir, 'node');
+        expect(result).not.toBeNull();
+        expect(result!.customerCreationCalls).toHaveLength(1);
+        expect(result!.customerCreationCalls[0].file).toBe(
+          'backend/src/billing.ts',
+        );
+      } finally {
+        cleanup();
+      }
+    });
+
+    test('detects Python Stripe in subdirectory', () => {
+      const { dir, cleanup } = createFixture({
+        'server/requirements.txt': 'stripe>=5.0.0\nflask',
+      });
+      try {
+        const result = detectStripe(dir, 'python');
+        expect(result).not.toBeNull();
+        expect(result!.sdkPackage).toBe('server/requirements.txt');
+      } finally {
+        cleanup();
+      }
+    });
+  });
+});
diff --git a/src/setup-revenue-analytics/__tests__/stripe-docs-fetcher.test.ts b/src/setup-revenue-analytics/__tests__/stripe-docs-fetcher.test.ts
new file mode 100644
index 0000000..251c252
--- /dev/null
+++ b/src/setup-revenue-analytics/__tests__/stripe-docs-fetcher.test.ts
@@ -0,0 +1,81 @@
+/**
+ * We only test decodeHtmlEntities here — the fetch logic is tested
+ * via integration tests against the live Stripe docs site.
+ */
+
+// decodeHtmlEntities is not exported, so we reach it through the module internals.
+// Re-implement as a standalone to test the logic in isolation.
+// This mirrors the implementation in stripe-docs-fetcher.ts exactly.
+function decodeHtmlEntities(text: string): string {
+  let stripped = text;
+  let prev: string;
+  do {
+    prev = stripped;
+    stripped = stripped.replace(/<[^>]+>/g, '');
+  } while (stripped !== prev);
+
+  return stripped
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+describe('decodeHtmlEntities', () => {
+  test('decodes basic HTML entities', () => {
+    expect(decodeHtmlEntities('a &amp; b')).toBe('a & b');
+    expect(decodeHtmlEntities('a &lt; b')).toBe('a < b');
+    expect(decodeHtmlEntities('a &gt; b')).toBe('a > b');
+    expect(decodeHtmlEntities('&quot;hello&quot;')).toBe('"hello"');
+  });
+
+  test('decodes apostrophe entities', () => {
+    expect(decodeHtmlEntities('it&#39;s')).toBe("it's");
+    expect(decodeHtmlEntities('it&#x27;s')).toBe("it's");
+  });
+
+  test('strips HTML tags', () => {
+    expect(decodeHtmlEntities('<span>hello</span>')).toBe('hello');
+    expect(decodeHtmlEntities('<a href="url">link</a>')).toBe('link');
+    expect(decodeHtmlEntities('before<br/>after')).toBe('beforeafter');
+  });
+
+  test('strips nested/reconstructed tags via loop', () => {
+    // <scr<script>ipt> is matched as one tag, leaving harmless "ipt>" text.
+    // The key point: no executable <script> tag survives.
+    const result = decodeHtmlEntities('<scr<script>ipt>alert(1)</script>');
+    expect(result).not.toContain('<script');
+    expect(result).toContain('alert(1)');
+  });
+
+  test('strips tags before decoding entities to prevent injection', () => {
+    // &lt;script&gt; should decode to <script> as plain text,
+    // NOT be treated as an HTML tag and stripped
+    expect(decodeHtmlEntities('&lt;script&gt;alert(1)&lt;/script&gt;')).toBe(
+      '<script>alert(1)</script>',
+    );
+  });
+
+  test('handles double-encoded entities', () => {
+    // &amp;lt; → strip tags (none present) → decode &lt; → < (NO)
+    // We intentionally decode &amp; last, so &amp;lt;script&amp;gt; becomes
+    // &lt;script&gt; rather than <script>. This avoids double-unescaping
+    // and matches safer, standards-compliant behavior.
+    expect(decodeHtmlEntities('&amp;lt;script&amp;gt;')).toBe('&lt;script&gt;');
+  });
+
+  test('handles mixed content', () => {
+    expect(
+      decodeHtmlEntities(
+        '<code>stripe.customers.create({ &quot;email&quot;: user.email })</code>',
+      ),
+    ).toBe('stripe.customers.create({ "email": user.email })');
+  });
+
+  test('preserves plain text', () => {
+    expect(decodeHtmlEntities('hello world')).toBe('hello world');
+    expect(decodeHtmlEntities('const x = 42;')).toBe('const x = 42;');
+  });
+});
diff --git a/src/setup-revenue-analytics/__tests__/stripe-docs.test.ts b/src/setup-revenue-analytics/__tests__/stripe-docs.test.ts
new file mode 100644
index 0000000..cd67f4e
--- /dev/null
+++ b/src/setup-revenue-analytics/__tests__/stripe-docs.test.ts
@@ -0,0 +1,59 @@
+import { getStripeDocs, clearStripeDocsCache } from '../stripe-docs';
+import { STRIPE_DOCS_FALLBACK } from '../stripe-docs-fallback';
+import type { Language } from '../types';
+
+// Mock the fetcher to avoid real HTTP calls in tests
+jest.mock('../stripe-docs-fetcher', () => ({
+  fetchStripeDocs: jest.fn().mockResolvedValue(null),
+}));
+
+describe('getStripeDocs', () => {
+  beforeEach(() => {
+    clearStripeDocsCache();
+  });
+
+  test('returns fallback docs when fetcher returns null', async () => {
+    const docs = await getStripeDocs('node');
+    expect(docs).toEqual(STRIPE_DOCS_FALLBACK.node);
+  });
+
+  test('caches results across calls', async () => {
+    const docs1 = await getStripeDocs('python');
+    const docs2 = await getStripeDocs('python');
+    expect(docs1).toBe(docs2); // Same reference
+  });
+
+  test.each(['node', 'python', 'ruby', 'php', 'go', 'java', 'dotnet'] as const)(
+    'returns docs for %s',
+    async (language: Language) => {
+      const docs = await getStripeDocs(language);
+      expect(docs.customerCreate).toBeDefined();
+      expect(docs.customerCreate.pattern).toBeTruthy();
+      expect(docs.customerCreate.metadataExample).toContain(
+        'posthog_person_distinct_id',
+      );
+      expect(docs.customerUpdate).toBeDefined();
+      expect(docs.customerUpdate.pattern).toBeTruthy();
+      expect(docs.customerUpdate.metadataExample).toContain(
+        'posthog_person_distinct_id',
+      );
+    },
+  );
+});
+
+describe('STRIPE_DOCS_FALLBACK', () => {
+  test.each(['node', 'python', 'ruby', 'php', 'go', 'java', 'dotnet'] as const)(
+    '%s has complete customer create and update examples',
+    (language: Language) => {
+      const docs = STRIPE_DOCS_FALLBACK[language];
+      expect(docs.customerCreate.fullExample).toBeTruthy();
+      expect(docs.customerCreate.fullExample).toContain(
+        'posthog_person_distinct_id',
+      );
+      expect(docs.customerUpdate.fullExample).toBeTruthy();
+      expect(docs.customerUpdate.fullExample).toContain(
+        'posthog_person_distinct_id',
+      );
+    },
+  );
+});
diff --git a/src/setup-revenue-analytics/index.ts b/src/setup-revenue-analytics/index.ts
new file mode 100644
index 0000000..caf91c3
--- /dev/null
+++ b/src/setup-revenue-analytics/index.ts
@@ -0,0 +1,298 @@
+/**
+ * Entry point for the setup-revenue-analytics command.
+ *
+ * Orchestrates: language detection → Stripe detection → PostHog distinct_id
+ * detection → Stripe docs fetching → prompt building → agent execution.
+ */
+
+import type { WizardSession } from '../lib/wizard-session';
+import { getUI } from '../ui';
+import { detectLanguage } from './language-detection';
+import { detectStripe } from './stripe-detection';
+import { detectPostHogDistinctId } from './posthog-detection';
+import { getStripeDocs } from './stripe-docs';
+import { buildRevenueAnalyticsPrompt } from './prompt-builder';
+import {
+  initializeAgent,
+  runAgent,
+  AgentSignals,
+  AgentErrorType,
+  buildWizardMetadata,
+  checkAllSettingsConflicts,
+  backupAndFixClaudeSettings,
+  restoreClaudeSettings,
+} from '../lib/agent-interface';
+import { getOrAskForProjectData } from '../utils/setup-utils';
+import {
+  evaluateWizardReadiness,
+  WizardReadiness,
+} from '../lib/health-checks/readiness';
+import { analytics } from '../utils/analytics';
+import { initLogFile, logToFile, enableDebugLogs } from '../utils/debug';
+import {
+  wizardAbort,
+  WizardError,
+  registerCleanup,
+} from '../utils/wizard-abort';
+import { formatScanReport, writeScanReport } from '../lib/yara-hooks';
+
+export async function runSetupRevenueAnalytics(
+  session: WizardSession,
+): Promise<void> {
+  initLogFile();
+  logToFile('[setup-revenue-analytics] START');
+
+  if (session.debug) {
+    enableDebugLogs();
+  }
+
+  getUI().intro('PostHog Revenue Analytics Setup');
+
+  // 1. Detect language
+  getUI().log.step('Detecting project language...');
+  const language = await detectLanguage(session.installDir);
+  if (!language) {
+    return wizardAbort({
+      message:
+        'Could not detect the project language. Revenue analytics setup requires a Node.js, Python, Ruby, PHP, Go, Java, or .NET project.',
+    });
+  }
+  logToFile(`[setup-revenue-analytics] language=${language}`);
+  getUI().log.success(`Detected language: ${language}`);
+
+  // 2. Detect Stripe SDK
+  getUI().log.step('Scanning for Stripe SDK...');
+  const stripeResult = detectStripe(session.installDir, language);
+  if (!stripeResult) {
+    return wizardAbort({
+      message:
+        'No Stripe SDK detected in this project. Install the Stripe SDK for your language first, then re-run this command.',
+    });
+  }
+  logToFile(
+    `[setup-revenue-analytics] stripe=${stripeResult.sdkPackage} v=${stripeResult.sdkVersion}`,
+  );
+  getUI().log.success(
+    `Found Stripe SDK: ${stripeResult.sdkPackage}${
+      stripeResult.sdkVersion ? ` v${stripeResult.sdkVersion}` : ''
+    }`,
+  );
+
+  if (stripeResult.customerCreationCalls.length > 0) {
+    getUI().log.info(
+      `  Customer creation calls: ${stripeResult.customerCreationCalls.length} location(s)`,
+    );
+  }
+  if (stripeResult.chargeCalls.length > 0) {
+    getUI().log.info(
+      `  Charge/payment calls: ${stripeResult.chargeCalls.length} location(s)`,
+    );
+  }
+
+  // 3. Detect PostHog distinct_id
+  getUI().log.step('Looking for PostHog distinct_id usage...');
+  const posthogResult = await detectPostHogDistinctId(
+    session.installDir,
+    language,
+  );
+  if (posthogResult.distinctIdExpression) {
+    logToFile(
+      `[setup-revenue-analytics] distinct_id=${posthogResult.distinctIdExpression}`,
+    );
+    getUI().log.success(
+      `Found distinct_id expression: ${posthogResult.distinctIdExpression}`,
+    );
+  } else {
+    getUI().log.warn(
+      'Could not detect PostHog distinct_id usage. The agent will search your codebase to find it.',
+    );
+  }
+
+  // 4. Fetch Stripe docs
+  getUI().log.step('Fetching Stripe documentation...');
+  const stripeDocs = await getStripeDocs(language, stripeResult.sdkVersion);
+  getUI().log.success('Stripe docs ready');
+
+  // 5. Build prompt
+  const prompt = buildRevenueAnalyticsPrompt({
+    language,
+    stripeDetection: stripeResult,
+    posthogDetection: posthogResult,
+    stripeDocs,
+  });
+  logToFile('[setup-revenue-analytics] prompt built');
+
+  // 6. Health check
+  if (!session.readinessResult) {
+    logToFile('[setup-revenue-analytics] evaluating readiness');
+    const readiness = await evaluateWizardReadiness();
+    if (readiness.decision === WizardReadiness.No) {
+      await getUI().showBlockingOutage(readiness);
+    }
+  }
+
+  // 7. Settings conflict check
+  const settingsConflicts = checkAllSettingsConflicts(session.installDir);
+  if (settingsConflicts.length > 0) {
+    await getUI().showSettingsOverride(settingsConflicts, () =>
+      backupAndFixClaudeSettings(session.installDir),
+    );
+  }
+
+  // 8. Authenticate
+  logToFile('[setup-revenue-analytics] starting auth');
+  const { projectApiKey, host, accessToken, projectId, cloudRegion } =
+    await getOrAskForProjectData({
+      signup: session.signup,
+      ci: session.ci,
+      apiKey: session.apiKey,
+      projectId: session.projectId,
+    });
+
+  session.credentials = { accessToken, projectApiKey, host, projectId };
+  getUI().setCredentials(session.credentials);
+
+  analytics.wizardCapture('revenue_analytics started', {
+    language,
+    stripe_version: stripeResult.sdkVersion,
+    customer_creation_calls: stripeResult.customerCreationCalls.length,
+    charge_calls: stripeResult.chargeCalls.length,
+    distinct_id_found: !!posthogResult.distinctIdExpression,
+  });
+
+  // 9. Compute MCP URL and skills URL
+  const mcpUrl = session.localMcp
+    ? 'http://localhost:8787/mcp'
+    : process.env.MCP_URL ||
+      (cloudRegion === 'eu'
+        ? 'https://mcp-eu.posthog.com/mcp'
+        : 'https://mcp.posthog.com/mcp');
+
+  const skillsBaseUrl = session.localMcp
+    ? 'http://localhost:8765'
+    : 'https://github.com/PostHog/context-mill/releases/latest/download';
+
+  // 10. Initialize and run agent
+  const wizardFlags = await analytics.getAllFlagsForWizard();
+  const wizardMetadata = buildWizardMetadata(wizardFlags);
+
+  const restoreSettings = () => restoreClaudeSettings(session.installDir);
+  getUI().onEnterScreen('outro', restoreSettings);
+
+  if (session.yaraReport) {
+    registerCleanup(() => {
+      const reportPath = writeScanReport();
+      if (reportPath) {
+        const summary = formatScanReport();
+        getUI().log.info(`YARA scan report: ${reportPath}${summary ?? ''}`);
+      }
+    });
+  }
+
+  getUI().startRun();
+
+  const spinner = getUI().spinner();
+
+  const { detectPackageManager: getPackageManagerDetector } = await import(
+    './package-manager.js'
+  );
+  const detectPackageManager = getPackageManagerDetector(language);
+
+  const agent = await initializeAgent(
+    {
+      workingDirectory: session.installDir,
+      posthogMcpUrl: mcpUrl,
+      posthogApiKey: accessToken,
+      posthogApiHost: host,
+      detectPackageManager,
+      skillsBaseUrl,
+      wizardFlags,
+      wizardMetadata,
+    },
+    {
+      installDir: session.installDir,
+      debug: session.debug,
+      forceInstall: false,
+      default: false,
+      signup: session.signup,
+      localMcp: session.localMcp,
+      ci: session.ci,
+      menu: false,
+      benchmark: session.benchmark,
+      projectId: session.projectId,
+      apiKey: session.apiKey,
+      yaraReport: session.yaraReport,
+    },
+  );
+
+  const agentResult = await runAgent(
+    agent,
+    prompt,
+    {
+      installDir: session.installDir,
+      debug: session.debug,
+      forceInstall: false,
+      default: false,
+      signup: session.signup,
+      localMcp: session.localMcp,
+      ci: session.ci,
+      menu: false,
+      benchmark: session.benchmark,
+      projectId: session.projectId,
+      apiKey: session.apiKey,
+      yaraReport: session.yaraReport,
+    },
+    spinner,
+    {
+      estimatedDurationMinutes: 3,
+      spinnerMessage: 'Setting up revenue analytics...',
+      successMessage: 'Revenue analytics setup complete',
+      errorMessage: 'Revenue analytics setup failed',
+    },
+  );
+
+  // Handle errors
+  if (agentResult.error === AgentErrorType.MCP_MISSING) {
+    await wizardAbort({
+      message: `Could not access the PostHog MCP server.\n\nPlease try again, or follow the manual setup guide:\nhttps://posthog.com/docs/revenue-analytics/connect-to-customers`,
+      error: new WizardError('Agent could not access PostHog MCP server', {
+        error_type: AgentErrorType.MCP_MISSING,
+        signal: AgentSignals.ERROR_MCP_MISSING,
+      }),
+    });
+  }
+
+  if (agentResult.error === AgentErrorType.YARA_VIOLATION) {
+    await wizardAbort({
+      message:
+        'Security violation detected.\n\nPlease report this to: wizard@posthog.com',
+      error: new WizardError('YARA scanner terminated session', {
+        error_type: AgentErrorType.YARA_VIOLATION,
+      }),
+    });
+  }
+
+  if (
+    agentResult.error === AgentErrorType.RATE_LIMIT ||
+    agentResult.error === AgentErrorType.API_ERROR
+  ) {
+    await wizardAbort({
+      message: `API Error\n\n${
+        agentResult.message || 'Unknown error'
+      }\n\nPlease report this to: wizard@posthog.com`,
+      error: new WizardError(`API error: ${agentResult.message}`, {
+        error_type: agentResult.error,
+      }),
+    });
+  }
+
+  analytics.wizardCapture('revenue_analytics completed', {
+    language,
+  });
+
+  getUI().outro(
+    'Revenue analytics setup complete! Visit your PostHog dashboard to see revenue data.',
+  );
+
+  await analytics.shutdown('success');
+}
diff --git a/src/setup-revenue-analytics/language-detection.ts b/src/setup-revenue-analytics/language-detection.ts
new file mode 100644
index 0000000..2ef93d2
--- /dev/null
+++ b/src/setup-revenue-analytics/language-detection.ts
@@ -0,0 +1,114 @@
+/**
+ * Language detection for setup-revenue-analytics.
+ *
+ * Reuses the existing framework detection from the wizard, mapping
+ * detected integrations to base languages. Falls back to scanning
+ * for language indicator files when framework detection fails.
+ */
+
+import { Integration } from '../lib/constants';
+import type { Language } from './types';
+import fg from 'fast-glob';
+
+const INTEGRATION_TO_LANGUAGE: Record<Integration, Language | null> = {
+  [Integration.nextjs]: 'node',
+  [Integration.nuxt]: 'node',
+  [Integration.vue]: 'node',
+  [Integration.reactRouter]: 'node',
+  [Integration.tanstackStart]: 'node',
+  [Integration.tanstackRouter]: 'node',
+  [Integration.reactNative]: 'node',
+  [Integration.angular]: 'node',
+  [Integration.astro]: 'node',
+  [Integration.sveltekit]: 'node',
+  [Integration.javascript_web]: 'node',
+  [Integration.javascriptNode]: 'node',
+  [Integration.django]: 'python',
+  [Integration.flask]: 'python',
+  [Integration.fastapi]: 'python',
+  [Integration.python]: 'python',
+  [Integration.laravel]: 'php',
+  [Integration.rails]: 'ruby',
+  [Integration.ruby]: 'ruby',
+  [Integration.swift]: null,
+  [Integration.android]: null,
+};
+
+interface LanguageIndicator {
+  language: Language;
+  patterns: string[];
+}
+
+const LANGUAGE_INDICATORS: LanguageIndicator[] = [
+  { language: 'node', patterns: ['**/package.json'] },
+  {
+    language: 'python',
+    patterns: [
+      '**/requirements.txt',
+      '**/pyproject.toml',
+      '**/Pipfile',
+      '**/setup.py',
+    ],
+  },
+  { language: 'ruby', patterns: ['**/Gemfile'] },
+  { language: 'php', patterns: ['**/composer.json'] },
+  { language: 'go', patterns: ['**/go.mod'] },
+  {
+    language: 'java',
+    patterns: ['**/build.gradle', '**/build.gradle.kts', '**/pom.xml'],
+  },
+  { language: 'dotnet', patterns: ['**/*.csproj', '**/*.sln'] },
+];
+
+const IGNORE_DIRS = [
+  '**/node_modules/**',
+  '**/venv/**',
+  '**/.venv/**',
+  '**/env/**',
+  '**/.env/**',
+  '**/vendor/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.git/**',
+];
+
+export function languageFromIntegration(
+  integration: Integration,
+): Language | null {
+  return INTEGRATION_TO_LANGUAGE[integration] ?? null;
+}
+
+export async function detectLanguageFromFiles(
+  installDir: string,
+): Promise<Language | null> {
+  for (const { language, patterns } of LANGUAGE_INDICATORS) {
+    const matches = await fg(patterns, {
+      cwd: installDir,
+      deep: 3,
+      onlyFiles: true,
+      ignore: IGNORE_DIRS,
+    });
+    if (matches.length > 0) {
+      return language;
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect the codebase language. Tries framework detection first,
+ * then falls back to file-based detection.
+ */
+export async function detectLanguage(
+  installDir: string,
+): Promise<Language | null> {
+  const { detectIntegration } = await import('../run.js');
+  const integration = await detectIntegration(installDir);
+
+  if (integration) {
+    const language = languageFromIntegration(integration);
+    if (language) return language;
+  }
+
+  return detectLanguageFromFiles(installDir);
+}
diff --git a/src/setup-revenue-analytics/package-manager.ts b/src/setup-revenue-analytics/package-manager.ts
new file mode 100644
index 0000000..bcfa7f1
--- /dev/null
+++ b/src/setup-revenue-analytics/package-manager.ts
@@ -0,0 +1,49 @@
+/**
+ * Map language to the appropriate package manager detector.
+ */
+
+import type { PackageManagerDetector } from '../lib/package-manager-detection';
+import {
+  detectNodePackageManagers,
+  detectPythonPackageManagers,
+  composerPackageManager,
+  bundlerPackageManager,
+  gradlePackageManager,
+} from '../lib/package-manager-detection';
+import type { Language } from './types';
+
+const DETECTORS: Record<Language, PackageManagerDetector> = {
+  node: detectNodePackageManagers,
+  python: detectPythonPackageManagers,
+  php: () => composerPackageManager(),
+  ruby: () => bundlerPackageManager(),
+  java: () => gradlePackageManager(),
+  go: () =>
+    Promise.resolve({
+      detected: [{ name: 'go', label: 'Go Modules', installCommand: 'go get' }],
+      primary: { name: 'go', label: 'Go Modules', installCommand: 'go get' },
+      recommendation: 'Use Go Modules (go get).',
+    }),
+  dotnet: () =>
+    Promise.resolve({
+      detected: [
+        {
+          name: 'nuget',
+          label: 'NuGet',
+          installCommand: 'dotnet add package',
+        },
+      ],
+      primary: {
+        name: 'nuget',
+        label: 'NuGet',
+        installCommand: 'dotnet add package',
+      },
+      recommendation: 'Use NuGet (dotnet add package).',
+    }),
+};
+
+export function detectPackageManager(
+  language: Language,
+): PackageManagerDetector {
+  return DETECTORS[language];
+}
diff --git a/src/setup-revenue-analytics/posthog-detection.ts b/src/setup-revenue-analytics/posthog-detection.ts
new file mode 100644
index 0000000..e74110e
--- /dev/null
+++ b/src/setup-revenue-analytics/posthog-detection.ts
@@ -0,0 +1,240 @@
+/**
+ * PostHog distinct_id detection — scans for how the project references distinct_id.
+ *
+ * Patterns sourced from the PostHog docs "Identifying users" page.
+ * Each language has SDK-specific patterns for identify(), capture(), alias(),
+ * and get_distinct_id() calls. Patterns are ordered by specificity so that
+ * the most informative match (e.g. an identify() call) wins over a generic
+ * property access.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import type { Language, PostHogDistinctIdResult } from './types';
+
+const FILE_EXTENSIONS: Record<Language, string> = {
+  node: '**/*.{ts,js,tsx,jsx,mjs,cjs}',
+  python: '**/*.py',
+  ruby: '**/*.rb',
+  php: '**/*.php',
+  go: '**/*.go',
+  java: '**/*.{java,kt,kts}',
+  dotnet: '**/*.{cs,fs}',
+};
+
+const IGNORE_DIRS = [
+  '**/node_modules/**',
+  '**/venv/**',
+  '**/.venv/**',
+  '**/env/**',
+  '**/.env/**',
+  '**/vendor/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.git/**',
+  '**/bin/**',
+  '**/obj/**',
+  '**/__tests__/**',
+  '**/*.test.*',
+  '**/*.spec.*',
+];
+
+/**
+ * Patterns ordered by specificity — identify() calls first (most reliable
+ * indicator of what the app uses as distinct_id), then capture() calls
+ * (backend SDKs require distinct_id), then alias/assignment patterns.
+ *
+ * The last capturing group in each regex is the distinct_id expression.
+ */
+const IDENTIFY_PATTERNS: Record<Language, RegExp[]> = {
+  node: [
+    // posthog.identify(user.id, ...) — frontend JS/TS SDK
+    /posthog\.identify\(\s*(['"`]?)([\w.[\]]+)\1/,
+
+    // client.capture({ distinctId: user.id, ... }) — backend Node SDK
+    /\.capture\(\s*\{[^}]*distinctId:\s*([^\s,}]+)/,
+
+    // client.alias({ distinctId: user.id, ... }) — backend Node SDK
+    /\.alias\(\s*\{[^}]*distinctId:\s*([^\s,}]+)/,
+
+    // const distinctId = session.user.id — variable assignment
+    /(?:const|let|var)\s+distinctId\s*=\s*([^\s,;]+)/,
+
+    // distinctId: user.id — object property (e.g. in capture/alias call)
+    /distinctId:\s*([^\s,}]+)/,
+
+    // result = posthog.get_distinct_id() — reveals variable holding the id
+    /(\w[\w.]*)\s*=\s*posthog\.get_distinct_id\(\)/,
+  ],
+
+  python: [
+    // posthog.identify(request.user.pk) — first positional arg
+    /posthog\.identify\(\s*([^\s,)]+)/,
+
+    // posthog.capture(distinct_id=user.id, ...) — keyword arg (check before positional)
+    /distinct_id\s*=\s*([^\s,)]+)/,
+
+    // posthog.capture(user.id, 'event') — first positional arg
+    /posthog\.capture\(\s*([^\s,)]+)/,
+
+    // posthog.alias(previous_id=..., distinct_id=...) — alias call
+    /posthog\.alias\([^)]*distinct_id\s*=\s*([^\s,)]+)/,
+  ],
+
+  ruby: [
+    // posthog.identify({ distinct_id: current_user.id, ... })
+    /\.identify\(\s*\{[^}]*distinct_id:\s*([^\s,}]+)/,
+
+    // posthog.capture({ distinct_id: current_user.id, ... })
+    /\.capture\(\s*\{[^}]*distinct_id:\s*([^\s,}]+)/,
+
+    // posthog.alias({ distinct_id: value, ... })
+    /\.alias\(\s*\{[^}]*distinct_id:\s*([^\s,}]+)/,
+
+    // distinct_id: current_user.id — hash key in any context
+    /distinct_id:\s*([^\s,}]+)/,
+  ],
+
+  php: [
+    // PostHog::identify(['distinctId' => $user->id, ...])
+    /PostHog::identify\(\s*\[[^\]]*['"]distinctId['"]\s*=>\s*([^\s,\]]+)/,
+
+    // PostHog::capture(['distinctId' => $user->id, ...])
+    /PostHog::capture\(\s*\[[^\]]*['"]distinctId['"]\s*=>\s*([^\s,\]]+)/,
+
+    // PostHog::alias(['distinctId' => $user->id, ...])
+    /PostHog::alias\(\s*\[[^\]]*['"]distinctId['"]\s*=>\s*([^\s,\]]+)/,
+
+    // 'distinctId' => $user->id — array key in any context
+    /['"]distinctId['"]\s*=>\s*([^\s,\]]+)/,
+  ],
+
+  go: [
+    // posthog.Identify{ DistinctId: user.ID, ... }
+    /posthog\.Identify\{[^}]*DistinctId:\s*([^\s,}]+)/,
+
+    // posthog.Capture{ DistinctId: user.ID, ... }
+    /posthog\.Capture\{[^}]*DistinctId:\s*([^\s,}]+)/,
+
+    // posthog.Alias{ DistinctId: user.ID, ... }
+    /posthog\.Alias\{[^}]*DistinctId:\s*([^\s,}]+)/,
+
+    // DistinctId: user.ID — struct field in any context
+    /DistinctId:\s*([^\s,}]+)/,
+  ],
+
+  java: [
+    // posthog.identify(user.getId(), ...) — first positional arg
+    /posthog\.identify\(\s*([\w.]+(?:\(\))?)/,
+
+    // posthog.capture(user.getId(), ...) — first positional arg
+    /posthog\.capture\(\s*([\w.]+(?:\(\))?)/,
+
+    // posthog.alias(frontendId, backendId) — first arg is distinct_id
+    /posthog\.alias\(\s*([\w.]+(?:\(\))?)/,
+
+    // PostHog.identify(distinctId = value, ...) — Kotlin named param (Android SDK)
+    /PostHog\.identify\(\s*distinctId\s*=\s*([\w.]+(?:\(\))?)/,
+
+    // .distinctId(user.getId()) — builder pattern
+    /\.distinctId\(\s*([\w.]+(?:\(\))?)/,
+
+    // setDistinctId(user.getId())
+    /setDistinctId\(\s*([\w.]+(?:\(\))?)/,
+  ],
+
+  dotnet: [
+    // posthog.Identify(userId, ...) or posthog.IdentifyAsync(userId, ...)
+    /\.Identify(?:Async)?\(\s*([^\s,)]+)/,
+
+    // posthog.Capture(userId, ...) or posthog.CaptureAsync(userId, ...)
+    /\.Capture(?:Async)?\(\s*([^\s,)]+)/,
+
+    // DistinctId = user.Id — property assignment in options object
+    /DistinctId\s*=\s*([^\s,}]+)/,
+  ],
+};
+
+/**
+ * Values that are clearly placeholder/example strings, not real expressions.
+ * These come from PostHog docs examples and should be skipped.
+ */
+const PLACEHOLDER_VALUES = new Set([
+  'distinct_id',
+  'distinctId',
+  'distinctid',
+  'distinct_id_one',
+  'distinct_id_two',
+  'user_A',
+  'user1',
+  'user2',
+  'frontend_id',
+  'backend_id',
+]);
+
+function isValidExpression(expression: string): boolean {
+  if (!expression) return false;
+
+  // Skip string literals
+  if (
+    expression.startsWith("'") ||
+    expression.startsWith('"') ||
+    expression.startsWith('`')
+  ) {
+    return false;
+  }
+
+  // Skip placeholder values commonly seen in docs/examples
+  if (PLACEHOLDER_VALUES.has(expression)) return false;
+
+  // Skip purely numeric values
+  if (/^\d+$/.test(expression)) return false;
+
+  // Must look like a variable/property access (contains at least one letter)
+  return /[a-zA-Z]/.test(expression);
+}
+
+export async function detectPostHogDistinctId(
+  installDir: string,
+  language: Language,
+): Promise<PostHogDistinctIdResult> {
+  const files = await fg(FILE_EXTENSIONS[language], {
+    cwd: installDir,
+    ignore: IGNORE_DIRS,
+  });
+
+  const patterns = IDENTIFY_PATTERNS[language];
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(installDir, file), 'utf-8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const pattern of patterns) {
+          const match = pattern.exec(line);
+          if (match) {
+            const expression = match[match.length - 1];
+            if (isValidExpression(expression)) {
+              return {
+                distinctIdExpression: expression,
+                sourceFile: file,
+                sourceLine: line.trim(),
+              };
+            }
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return {
+    distinctIdExpression: null,
+    sourceFile: null,
+    sourceLine: null,
+  };
+}
diff --git a/src/setup-revenue-analytics/prompt-builder.ts b/src/setup-revenue-analytics/prompt-builder.ts
new file mode 100644
index 0000000..719e52f
--- /dev/null
+++ b/src/setup-revenue-analytics/prompt-builder.ts
@@ -0,0 +1,184 @@
+/**
+ * Build the agent prompt for revenue analytics setup.
+ *
+ * Assembles all detected context (language, Stripe calls, PostHog distinct_id,
+ * Stripe docs) into a structured prompt the agent can follow step-by-step.
+ */
+
+import { AgentSignals } from '../lib/agent-interface';
+import type {
+  Language,
+  StripeDetectionResult,
+  PostHogDistinctIdResult,
+  StripeDocsForLanguage,
+} from './types';
+
+interface PromptContext {
+  language: Language;
+  stripeDetection: StripeDetectionResult;
+  posthogDetection: PostHogDistinctIdResult;
+  stripeDocs: StripeDocsForLanguage;
+}
+
+export function buildRevenueAnalyticsPrompt(context: PromptContext): string {
+  const { language, stripeDetection, posthogDetection, stripeDocs } = context;
+
+  const distinctIdSection = posthogDetection.distinctIdExpression
+    ? `- PostHog distinct_id: \`${posthogDetection.distinctIdExpression}\` (found in ${posthogDetection.sourceFile}: \`${posthogDetection.sourceLine}\`)`
+    : `- PostHog distinct_id: **Not automatically detected**.`;
+
+  const customerCreationSection =
+    stripeDetection.customerCreationCalls.length > 0
+      ? stripeDetection.customerCreationCalls
+          .map((c) => `  - ${c.file}:${c.line} — \`${c.snippet}\``)
+          .join('\n')
+      : '  (none found — search the codebase yourself)';
+
+  const chargeSection =
+    stripeDetection.chargeCalls.length > 0
+      ? stripeDetection.chargeCalls
+          .map((c) => `  - ${c.file}:${c.line} [${c.type}] — \`${c.snippet}\``)
+          .join('\n')
+      : '  (none found — search the codebase yourself)';
+
+  const checkoutNote = stripeDetection.usesCheckoutSessions
+    ? `
+IMPORTANT — Stripe Checkout detected:
+This project uses checkout.Session.create, which means Stripe may auto-create customers.
+If there is no explicit Customer.create call, you need to handle this in the checkout.session.completed webhook handler instead.
+In the webhook handler, after receiving the session object, update the customer with the PostHog metadata.
+
+Tip: Set client_reference_id to the internal user ID when creating Checkout Sessions. This lets you look up the user in your database when the webhook fires.`
+    : '';
+
+  return `You are setting up PostHog revenue analytics for a ${language} project that uses Stripe.
+
+Your goal: Modify the codebase so that every Stripe customer has a \`posthog_person_distinct_id\` metadata field. This connects Stripe revenue data to PostHog persons.
+
+## Guiding Tenets
+
+Follow these tenets for every decision you make:
+
+1. **Never fabricate the value.** If the PostHog distinct_id is not available in the current scope, do NOT substitute another identifier (Stripe customer ID, internal user ID, org ID, etc.). A wrong value is worse than no value — it corrupts metadata and blocks correct identification downstream.
+
+2. **Thread the value, don't invent it.** If a function needs the distinct_id but doesn't have it, add it as an optional parameter propagated from a caller that does. If no caller in the chain has it, skip that call site entirely and leave a TODO comment.
+
+3. **Minimize extra API calls.** Each \`stripe.Customer.modify\` / \`stripe.customers.update\` is a network round-trip with rate-limit cost. Don't add one before every payment intent, subscription, or invoice creation. If multiple charge calls share the same customer in a single flow, update once at the top, not before each call.
+
+4. **Follow existing Stripe abstraction patterns.** If the codebase wraps Stripe calls behind a utility/service layer, modify that layer. Don't call the Stripe API directly from business logic just to set metadata.
+
+## Context
+
+- Language: ${language}
+- Stripe SDK: ${stripeDetection.sdkPackage}${
+    stripeDetection.sdkVersion ? ` v${stripeDetection.sdkVersion}` : ''
+  }
+${distinctIdSection}
+
+### Customer creation locations:
+${customerCreationSection}
+
+### Charge/payment locations:
+${chargeSection}
+
+## CRITICAL FIRST STEP: Determine the PostHog distinct_id value
+
+Before writing ANY code, you must determine what this project uses as the PostHog distinct_id. This is the value that must go into \`posthog_person_distinct_id\` metadata on Stripe customers.
+
+${
+  posthogDetection.distinctIdExpression
+    ? `The pre-scan detected \`${posthogDetection.distinctIdExpression}\` (from \`${posthogDetection.sourceLine}\`). Verify this is correct by reading the file, then determine how to access the same value at each Stripe call site.`
+    : `Search the codebase for how the distinct_id is set.`
+}
+
+How to find it:
+1. Search for \`posthog.identify(\` — the FIRST ARGUMENT is the distinct_id. This is the most reliable source.
+   Example: \`posthog.identify(email, { ... })\` → the distinct_id is \`email\`
+   Example: \`posthog.identify(user.id, { ... })\` → the distinct_id is \`user.id\`
+2. Search for \`posthog.capture(\` or \`client.capture(\` — look for \`distinctId\` or \`distinct_id\` in the arguments.
+3. Search for \`posthog.get_distinct_id()\` — the variable it's assigned to tells you what holds the distinct_id.
+
+Once you know WHAT value is the distinct_id (e.g. \`email\`, \`user.id\`, \`userId\`), determine HOW to access that same value at each Stripe call site. The variable name may differ between files — trace the data flow.
+
+If the distinct_id is not available at a Stripe call site, apply Tenet 2: add it as an optional parameter from a caller that has it. If no caller has it, skip that site and add a TODO.
+
+Once determined, emit: ${
+    AgentSignals.STATUS
+  } Identified distinct_id — updating Stripe customer creation...
+
+## Instructions
+
+Follow these steps IN ORDER. Emit a \`${
+    AgentSignals.STATUS
+  }\` message at the start of each step so the user can see progress.
+
+### STEP 1: Update Stripe Customer Creation
+
+For each Stripe Customer.create call, add \`posthog_person_distinct_id\` to the metadata.
+
+Before modifying: check if the codebase wraps Stripe calls behind a utility or service layer. If so, modify that layer — don't add direct API calls in business logic (Tenet 4).
+
+**API pattern (replace \`<POSTHOG_DISTINCT_ID>\` with the actual value):**
+\`\`\`
+${stripeDocs.customerCreate.fullExample}
+\`\`\`
+
+Rules:
+- Replace \`<POSTHOG_DISTINCT_ID>\` with the actual distinct_id expression available at this call site.
+- If the distinct_id is not in scope, thread it as an optional parameter from the caller (Tenet 2). If no caller has it, skip this site and add \`// TODO: pass PostHog distinct_id here\`.
+- If the call already has a metadata object, ADD the \`posthog_person_distinct_id\` key to it. Do NOT overwrite existing metadata.
+- Preserve all existing arguments and code structure.
+
+After modifying customer creation, emit: ${
+    AgentSignals.STATUS
+  } Customer creation updated — adding metadata for existing customers...
+
+### STEP 2: Add Customer Update for Existing Customers
+
+This step handles customers created before this setup — they won't have the metadata from Step 1.
+
+Add a \`Customer.update\` / \`Customer.modify\` call to tag existing customers with the PostHog distinct_id. But apply Tenet 3 — minimize API calls:
+- Do NOT add an update before every single charge call. Instead, find the earliest point where both the customer ID and the distinct_id are available.
+- If multiple charge calls share the same customer in a single function or flow, update once at the top.
+- If the codebase already has a "get or ensure customer" pattern, add the metadata there.
+
+**API pattern (replace \`<POSTHOG_DISTINCT_ID>\` with the actual value):**
+\`\`\`
+${stripeDocs.customerUpdate.fullExample}
+\`\`\`
+
+Rules:
+- Same as Step 1: if the distinct_id is not in scope, thread it or skip with a TODO (Tenet 2). Never substitute a different identifier (Tenet 1).
+- Respect existing Stripe abstraction layers (Tenet 4).
+${checkoutNote}
+
+After modifying existing customer handling, emit: ${
+    AgentSignals.STATUS
+  } Verifying changes...
+
+### STEP 3: Verify
+
+After making all changes, read each modified file to verify:
+- No syntax errors
+- Existing code logic is preserved
+- The metadata field uses the correct distinct_id value — not a fabricated property
+- No unnecessary duplicate API calls (Tenet 3)
+- Changes respect existing abstraction patterns (Tenet 4)
+- Imports are present if needed
+
+## Constraints
+
+- **Never fabricate.** Do not invent properties or values. \`user.posthogDistinctId\` does not exist — use only values from the codebase.
+- **Thread, don't invent.** If the distinct_id isn't in scope, propagate it as a parameter. If impossible, skip the site with a TODO.
+- **Minimize API calls.** Don't add a Customer.modify before every charge — deduplicate.
+- **Respect abstractions.** If the codebase wraps Stripe, modify the wrapper.
+- Do NOT modify charge/payment logic — only add metadata to customer creation and customer update calls.
+- Do NOT remove any existing code.
+- Do NOT add new packages or dependencies.
+- Preserve all imports and error handling.
+
+When done, emit: ${
+    AgentSignals.STATUS
+  } Revenue analytics setup complete — modified files summary.
+`;
+}
diff --git a/src/setup-revenue-analytics/stripe-detection.ts b/src/setup-revenue-analytics/stripe-detection.ts
new file mode 100644
index 0000000..14677f0
--- /dev/null
+++ b/src/setup-revenue-analytics/stripe-detection.ts
@@ -0,0 +1,344 @@
+/**
+ * Stripe SDK detection — finds Stripe packages, versions, and API call patterns.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import type {
+  Language,
+  StripeDetectionResult,
+  StripeCallLocation,
+  StripeChargeCall,
+} from './types';
+
+const STRIPE_PACKAGES: Record<Language, { file: string; pattern: RegExp }[]> = {
+  node: [{ file: 'package.json', pattern: /"stripe"/ }],
+  python: [
+    { file: 'requirements.txt', pattern: /^stripe([>=~!<\s]|$)/m },
+    { file: 'pyproject.toml', pattern: /["']stripe["']/ },
+    { file: 'Pipfile', pattern: /stripe/ },
+    { file: 'uv.lock', pattern: /name\s*=\s*["']stripe["']/ },
+    { file: 'poetry.lock', pattern: /name\s*=\s*["']stripe["']/ },
+  ],
+  ruby: [{ file: 'Gemfile', pattern: /['"]stripe['"]/ }],
+  php: [{ file: 'composer.json', pattern: /"stripe\/stripe-php"/ }],
+  go: [{ file: 'go.mod', pattern: /github\.com\/stripe\/stripe-go/ }],
+  java: [
+    { file: 'build.gradle', pattern: /com\.stripe:stripe-java/ },
+    { file: 'build.gradle.kts', pattern: /com\.stripe:stripe-java/ },
+    { file: 'pom.xml', pattern: /stripe-java/ },
+  ],
+  dotnet: [{ file: '*.csproj', pattern: /Stripe\.net/i }],
+};
+
+const CUSTOMER_CREATE_PATTERNS: Record<Language, RegExp> = {
+  node: /stripe\.customers\.create\s*\(/,
+  python: /stripe\.Customer\.create\s*\(/,
+  ruby: /Stripe::Customer\.create\s*\(/,
+  php: /(?:\$stripe->customers->create|\\\s*Stripe\\\s*Customer::create)\s*\(/,
+  go: /customer\.New\s*\(/,
+  java: /Customer\.create\s*\(/,
+  dotnet: /(?:CustomerService|customerService).*\.Create/,
+};
+
+type ChargeType = StripeChargeCall['type'];
+
+const CHARGE_PATTERNS: Record<
+  Language,
+  { pattern: RegExp; type: ChargeType }[]
+> = {
+  node: [
+    { pattern: /stripe\.paymentIntents\.create\s*\(/, type: 'payment_intent' },
+    { pattern: /stripe\.subscriptions\.create\s*\(/, type: 'subscription' },
+    {
+      pattern: /stripe\.checkout\.sessions\.create\s*\(/,
+      type: 'checkout_session',
+    },
+    { pattern: /stripe\.invoices\.create\s*\(/, type: 'invoice' },
+  ],
+  python: [
+    { pattern: /stripe\.PaymentIntent\.create\s*\(/, type: 'payment_intent' },
+    { pattern: /stripe\.Subscription\.create\s*\(/, type: 'subscription' },
+    {
+      pattern: /stripe\.checkout\.Session\.create\s*\(/,
+      type: 'checkout_session',
+    },
+    { pattern: /stripe\.Invoice\.create\s*\(/, type: 'invoice' },
+  ],
+  ruby: [
+    { pattern: /Stripe::PaymentIntent\.create\s*\(/, type: 'payment_intent' },
+    { pattern: /Stripe::Subscription\.create\s*\(/, type: 'subscription' },
+    {
+      pattern: /Stripe::Checkout::Session\.create\s*\(/,
+      type: 'checkout_session',
+    },
+    { pattern: /Stripe::Invoice\.create\s*\(/, type: 'invoice' },
+  ],
+  php: [
+    {
+      pattern: /(?:paymentIntents->create|PaymentIntent::create)\s*\(/,
+      type: 'payment_intent',
+    },
+    {
+      pattern: /(?:subscriptions->create|Subscription::create)\s*\(/,
+      type: 'subscription',
+    },
+    {
+      pattern: /(?:checkout->sessions->create|Session::create)\s*\(/,
+      type: 'checkout_session',
+    },
+    { pattern: /(?:invoices->create|Invoice::create)\s*\(/, type: 'invoice' },
+  ],
+  go: [
+    { pattern: /paymentintent\.New\s*\(/, type: 'payment_intent' },
+    { pattern: /sub\.New\s*\(/, type: 'subscription' },
+    { pattern: /session\.New\s*\(/, type: 'checkout_session' },
+    { pattern: /invoice\.New\s*\(/, type: 'invoice' },
+  ],
+  java: [
+    { pattern: /PaymentIntent\.create\s*\(/, type: 'payment_intent' },
+    { pattern: /Subscription\.create\s*\(/, type: 'subscription' },
+    { pattern: /Session\.create\s*\(/, type: 'checkout_session' },
+    { pattern: /Invoice\.create\s*\(/, type: 'invoice' },
+  ],
+  dotnet: [
+    { pattern: /PaymentIntentService.*\.Create/, type: 'payment_intent' },
+    { pattern: /SubscriptionService.*\.Create/, type: 'subscription' },
+    { pattern: /SessionService.*\.Create/, type: 'checkout_session' },
+    { pattern: /InvoiceService.*\.Create/, type: 'invoice' },
+  ],
+};
+
+const FILE_EXTENSIONS: Record<Language, string> = {
+  node: '**/*.{ts,js,tsx,jsx,mjs,cjs}',
+  python: '**/*.py',
+  ruby: '**/*.rb',
+  php: '**/*.php',
+  go: '**/*.go',
+  java: '**/*.{java,kt,kts}',
+  dotnet: '**/*.{cs,fs}',
+};
+
+const IGNORE_DIRS = [
+  '**/node_modules/**',
+  '**/venv/**',
+  '**/.venv/**',
+  '**/env/**',
+  '**/.env/**',
+  '**/vendor/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.git/**',
+  '**/bin/**',
+  '**/obj/**',
+];
+
+function detectStripePackage(
+  installDir: string,
+  language: Language,
+): string | null {
+  const checks = STRIPE_PACKAGES[language];
+  for (const { file, pattern } of checks) {
+    try {
+      const globPattern = file.includes('*') ? file : `**/${file}`;
+      const matches = fg.sync(globPattern, {
+        cwd: installDir,
+        deep: 3,
+        ignore: IGNORE_DIRS,
+      });
+      for (const match of matches) {
+        const content = fs.readFileSync(path.join(installDir, match), 'utf-8');
+        if (pattern.test(content)) return match;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract Stripe SDK version from lockfiles / dependency declarations.
+ * Searches relative to the directory where the package file was found,
+ * supporting monorepos where the package file may be in a subdirectory.
+ */
+function extractStripeVersion(
+  installDir: string,
+  language: Language,
+  packageFile: string,
+): string | null {
+  const packageDir = path.join(installDir, path.dirname(packageFile));
+  try {
+    switch (language) {
+      case 'node': {
+        for (const lockfile of [
+          'package-lock.json',
+          'yarn.lock',
+          'pnpm-lock.yaml',
+        ]) {
+          const lockPath = path.join(packageDir, lockfile);
+          if (!fs.existsSync(lockPath)) continue;
+          const content = fs.readFileSync(lockPath, 'utf-8');
+
+          if (lockfile === 'package-lock.json') {
+            const parsed = JSON.parse(content);
+            const stripePkg =
+              parsed.packages?.['node_modules/stripe'] ??
+              parsed.dependencies?.stripe;
+            if (stripePkg?.version) return stripePkg.version;
+          } else if (lockfile === 'yarn.lock') {
+            const match = content.match(/stripe@[^:]+:\s+version\s+"([^"]+)"/);
+            if (match) return match[1];
+          } else if (lockfile === 'pnpm-lock.yaml') {
+            const match = content.match(/stripe@([^\s:]+)/);
+            if (match) return match[1];
+          }
+        }
+        const pkgJson = JSON.parse(
+          fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'),
+        );
+        const ver =
+          pkgJson.dependencies?.stripe ?? pkgJson.devDependencies?.stripe;
+        return ver ?? null;
+      }
+      case 'python': {
+        for (const lockfile of ['requirements.txt', 'poetry.lock', 'uv.lock']) {
+          const lockPath = path.join(packageDir, lockfile);
+          if (!fs.existsSync(lockPath)) continue;
+          const content = fs.readFileSync(lockPath, 'utf-8');
+          const match = content.match(/stripe[=~>=<]+([0-9][0-9.]*)/i);
+          if (match) return match[1];
+        }
+        return null;
+      }
+      case 'ruby': {
+        const lockPath = path.join(packageDir, 'Gemfile.lock');
+        if (fs.existsSync(lockPath)) {
+          const content = fs.readFileSync(lockPath, 'utf-8');
+          const match = content.match(/stripe\s+\(([^)]+)\)/);
+          if (match) return match[1];
+        }
+        return null;
+      }
+      case 'php': {
+        const lockPath = path.join(packageDir, 'composer.lock');
+        if (fs.existsSync(lockPath)) {
+          const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+          const pkg = parsed.packages?.find(
+            (p: { name: string }) => p.name === 'stripe/stripe-php',
+          );
+          if (pkg?.version) return pkg.version.replace(/^v/, '');
+        }
+        return null;
+      }
+      case 'go': {
+        const sumPath = path.join(packageDir, 'go.sum');
+        if (fs.existsSync(sumPath)) {
+          const content = fs.readFileSync(sumPath, 'utf-8');
+          const match = content.match(
+            /github\.com\/stripe\/stripe-go\/v\d+\s+v([^\s]+)/,
+          );
+          if (match) return match[1];
+        }
+        return null;
+      }
+      case 'java': {
+        for (const buildFile of [
+          'build.gradle',
+          'build.gradle.kts',
+          'pom.xml',
+        ]) {
+          const filePath = path.join(packageDir, buildFile);
+          if (!fs.existsSync(filePath)) continue;
+          const content = fs.readFileSync(filePath, 'utf-8');
+          const match = content.match(/stripe-java[:'"\s]+([0-9][0-9.]*)/);
+          if (match) return match[1];
+        }
+        return null;
+      }
+      case 'dotnet': {
+        const csprojFiles = fg.sync('**/*.csproj', {
+          cwd: installDir,
+          deep: 3,
+        });
+        for (const file of csprojFiles) {
+          const content = fs.readFileSync(path.join(installDir, file), 'utf-8');
+          const match = content.match(
+            /Stripe\.net['"]\s+Version=['"]([^'"]+)/i,
+          );
+          if (match) return match[1];
+        }
+        return null;
+      }
+    }
+  } catch {
+    return null;
+  }
+}
+
+function scanForPatterns(
+  installDir: string,
+  language: Language,
+  pattern: RegExp,
+): StripeCallLocation[] {
+  const results: StripeCallLocation[] = [];
+  const files = fg.sync(FILE_EXTENSIONS[language], {
+    cwd: installDir,
+    ignore: IGNORE_DIRS,
+  });
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(installDir, file), 'utf-8');
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i])) {
+          results.push({
+            file,
+            line: i + 1,
+            snippet: lines[i].trim(),
+          });
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return results;
+}
+
+export function detectStripe(
+  installDir: string,
+  language: Language,
+): StripeDetectionResult | null {
+  const packageFile = detectStripePackage(installDir, language);
+  if (!packageFile) return null;
+
+  const sdkVersion = extractStripeVersion(installDir, language, packageFile);
+
+  const customerCreationCalls = scanForPatterns(
+    installDir,
+    language,
+    CUSTOMER_CREATE_PATTERNS[language],
+  );
+
+  const chargeCalls: StripeChargeCall[] = [];
+  for (const { pattern, type } of CHARGE_PATTERNS[language]) {
+    const locations = scanForPatterns(installDir, language, pattern);
+    chargeCalls.push(...locations.map((loc) => ({ ...loc, type })));
+  }
+
+  const usesCheckoutSessions = chargeCalls.some(
+    (c) => c.type === 'checkout_session',
+  );
+
+  return {
+    sdkPackage: packageFile,
+    sdkVersion,
+    language,
+    customerCreationCalls,
+    chargeCalls,
+    usesCheckoutSessions,
+  };
+}
diff --git a/src/setup-revenue-analytics/stripe-docs-fallback.ts b/src/setup-revenue-analytics/stripe-docs-fallback.ts
new file mode 100644
index 0000000..8de33a2
--- /dev/null
+++ b/src/setup-revenue-analytics/stripe-docs-fallback.ts
@@ -0,0 +1,174 @@
+/**
+ * Hardcoded fallback Stripe code examples for each language.
+ * Used when runtime fetching from Stripe's docs site fails.
+ *
+ * IMPORTANT: Examples use <POSTHOG_DISTINCT_ID> as a placeholder.
+ * The prompt instructs the agent to replace this with the actual
+ * distinct_id expression found in the codebase (e.g. the value
+ * passed to posthog.identify()).
+ */
+
+import type { Language, StripeDocsForLanguage } from './types';
+
+export const STRIPE_DOCS_FALLBACK: Record<Language, StripeDocsForLanguage> = {
+  node: {
+    customerCreate: {
+      pattern: 'stripe.customers.create({ ... })',
+      metadataExample:
+        'metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> }',
+      fullExample: `const customer = await stripe.customers.create({
+  email: user.email,
+  metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> },
+});`,
+    },
+    customerUpdate: {
+      pattern: 'stripe.customers.update(customerId, { ... })',
+      metadataExample:
+        '{ metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> } }',
+      fullExample: `await stripe.customers.update(
+  customerId,
+  { metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> } }
+);`,
+    },
+  },
+
+  python: {
+    customerCreate: {
+      pattern: 'stripe.Customer.create(...)',
+      metadataExample:
+        'metadata={"posthog_person_distinct_id": <POSTHOG_DISTINCT_ID>}',
+      fullExample: `customer = stripe.Customer.create(
+    email=user.email,
+    metadata={"posthog_person_distinct_id": <POSTHOG_DISTINCT_ID>},
+)`,
+    },
+    customerUpdate: {
+      pattern: 'stripe.Customer.modify(customer_id, ...)',
+      metadataExample:
+        'metadata={"posthog_person_distinct_id": <POSTHOG_DISTINCT_ID>}',
+      fullExample: `stripe.Customer.modify(
+    customer_id,
+    metadata={"posthog_person_distinct_id": <POSTHOG_DISTINCT_ID>},
+)`,
+    },
+  },
+
+  ruby: {
+    customerCreate: {
+      pattern: 'Stripe::Customer.create({ ... })',
+      metadataExample:
+        'metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> }',
+      fullExample: `customer = Stripe::Customer.create({
+  email: user.email,
+  metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> },
+})`,
+    },
+    customerUpdate: {
+      pattern: 'Stripe::Customer.update(customer_id, { ... })',
+      metadataExample:
+        '{ metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> } }',
+      fullExample: `Stripe::Customer.update(
+  customer_id,
+  { metadata: { posthog_person_distinct_id: <POSTHOG_DISTINCT_ID> } }
+)`,
+    },
+  },
+
+  php: {
+    customerCreate: {
+      pattern: '$stripe->customers->create([...])',
+      metadataExample:
+        "'metadata' => ['posthog_person_distinct_id' => <POSTHOG_DISTINCT_ID>]",
+      fullExample: `$customer = $stripe->customers->create([
+    'email' => $user->email,
+    'metadata' => ['posthog_person_distinct_id' => <POSTHOG_DISTINCT_ID>],
+]);`,
+    },
+    customerUpdate: {
+      pattern: '$stripe->customers->update($customerId, [...])',
+      metadataExample:
+        "['metadata' => ['posthog_person_distinct_id' => <POSTHOG_DISTINCT_ID>]]",
+      fullExample: `$stripe->customers->update(
+    $customerId,
+    ['metadata' => ['posthog_person_distinct_id' => <POSTHOG_DISTINCT_ID>]]
+);`,
+    },
+  },
+
+  go: {
+    customerCreate: {
+      pattern: 'customer.New(params)',
+      metadataExample:
+        'params.AddMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)',
+      fullExample: `params := &stripe.CustomerParams{
+    Email: stripe.String(user.Email),
+}
+params.AddMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)
+cust, err := customer.New(params)`,
+    },
+    customerUpdate: {
+      pattern: 'customer.Update(customerId, params)',
+      metadataExample:
+        'params.AddMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)',
+      fullExample: `params := &stripe.CustomerParams{}
+params.AddMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)
+_, err := customer.Update(stripeCustomerID, params)`,
+    },
+  },
+
+  java: {
+    customerCreate: {
+      pattern: 'Customer.create(params)',
+      metadataExample:
+        '.putMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)',
+      fullExample: `CustomerCreateParams params = CustomerCreateParams.builder()
+    .setEmail(user.getEmail())
+    .putMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)
+    .build();
+Customer customer = Customer.create(params);`,
+    },
+    customerUpdate: {
+      pattern: 'Customer.retrieve(customerId).update(params)',
+      metadataExample:
+        '.putMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)',
+      fullExample: `CustomerUpdateParams params = CustomerUpdateParams.builder()
+    .putMetadata("posthog_person_distinct_id", <POSTHOG_DISTINCT_ID>)
+    .build();
+Customer.retrieve(stripeCustomerId).update(params);`,
+    },
+  },
+
+  dotnet: {
+    customerCreate: {
+      pattern: 'customerService.CreateAsync(options)',
+      metadataExample: `Metadata = new Dictionary<string, string>
+{
+    { "posthog_person_distinct_id", <POSTHOG_DISTINCT_ID> },
+}`,
+      fullExample: `var options = new CustomerCreateOptions
+{
+    Email = user.Email,
+    Metadata = new Dictionary<string, string>
+    {
+        { "posthog_person_distinct_id", <POSTHOG_DISTINCT_ID> },
+    },
+};
+var customer = await customerService.CreateAsync(options);`,
+    },
+    customerUpdate: {
+      pattern: 'customerService.UpdateAsync(customerId, options)',
+      metadataExample: `Metadata = new Dictionary<string, string>
+{
+    { "posthog_person_distinct_id", <POSTHOG_DISTINCT_ID> },
+}`,
+      fullExample: `var options = new CustomerUpdateOptions
+{
+    Metadata = new Dictionary<string, string>
+    {
+        { "posthog_person_distinct_id", <POSTHOG_DISTINCT_ID> },
+    },
+};
+await customerService.UpdateAsync(stripeCustomerId, options);`,
+    },
+  },
+};
diff --git a/src/setup-revenue-analytics/stripe-docs-fetcher.ts b/src/setup-revenue-analytics/stripe-docs-fetcher.ts
new file mode 100644
index 0000000..3735f76
--- /dev/null
+++ b/src/setup-revenue-analytics/stripe-docs-fetcher.ts
@@ -0,0 +1,160 @@
+/**
+ * Runtime Stripe docs fetcher — retrieves code examples from Stripe's API docs.
+ *
+ * Fetches from known, stable Stripe docs URLs and extracts language-specific
+ * code examples. Falls back to hardcoded examples if fetching fails.
+ */
+
+import { logToFile } from '../utils/debug';
+import type { Language, StripeDocsForLanguage } from './types';
+import { STRIPE_DOCS_FALLBACK } from './stripe-docs-fallback';
+
+const STRIPE_DOCS_URLS = {
+  customerCreate: 'https://docs.stripe.com/api/customers/create',
+  customerUpdate: 'https://docs.stripe.com/api/customers/update',
+};
+
+const LANGUAGE_TO_STRIPE_TAB: Record<Language, string> = {
+  node: 'node',
+  python: 'python',
+  ruby: 'ruby',
+  php: 'php',
+  go: 'go',
+  java: 'java',
+  dotnet: 'dotnet',
+};
+
+/**
+ * Extract code blocks for a specific language from Stripe's API docs HTML.
+ *
+ * Stripe docs use a structured format where code examples are wrapped in
+ * elements with language-specific identifiers.
+ */
+function extractCodeBlock(html: string, language: Language): string | null {
+  const tab = LANGUAGE_TO_STRIPE_TAB[language];
+
+  // Stripe docs use `data-language="node"` (or similar) attributes on code blocks.
+  // Try multiple patterns to be resilient to minor HTML changes.
+  const patterns = [
+    // Pattern: <pre><code class="language-{tab}">...</code></pre>
+    new RegExp(
+      `<code[^>]*class="[^"]*language-${tab}[^"]*"[^>]*>([\\s\\S]*?)</code>`,
+      'i',
+    ),
+    // Pattern: data-language="{tab}" attribute
+    new RegExp(
+      `data-language="${tab}"[^>]*>[\\s\\S]*?<code[^>]*>([\\s\\S]*?)</code>`,
+      'i',
+    ),
+    // Pattern: id containing the language name within a code section
+    new RegExp(
+      `id="[^"]*${tab}[^"]*"[^>]*>[\\s\\S]*?<code[^>]*>([\\s\\S]*?)</code>`,
+      'i',
+    ),
+  ];
+
+  for (const pattern of patterns) {
+    const match = html.match(pattern);
+    if (match?.[1]) {
+      return decodeHtmlEntities(match[1].trim());
+    }
+  }
+
+  return null;
+}
+
+function decodeHtmlEntities(text: string): string {
+  // Loop tag stripping until stable — a single pass misses tags
+  // reconstructed from nested fragments (e.g. <scr<script>ipt>).
+  let stripped = text;
+  let prev: string;
+  do {
+    prev = stripped;
+    stripped = stripped.replace(/<[^>]+>/g, '');
+  } while (stripped !== prev);
+
+  return stripped
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+async function fetchPage(url: string): Promise<string | null> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10_000);
+
+    const response = await fetch(url, {
+      headers: {
+        'User-Agent': 'PostHog-Wizard/1.0',
+        Accept: 'text/html',
+      },
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeout);
+
+    if (!response.ok) {
+      logToFile(
+        `[stripe-docs-fetcher] fetch failed: ${url} status=${response.status}`,
+      );
+      return null;
+    }
+
+    return await response.text();
+  } catch (error) {
+    logToFile(
+      `[stripe-docs-fetcher] fetch error: ${url} error=${String(error)}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Fetch Stripe docs for a specific language at runtime.
+ * Returns null if fetching or parsing fails.
+ */
+export async function fetchStripeDocs(
+  language: Language,
+): Promise<StripeDocsForLanguage | null> {
+  const [createHtml, updateHtml] = await Promise.all([
+    fetchPage(STRIPE_DOCS_URLS.customerCreate),
+    fetchPage(STRIPE_DOCS_URLS.customerUpdate),
+  ]);
+
+  if (!createHtml || !updateHtml) {
+    logToFile('[stripe-docs-fetcher] failed to fetch one or more pages');
+    return null;
+  }
+
+  const createCode = extractCodeBlock(createHtml, language);
+  const updateCode = extractCodeBlock(updateHtml, language);
+
+  if (!createCode || !updateCode) {
+    logToFile(
+      `[stripe-docs-fetcher] could not extract code for language=${language}`,
+    );
+    return null;
+  }
+
+  // We have the raw code examples from Stripe. Build our structured format.
+  // The fetched examples are the "full example" — the pattern and metadata
+  // example come from our fallback (they're stable across versions).
+  const fallback = STRIPE_DOCS_FALLBACK[language];
+
+  return {
+    customerCreate: {
+      pattern: fallback.customerCreate.pattern,
+      metadataExample: fallback.customerCreate.metadataExample,
+      fullExample: createCode,
+    },
+    customerUpdate: {
+      pattern: fallback.customerUpdate.pattern,
+      metadataExample: fallback.customerUpdate.metadataExample,
+      fullExample: updateCode,
+    },
+  };
+}
diff --git a/src/setup-revenue-analytics/stripe-docs.ts b/src/setup-revenue-analytics/stripe-docs.ts
new file mode 100644
index 0000000..d641d74
--- /dev/null
+++ b/src/setup-revenue-analytics/stripe-docs.ts
@@ -0,0 +1,36 @@
+/**
+ * Stripe docs orchestrator — tries runtime fetch, falls back to hardcoded examples.
+ * Caches results for the session.
+ */
+
+import { logToFile } from '../utils/debug';
+import type { Language, StripeDocsForLanguage } from './types';
+import { fetchStripeDocs } from './stripe-docs-fetcher';
+import { STRIPE_DOCS_FALLBACK } from './stripe-docs-fallback';
+
+const cache = new Map<Language, StripeDocsForLanguage>();
+
+export async function getStripeDocs(
+  language: Language,
+  _sdkVersion?: string | null,
+): Promise<StripeDocsForLanguage> {
+  const cached = cache.get(language);
+  if (cached) return cached;
+
+  const fetched = await fetchStripeDocs(language);
+  if (fetched) {
+    logToFile(`[stripe-docs] using fetched docs for ${language}`);
+    cache.set(language, fetched);
+    return fetched;
+  }
+
+  logToFile(`[stripe-docs] using fallback docs for ${language}`);
+  const fallback = STRIPE_DOCS_FALLBACK[language];
+  cache.set(language, fallback);
+  return fallback;
+}
+
+/** Clear the cache (for testing). */
+export function clearStripeDocsCache(): void {
+  cache.clear();
+}
diff --git a/src/setup-revenue-analytics/types.ts b/src/setup-revenue-analytics/types.ts
new file mode 100644
index 0000000..100958b
--- /dev/null
+++ b/src/setup-revenue-analytics/types.ts
@@ -0,0 +1,50 @@
+/**
+ * Shared types for the setup-revenue-analytics command.
+ */
+
+export type Language =
+  | 'node'
+  | 'python'
+  | 'ruby'
+  | 'php'
+  | 'go'
+  | 'java'
+  | 'dotnet';
+
+export interface StripeCallLocation {
+  file: string;
+  line: number;
+  snippet: string;
+}
+
+export interface StripeChargeCall extends StripeCallLocation {
+  type: 'payment_intent' | 'subscription' | 'checkout_session' | 'invoice';
+}
+
+export interface StripeDetectionResult {
+  sdkPackage: string;
+  sdkVersion: string | null;
+  language: Language;
+  customerCreationCalls: StripeCallLocation[];
+  chargeCalls: StripeChargeCall[];
+  usesCheckoutSessions: boolean;
+}
+
+export interface PostHogDistinctIdResult {
+  distinctIdExpression: string | null;
+  sourceFile: string | null;
+  sourceLine: string | null;
+}
+
+export interface StripeDocsForLanguage {
+  customerCreate: {
+    pattern: string;
+    metadataExample: string;
+    fullExample: string;
+  };
+  customerUpdate: {
+    pattern: string;
+    metadataExample: string;
+    fullExample: string;
+  };
+}