@codeyam/codeyam-cli 0.1.0-staging.76566f9 → 0.1.0-staging.79ef713

package/analyzer-template/packages/github/dist/types/src/types/ScopeAnalysis.d.ts

@@ -4,8 +4,13 @@ export interface ScopeAnalysis {
     isolatedStructure: {
         [key: string]: string;
     };
+    /**
+     * Maps variable names to their equivalent paths.
+     * Supports multiple equivalencies per key (e.g., for OR expressions like `x = a || b`
+     * where x is equivalent to both a and b).
+     */
     isolatedEquivalentVariables: {
-        [key: string]: string;
+        [key: string]: string | string[];
     };
     llmCalls: LlmCall[];
     environmentVariables: string[];

package/analyzer-template/packages/github/dist/types/src/types/ScopeAnalysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScopeAnalysis.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/ScopeAnalysis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC7C,2BAA2B,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvD,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC"}
+{"version":3,"file":"ScopeAnalysis.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/ScopeAnalysis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;OAIG;IACH,2BAA2B,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;KAAE,CAAC;IAClE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC"}

package/analyzer-template/packages/github/dist/types/src/types/StatementInfo.d.ts

@@ -5,6 +5,8 @@ export interface StatementInfo {
     name?: string;
     childBoundaries: {
         name?: string;
+        /** The synthetic scope name (e.g., 'cyScope1') if JSX was extracted */
+        syntheticName?: string;
         start: number;
         end: number;
     }[];

package/analyzer-template/packages/github/dist/types/src/types/StatementInfo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StatementInfo.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/StatementInfo.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,EAAE,CAAC;CACL"}
+{"version":3,"file":"StatementInfo.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/StatementInfo.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,uEAAuE;QACvE,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,EAAE,CAAC;CACL"}

package/analyzer-template/packages/github/dist/utils/src/lib/safeFileName.d.ts

@@ -1,2 +1,10 @@
-export default function safeFileName(name: string): string;
+export interface SafeFileNameOptions {
+    /**
+     * Maximum length of the resulting filename.
+     * If the name exceeds this length, it will be truncated and a hash suffix added.
+     * macOS has a 255 byte filename limit. Default is undefined (no limit).
+     */
+    maxLength?: number;
+}
+export default function safeFileName(name: string, options?: SafeFileNameOptions): string;
 //# sourceMappingURL=safeFileName.d.ts.map

package/analyzer-template/packages/github/dist/utils/src/lib/safeFileName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safeFileName.d.ts","sourceRoot":"","sources":["../../../../../utils/src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,IAAI,EAAE,MAAM,UAShD"}
+{"version":3,"file":"safeFileName.d.ts","sourceRoot":"","sources":["../../../../../utils/src/lib/safeFileName.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA4BR"}

package/analyzer-template/packages/github/dist/utils/src/lib/safeFileName.js

@@ -1,10 +1,36 @@
-export default function safeFileName(name) {
+/**
+ * Simple hash function for generating unique suffixes.
+ * Uses djb2 algorithm - fast and produces good distribution.
+ * Not cryptographically secure, but sufficient for filename uniqueness.
+ */
+function simpleHash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = (hash * 33) ^ str.charCodeAt(i);
+    }
+    // Convert to unsigned 32-bit and then to hex
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+export default function safeFileName(name, options = {}) {
+    const { maxLength } = options;
     // Replace unsafe characters with underscores, preserving original casing
     // Then trim leading/trailing underscores to avoid malformed route segments
-    const safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+    let safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
     if (!safeSlug)
         return '';
     // Ensure it starts with a capital letter (for consistency with Remix routes)
-    return safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+    safeSlug = safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+    // If maxLength is specified and the slug exceeds it, truncate and add a hash
+    if (maxLength && safeSlug.length > maxLength) {
+        // Create an 8-character hash of the full name for uniqueness
+        const hash = simpleHash(name);
+        // Reserve space for underscore + hash (9 chars total)
+        const truncateLength = maxLength - 9;
+        const truncated = safeSlug.substring(0, truncateLength);
+        // Remove trailing underscore if present (from mid-word truncation)
+        const cleanTruncated = truncated.replace(/_+$/, '');
+        safeSlug = `${cleanTruncated}_${hash}`;
+    }
+    return safeSlug;
 }
 //# sourceMappingURL=safeFileName.js.map

package/analyzer-template/packages/github/dist/utils/src/lib/safeFileName.js.map

@@ -1 +1 @@
-{"version":3,"file":"safeFileName.js","sourceRoot":"","sources":["../../../../../utils/src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,IAAY;IAC/C,yEAAyE;IACzE,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE9E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,6EAA6E;IAC7E,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"safeFileName.js","sourceRoot":"","sources":["../../../../../utils/src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,6CAA6C;IAC7C,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAWD,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,IAAY,EACZ,UAA+B,EAAE;IAEjC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAE9B,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE5E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,6EAA6E;IAC7E,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAElE,6EAA6E;IAC7E,IAAI,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC7C,6DAA6D;QAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAE9B,sDAAsD;QACtD,MAAM,cAAc,GAAG,SAAS,GAAG,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QAExD,mEAAmE;QACnE,MAAM,cAAc,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEpD,QAAQ,GAAG,GAAG,cAAc,IAAI,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/analyzer-template/packages/github/package.json

@@ -16,6 +16,6 @@
     "@octokit/rest": "^22.0.0"
   },
   "devDependencies": {
-    "@octokit/types": "^15.0.0"
+    "@octokit/types": "^16.0.0"
   }
 }

package/analyzer-template/packages/github/src/lib/loadOrCreateCommit.ts

@@ -124,6 +124,20 @@ export default async function loadOrCreateCommit(
     branchFromDb = newBranches[0];
   }
 
+  // If no branch was found or created (e.g., non-HEAD commit where
+  // listBranchesForHeadCommit returns empty), fall back to the primary branch.
+  // Only do this for baseline commits where the assumption is justified.
+  if (!branchFromDb && baseline && project.branches) {
+    branchFromDb = project.branches.find((b) => b.primary) ?? null;
+  }
+
+  if (!branchFromDb) {
+    throw new Error(
+      `Could not determine branch for commit ${commitSha}. ` +
+        `The commit may not be at the HEAD of any branch, and no primary branch was found.`,
+    );
+  }
+
   commit.branch = branchFromDb;
   branchName = branchFromDb.name;
 

package/analyzer-template/packages/github/src/lib/syncPrimaryBranch.ts

@@ -79,6 +79,8 @@ export default async function syncPrimaryBranch({
       const index = projectBranches.findIndex((b) => b.name === branch.name);
       if (index !== -1) {
         projectBranches[index] = branch;
+      } else {
+        projectBranches.push(branch);
       }
     }
 

package/analyzer-template/packages/process/index.ts

@@ -0,0 +1,2 @@
+// Re-export everything from src/index.ts
+export * from './src/index';

package/analyzer-template/packages/process/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@codeyam/process",
+  "version": "1.0.0",
+  "description": "Process management utilities for CodeYam",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {},
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
+}

package/analyzer-template/packages/process/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"]
+}

package/analyzer-template/packages/types/index.ts

@@ -43,18 +43,14 @@ export type {
   DataStructure,
   ConditionalUsage,
   CompoundConditional,
+  ConditionalEffect,
+  JsxRenderingUsage,
 } from './src/types/ScenariosDataStructure';
 export type {
   Scenario,
   ScenarioMetadata,
   PlaywrightInstruction,
   ExecutionResult,
-  ValueOptionRef,
-  KeyAttributeValueReference,
-} from './src/types/Scenario';
-export {
-  isStructuredReference,
-  hasStructuredReferences,
 } from './src/types/Scenario';
 export type { ScenarioData } from './src/types/ScenarioData';
 export type { JsonTypeDefinition } from './src/types/JsonTypeDefinition';
@@ -71,6 +67,7 @@ export type {
   AnalysisMetadata,
   ReadonlyAnalysis,
   SourceLocation,
+  ExecutionFlow,
 } from './src/types/Analysis';
 export { EMPTY_SHA_MARKER } from './src/types/Analysis';
 export type { CodeExplanation } from './src/types/CodeExplanation';

package/analyzer-template/packages/types/src/types/Analysis.ts

@@ -17,7 +17,7 @@ import { DeepReadonly } from './DeepReadonly';
 // used for e.g. analyzedTreeSha for analyses that have no meaningful content to hash
 export const EMPTY_SHA_MARKER = '0000000000000000000000000000000000000000';
 
-/** Represents a location in source code where a key attribute is used */
+/** Represents a location in source code */
 export interface SourceLocation {
   /** Entity name where this usage occurs */
   entityName: string;
@@ -42,6 +42,90 @@ export interface AnalysisError {
   phase: 'capture' | 'analyze';
 }
 
+/** Represents a distinct execution path/outcome in a component with the required attribute values */
+export interface ExecutionFlow {
+  /** Unique identifier for this execution flow */
+  id: string;
+  /** Human-readable name (e.g., "Modal visible", "Loading spinner shown") */
+  name: string;
+  /** Description of what the user sees or what behavior occurs */
+  description: string;
+  /** Whether this is an error/exception scenario */
+  isError?: boolean;
+  /** Attribute values required to produce this outcome */
+  requiredValues: {
+    /** Path to the attribute (e.g., "signature[0].showModal") */
+    attributePath: string;
+    /** The required value (descriptive or literal) */
+    value: string;
+    /** Comparison type for the value */
+    comparison:
+      | 'equals'
+      | 'notEquals'
+      | 'truthy'
+      | 'falsy'
+      | 'length>'
+      | 'length<'
+      | 'exists'
+      | 'not-exists';
+    /** Type of the attribute for mock generation */
+    valueType?:
+      | 'string'
+      | 'number'
+      | 'boolean'
+      | 'object'
+      | 'array'
+      | 'null'
+      | 'function';
+    /**
+     * The full original expression as a semantic constraint for LLM reasoning.
+     * Used when the attributePath is a base that needs additional context to
+     * generate correct mock data.
+     *
+     * Examples:
+     * - `scenarios.filter(s => s.active).length > 1`
+     * - `users.some(u => u.role === 'admin' && u.active)`
+     *
+     * The LLM interprets this constraint to generate data that satisfies it.
+     */
+    constraint?: string;
+  }[];
+  /** Visual/behavioral impact level */
+  impact: 'high' | 'medium' | 'low';
+  /** True if this outcome hides/blocks other outcomes (modals, overlays, full-screen states) */
+  blocksOtherFlows?: boolean;
+  /**
+   * True if this flow can only be triggered by user interaction (clicking a button, etc.)
+   * and cannot be controlled via mock data. These flows need Playwright instructions.
+   */
+  interactionRequired?: boolean;
+  /**
+   * Group name for mutually exclusive flows - only ONE flow from a group can be active at a time.
+   * Examples: "status-badge", "active-tab", "modal-state"
+   * Flows in the same group represent alternative states of the same UI element/feature.
+   */
+  exclusiveGroup?: string;
+  /** Code snippet showing where this outcome is determined */
+  codeSnippet?: string;
+  /** Source location in code */
+  sourceLocation?: {
+    lineNumber: number;
+    column?: number;
+  };
+  /**
+   * Priority score for this flow (higher = more important to simulate).
+   * Based on rendering impact: flows that control more content/child components
+   * are prioritized higher. Used for sorting and filtering when there are many flows.
+   */
+  priority?: number;
+  /**
+   * Names of child components whose rendering is controlled by this flow.
+   * Flows that gate child component rendering should have higher priority
+   * as they affect more of the UI.
+   */
+  childComponentsControlled?: string[];
+}
+
 export interface Analysis {
   id?: string;
   projectId: string;
@@ -76,32 +160,8 @@ export interface Analysis {
     }[];
     mergedDataStructure?: Omit<DataStructure, 'equivalentSignatureVariables'>;
     scenariosDataStructure?: ScenariosDataStructure;
-    keyAttributes?: {
-      dependentEntityName?: string;
-      internalPath: string;
-      externalPath: string;
-      dataStructurePath?: string; // Full path like "useDiffModal().diffView" for mapping to mockData
-      description: string;
-      validValueOptions: string[];
-      errorValueOptions: string[];
-      /** The expected type of this attribute (e.g., "string", "boolean", "object") */
-      valueType?: string;
-      /** Dependencies that must have specific values for this attribute to have effect */
-      dependencies?: {
-        /** Path to the dependent attribute */
-        path: string;
-        /** Required value or condition for the dependency */
-        requiredValue: string | boolean;
-        /** Human-readable description of the dependency */
-        description: string;
-        /** ID of the compound conditional this dependency comes from */
-        fromChainId?: string;
-      }[];
-      /** IDs of compound conditionals this attribute participates in */
-      compoundConditionalIds?: string[];
-      /** Source locations where this key attribute is used in the code */
-      sourceLocations?: SourceLocation[];
-    }[];
+    /** All distinct execution flows/outcomes this entity can produce */
+    executionFlows?: ExecutionFlow[];
     dependencyTree?: DependencyTreeNode;
     dependentAnalyses?: string[];
     dependencyAnalyzedTreeShas?: {

package/analyzer-template/packages/types/src/types/Commit.ts

@@ -20,6 +20,8 @@ export type CommitRunStatus = {
   capturesAttempted?: number; // number of analyses captures attempted
   capturesCompleted?: number; // number of entity analyses captured
   analysisCompletedAt?: string; // timestamp when all analysis was completed
+  captureCompletedAt?: string; // timestamp when capture orchestration finished (success or graceful exit)
+  completedAt?: string; // latest phase completion — always set alongside analysisCompletedAt or captureCompletedAt
   firstCaptureAt?: string; // timestamp when the first capture was initiated
   lastCaptureAt?: string; // timestamp when the last capture was initiated
 

package/analyzer-template/packages/types/src/types/Entity.ts

@@ -101,6 +101,8 @@ export interface Entity {
     previousVersionWithAnalyses?: string;
     isSuperseded?: boolean;
     mockInfo?: any;
+    /** Whether the entity is an async function/component (Server Component in Next.js) */
+    isAsync?: boolean;
   };
   file?: File;
   commit?: Commit;

package/analyzer-template/packages/types/src/types/ProjectMetadata.ts

@@ -46,4 +46,5 @@ export type ProjectMetadata = {
   webapps?: WebApp[]; // Array of webapps in the project
   framework?: any; // Deprecated: use webapps[].framework instead
   environmentVariables?: EnvironmentVariable[]; // Environment variables to pass during startup/analysis
+  labs?: { simulations?: boolean };
 };

package/analyzer-template/packages/types/src/types/Scenario.ts

@@ -9,72 +9,6 @@ export interface PlaywrightInstruction {
   actionArgs?: unknown[];
 }
 
-/**
- * Reference to a specific validValueOption or errorValueOption from keyAttributes.
- * Used in KeyAttributeValueReference to track which predefined value a scenario uses.
- */
-export interface ValueOptionRef {
-  /** Index into the validValueOptions or errorValueOptions array */
-  index: number;
-  /**
-   * Type of reference:
-   * - 'exact': Uses exactly this value option
-   * - 'derived': Based on this value but modified (see derivation field)
-   * - 'custom': Not from predefined options (value was custom-generated)
-   */
-  refType: 'exact' | 'derived' | 'custom';
-  /** For 'derived' type: describes how the value differs from the original */
-  derivation?: string;
-}
-
-/**
- * Structured reference for key attribute instructions.
- * Enables tracking of which validValueOptions each scenario uses.
- */
-export interface KeyAttributeValueReference {
-  /** The local variable name for this attribute */
-  localVariable: string;
-  /** Human-readable instruction (kept for backwards compat and readability) */
-  instruction: string;
-  /** Reference to a validValueOption (for normal scenarios) */
-  valueOptionRef?: ValueOptionRef;
-  /** Reference to an errorValueOption (for error scenarios) */
-  errorOptionRef?: ValueOptionRef;
-}
-
-/**
- * Type guard to check if a keyAttributeInstruction is the new structured format
- */
-export function isStructuredReference(
-  value:
-    | string
-    | { localVariable: string; instruction: string }
-    | KeyAttributeValueReference,
-): value is KeyAttributeValueReference {
-  return (
-    typeof value === 'object' &&
-    'localVariable' in value &&
-    'instruction' in value &&
-    ('valueOptionRef' in value || 'errorOptionRef' in value)
-  );
-}
-
-/**
- * Check if a scenario has structured value references in its keyAttributeInstructions.
- * Scenarios without structured references need re-analysis to be included in breakdown view.
- */
-export function hasStructuredReferences(scenario: Scenario): boolean {
-  const instructions = scenario.metadata?.keyAttributeInstructions;
-  if (!instructions || Object.keys(instructions).length === 0) {
-    return false;
-  }
-  return Object.values(instructions).some(
-    (value) =>
-      typeof value === 'object' &&
-      ('valueOptionRef' in value || 'errorOptionRef' in value),
-  );
-}
-
 export interface ExecutionResult {
   returnValue?: unknown;
   error?: {
@@ -138,18 +72,10 @@ export interface Scenario {
     }[];
     dataMapping?: { [key: string]: string };
     /**
-     * Key attribute instructions map data structure paths to their values.
-     * Supports three formats (in order of preference):
-     * 1. KeyAttributeValueReference (new): structured with valueOptionRef for tracking
-     * 2. { localVariable, instruction } (current): basic structured format
-     * 3. string (deprecated): legacy instruction-only format
+     * IDs of execution flows this scenario covers.
+     * Mock data is generated to satisfy all requiredValues from these flows.
      */
-    keyAttributeInstructions?: {
-      [key: string]:
-        | string
-        | { localVariable: string; instruction: string }
-        | KeyAttributeValueReference;
-    };
+    coveredFlows?: string[];
     data?: {
       mockData: { [key: string]: unknown };
       argumentsData: { [key: string]: unknown }[];
@@ -168,6 +94,12 @@ export interface Scenario {
      * all scenarios and can only contain one scenario's mock data at a time.
      */
     runAlone?: boolean;
+    /**
+     * When true, this scenario's screenshots need to be recaptured.
+     * Set when entity code changed but data structure didn't (scenarios reused from previous analysis).
+     * The capture process should check this flag and recapture if needed.
+     */
+    needsRecapture?: boolean;
   };
   previousVersionId?: string;
   analysis?: Analysis;