@popoverai/dotrequirements 0.21.1 → 0.23.0

package/README.md

@@ -182,18 +182,21 @@ dotreq browsertest LOGIN-1 --json
 
 **Configuration required:**
 
-Browser testing requires credentials in `project-settings.json`:
+Browser testing needs a Stagehand model and the API key for that model's provider in `project-settings.json`:
 
 ```json
 {
   "defaultURL": "https://your-app.com",
   "browserTest": {
-    "geminiApiKey": "your-gemini-api-key"
+    "modelName": "gateway/anthropic/claude-haiku-4-5",
+    "modelApiKey": "your-api-key"
   }
 }
 ```
 
-Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`.
+Pick any Stagehand-supported model. Example values: `gateway/anthropic/claude-haiku-4-5` (Vercel AI Gateway key), `google/gemini-3-flash-preview` (Gemini key).
+
+Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`. Setting both Browserbase fields switches runs from LOCAL (spawns Playwright on your machine) to BROWSERBASE (managed cloud browsers).
 
 ### `dotreq mcp-setup`
 
@@ -276,6 +279,14 @@ await finalize({ showTestedList: true }); // Include tested requirements
 await finalize({ showSummary: false, showUntestedList: false }); // Quiet mode
 ```
 
+**Attribution:** tag cloud coverage rows with the name of the framework that produced them:
+
+```typescript
+await finalize({ context: 'Vitest' });
+```
+
+The Coverage tab uses this label to show which tool produced each result. Any string works — useful when you have multiple test suites (`"Vitest — unit"`, `"Vitest — integration"`).
+
 By default, only untested requirements are shown. See the [test harness docs](https://docs.dotrequirements.io/tools/test-harness) for all options.
 
 ### Setup with Jest

package/dist/cli.js

@@ -78,7 +78,6 @@ program
     .command('browsertest <requirement-key> [url]')
     .description('Run browser-based acceptance test for a requirement')
     .option('--json', 'Output results as JSON')
-    .option('--useAgent', 'Encourage Claude to use the Agent tool for multi-step tasks')
     .action(wrapCommand(browserTestCommand));
 program
     .command('prepare')
@@ -90,6 +89,7 @@ program
     .description('Aggregate test tracking data and generate coverage report')
     .option('--push', 'Push coverage to DotRequirements Cloud')
     .option('-q, --quiet', 'Output only coverage percentage (for scripting)')
+    .option('--context <label>', 'Attribution label identifying the reporter (e.g. "Vitest", "pytest")')
     .action(wrapCommand(finalizeCommand));
 program
     .command('report')

package/dist/commands/browsertest.d.ts

@@ -1,6 +1,5 @@
 interface BrowserTestOptions {
     json?: boolean;
-    useAgent?: boolean;
 }
 export declare function browserTestCommand(requirementKey: string, url: string | undefined, options: BrowserTestOptions): Promise<void>;
 export {};

package/dist/commands/browsertest.js

@@ -44,11 +44,22 @@ export async function browserTestCommand(requirementKey, url, options) {
         console.log('Either provide a URL argument or add "defaultURL" to .requirements/project-settings.json');
         process.exit(1);
     }
-    // 3. Check for required credentials
+    // 3. Resolve model config
+    const modelName = settings?.browserTest?.modelName;
+    const modelApiKey = settings?.browserTest?.modelApiKey;
     const geminiApiKey = settings?.browserTest?.geminiApiKey;
-    if (!geminiApiKey) {
-        console.error('Error: browserTest.geminiApiKey not found in project-settings.json.');
-        console.log('Add "browserTest": { "geminiApiKey": "..." } to .requirements/project-settings.json');
+    if (!modelName && !modelApiKey && !geminiApiKey) {
+        console.error('Error: no browser-test model configured in project-settings.json.');
+        console.log('Add a block like:\n' +
+            '  "browserTest": {\n' +
+            '    "modelName": "gateway/anthropic/claude-haiku-4-5",\n' +
+            '    "modelApiKey": "..."\n' +
+            '  }\n' +
+            'to .requirements/project-settings.json. See the docs for supported models.');
+        process.exit(1);
+    }
+    if ((modelName && !modelApiKey) || (modelApiKey && !modelName)) {
+        console.error('Error: browserTest.modelName and browserTest.modelApiKey must be set together.');
         process.exit(1);
     }
     // 4. Load requirements
@@ -67,7 +78,13 @@ export async function browserTestCommand(requirementKey, url, options) {
     const assertions = requirementTree.map((req) => formatRequirement(req));
     // 7. Build environment with injected secrets
     const env = { ...process.env };
-    env.GEMINI_API_KEY = geminiApiKey;
+    // env var keeps the key out of process listings (not a CLI flag)
+    if (modelApiKey) {
+        env.MODEL_API_KEY = modelApiKey;
+    }
+    else if (geminiApiKey) {
+        env.GEMINI_API_KEY = geminiApiKey;
+    }
     if (settings?.browserTest?.vercelBypassSecret) {
         env.VERCEL_AUTOMATION_BYPASS_SECRET = settings.browserTest.vercelBypassSecret;
     }
@@ -82,7 +99,8 @@ export async function browserTestCommand(requirementKey, url, options) {
         console.log(`Testing ${requirementKey} against ${targetURL}...\n`);
     }
     try {
-        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', ...(options.useAgent ? ['--useAgent'] : []), targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
+        const modelFlags = modelName ? ['--modelName', modelName] : [];
+        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', ...modelFlags, targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
         // 9. Parse results
         let results;
         try {

package/dist/commands/finalize.d.ts

@@ -1,6 +1,7 @@
 interface FinalizeOptions {
     push?: boolean;
     quiet?: boolean;
+    context?: string;
 }
 export declare function finalizeCommand(options: FinalizeOptions): Promise<void>;
 export {};

package/dist/commands/finalize.js

@@ -31,6 +31,7 @@ export async function finalizeCommand(options) {
         showTestedList: true,
         showUntestedList: true,
         showCloudStatus: !options.quiet,
+        context: options.context,
     });
     if (options.quiet) {
         // In quiet mode, just output the coverage percent for scripting

package/dist/harness/cache.d.ts

@@ -39,17 +39,22 @@ export interface LookupCache {
 /**
  * Structure of the coverage.json cache (for cloud deduplication)
  */
+/** Attribution tuple used for debounce keying (COVERAGE-DEBOUNCE-2). */
+export interface CoverageTuple {
+    requirementKey: string;
+    context?: string;
+    branch?: string;
+}
+export interface CoverageCacheEntry {
+    testRunId: string;
+    timestamp: number;
+    tuples: CoverageTuple[];
+    /** Legacy field retained for backward-compat reads of pre-attribution caches. */
+    requirementKeys?: string[];
+}
 export interface CoverageCache {
-    current: {
-        testRunId: string;
-        timestamp: number;
-        requirementKeys: string[];
-    } | null;
-    previous: {
-        testRunId: string;
-        timestamp: number;
-        requirementKeys: string[];
-    } | null;
+    current: CoverageCacheEntry | null;
+    previous: CoverageCacheEntry | null;
 }
 /**
  * Find the nearest .requirements directory by walking up from startDir
@@ -123,16 +128,16 @@ export declare function readTrackingEntries(requirementsDir: string): TrackingEn
  * Delete the tracking file after finalize
  */
 export declare function deleteTrackingFile(requirementsDir: string): void;
-/**
- * Read the coverage cache for cloud deduplication
- */
 export declare function readCoverageCache(requirementsDir: string): CoverageCache;
 /**
- * Update the coverage cache after reporting
+ * Update the coverage cache after reporting. Accepts either attribution tuples
+ * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
  */
-export declare function updateCoverageCache(requirementsDir: string, testRunId: string, requirementKeys: string[]): void;
+export declare function updateCoverageCache(requirementsDir: string, testRunId: string, tuples: CoverageTuple[] | string[]): void;
+export declare const COVERAGE_DEBOUNCE_WINDOW_MS: number;
 /**
- * Check if a requirement needs reporting based on coverage cache
+ * Check if an attribution tuple needs reporting based on the coverage cache.
+ * Returns true if no matching tuple was reported within the debounce window.
  */
-export declare function needsReporting(requirementKey: string, cache: CoverageCache): boolean;
+export declare function needsReporting(tupleOrKey: CoverageTuple | string, cache: CoverageCache): boolean;
 //# sourceMappingURL=cache.d.ts.map

package/dist/harness/cache.js

@@ -288,6 +288,30 @@ export function deleteTrackingFile(requirementsDir) {
 /**
  * Read the coverage cache for cloud deduplication
  */
+/**
+ * Normalize a cache entry read from disk. Migrates legacy `requirementKeys`
+ * arrays into the tuple shape (context/branch undefined) so downstream code
+ * can treat both shapes uniformly.
+ */
+function normalizeEntry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    if (Array.isArray(raw.tuples)) {
+        return {
+            testRunId: raw.testRunId,
+            timestamp: raw.timestamp,
+            tuples: raw.tuples,
+        };
+    }
+    if (Array.isArray(raw.requirementKeys)) {
+        return {
+            testRunId: raw.testRunId,
+            timestamp: raw.timestamp,
+            tuples: raw.requirementKeys.map((requirementKey) => ({ requirementKey })),
+        };
+    }
+    return null;
+}
 export function readCoverageCache(requirementsDir) {
     const cacheDir = getCacheDir(requirementsDir);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
@@ -296,45 +320,58 @@ export function readCoverageCache(requirementsDir) {
     }
     try {
         const content = fs.readFileSync(coveragePath, 'utf-8');
-        return JSON.parse(content);
+        const raw = JSON.parse(content);
+        return {
+            current: normalizeEntry(raw?.current),
+            previous: normalizeEntry(raw?.previous),
+        };
     }
     catch {
         return { current: null, previous: null };
     }
 }
 /**
- * Update the coverage cache after reporting
+ * Update the coverage cache after reporting. Accepts either attribution tuples
+ * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
  */
-export function updateCoverageCache(requirementsDir, testRunId, requirementKeys) {
+export function updateCoverageCache(requirementsDir, testRunId, tuples) {
     const cacheDir = getCacheDir(requirementsDir, true);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
+    const normalized = tuples.map((t) => typeof t === 'string' ? { requirementKey: t } : t);
     const existing = readCoverageCache(requirementsDir);
     const newCache = {
         current: {
             testRunId,
             timestamp: Date.now(),
-            requirementKeys,
+            tuples: normalized,
         },
         previous: existing.current,
     };
     fs.writeFileSync(coveragePath, JSON.stringify(newCache, null, 2));
 }
+export const COVERAGE_DEBOUNCE_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours — must match server-side in testCoverage/mutations.ts
+function tuplesMatch(a, b) {
+    return (a.requirementKey === b.requirementKey &&
+        a.context === b.context &&
+        a.branch === b.branch);
+}
 /**
- * Check if a requirement needs reporting based on coverage cache
+ * Check if an attribution tuple needs reporting based on the coverage cache.
+ * Returns true if no matching tuple was reported within the debounce window.
  */
-export function needsReporting(requirementKey, cache) {
-    const STALENESS_THRESHOLD_MS = 4 * 60 * 60 * 1000; // 4 hours
+export function needsReporting(tupleOrKey, cache) {
+    const tuple = typeof tupleOrKey === 'string' ? { requirementKey: tupleOrKey } : tupleOrKey;
     // If no current run, everything needs reporting
     if (!cache.current) {
         return true;
     }
-    // If requirement wasn't in current run, it needs reporting
-    if (!cache.current.requirementKeys.includes(requirementKey)) {
+    // If the tuple wasn't in the current cached run, it needs reporting
+    if (!cache.current.tuples.some((t) => tuplesMatch(t, tuple))) {
         return true;
     }
     // If current run is stale (>4 hours old), needs reporting
     const age = Date.now() - cache.current.timestamp;
-    if (age > STALENESS_THRESHOLD_MS) {
+    if (age > COVERAGE_DEBOUNCE_WINDOW_MS) {
         return true;
     }
     // Otherwise, skip reporting (already reported recently)

package/dist/harness/finalize.d.ts

@@ -24,6 +24,11 @@ export interface FinalizeOptions {
     showUntestedList?: boolean;
     /** Whether to show cloud reporting status messages (defaults to true) */
     showCloudStatus?: boolean;
+    /**
+     * Attribution label identifying the reporter (e.g. "Vitest", "Jest", "pytest").
+     * When omitted, rows are recorded with context absent per COVERAGE-CONTEXT-1.2.
+     */
+    context?: string;
 }
 export interface FinalizeResult {
     /** Number of unique requirements exercised */

package/dist/harness/finalize.js

@@ -10,6 +10,7 @@
  * Implements: HARNESS-FINALIZE-1, HARNESS-FINALIZE-2, HARNESS-FINALIZE-3, HARNESS-FINALIZE-4
  */
 import { execSync } from 'child_process';
+import { randomUUID } from 'crypto';
 import { findRequirementsDir, findProjectRoot, getTestRunId, cleanupTestRunId, readTrackingEntries, deleteTrackingFile, readLookupCache, readCoverageCache, updateCoverageCache, needsReporting, } from './cache.js';
 import { getProjectInfo } from '../utils/project-settings.js';
 /**
@@ -40,6 +41,26 @@ function getCurrentBranch(cwd) {
         return 'unknown';
     }
 }
+/**
+ * Return the git-blame author email for a specific file:line, or undefined
+ * if unavailable (not a git repo, file untracked, git unavailable, etc.).
+ *
+ * COVERAGE-CONTEXT-2: "last reported by" attribution.
+ */
+function getLineAuthor(cwd, file, line) {
+    try {
+        const output = execSync(`git blame -L ${line},${line} --porcelain -- "${file}"`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        const match = output.match(/^author-mail\s+<([^>]+)>/m);
+        return match?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Print local coverage report to console
  *
@@ -112,7 +133,7 @@ const CONVEX_URL = 'https://data.dotrequirements.io';
  * HARNESS-FINALIZE-2: Cloud reporting with error tolerance
  * HARNESS-FINALIZE-3: Coverage records include requirement, file, line, branch
  */
-async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus) {
+async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context) {
     try {
         // Get project info from .requirements/project-settings.json
         const projectInfo = getProjectInfo(projectRoot);
@@ -125,24 +146,34 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
         }
         const { projectId, projectSecret } = projectInfo.credentials;
         const requirementsDir = findRequirementsDir(projectRoot);
-        // Get all tracked requirement keys
+        const branch = getCurrentBranch(projectRoot);
+        // Build the full set of tuples for this run, one per tracked requirement
         const requirementKeys = Array.from(aggregated.keys());
-        // Use coverage cache for deduplication
+        const allTuples = requirementKeys.map((key) => ({
+            requirementKey: key,
+            context,
+            branch,
+        }));
+        // Local debounce (COVERAGE-DEBOUNCE-1): only report tuples not recently cached.
+        // Server-side debounce is a backstop (COVERAGE-DEBOUNCE-4) — this layer just
+        // prevents unnecessary HTTP calls.
         const coverageCache = readCoverageCache(requirementsDir);
-        const keysToReport = requirementKeys.filter(key => needsReporting(key, coverageCache));
-        if (keysToReport.length === 0) {
+        const tuplesToReport = allTuples.filter((tuple) => needsReporting(tuple, coverageCache));
+        if (tuplesToReport.length === 0) {
             if (showCloudStatus) {
                 console.log('\n✓ Coverage unchanged since last run (skipping cloud report)');
             }
-            // Still update the cache
-            updateCoverageCache(requirementsDir, testRunId, requirementKeys);
+            // Still update the cache so the window continues tracking
+            updateCoverageCache(requirementsDir, testRunId, allTuples);
             return { sent: false, count: 0 };
         }
-        const branch = getCurrentBranch(projectRoot);
+        // Deterministic runId for this finalize invocation (COVERAGE-CONTEXT-4)
+        const runId = randomUUID();
+        // Cache git-blame lookups per file:line to avoid redundant subprocess spawns
+        const userCache = new Map();
         // Build coverage payload
-        // HARNESS-FINALIZE-3: Include requirement path, test file, line, branch
-        const coverage = keysToReport.map(key => {
-            const entries = aggregated.get(key);
+        const coverage = tuplesToReport.map((tuple) => {
+            const entries = aggregated.get(tuple.requirementKey);
             // Use the first access location
             const firstEntry = entries[0];
             const location = firstEntry.callerLocation;
@@ -159,10 +190,23 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                     testFile = location;
                 }
             }
+            // COVERAGE-CONTEXT-2: git blame on the requirement() call line
+            let user;
+            if (testFile && testLine !== undefined) {
+                const cacheKey = `${testFile}:${testLine}`;
+                if (userCache.has(cacheKey)) {
+                    user = userCache.get(cacheKey);
+                }
+                else {
+                    user = getLineAuthor(projectRoot, testFile, testLine);
+                    userCache.set(cacheKey, user);
+                }
+            }
             return {
-                requirementKey: key,
+                requirementKey: tuple.requirementKey,
                 testFile,
                 testLine,
+                user,
             };
         });
         // Send to Convex
@@ -185,6 +229,8 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                         slug: projectId,
                     },
                     branch,
+                    context,
+                    runId,
                     coverage,
                 },
                 format: 'json',
@@ -218,11 +264,11 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
             }
         }
         if (showCloudStatus) {
-            console.log(`\n✓ Reported ${keysToReport.length} requirement(s) to cloud (branch: ${branch})`);
+            console.log(`\n✓ Reported ${tuplesToReport.length} requirement(s) to cloud (branch: ${branch})`);
         }
-        // Update coverage cache
-        updateCoverageCache(requirementsDir, testRunId, requirementKeys);
-        return { sent: true, count: keysToReport.length };
+        // Update coverage cache with the full tuple set (includes those not reported this run)
+        updateCoverageCache(requirementsDir, testRunId, allTuples);
+        return { sent: true, count: tuplesToReport.length };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -244,7 +290,7 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
  * HARNESS-FINALIZE-4: Finalize cleans up after itself
  */
 export async function finalize(options = {}) {
-    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, cleanup: shouldCleanup = true, showSummary = true, showTestedList = false, showUntestedList = true, showCloudStatus = true, } = options;
+    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, cleanup: shouldCleanup = true, showSummary = true, showTestedList = false, showUntestedList = true, showCloudStatus = true, context, } = options;
     // Priority 1: Use environment variable (cross-process persistence from globalSetup)
     let projectRoot = process.env.DOTREQUIREMENTS_PROJECT_ROOT || null;
     // Priority 2: Find from cwd
@@ -309,7 +355,7 @@ export async function finalize(options = {}) {
     // HARNESS-FINALIZE-2, HARNESS-FINALIZE-3: Report to cloud
     let cloudResult = { sent: false, count: 0 };
     if (shouldReportToCloud) {
-        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus);
+        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context);
     }
     // HARNESS-FINALIZE-4: Clean up tracking data
     if (shouldCleanup && !cloudResult.error) {

package/dist/mcp/index.js

@@ -33,17 +33,16 @@ const PROJECT_PATHS = getProjectPathsFromEnv();
 // Parse --auth-from-env flag for CI/CD environments
 // When set, credentials are read from DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET env vars
 const USE_ENV_AUTH = process.argv.includes('--auth-from-env');
-// Cache for loaded requirements (refreshed on each tool call for now)
-let cachedRequirements = new Map();
 let cachedDiscoveryResult = null;
+// Requirements are loaded fresh on every call. A long-lived in-memory cache
+// silently served stale data when .requirements/*.md files were created or
+// edited mid-session, which is the primary authoring workflow the MCP server
+// is meant to support. If this ever becomes a measured performance concern,
+// invalidate via directory mtime rather than reintroducing a lifetime cache.
 async function getRequirements(projectId) {
     const project = await getProjectFromDiscovery(projectId);
-    const cacheKey = project.projectId;
-    if (!cachedRequirements.has(cacheKey)) {
-        const { flattened } = await loadAllRequirements(project.path);
-        cachedRequirements.set(cacheKey, flattened);
-    }
-    return cachedRequirements.get(cacheKey);
+    const { flattened } = await loadAllRequirements(project.path);
+    return flattened;
 }
 async function getProjectFromDiscovery(projectId) {
     const { isConfiguredProject } = await import('../utils/project-discovery.js');
@@ -92,10 +91,9 @@ async function getProjectFromDiscovery(projectId) {
     }
     return resolveProject(cachedDiscoveryResult, projectId);
 }
-// Invalidate cache (call before operations that should see fresh data)
-// Exported for testing
+// Invalidate the project-discovery cache. Requirements are no longer cached,
+// so this only resets discovery state. Exported for testing.
 export function invalidateCache() {
-    cachedRequirements.clear();
     cachedDiscoveryResult = null;
 }
 // Tool definitions

package/dist/schema/browser.d.ts

@@ -9,4 +9,6 @@ export { DEFAULT_DELIMITER, buildRequirementsMarkdown, buildRequirementMarkdown,
 export type { ConvexRequirement, } from './conversions.js';
 export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
 export { DELIMITER_PATTERN, parseCriterionLine, parseRootLine, parseRequirementBlock, extractRequirementBlocks, parseRequirementBlocksFromMarkdown, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser-core.js';
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
+export type { Scenario, ScenarioStep, ScenarioAssertionSource, BuildScenarioOptions, } from './scenario.js';
 //# sourceMappingURL=browser.d.ts.map

package/dist/schema/browser.js

@@ -21,4 +21,6 @@ export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequi
 export { DELIMITER_PATTERN, parseCriterionLine, parseRootLine, parseRequirementBlock, extractRequirementBlocks, parseRequirementBlocksFromMarkdown, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser-core.js';
 // NOTE: parser.ts and resolver.ts are excluded because they use Node.js 'fs' module.
 // Use parser-core.ts functions above for browser/Convex environments.
+// Scenario building (pure TypeScript - browser-safe, used by Convex Node actions)
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
 //# sourceMappingURL=browser.js.map

package/dist/schema/index.d.ts

@@ -11,4 +11,6 @@ export { buildRequirementsMarkdown, buildRequirementMarkdown, buildRequirementsF
 export { parseRequirementPath, parsePathSegment, findChildrenByLabel, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, getAllLabelPaths, checkPathAmbiguity, } from './resolver.js';
 export type { ConvexRequirement, } from './conversions.js';
 export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
+export type { Scenario, ScenarioStep, ScenarioAssertionSource, BuildScenarioOptions, } from './scenario.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/schema/index.js

@@ -21,4 +21,6 @@ export { buildRequirementsMarkdown, buildRequirementMarkdown, buildRequirementsF
 // Path resolution
 export { parseRequirementPath, parsePathSegment, findChildrenByLabel, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, getAllLabelPaths, checkPathAmbiguity, } from './resolver.js';
 export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
+// Scenario building (for browser-automation / runScenario)
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
 //# sourceMappingURL=index.js.map

package/dist/schema/scenario.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Scenario builder — turns a requirement tree into a browser-automation Scenario.
+ *
+ * Used by both the CLI (via `dotreq browsertest`) and the Convex Node action
+ * (`testCoverage/browserRun:run`) so the two paths produce identical scenarios
+ * for the same input.
+ *
+ * Naive passthrough: every requirement node with non-empty content becomes
+ * exactly one assertion keyed by its numeric-path id (e.g. "LOGIN-1" for the
+ * root, "LOGIN-1.0" for the first criterion). No arrange/act steps are
+ * emitted; Stagehand's hybrid agent is expected to infer setup from the
+ * assertion list. See BROWSER-RUN-3 in
+ * .requirements/testing-tab-browser-run.requirements.md.
+ *
+ * Types here are defined locally to avoid adding `@popoverai/browser-automation`
+ * as a runtime dependency of this package. They are structurally compatible
+ * with browser-automation's exported `Scenario` / `Step` types and can be
+ * passed directly to `runScenario`.
+ */
+import type { RequirementNode } from "./schemas.js";
+/**
+ * One step in a scenario. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Step` type.
+ */
+export interface ScenarioStep {
+    step: "arrange" | "act" | "assert";
+    description: string;
+    url?: string;
+    key?: string;
+}
+/**
+ * One entry in the `Scenario.variables` map. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Variable` type — the `value` is what
+ * gets substituted into the scenario, and the optional `description` gives
+ * the agent extra context about what the substitution represents.
+ */
+export interface ScenarioVariable {
+    value: string;
+    description?: string;
+}
+export type ScenarioVariables = Record<string, ScenarioVariable>;
+/**
+ * A scenario passed to `runScenario`. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Scenario` type.
+ */
+export interface Scenario {
+    baseUrl: string;
+    steps: ScenarioStep[];
+    variables?: ScenarioVariables;
+}
+/**
+ * One requirement contributing an assertion to a scenario. The minimum shape
+ * the builder needs so callers sourcing requirements from different backends
+ * (Markdown files via `RequirementNode`, Convex rows, etc.) can all use it.
+ */
+export interface ScenarioAssertionSource {
+    /** Full requirement key including path, e.g. "LOGIN-1" or "LOGIN-1.0.1". */
+    id: string;
+    /** Requirement text; becomes the assertion's `description`. */
+    content: string;
+}
+export interface BuildScenarioOptions {
+    /**
+     * The requirements contributing assertions, in the order they should be
+     * evaluated. Every entry with non-empty `content` becomes one `assert` step.
+     */
+    assertions: ScenarioAssertionSource[];
+    /** Target URL the scenario runs against; becomes `Scenario.baseUrl`. */
+    baseUrl: string;
+    /**
+     * Optional Stagehand variable substitutions. Used to inject secrets
+     * (test-user credentials, bypass tokens) into assertion descriptions
+     * without exposing them to the language model in plaintext.
+     */
+    variables?: Record<string, string>;
+}
+/**
+ * Build a `Scenario` from a list of requirement assertion sources.
+ *
+ * Throws if the resulting scenario would have zero assertions
+ * (browser-automation rejects scenarios with no asserts).
+ */
+export declare function buildScenarioFromRequirements(opts: BuildScenarioOptions): Scenario;
+/**
+ * Convenience wrapper for callers that have a `RequirementNode` tree (root
+ * plus nested children). Flattens the tree to the order produced by
+ * `flattenRequirementTree` (pre-order: root first, then each subtree), then
+ * delegates to `buildScenarioFromRequirements`.
+ */
+export declare function requirementTreeToScenario(root: RequirementNode, opts: Omit<BuildScenarioOptions, "assertions">): Scenario;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/schema/scenario.js

@@ -0,0 +1,82 @@
+/**
+ * Scenario builder — turns a requirement tree into a browser-automation Scenario.
+ *
+ * Used by both the CLI (via `dotreq browsertest`) and the Convex Node action
+ * (`testCoverage/browserRun:run`) so the two paths produce identical scenarios
+ * for the same input.
+ *
+ * Naive passthrough: every requirement node with non-empty content becomes
+ * exactly one assertion keyed by its numeric-path id (e.g. "LOGIN-1" for the
+ * root, "LOGIN-1.0" for the first criterion). No arrange/act steps are
+ * emitted; Stagehand's hybrid agent is expected to infer setup from the
+ * assertion list. See BROWSER-RUN-3 in
+ * .requirements/testing-tab-browser-run.requirements.md.
+ *
+ * Types here are defined locally to avoid adding `@popoverai/browser-automation`
+ * as a runtime dependency of this package. They are structurally compatible
+ * with browser-automation's exported `Scenario` / `Step` types and can be
+ * passed directly to `runScenario`.
+ */
+/**
+ * Pre-order flatten: root first, then each subtree's nodes in order.
+ * Inlined here (rather than imported from `parser.ts`) so this module stays
+ * free of Node-only dependencies and can be re-exported from the browser
+ * entry point.
+ */
+function flattenTree(node) {
+    const result = [node];
+    for (const child of node.children) {
+        result.push(...flattenTree(child));
+    }
+    return result;
+}
+/**
+ * Build a `Scenario` from a list of requirement assertion sources.
+ *
+ * Throws if the resulting scenario would have zero assertions
+ * (browser-automation rejects scenarios with no asserts).
+ */
+export function buildScenarioFromRequirements(opts) {
+    const { assertions, baseUrl, variables } = opts;
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        throw new Error("buildScenarioFromRequirements: baseUrl is required");
+    }
+    const steps = [];
+    for (const source of assertions) {
+        const description = source.content.trim();
+        if (description.length === 0)
+            continue;
+        steps.push({
+            step: "assert",
+            description,
+            key: source.id,
+        });
+    }
+    if (steps.length === 0) {
+        throw new Error("buildScenarioFromRequirements: requirement tree has no nodes with content; cannot build a scenario");
+    }
+    const scenario = { baseUrl, steps };
+    if (variables && Object.keys(variables).length > 0) {
+        // Callers pass a flat Record<string, string> for ergonomics; wrap each
+        // entry as `{ value }` so the scenario matches runScenario's expected
+        // Variables shape. Callers with richer values can set variables on the
+        // returned scenario directly before invocation.
+        scenario.variables = Object.fromEntries(Object.entries(variables).map(([key, value]) => [key, { value }]));
+    }
+    return scenario;
+}
+/**
+ * Convenience wrapper for callers that have a `RequirementNode` tree (root
+ * plus nested children). Flattens the tree to the order produced by
+ * `flattenRequirementTree` (pre-order: root first, then each subtree), then
+ * delegates to `buildScenarioFromRequirements`.
+ */
+export function requirementTreeToScenario(root, opts) {
+    const flat = flattenTree(root);
+    const assertions = flat.map((node) => ({
+        id: node.id,
+        content: node.content,
+    }));
+    return buildScenarioFromRequirements({ ...opts, assertions });
+}
+//# sourceMappingURL=scenario.js.map

package/dist/utils/project-settings.d.ts

@@ -1,7 +1,8 @@
-/**
- * Browser test configuration
- */
+/** Browser test configuration. */
 export interface BrowserTestSettings {
+    modelName?: string;
+    modelApiKey?: string;
+    /** @deprecated Backward-compat fallback; use modelName + modelApiKey instead. */
     geminiApiKey?: string;
     vercelBypassSecret?: string;
     browserbaseApiKey?: string;

package/dist/utils/project-settings.js

@@ -80,6 +80,12 @@ export function readProjectSettings(projectRoot) {
     if (typeof record.browserTest === 'object' && record.browserTest !== null) {
         const bt = record.browserTest;
         settings.browserTest = {};
+        if (typeof bt.modelName === 'string') {
+            settings.browserTest.modelName = bt.modelName;
+        }
+        if (typeof bt.modelApiKey === 'string') {
+            settings.browserTest.modelApiKey = bt.modelApiKey;
+        }
         if (typeof bt.geminiApiKey === 'string') {
             settings.browserTest.geminiApiKey = bt.geminiApiKey;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {