@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.76566f9

package/analyzer-template/packages/ai/src/lib/generateEntityKeyAttributes.ts

@@ -1,15 +1,16 @@
 import completionCall from './completionCall';
 import { saveLlmCall } from '~codeyam/aws/dynamodb';
-import { DataStructure, Entity } from '~codeyam/types';
+import { DataStructure, Entity, SourceLocation } from '~codeyam/types';
 import generateEntityKeyAttributesGenerator from './promptGenerators/generateEntityKeyAttributesGenerator';
 import { awsLog } from '~codeyam/utils';
 import { DEFAULT_LARGER_MODEL } from './aiConfig';
 import { gatherAttributesMap } from './promptGenerators/gatherAttributesMap';
 import { fillInDirectSchemaGapsAndUnknowns } from './dataStructure/helpers/fillInSchemaGapsAndUnknowns';
+import { clearAttributesFromMapping } from './dataStructure/helpers/cleanNonObjectFunctions';
 import isFrontend from './isFrontend';
 import { AI } from '~codeyam/ai';
 import { formatConditionalUsagesForPrompt } from './getConditionalUsagesFromCode';
-import type { ConditionalUsage } from '~codeyam/types';
+import type { CompoundConditional, ConditionalUsage } from '~codeyam/types';
 
 interface GenerateEntityKeyAttributesArgs {
   entity: Pick<Entity, 'sha' | 'name' | 'filePath' | 'code' | 'metadata'>;
@@ -38,6 +39,11 @@ export default async function generateEntityKeyAttributes({
       true,
     );
 
+  // Clean the attributes map to remove primitive-returning array method paths
+  // like .includes().functionCallReturnValue, .indexOf().functionCallReturnValue, etc.
+  // These paths are not mockable and should not be presented as key attributes.
+  clearAttributesFromMapping(attributesMap);
+
   if (Object.keys(attributesMap).length === 0) {
     console.log(
       `CodeYam Error: No valid attributes found for ${entity.filePath} ${entity.name}`,
@@ -48,17 +54,31 @@ export default async function generateEntityKeyAttributes({
     };
   }
 
+  // Build merged schema for type inference (has more complete nested paths)
+  // Strip signature[N] prefix to match attributesMap format
+  const mergedSchemaForTypeLookup = Object.fromEntries(
+    Object.entries(mergedDataStructure.signatureSchema ?? {})
+      .filter(([k]) => k.startsWith('signature['))
+      .map(([k, v]) => [k.replace(/^signature\[\d+\]\./, ''), v]),
+  );
+
   // Resolve unknown types using heuristics (e.g., "unknown | undefined" -> "string | undefined")
+  // Pass mergedSchema so checkIfObjectOrFunction can detect nested paths that prove a type is an object
   const resolvedAttributesMap = fillInDirectSchemaGapsAndUnknowns({
     scopeName: entity.name,
     schema: { ...attributesMap },
+    mergedSchema: mergedSchemaForTypeLookup,
   });
 
   // Use pre-computed conditional usages from metadata, or compute on-the-fly as fallback
   const conditionalUsages: Record<string, ConditionalUsage[]> =
     entity.metadata?.isolatedDataStructure?.conditionalUsages ?? {};
-  const staticAnalysisContext =
-    formatConditionalUsagesForPrompt(conditionalUsages);
+  const compoundConditionals: CompoundConditional[] =
+    entity.metadata?.isolatedDataStructure?.compoundConditionals ?? [];
+  const staticAnalysisContext = formatConditionalUsagesForPrompt(
+    conditionalUsages,
+    compoundConditionals,
+  );
 
   const prompt = generateEntityKeyAttributesGenerator({
     code: entity.code,
@@ -133,6 +153,106 @@ export default async function generateEntityKeyAttributes({
     ]),
   );
 
+  // Helper to extract source locations from conditional usages for a given path
+  const getSourceLocationsForPath = (path: string): SourceLocation[] => {
+    const usages = conditionalUsages[path] || [];
+    const locations: SourceLocation[] = [];
+
+    for (const usage of usages.slice(0, 5)) {
+      // Limit to 5 locations
+      if (usage.sourceLocation) {
+        locations.push({
+          entityName: entity.name,
+          filePath: entity.filePath,
+          lineNumber: usage.sourceLocation.lineNumber,
+          column: usage.sourceLocation.column,
+          codeSnippet: usage.sourceLocation.codeSnippet,
+          usageType: 'conditional',
+          description: `Used in ${usage.location} statement (${usage.conditionType} check)`,
+        });
+      }
+    }
+
+    return locations;
+  };
+
+  // Helper to find source locations by matching sourceDataPath
+  // This handles cases where local variables (e.g., displayState.hasError) trace back
+  // to data structure paths (e.g., getScenarioDisplayState().functionCallReturnValue.hasError)
+  const getSourceLocationsBySourceDataPath = (
+    targetPath: string,
+  ): SourceLocation[] => {
+    const locations: SourceLocation[] = [];
+
+    // Search all conditional usages for ones whose sourceDataPath matches
+    for (const [, usages] of Object.entries(conditionalUsages)) {
+      for (const usage of usages) {
+        const sourceDataPath = (usage as { sourceDataPath?: string })
+          .sourceDataPath;
+        if (!sourceDataPath || !usage.sourceLocation) continue;
+
+        // Check if sourceDataPath ends with the target path
+        // e.g., "LibraryFunctionPreview.signature[0].isOutdated" ends with "isOutdated"
+        // or "getScenarioDisplayState.getScenarioDisplayState(...).functionCallReturnValue.hasError" ends with "hasError"
+        const normalizedSourcePath = sourceDataPath
+          .replace(/\.functionCallReturnValue/g, '')
+          .replace(/\([^)]*\)/g, '()');
+
+        if (
+          normalizedSourcePath.endsWith('.' + targetPath) ||
+          normalizedSourcePath.endsWith('.' + targetPath.replace(/\./g, '.'))
+        ) {
+          locations.push({
+            entityName: entity.name,
+            filePath: entity.filePath,
+            lineNumber: usage.sourceLocation.lineNumber,
+            column: usage.sourceLocation.column,
+            codeSnippet: usage.sourceLocation.codeSnippet,
+            usageType: 'conditional',
+            description: `Used in ${usage.location} statement (${usage.conditionType} check)`,
+          });
+        }
+      }
+    }
+
+    return locations.slice(0, 5); // Limit to 5
+  };
+
+  // Helper to find source locations from LLM-provided code snippets
+  const getSourceLocationsFromSnippets = (
+    codeSnippets: string[] | undefined,
+  ): SourceLocation[] => {
+    if (!codeSnippets || !Array.isArray(codeSnippets)) return [];
+
+    const locations: SourceLocation[] = [];
+    const codeLines = entity.code.split('\n');
+
+    for (const snippet of codeSnippets.slice(0, 3)) {
+      // Limit to 3 snippets
+      if (!snippet || typeof snippet !== 'string') continue;
+
+      // Normalize whitespace for matching
+      const normalizedSnippet = snippet.trim().replace(/\s+/g, ' ');
+
+      for (let i = 0; i < codeLines.length; i++) {
+        const normalizedLine = codeLines[i].replace(/\s+/g, ' ');
+        if (normalizedLine.includes(normalizedSnippet)) {
+          locations.push({
+            entityName: entity.name,
+            filePath: entity.filePath,
+            lineNumber: i + 1, // 1-based line numbers
+            codeSnippet: codeLines[i].trim(),
+            usageType: 'conditional',
+            description: `Key usage identified by analysis`,
+          });
+          break; // Only find first occurrence of each snippet
+        }
+      }
+    }
+
+    return locations;
+  };
+
   const fullKeyAttributes = keyAttributes
     .filter(Boolean)
     .filter(
@@ -144,6 +264,46 @@ export default async function generateEntityKeyAttributes({
     .filter((keyAttribute) => fullPathToInternalPath[keyAttribute.fullPath])
     .map((keyAttribute) => {
       const internalPath = fullPathToInternalPath[keyAttribute.fullPath];
+
+      // Get source locations from conditional usages
+      // Try multiple path formats since conditionalUsages might use different formats:
+      // - internalPath: the short path like "status"
+      // - fullPath: the LLM's path like "signature[0].status"
+      // - dataStructurePath: the external path like "useStatus().status"
+      // - Also try stripping signature[N] prefix since conditional usages use AST paths
+      let sourceLocations = getSourceLocationsForPath(internalPath);
+      if (sourceLocations.length === 0) {
+        sourceLocations = getSourceLocationsForPath(keyAttribute.fullPath);
+      }
+      if (sourceLocations.length === 0) {
+        const dataStructurePath =
+          dataStructurePathMap[internalPath] || keyAttribute.fullPath;
+        sourceLocations = getSourceLocationsForPath(dataStructurePath);
+      }
+      // Also try the path without signature[N] prefix since AST uses local variable names
+      if (sourceLocations.length === 0) {
+        const pathWithoutSignature = internalPath.replace(
+          /^signature\[\d+\]\./,
+          '',
+        );
+        if (pathWithoutSignature !== internalPath) {
+          sourceLocations = getSourceLocationsForPath(pathWithoutSignature);
+        }
+      }
+      // Finally, search by sourceDataPath which traces local variables back to data sources
+      // This handles cases like displayState.hasError → getScenarioDisplayState().hasError
+      if (sourceLocations.length === 0) {
+        sourceLocations = getSourceLocationsBySourceDataPath(internalPath);
+      }
+
+      // Last resort: use LLM-provided code snippets to find source locations
+      // This ensures every key attribute the LLM identifies has a source location
+      if (sourceLocations.length === 0 && keyAttribute.codeSnippets) {
+        sourceLocations = getSourceLocationsFromSnippets(
+          keyAttribute.codeSnippets,
+        );
+      }
+
       return {
         internalPath,
         externalPath: associationMap[internalPath],
@@ -155,6 +315,9 @@ export default async function generateEntityKeyAttributes({
         // Preserve new fields from LLM response
         valueType: keyAttribute.valueType,
         dependencies: keyAttribute.dependencies,
+        // Add source locations from static analysis or LLM snippets
+        sourceLocations:
+          sourceLocations.length > 0 ? sourceLocations : undefined,
       };
     });
 
@@ -184,15 +347,31 @@ NOT key attributes:
 
 We've provided a list of variables that are used in conditional statements in the code. These are very likely key attributes.
 
-Each conditional lists it's source and how it is used. This should help you identify which attributes to include and what values to suggest.
+Each conditional lists its source and how it is used. This should help you identify which attributes to include and what values to suggest.
+
+**IMPORTANT**: Only include attributes with explicit evidence of impact in THIS code:
+- Used directly in a conditional statement (if/ternary/switch)
+- Displayed or rendered directly (e.g., text content, list length)
+- Used in a computation that affects rendering
+
+Do NOT include attributes that are only passed as arguments to other functions without direct usage here. We analyze those functions separately and merge their key attributes automatically.
 
 ## Path Format
 
 Only return attributes from the "Attributes and Value Types" list — these are the only values we can control. Use the exact \`fullPath\` provided. Use \`functionCallReturnValue\` for function return values. Use \`[]\` for array items (e.g., \`items[]\`).
 
-## Dependencies
+## Dependencies and Compound Conditionals
+
+When attributes are used in && chains (compound conditionals), they form dependencies on each other:
+- Each attribute in the chain only has effect when ALL other conditions in the chain are satisfied
+- Include these as dependencies with the required value for the code path to execute
 
-If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
+Example: For \`a && b && !c\`:
+- \`a\` has dependencies: \`b\` must be truthy, \`c\` must be falsy
+- \`b\` has dependencies: \`a\` must be truthy, \`c\` must be falsy
+- \`c\` has dependencies: \`a\` must be truthy, \`b\` must be truthy (for the falsy check to matter)
+
+The static analysis section may show "Compound Conditionals" that list which conditions must be true together. Use this to populate the \`dependencies\` array with \`{ "path": "...", "requiredValue": "..." }\` entries.
 
 ## Value Type
 
@@ -218,8 +397,9 @@ List all key attributes in order from most impactful to least impactful regardin
     {
       "fullPath": "signature[0].user",
       "description": "Controls whether the main form or redirect screen displays",
+      "codeSnippets": ["if (!user) return <Redirect />", "user.name"],
       "dependencies": [
-        "signature[0].projectId": "must be a valid project ID for 'user' to have effect"
+        { "path": "signature[0].projectId", "requiredValue": "truthy", "description": "must be a valid project ID for 'user' to have effect" }
       ],
       "valueType": "object",
       "validValueOptions": ["an empty object {}", "null/undefined"]
@@ -227,6 +407,8 @@ List all key attributes in order from most impactful to least impactful regardin
   ]
 }
 \`\`\`
+
+The \`codeSnippets\` field is required - provide 1-3 short code excerpts (under 80 chars each) showing exactly where and how this attribute is used. These snippets must appear verbatim in the code.
 `;
 
 const BACKEND_SYSTEM_MESSAGE = `You analyze backend functions to identify key data attributes that significantly impact behavior.
@@ -248,15 +430,31 @@ NOT key attributes:
 
 We've provided a list of variables that are used in conditional statements in the code. These are very likely key attributes.
 
-Each conditional lists it's source and how it is used. This should help you identify which attributes to include and what values to suggest.
+Each conditional lists its source and how it is used. This should help you identify which attributes to include and what values to suggest.
+
+**IMPORTANT**: Only include attributes with explicit evidence of impact in THIS code:
+- Used directly in a conditional statement (if/ternary/switch)
+- Displayed or rendered directly (e.g., text content, list length)
+- Used in a computation that affects rendering
+
+Do NOT include attributes that are only passed as arguments to other functions without direct usage here. We analyze those functions separately and merge their key attributes automatically.
 
 ## Path Format
 
 Only return attributes from the "Attributes and Value Types" list — these are the only values we can control. Use the exact \`fullPath\` provided. Use \`functionCallReturnValue\` for function return values. Use \`[]\` for array items (e.g., \`items[]\`).
 
-## Dependencies
+## Dependencies and Compound Conditionals
 
-If this key attribute is only used if one or more other attributes have specific values, include those dependencies in a \`dependencies\` array.
+When attributes are used in && chains (compound conditionals), they form dependencies on each other:
+- Each attribute in the chain only has effect when ALL other conditions in the chain are satisfied
+- Include these as dependencies with the required value for the code path to execute
+
+Example: For \`a && b && !c\`:
+- \`a\` has dependencies: \`b\` must be truthy, \`c\` must be falsy
+- \`b\` has dependencies: \`a\` must be truthy, \`c\` must be falsy
+- \`c\` has dependencies: \`a\` must be truthy, \`b\` must be truthy (for the falsy check to matter)
+
+The static analysis section may show "Compound Conditionals" that list which conditions must be true together. Use this to populate the \`dependencies\` array with \`{ "path": "...", "requiredValue": "..." }\` entries.
 
 ## Value Type
 
@@ -282,8 +480,9 @@ List all key attributes in order from most impactful to least impactful using th
     {
       "fullPath": "signature[0].config.enabled",
       "description": "Controls whether the main processing logic runs",
+      "codeSnippets": ["if (!config.enabled) return", "enabled && processData()"],
       "dependencies": [
-        "signature[0].analysisMode": "must be 'full' for 'enabled' to have effect"
+        { "path": "signature[0].analysisMode", "requiredValue": "full", "description": "must be 'full' for 'enabled' to have effect" }
       ],
       "valueType": "boolean",
       "validValueOptions": ["true", "false"]
@@ -291,4 +490,6 @@ List all key attributes in order from most impactful to least impactful using th
   ]
 }
 \`\`\`
+
+The \`codeSnippets\` field is required - provide 1-3 short code excerpts (under 80 chars each) showing exactly where and how this attribute is used. These snippets must appear verbatim in the code.
 `;

package/analyzer-template/packages/ai/src/lib/generateEntityScenarioData.ts

@@ -11,6 +11,7 @@ import type {
 import validateJson from './validateJson';
 import { awsLog, awsLogDebugLevel } from '~codeyam/utils';
 import { AI, parseJsonSafe } from '~codeyam/ai';
+import convertNullToUndefinedBySchema from './dataStructure/helpers/convertNullToUndefinedBySchema';
 
 const DEFAULT_SCENARIO_NAME = 'Default Scenario';
 
@@ -166,6 +167,27 @@ export async function generateDataForScenario({
     }
   }
 
+  // Convert null values to undefined based on schema type constraints.
+  // LLM uses null for "no value" (JSON doesn't support undefined), but TypeScript
+  // types like "string | undefined" don't accept null. This converts null→undefined
+  // for fields typed as "T | undefined" (but preserves null for "T | null").
+  if (structure.dataForMocks && fullScenarioData.data.mockData) {
+    convertNullToUndefinedBySchema(
+      fullScenarioData.data.mockData,
+      structure.dataForMocks,
+    );
+  }
+  if (structure.arguments && fullScenarioData.data.argumentsData) {
+    for (let i = 0; i < fullScenarioData.data.argumentsData.length; i++) {
+      if (structure.arguments[i]) {
+        convertNullToUndefinedBySchema(
+          fullScenarioData.data.argumentsData[i],
+          structure.arguments[i],
+        );
+      }
+    }
+  }
+
   return {
     scenarioData: fullScenarioData,
     llmCall: { name: scenario.name, id: llmCall.id },
@@ -285,7 +307,7 @@ export const generateSystemMessage = (
     ? `## Default Scenario
 Generate COMPLETE, robust data for the entire data structure.
 - Fill ALL fields with realistic values (except error attributes and key attributes set to null or undefined)
-- Arrays should have 2-3 items
+- Arrays should have 3-5 items to provide realistic test data variety
 - Don't skip nested attributes unless the key attributes specify a parent attribute should be null or undefined
 - This provides the baseline data for all other scenarios`
     : `## Non-Default Scenario
@@ -317,30 +339,19 @@ Use for relative dates. Code runs in Node (no browser APIs, no external librarie
 \`\`\`
 Use simple elements only (\`<div>\`, \`<span>\`). No custom components.
 
-## Mock Data Keys
-Preserve keys exactly as written in the structure. There are two formats:
+### Arrays
+- Arrays should have many items (at least 4) unless specified otherwise
+- Each item must follow the exact structure provided
+- In general we want robust data, not minimal data unless specified otherwise
 
-### Standard function calls
-\`\`\`json
-{
-  "mockData": {
-    "useUser()": { "user": { "name": "John" } },
-    "from().select()": [{ "id": "1" }]
-  }
-}
-\`\`\`
-
-### Variable-qualified calls (for multiple calls to the same function)
-When the same function is called multiple times with results stored in different variables, keys use the format \`variableName <- functionName\`:
-\`\`\`json
-{
-  "mockData": {
-    "entityDiffFetcher <- useFetcher": { "data": null, "state": "idle" },
-    "reportFetcher <- useFetcher": { "data": { "reportId": "abc123" }, "state": "idle" }
-  }
-}
-\`\`\`
-This reads as "entityDiffFetcher receives from useFetcher". Each variable gets its own distinct mock data.
+## CRITICAL: Preserve Exact Structure
+Your response MUST mirror the EXACT nested structure provided in mockData Structure.
+- Do NOT reorganize, split, or create duplicate keys
+- The hierarchy of nested objects must match exactly what was provided unless overridden by scenario rules
+- Only change the leaf VALUES (replacing type descriptions like "string" with actual data like "hello")
+- Copy the key strings EXACTLY from the structure
+- Do NOT modify type parameters, arguments, or any part of the key
+- The keys preserve the exact function call as written in the original code
 
 ## Response Format
 \`\`\`json
@@ -358,7 +369,7 @@ This reads as "entityDiffFetcher receives from useFetcher". Each variable gets i
 ## Rules
 - Valid JSON only—no raw code outside markers
 - No \`undefined\`—use \`null\` or omit
-- No data references (can't use \`posts[0]\` elsewhere—duplicate the value)
+- No data references (can't use \`posts[0]\` elsewhere — duplicate the value)
 - Scenario name must match exactly: "${scenarioName}"
 - Empty mockData: \`{}\`, empty argumentsData: \`[]\`
 `;

package/analyzer-template/packages/ai/src/lib/generateEntityScenarios.ts

@@ -8,6 +8,7 @@ import {
   PlaywrightInstruction,
   ReadonlyAnalysisMap,
   Scenario,
+  ValueOptionRef,
 } from '~codeyam/types';
 // import findMatchingAttribute from './findMatchingAttribute';
 import { awsLog } from '~codeyam/utils';
@@ -18,14 +19,20 @@ export interface ScenarioResult {
   name: string;
   testName: string;
   description: string;
-  // New format: { dataStructurePath: { localVariable, instruction } }
-  // Old format (deprecated): { path: instruction_string }
+  /**
+   * Key attribute instructions with structured value references.
+   * Format: { dataStructurePath: { localVariable, instruction, valueOptionRef? } }
+   */
   keyAttributeInstructions: {
     [key: string]:
       | string
       | {
           localVariable: string;
           instruction: string;
+          /** Reference to validValueOption index for tracking coverage */
+          valueOptionRef?: ValueOptionRef;
+          /** Reference to errorValueOption index for error scenarios */
+          errorOptionRef?: ValueOptionRef;
         };
   };
   codeSnippet: string;
@@ -212,6 +219,17 @@ Focus scenarios on demonstrating this specific behavior change.
 
 ${contextSection}${scenarioCountText}
 
+## Coverage Goals (IMPORTANT)
+Your primary goal is to MAXIMIZE coverage of key attributes across all scenarios:
+
+1. **Use ALL validValueOptions**: Each key attribute has indexed \`validValueOptions\`. Across your scenarios, try to use EVERY option at least once. If an attribute has 3 options (indices 0, 1, 2), create scenarios that collectively cover all 3.
+
+2. **Prioritize attributes with dependencies**: Key attributes with a \`dependencies\` array are HIGH PRIORITY - they control conditionally-rendered content. Create scenarios that satisfy these dependencies to reveal gated UI/behavior.
+
+3. **Cover conditional branches**: Use \`codeUsages\` to identify all conditional paths. If code shows \`status === 'active'\` and \`status === 'pending'\`, ensure scenarios cover BOTH values.
+
+4. **Vary values strategically**: Don't repeat the same validValueOption across scenarios unless necessary. Use different indices to maximize coverage.
+
 ## Default Scenario Rules
 The FIRST scenario MUST be named exactly "${DEFAULT_SCENARIO_NAME}" (case-sensitive).
 - Fill ALL key attributes using values from their \`validValueOptions\` list
@@ -219,23 +237,69 @@ The FIRST scenario MUST be named exactly "${DEFAULT_SCENARIO_NAME}" (case-sensit
 - Ignore error-related attributes (set to null)
 - NEVER include \`playwrightInstructions\` - we need a screenshot BEFORE any user interaction
 - Do NOT add playwrightInstructions even if the component has forms/buttons - default shows initial state only
+- **For attributes WITH dependencies**: The Default scenario should satisfy ALL dependencies so the attribute's effect is visible
 
 ## Other Scenarios
 - Each produces DISTINCT output (visual: different screenshot; backend: different return/side-effect)
+- **Use DIFFERENT validValueOptions** than the Default scenario - this is how we achieve coverage
 - Only specify attributes that DIFFER from default
+- Target uncovered validValueOptions: check which indices you haven't used yet
 - May include \`playwrightInstructions\` for user interactions (clicks, form fills)
 
+## Using codeUsages for Branch Coverage
+Key attributes may include a \`codeUsages\` array showing exactly where they're used in conditionals:
+\`\`\`json
+{
+  "codeUsages": [
+    { "line": 45, "code": "if (status === 'active')", "context": "Used in if statement (comparison check)" }
+  ]
+}
+\`\`\`
+Use this to ensure scenarios cover all conditional branches. If you see \`status === 'active'\`, create scenarios for both active AND non-active states.
+
+## Handling Dependencies (Compound Conditionals) - HIGH PRIORITY
+Key attributes with \`dependencies\` are the MOST IMPORTANT to cover because they reveal conditionally-gated content that only appears when multiple conditions are satisfied together.
+
+**Why this matters**: If you see \`items.length > 0 && !isLoading && !hasError\`, the content only renders when ALL THREE conditions are true. Missing even one dependency means the UI won't show.
+
+**Strategy for dependent attributes**:
+1. **Default scenario**: MUST satisfy ALL dependencies of the highest-impact key attributes
+2. **Other scenarios**: Can vary the dependent values to show alternative states (e.g., what happens when isLoading=true)
+
+When a key attribute has dependencies like:
+\`\`\`json
+{
+  "dependencies": [
+    { "path": "signature[0].isLoading", "requiredValue": false },
+    { "path": "signature[0].hasError", "requiredValue": false }
+  ]
+}
+\`\`\`
+The Default scenario MUST set BOTH dependent attributes to their required values so the key attribute's effect is visible.
+
+**Creating scenarios for dependent pathways**:
+- Create at least one scenario where ALL dependencies are satisfied (usually Default)
+- Consider creating additional scenarios that intentionally break dependencies to show the "hidden" state
+
 ## keyAttributeInstructions Format
-Use \`dataStructurePath\` as key, include both variable name and instruction:
+Use \`dataStructurePath\` as key. Include variable name, instruction, AND a valueOptionRef that references which validValueOption you're using:
 \`\`\`json
 {
   "useDiffModal().diffView": {
     "localVariable": "diffView",
-    "instruction": "Set to 'split' mode"
+    "instruction": "Set to 'split' mode",
+    "valueOptionRef": { "index": 0, "refType": "exact" }
   }
 }
 \`\`\`
 
+### valueOptionRef Types
+- \`"exact"\`: Uses the validValueOption at this index exactly
+- \`"derived"\`: Based on this validValueOption but modified (include \`derivation\` field explaining how)
+- \`"custom"\`: Value not from validValueOptions list (use sparingly)
+
+The \`index\` refers to the validValueOptions array position (0 = first option).
+
 ## playwrightInstructions (optional, non-default only)
 \`\`\`json
 {
@@ -263,24 +327,63 @@ Use when: data only appears after user action (button click, form submit), or ke
   "dataScenarios": [
     {
       "name": "${DEFAULT_SCENARIO_NAME}",
-      "testName": "it(\"displays notifications with unread indicator\")",
-      "description": "Default state with 3 unread and 2 read notifications",
+      "testName": "it(\"displays items list with data\")",
+      "description": "Shows item list when data is loaded and no errors",
       "keyAttributeInstructions": {
-        "useNotifications().notifications[]": { "localVariable": "notifications[]", "instruction": "Create 5 notifications" },
-        "useNotifications().notifications[].read": { "localVariable": "notifications[].read", "instruction": "false for 3, true for 2" }
+        "useData().items[]": {
+          "localVariable": "items[]",
+          "instruction": "Array with 3 items",
+          "valueOptionRef": { "index": 0, "refType": "exact" }
+        },
+        "useData().isLoading": {
+          "localVariable": "isLoading",
+          "instruction": "false - satisfies dependency for items to show",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        },
+        "useData().status": {
+          "localVariable": "status",
+          "instruction": "Set to 'success'",
+          "valueOptionRef": { "index": 0, "refType": "exact" }
+        }
+      }
+    },
+    {
+      "name": "Loading state",
+      "testName": "it(\"shows spinner when loading\")",
+      "description": "Data is loading - items hidden, spinner shown",
+      "keyAttributeInstructions": {
+        "useData().isLoading": {
+          "localVariable": "isLoading",
+          "instruction": "true - breaks dependency, items won't show",
+          "valueOptionRef": { "index": 0, "refType": "exact" }
+        },
+        "useData().status": {
+          "localVariable": "status",
+          "instruction": "Set to 'loading' for coverage of loading state",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        }
       }
     },
     {
       "name": "Empty state",
-      "testName": "it(\"shows placeholder when no notifications\")",
-      "description": "User has no notifications",
+      "testName": "it(\"shows empty message when no items\")",
+      "description": "No items to display",
       "keyAttributeInstructions": {
-        "useNotifications().notifications[]": { "localVariable": "notifications[]", "instruction": "Empty array" }
+        "useData().items[]": {
+          "localVariable": "items[]",
+          "instruction": "Empty array [] to show empty state",
+          "valueOptionRef": { "index": 1, "refType": "exact" }
+        }
       }
     }
   ]
 }
 \`\`\`
+Note how the example:
+- Default satisfies ALL dependencies (isLoading=false) so items content shows
+- "Loading state" uses a different valueOptionRef for status to cover that code path
+- "Empty state" covers the empty array case to maximize coverage
+- Instructions describe the VALUE, not the index (e.g., "Empty array []" not "uses index 1")
 `;
 }