@haystackeditor/cli 0.2.0 → 0.4.0

package/README.md

@@ -1,105 +1,81 @@
 # @haystackeditor/cli
 
-Unified CLI for Haystack verification, fixtures, and sandboxes.
+Set up Haystack verification for your project. When PRs are opened, an AI agent spins up your app in a sandbox and verifies changes work correctly.
 
-## Installation
+## Quick Start
 
 ```bash
-# Global install
-npm install -g @haystackeditor/cli
-
-# Or run directly with npx
 npx @haystackeditor/cli init
 ```
 
+This auto-detects your framework, package manager, and ports, then creates:
+- `.haystack.yml` - Configuration for the verification agent
+- `.agents/skills/haystack.md` - Skill file for AI agent discovery
+
 ## Commands
 
 ### `haystack init`
 
-Interactive setup wizard to create `.haystack.yml` configuration:
+Interactive setup wizard:
 
 ```bash
-haystack init              # Interactive wizard
-haystack init -y           # Accept all defaults
+npx @haystackeditor/cli init       # Interactive wizard
+npx @haystackeditor/cli init -y    # Accept all defaults
 ```
 
-### `haystack login`
+### `haystack status`
 
-Authenticate with Haystack via GitHub OAuth:
+Check if your project is configured:
 
 ```bash
-haystack login             # Opens browser for GitHub OAuth
-haystack login --token     # Use existing GitHub token
-haystack logout            # Clear stored credentials
+npx @haystackeditor/cli status
 ```
 
-### `haystack secrets`
+### `haystack login`
 
-Manage secrets for fixtures and integrations:
+Authenticate with GitHub (required for secrets management):
 
 ```bash
-haystack secrets list                # List all secrets
-haystack secrets set KEY value       # Set a secret
-haystack secrets delete KEY          # Delete a secret
+npx @haystackeditor/cli login
 ```
 
-Secrets are stored securely in the Haystack platform and referenced in `.haystack.yml` using `$VARIABLE` syntax.
-
-### `haystack record`
-
-Record API responses as fixtures:
+This uses GitHub's device flow - you'll get a code to enter at github.com/login/device.
 
 ```bash
-haystack record https://api.example.com/data
-haystack record https://api.example.com/data --output fixtures/data.json
+# Log out (removes stored credentials)
+npx @haystackeditor/cli logout
 ```
 
-### `haystack verify`
+### `haystack secrets`
 
-Run verification commands from `.haystack.yml`:
+Manage secrets that will be injected into your sandbox environment:
 
 ```bash
-haystack verify                # Run all verification commands
-haystack verify -c build       # Run specific command
-haystack verify --dry-run      # Show commands without running
-```
+# List all secrets (keys only, values are never shown)
+npx @haystackeditor/cli secrets list
 
-### `haystack dev`
+# Set a secret
+npx @haystackeditor/cli secrets set OPENAI_API_KEY sk-xxx
 
-Start dev server with fixtures enabled:
-
-```bash
-haystack dev                   # Start dev server
-haystack dev -s frontend       # Start specific service (monorepo)
-haystack dev --no-fixtures     # Start without fixture loading
+# Delete a secret
+npx @haystackeditor/cli secrets delete OPENAI_API_KEY
 ```
 
-### `haystack sandbox`
+Secrets are encrypted and stored securely. They're automatically injected as environment variables when the sandbox runs your app.
 
-Manage Haystack sandboxes:
+**Scopes**: By default, secrets are user-scoped. You can also scope to an org or repo:
 
 ```bash
-haystack sandbox create        # Create sandbox for current branch
-haystack sandbox status        # Check sandbox status
-haystack sandbox open          # Open sandbox in browser
-haystack sandbox logs          # Stream sandbox logs
-haystack sandbox destroy       # Destroy sandbox
-```
-
-### `haystack mcp`
+# Org-scoped (available to all repos in the org)
+npx @haystackeditor/cli secrets set API_KEY xxx --scope org --scope-id myorg
 
-Run as MCP server for Claude Code integration:
-
-```bash
-# Add to Claude Code
-claude mcp add haystack -- npx @haystackeditor/cli mcp
+# Repo-scoped (available only to this repo)
+npx @haystackeditor/cli secrets set API_KEY xxx --scope repo --scope-id owner/repo
 ```
 
 ## Configuration
 
-Create `.haystack.yml` in your project root:
-
-### Simple Project
+The `init` command creates `.haystack.yml`:
 
 ```yaml
 version: "1"
@@ -118,84 +94,27 @@ verification:
       run: pnpm build
     - name: lint
       run: pnpm lint
-    - name: typecheck
-      run: pnpm tsc --noEmit
-```
-
-### Monorepo
-
-```yaml
-version: "1"
-name: my-monorepo
-
-services:
-  frontend:
-    command: pnpm dev
-    port: 3000
-    ready_pattern: "Local:"
-    env:
-      SKIP_AUTH: "true"
-
-  api:
-    root: packages/api
-    command: pnpm dev
-    port: 8080
-    ready_pattern: "listening"
-
-  worker:
-    root: infra/worker
-    command: pnpm dev
-    ready_pattern: "Ready"
-
-  analysis:
-    root: packages/analysis
-    type: batch
-    command: pnpm start
-
-verification:
-  commands:
-    - name: build
-      run: pnpm build
-    - name: test
-      run: pnpm test
-
-  fixtures:
-    "*/api/github/*":
-      source: file://fixtures/github-api.json
-
-    "*/api/analysis/*":
-      source: pr://haystackeditor/example-repo/42
 ```
 
-## Fixtures
-
-Fixtures mock external API responses during development and testing. Sources:
-
-| Prefix | Description |
-|--------|-------------|
-| `file://` | Local JSON file |
-| `https://` | Remote URL (cached) |
-| `s3://` | AWS S3 bucket |
-| `r2://` | Cloudflare R2 bucket |
-| `pr://owner/repo/number` | Haystack PR analysis data |
-| `recorded://id` | Previously recorded fixture |
-| `passthrough` | Don't intercept, let request through |
+### Customizing After Init
 
-### Using Secrets in Fixtures
+| If your app has... | Add this |
+|-------------------|----------|
+| Login/authentication | Auth bypass env var in `dev_server.env` |
+| Key user journeys | Flows describing what to verify |
+| API calls needing auth | Fixtures to mock responses |
 
-```yaml
-fixtures:
-  "*/api/private/*":
-    source: s3://my-bucket/fixtures/data.json
-    headers:
-      Authorization: Bearer $AWS_TOKEN
-```
+See the generated `.agents/skills/haystack.md` for full documentation on flows, fixtures, and monorepo configuration.
 
-Set the secret:
+## How It Works
 
-```bash
-haystack secrets set AWS_TOKEN "your-token-here"
-```
+1. You run `npx @haystackeditor/cli init` and commit the config
+2. When a PR is opened, Haystack's AI agent:
+   - Spins up your app in a Modal sandbox
+   - Reads the flows to understand what to verify
+   - Navigates the app autonomously
+   - Captures screenshots and evidence
+   - Reports results on the PR
 
 ## License
 

package/dist/commands/init.js

@@ -8,9 +8,15 @@ import chalk from 'chalk';
 import * as path from 'path';
 import { detectProject } from '../utils/detect.js';
 import { saveConfig, configExists } from '../utils/config.js';
-import { createSkillFile } from '../utils/skill.js';
+import { createSkillFile, createClaudeCommand } from '../utils/skill.js';
 import { validateConfigSecurity, formatSecurityReport } from '../utils/secrets.js';
 export async function initCommand(options) {
+    // Auto-use defaults when not in interactive terminal (e.g., when run by AI agents)
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    if (!isInteractive && !options.yes) {
+        console.log(chalk.dim('Non-interactive mode detected. Using --yes defaults.\n'));
+        options.yes = true;
+    }
     console.log(chalk.cyan('\n🌾 Haystack Setup Wizard\n'));
     // Check if config already exists
     if (await configExists()) {
@@ -50,10 +56,27 @@ export async function initCommand(options) {
         console.log(chalk.green(`✓ Created ${configPath}`));
         // Create skill file for agent discovery
         const skillPath = await createSkillFile();
-        console.log(chalk.green(`✓ Created ${skillPath}\n`));
+        console.log(chalk.green(`✓ Created ${skillPath}`));
+        // Create Claude Code slash command
+        const commandPath = await createClaudeCommand();
+        console.log(chalk.green(`✓ Created ${commandPath} (use /haystack in Claude Code)\n`));
         // Security validation
         await runSecurityCheck(configPath);
-        printNextSteps();
+        // Explain purpose and next steps
+        console.log(chalk.cyan('━'.repeat(70)));
+        console.log(chalk.cyan.bold('\n📋 WHAT IS HAYSTACK?\n'));
+        console.log(chalk.white('When a PR is opened, Haystack spins up your app in a sandbox and'));
+        console.log(chalk.white('an AI agent verifies the changes work correctly by:\n'));
+        console.log(chalk.white('  • Frontend: Navigating pages, clicking buttons, taking screenshots'));
+        console.log(chalk.white('  • Backend: Calling API endpoints, checking responses\n'));
+        console.log(chalk.white('The "flows" in .haystack.yml tell the agent WHAT to verify.\n'));
+        console.log(chalk.cyan.bold('⚠️  ACTION REQUIRED:\n'));
+        console.log(chalk.white('The config above only has dev server settings. You MUST add flows.\n'));
+        console.log(chalk.white.bold('1. Run: cat .agents/skills/haystack.md'));
+        console.log(chalk.white.bold('2. Read the "Codebase Discovery Guide" section'));
+        console.log(chalk.white.bold('3. Follow it to discover features and add flows to .haystack.yml\n'));
+        console.log(chalk.dim('Without flows, Haystack has nothing to verify.\n'));
+        console.log(chalk.cyan('━'.repeat(70)));
         return;
     }
     // Interactive prompts

package/dist/commands/login.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Login command - GitHub OAuth device flow
+ */
+/**
+ * Load token from disk
+ */
+export declare function loadToken(): Promise<string | null>;
+export declare function loginCommand(): Promise<void>;
+export declare function logoutCommand(): Promise<void>;

package/dist/commands/login.js

@@ -0,0 +1,162 @@
+/**
+ * Login command - GitHub OAuth device flow
+ */
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+const GITHUB_CLIENT_ID = 'Ov23liW3JE38D3gZWa85'; // Haystack GitHub OAuth App
+const CONFIG_DIR = path.join(os.homedir(), '.haystack');
+const TOKEN_FILE = path.join(CONFIG_DIR, 'credentials.json');
+/**
+ * Start device flow and get user code
+ */
+async function startDeviceFlow() {
+    const response = await fetch('https://github.com/login/device/code', {
+        method: 'POST',
+        headers: {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            client_id: GITHUB_CLIENT_ID,
+            scope: 'read:user read:org repo',
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to start device flow: ${response.status}`);
+    }
+    return response.json();
+}
+/**
+ * Poll for access token
+ */
+async function pollForToken(deviceCode, interval) {
+    while (true) {
+        await new Promise(resolve => setTimeout(resolve, interval * 1000));
+        const response = await fetch('https://github.com/login/oauth/access_token', {
+            method: 'POST',
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                client_id: GITHUB_CLIENT_ID,
+                device_code: deviceCode,
+                grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            }),
+        });
+        const data = await response.json();
+        if (data.access_token) {
+            return data.access_token;
+        }
+        if (data.error === 'authorization_pending') {
+            // Still waiting for user
+            continue;
+        }
+        if (data.error === 'slow_down') {
+            // Increase interval
+            interval += 5;
+            continue;
+        }
+        if (data.error === 'expired_token') {
+            throw new Error('Authorization timed out. Please try again.');
+        }
+        if (data.error === 'access_denied') {
+            throw new Error('Authorization denied by user.');
+        }
+        throw new Error(`OAuth error: ${data.error}`);
+    }
+}
+/**
+ * Save token to disk
+ */
+async function saveToken(token) {
+    await fs.mkdir(CONFIG_DIR, { recursive: true });
+    const credentials = {
+        github_token: token,
+        created_at: new Date().toISOString(),
+    };
+    await fs.writeFile(TOKEN_FILE, JSON.stringify(credentials, null, 2), {
+        mode: 0o600, // Owner read/write only
+    });
+}
+/**
+ * Load token from disk
+ */
+export async function loadToken() {
+    try {
+        const content = await fs.readFile(TOKEN_FILE, 'utf-8');
+        const credentials = JSON.parse(content);
+        return credentials.github_token;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify token is valid by calling GitHub API
+ */
+async function verifyToken(token) {
+    try {
+        const response = await fetch('https://api.github.com/user', {
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'User-Agent': 'Haystack-CLI',
+            },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        return response.json();
+    }
+    catch {
+        return null;
+    }
+}
+export async function loginCommand() {
+    console.log(chalk.bold('\nHaystack Login\n'));
+    // Check if already logged in
+    const existingToken = await loadToken();
+    if (existingToken) {
+        const user = await verifyToken(existingToken);
+        if (user) {
+            console.log(chalk.green(`Already logged in as ${chalk.bold(user.login)}`));
+            console.log(chalk.dim('Run `haystack logout` to sign out.\n'));
+            return;
+        }
+    }
+    console.log('Authenticating with GitHub...\n');
+    try {
+        // Start device flow
+        const deviceFlow = await startDeviceFlow();
+        console.log(chalk.yellow('Open this URL in your browser:\n'));
+        console.log(`  ${chalk.bold(deviceFlow.verification_uri)}\n`);
+        console.log(chalk.yellow('And enter this code:\n'));
+        console.log(`  ${chalk.bold.cyan(deviceFlow.user_code)}\n`);
+        console.log(chalk.dim('Waiting for authorization...'));
+        // Poll for token
+        const token = await pollForToken(deviceFlow.device_code, deviceFlow.interval);
+        // Verify and save
+        const user = await verifyToken(token);
+        if (!user) {
+            throw new Error('Failed to verify token');
+        }
+        await saveToken(token);
+        console.log(chalk.green(`\nLogged in as ${chalk.bold(user.login)}`));
+        console.log(chalk.dim('Credentials saved to ~/.haystack/credentials.json\n'));
+    }
+    catch (error) {
+        console.error(chalk.red(`\nLogin failed: ${error.message}\n`));
+        process.exit(1);
+    }
+}
+export async function logoutCommand() {
+    try {
+        await fs.unlink(TOKEN_FILE);
+        console.log(chalk.green('\nLogged out successfully.\n'));
+    }
+    catch {
+        console.log(chalk.yellow('\nNot logged in.\n'));
+    }
+}

package/dist/commands/secrets.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Secrets commands - manage secrets stored on Haystack Platform
+ */
+/**
+ * List all secrets (keys only, not values)
+ */
+export declare function listSecrets(): Promise<void>;
+/**
+ * Set a secret
+ */
+export declare function setSecret(key: string, value: string, options: {
+    scope?: string;
+    scopeId?: string;
+}): Promise<void>;
+/**
+ * Delete a secret
+ */
+export declare function deleteSecret(key: string): Promise<void>;

package/dist/commands/secrets.js

@@ -0,0 +1,133 @@
+/**
+ * Secrets commands - manage secrets stored on Haystack Platform
+ */
+import chalk from 'chalk';
+import { loadToken } from './login.js';
+const API_BASE = 'https://haystackeditor.com/api/secrets';
+async function requireAuth() {
+    const token = await loadToken();
+    if (!token) {
+        console.error(chalk.red('\nNot logged in. Run `haystack login` first.\n'));
+        process.exit(1);
+    }
+    return token;
+}
+async function apiRequest(method, path, token, body) {
+    const url = `${API_BASE}${path}`;
+    const response = await fetch(url, {
+        method,
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'Haystack-CLI',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return response;
+}
+/**
+ * List all secrets (keys only, not values)
+ */
+export async function listSecrets() {
+    const token = await requireAuth();
+    console.log(chalk.dim('\nFetching secrets...\n'));
+    try {
+        const response = await apiRequest('GET', '', token);
+        if (!response.ok) {
+            if (response.status === 401) {
+                console.error(chalk.red('Session expired. Run `haystack login` again.\n'));
+                process.exit(1);
+            }
+            throw new Error(`Failed to list secrets: ${response.status}`);
+        }
+        const data = await response.json();
+        const secrets = data.secrets || [];
+        if (secrets.length === 0) {
+            console.log(chalk.yellow('No secrets found.\n'));
+            console.log(chalk.dim('Set a secret with: haystack secrets set KEY VALUE\n'));
+            return;
+        }
+        console.log(chalk.bold('Your secrets:\n'));
+        for (const secret of secrets) {
+            const scope = secret.scope === 'user' ? '' : chalk.dim(` (${secret.scope}: ${secret.scopeId})`);
+            console.log(`  ${chalk.cyan(secret.key)}${scope}`);
+        }
+        console.log();
+    }
+    catch (error) {
+        console.error(chalk.red(`\nError: ${error.message}\n`));
+        process.exit(1);
+    }
+}
+/**
+ * Set a secret
+ */
+export async function setSecret(key, value, options) {
+    const token = await requireAuth();
+    if (!key || !value) {
+        console.error(chalk.red('\nUsage: haystack secrets set KEY VALUE\n'));
+        process.exit(1);
+    }
+    // Validate key format
+    if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+        console.error(chalk.red('\nSecret key must be uppercase with underscores (e.g., MY_API_KEY)\n'));
+        process.exit(1);
+    }
+    console.log(chalk.dim(`\nSetting secret ${key}...`));
+    try {
+        const body = {
+            key,
+            plaintextValue: value, // Server will encrypt
+        };
+        if (options.scope) {
+            body.scope = options.scope;
+        }
+        if (options.scopeId) {
+            body.scopeId = options.scopeId;
+        }
+        const response = await apiRequest('POST', '', token, body);
+        if (!response.ok) {
+            if (response.status === 401) {
+                console.error(chalk.red('Session expired. Run `haystack login` again.\n'));
+                process.exit(1);
+            }
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.error || `Failed to set secret: ${response.status}`);
+        }
+        console.log(chalk.green(`\nSecret ${chalk.bold(key)} saved.\n`));
+    }
+    catch (error) {
+        console.error(chalk.red(`\nError: ${error.message}\n`));
+        process.exit(1);
+    }
+}
+/**
+ * Delete a secret
+ */
+export async function deleteSecret(key) {
+    const token = await requireAuth();
+    if (!key) {
+        console.error(chalk.red('\nUsage: haystack secrets delete KEY\n'));
+        process.exit(1);
+    }
+    console.log(chalk.dim(`\nDeleting secret ${key}...`));
+    try {
+        const response = await apiRequest('DELETE', `/${encodeURIComponent(key)}`, token);
+        if (!response.ok) {
+            if (response.status === 401) {
+                console.error(chalk.red('Session expired. Run `haystack login` again.\n'));
+                process.exit(1);
+            }
+            if (response.status === 404) {
+                console.error(chalk.yellow(`\nSecret ${key} not found.\n`));
+                process.exit(1);
+            }
+            throw new Error(`Failed to delete secret: ${response.status}`);
+        }
+        console.log(chalk.green(`\nSecret ${chalk.bold(key)} deleted.\n`));
+    }
+    catch (error) {
+        console.error(chalk.red(`\nError: ${error.message}\n`));
+        process.exit(1);
+    }
+}

package/dist/index.d.ts

@@ -6,7 +6,9 @@
  * This enables AI agents to spin up sandboxes of your app for testing.
  *
  * Usage:
- *   npx @haystackeditor/cli init    # Set up .haystack.yml
- *   npx @haystackeditor/cli status  # Check configuration
+ *   npx @haystackeditor/cli init           # Set up .haystack.yml
+ *   npx @haystackeditor/cli status         # Check configuration
+ *   npx @haystackeditor/cli login          # Authenticate with GitHub
+ *   npx @haystackeditor/cli secrets list   # List stored secrets
  */
 export {};

package/dist/index.js

@@ -6,17 +6,21 @@
  * This enables AI agents to spin up sandboxes of your app for testing.
  *
  * Usage:
- *   npx @haystackeditor/cli init    # Set up .haystack.yml
- *   npx @haystackeditor/cli status  # Check configuration
+ *   npx @haystackeditor/cli init           # Set up .haystack.yml
+ *   npx @haystackeditor/cli status         # Check configuration
+ *   npx @haystackeditor/cli login          # Authenticate with GitHub
+ *   npx @haystackeditor/cli secrets list   # List stored secrets
  */
 import { Command } from 'commander';
 import { statusCommand } from './commands/status.js';
 import { initCommand } from './commands/init.js';
+import { loginCommand, logoutCommand } from './commands/login.js';
+import { listSecrets, setSecret, deleteSecret } from './commands/secrets.js';
 const program = new Command();
 program
     .name('haystack')
     .description('Set up Haystack verification for your project')
-    .version('0.2.0');
+    .version('0.3.0');
 program
     .command('init')
     .description('Create .haystack.yml configuration')
@@ -34,6 +38,34 @@ program
     .command('status')
     .description('Check if .haystack.yml exists and is valid')
     .action(statusCommand);
+program
+    .command('login')
+    .description('Authenticate with GitHub')
+    .action(loginCommand);
+program
+    .command('logout')
+    .description('Remove stored credentials')
+    .action(logoutCommand);
+// Secrets subcommands
+const secrets = program
+    .command('secrets')
+    .description('Manage secrets for sandbox environments');
+secrets
+    .command('list')
+    .description('List all secrets (keys only)')
+    .action(listSecrets);
+secrets
+    .command('set <key> <value>')
+    .description('Set a secret')
+    .option('--scope <scope>', 'Scope: user, org, or repo (default: user)')
+    .option('--scope-id <id>', 'Scope ID (org name or owner/repo)')
+    .action((key, value, options) => {
+    setSecret(key, value, options);
+});
+secrets
+    .command('delete <key>')
+    .description('Delete a secret')
+    .action(deleteSecret);
 // Show help if no command provided
 if (process.argv.length === 2) {
     program.help();

package/dist/utils/skill.d.ts

@@ -1,4 +1,10 @@
 /**
  * Create the .agents/skills/haystack.md file for agent discovery
+ * and .claude/commands/haystack.md for Claude Code slash command
  */
 export declare function createSkillFile(): Promise<string>;
+/**
+ * Create the .claude/commands/haystack.md file for Claude Code slash command
+ * Users can invoke with /haystack to start the setup wizard
+ */
+export declare function createClaudeCommand(): Promise<string>;

package/dist/utils/skill.js

@@ -1,11 +1,161 @@
 /**
  * Create the .agents/skills/haystack.md file for agent discovery
+ * and .claude/commands/haystack.md for Claude Code slash command
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
+/**
+ * Claude Code slash command - invoked with /haystack
+ * This is the "one command" entry point for users.
+ * Uses task decomposition - complete one step, validate, then next step.
+ */
+const CLAUDE_COMMAND_CONTENT = `# Set Up Haystack Verification
+
+You are setting up Haystack PR verification. Complete each step IN ORDER. Do NOT skip ahead.
+
+---
+
+## STEP 1: Initialize config
+
+\`\`\`bash
+npx @haystackeditor/cli init --yes
+\`\`\`
+
+✅ **Checkpoint**: \`.haystack.yml\` exists with dev_server config.
+
+---
+
+## STEP 2: Discover all routes
+
+Find every route in the app:
+\`\`\`bash
+grep -r "path=\\|Route\\|<Link" src/ --include="*.tsx" | head -30
+ls src/pages/ src/app/ 2>/dev/null
+\`\`\`
+
+Add a flow for EACH route to \`.haystack.yml\`. Use \`trigger: always\` for main pages, \`trigger: on_change\` with \`watch_patterns\` for others.
+
+✅ **Checkpoint**: Count your flows. You should have one for every route.
+
+---
+
+## STEP 3: Fix ALL selectors (CRITICAL)
+
+⛔ **STOP**: Look at every \`wait_for\` selector in your flows.
+
+If ANY selector is \`#root\`, \`div\`, or \`h1\`, you MUST fix it now:
+\`\`\`bash
+# Find specific selectors in the codebase
+grep -r "data-testid\\|className=" src/components/ --include="*.tsx" | head -20
+\`\`\`
+
+Replace generic selectors with specific ones:
+- \`[data-testid='dashboard']\`
+- \`.dashboard-content\`
+- \`[role='main']\`
+
+✅ **Checkpoint**: Run \`grep "wait_for" .haystack.yml\` - NONE should have \`#root\`.
+
+---
+
+## STEP 4: Add 3+ interactive flows (REQUIRED)
+
+Find interactive elements:
+\`\`\`bash
+grep -r "onClick\\|Modal\\|Dialog\\|toggle\\|Switch" src/ --include="*.tsx" | head -20
+\`\`\`
+
+Add AT LEAST 3 flows with \`click\` or \`type\` actions:
+
+\`\`\`yaml
+- name: "Theme toggle works"
+  steps:
+    - action: navigate
+      url: "/"
+    - action: click
+      selector: "[data-testid='theme-toggle']"
+    - action: screenshot
+      name: "after-toggle"
+
+- name: "Modal opens"
+  steps:
+    - action: navigate
+      url: "/dashboard"
+    - action: click
+      selector: "button[aria-label='Settings']"
+    - action: wait_for
+      selector: "[role='dialog']"
+    - action: screenshot
+      name: "modal-open"
+\`\`\`
+
+✅ **Checkpoint**: Run \`grep -c "action: click" .haystack.yml\` - must be ≥3.
+
+---
+
+## STEP 5: Add fixtures for data-dependent pages
+
+Find pages that fetch data:
+\`\`\`bash
+grep -r "useParams\\|fetch(\\|useQuery" src/ --include="*.tsx" | head -10
+\`\`\`
+
+For each data-dependent page, add fixtures:
+\`\`\`yaml
+fixtures:
+  - pattern: "/api/user/*"
+    source: "https://staging.example.com/api/user/demo"
+  - pattern: "/api/pr/*"
+    source: "file://fixtures/sample-pr.json"
+\`\`\`
+
+✅ **Checkpoint**: Every page with \`:id\` or API calls has a fixture.
+
+---
+
+## STEP 6: Final validation
+
+Count and verify:
+\`\`\`bash
+echo "=== Selector check (should be 0 #root) ==="
+grep "#root" .haystack.yml | wc -l
+
+echo "=== Interactive flows (should be ≥3) ==="
+grep -c "action: click\\|action: type" .haystack.yml
+
+echo "=== Fixtures (should be >0 for data pages) ==="
+grep -c "pattern:" .haystack.yml
+\`\`\`
+
+If any check fails, GO BACK to that step and fix it.
+
+---
+
+## STEP 7: Commit
+
+\`\`\`bash
+git add .haystack.yml .agents/ .claude/ fixtures/
+git commit -m "Add Haystack verification"
+\`\`\`
+
+🎉 Done!
+`;
 const SKILL_CONTENT = `# Haystack Verification
 
-Haystack provides automated PR verification. When a PR is opened, an AI agent spins up the app in a sandbox and verifies changes work correctly.
+## What is Haystack?
+
+Haystack provides **automated PR verification**. When a PR is opened:
+
+1. A sandbox spins up with your app running (dev server + any backend services)
+2. An AI agent reads the "flows" in \`.haystack.yml\`
+3. The agent executes each flow to verify changes work correctly
+4. Results (screenshots, API responses, errors) are posted to the PR
+
+**Frontend flows**: The agent uses a browser to navigate pages, click buttons, fill forms, and take screenshots. This catches visual regressions and broken interactions.
+
+**Backend flows**: The agent makes HTTP requests to API endpoints and verifies responses. This catches broken endpoints and API contract changes.
+
+**Without flows, Haystack has nothing to verify.** The config's \`dev_server\` settings just tell it how to start your app - the flows tell it what to actually test.
 
 ## Setup Workflow
 
@@ -237,6 +387,263 @@ Most apps need auth bypassed for testing. Common patterns:
 | Rails | \`SKIP_AUTH=true\` |
 
 Add to \`dev_server.env\` or \`services.*.env\` in your config.
+
+## Codebase Discovery Guide
+
+**Follow these steps to create comprehensive verification flows.**
+
+### ⚠️ REQUIRED CHECKLIST - Complete ALL items before finishing:
+
+1. [ ] **Page flows**: Every route in the app has a flow
+2. [ ] **Specific selectors**: Using \`[data-testid='x']\` or \`.specific-class\`, NOT \`#root\` or \`div\`
+3. [ ] **Interactive flows**: At least 3 flows that click buttons, open modals, or submit forms
+4. [ ] **Fixtures**: Pages with \`:id\` params or API fetches have fixtures (staging URL or local file)
+5. [ ] **Backend API flows**: If app has API endpoints, add http_request flows to test them
+6. [ ] **Watch patterns**: Each flow's \`watch_patterns\` matches the component file paths
+
+**You are NOT done until all 6 items are checked.**
+
+---
+
+### Step 1: Trace the Component Tree
+
+Start from the entry point and trace imports to discover ALL features:
+
+\`\`\`bash
+# Find the entry point
+cat src/main.tsx  # or src/index.tsx, pages/_app.tsx, etc.
+
+# Trace the router to find all routes
+grep -r "Route\|path=" src/ --include="*.tsx"
+
+# Find all page/feature components
+ls src/pages/ src/components/ src/features/
+\`\`\`
+
+### Step 2: Find Good Selectors
+
+**DON'T use generic selectors like \`#root\`.** The agent needs specific selectors to know the page loaded correctly.
+
+Priority order for selectors:
+1. \`[data-testid='feature-name']\` - Best, explicit test hooks
+2. \`[role='main']\`, \`[role='navigation']\` - Semantic roles
+3. \`.feature-specific-class\` - Component-specific classes
+4. \`h1\`, \`.page-title\` - Unique page identifiers
+
+**How to find selectors:**
+\`\`\`bash
+# Search for data-testid attributes
+grep -r "data-testid" src/ --include="*.tsx"
+
+# Search for unique classNames in a component
+grep -r "className=" src/components/Dashboard.tsx
+
+# Look for page-specific elements
+grep -r "<h1\|<header\|role=" src/pages/
+\`\`\`
+
+**Example - BAD vs GOOD:**
+\`\`\`yaml
+# BAD - too generic, every page has #root
+- action: wait_for
+  selector: "#root"
+
+# GOOD - specific to this feature
+- action: wait_for
+  selector: "[data-testid='dashboard-content']"
+# or
+- action: wait_for
+  selector: ".dashboard-stats-grid"
+# or
+- action: wait_for
+  selector: "h1:has-text('Dashboard')"
+\`\`\`
+
+### Step 3: Add Interactive Flows
+
+Don't just screenshot static pages. Verify that interactions work:
+
+**Look for interactive elements:**
+\`\`\`bash
+# Find buttons and clickable elements
+grep -r "onClick\|button\|Button" src/ --include="*.tsx"
+
+# Find modals and dialogs
+grep -r "Modal\|Dialog\|Drawer" src/ --include="*.tsx"
+
+# Find forms
+grep -r "<form\|onSubmit\|handleSubmit" src/ --include="*.tsx"
+
+# Find toggles and switches
+grep -r "toggle\|Switch\|theme" src/ --include="*.tsx"
+\`\`\`
+
+**Example interactive flows:**
+\`\`\`yaml
+# Theme toggle
+- name: "Theme toggle works"
+  steps:
+    - action: navigate
+      url: "/"
+    - action: click
+      selector: "[data-testid='theme-toggle']"
+    - action: screenshot
+      name: "dark-mode"
+    - action: click
+      selector: "[data-testid='theme-toggle']"
+    - action: screenshot
+      name: "light-mode"
+
+# Modal open/close
+- name: "Settings modal opens"
+  steps:
+    - action: navigate
+      url: "/dashboard"
+    - action: click
+      selector: "[aria-label='Settings']"
+    - action: wait_for
+      selector: "[role='dialog']"
+    - action: screenshot
+      name: "settings-modal"
+
+# Form submission
+- name: "Contact form submits"
+  steps:
+    - action: navigate
+      url: "/contact"
+    - action: type
+      selector: "input[name='email']"
+      value: "test@example.com"
+    - action: click
+      selector: "button[type='submit']"
+    - action: wait_for
+      selector: ".success-message"
+\`\`\`
+
+### Step 4: Handle Data-Dependent Pages
+
+**How to identify pages that need fixtures:**
+\`\`\`bash
+# Find components that fetch data
+grep -r "useQuery\|useSWR\|fetch(\|axios\|useEffect.*fetch" src/ --include="*.tsx"
+
+# Find API route parameters (these pages need data)
+grep -r "useParams\|router.query\|\[.*\]" src/pages/ src/app/ --include="*.tsx"
+\`\`\`
+
+If a page has \`:id\`, \`:slug\`, or fetches from \`/api/*\`, it needs fixtures.
+
+**Option A: Pull from staging (recommended for large/dynamic data)**
+\`\`\`yaml
+fixtures:
+  # Pull real data from staging API
+  - pattern: "/api/pr/*"
+    source: "https://staging.example.com/api/pr/sample"
+    headers:
+      Authorization: "Bearer $STAGING_TOKEN"
+
+  # Or from S3 bucket
+  - pattern: "/api/analytics/*"
+    source: "s3://my-fixtures-bucket/analytics-sample.json"
+\`\`\`
+
+**Option B: Commit small fixture files**
+For small, stable data only:
+\`\`\`bash
+mkdir -p fixtures
+cat > fixtures/user.json << 'EOF'
+{"id": 1, "name": "Test User", "email": "test@example.com"}
+EOF
+\`\`\`
+
+\`\`\`yaml
+fixtures:
+  - pattern: "/api/user"
+    source: "file://fixtures/user.json"
+\`\`\`
+
+**When to use each:**
+| Data Type | Use |
+|-----------|-----|
+| User profiles, settings | Local file (small, stable) |
+| PR data, analytics, lists | Staging API or S3 (large, dynamic) |
+| Auth tokens, sessions | Passthrough or mock inline |
+
+**Option B: Use demo/example routes**
+\`\`\`bash
+# Look for demo or example routes in the router
+grep -r "demo\|example\|sample" src/ --include="*.tsx"
+\`\`\`
+
+**Option C: Use real test data**
+If the app has seeded test data, use those identifiers:
+\`\`\`yaml
+- name: "PR review page loads"
+  steps:
+    - action: navigate
+      url: "/review/test-org/test-repo/1"  # Known test PR
+    - action: wait_for
+      selector: "[data-testid='pr-diff']"
+\`\`\`
+
+### Step 5: Add Backend API Flows (if applicable)
+
+If the app has API endpoints, test them directly:
+
+\`\`\`bash
+# Find API routes
+ls src/api/ app/api/ pages/api/ 2>/dev/null
+grep -r "app.get\|app.post\|router.get" --include="*.ts"
+\`\`\`
+
+**Example API flows:**
+\`\`\`yaml
+flows:
+  - name: "API health check"
+    description: "Verify API server responds"
+    trigger: always
+    steps:
+      - action: http_request
+        method: GET
+        url: "http://localhost:3001/health"
+      - action: assert_status
+        status: 200
+
+  - name: "API returns valid data"
+    trigger: on_change
+    watch_patterns:
+      - "src/api/**"
+    steps:
+      - action: http_request
+        method: GET
+        url: "http://localhost:3001/api/users"
+      - action: assert_status
+        status: 200
+\`\`\`
+
+### Step 6: Verify Your Flows
+
+After adding flows, validate the config:
+\`\`\`bash
+# Check YAML syntax
+npx @haystackeditor/cli validate
+
+# Or manually check
+cat .haystack.yml | head -50
+\`\`\`
+
+### ✅ Final Checklist (ALL required):
+
+Before you finish, verify:
+
+1. [ ] **Page flows**: Every route has a flow
+2. [ ] **Specific selectors**: All use \`[data-testid='x']\` or \`.class-name\`, NOT \`#root\`/\`div\`/\`h1\`
+3. [ ] **Interactive flows**: At least 3 flows with \`click\` or \`type\` actions
+4. [ ] **Fixtures configured**: Data-dependent pages have fixtures (staging URL preferred, or local JSON)
+5. [ ] **Backend API flows**: API endpoints have \`http_request\` flows (if app has backend)
+6. [ ] **Watch patterns**: Each \`watch_patterns\` matches component file paths
+
+⚠️ **If you have 0 interactive flows or 0 fixtures for data pages, you are not done.**
 `;
 export async function createSkillFile() {
     const skillDir = path.join(process.cwd(), '.agents', 'skills');
@@ -247,3 +654,16 @@ export async function createSkillFile() {
     await fs.writeFile(skillPath, SKILL_CONTENT, 'utf-8');
     return skillPath;
 }
+/**
+ * Create the .claude/commands/haystack.md file for Claude Code slash command
+ * Users can invoke with /haystack to start the setup wizard
+ */
+export async function createClaudeCommand() {
+    const commandDir = path.join(process.cwd(), '.claude', 'commands');
+    const commandPath = path.join(commandDir, 'haystack.md');
+    // Create directory if needed
+    await fs.mkdir(commandDir, { recursive: true });
+    // Write command file
+    await fs.writeFile(commandPath, CLAUDE_COMMAND_CONTENT, 'utf-8');
+    return commandPath;
+}

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Set up Haystack verification for your project",
   "type": "module",
   "bin": {
     "haystack": "./dist/index.js"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
   "keywords": [
     "haystack",
     "verification",
@@ -42,10 +48,5 @@
   ],
   "engines": {
     "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js"
   }
-}
+}