@cementic/cementic-test 0.2.11 → 0.2.13

package/dist/cli.js

@@ -501,39 +501,427 @@ function buildProviderConfigs(env) {
 function getAvailableCtVarKeys() {
   return Object.keys(process.env).filter((key) => /^CT_VAR_[A-Z0-9_]+$/.test(key)).sort();
 }
+var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE = `
+RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
+(sourced from playwright.dev official documentation)
+
+You are an expert in Playwright TypeScript. Apply this knowledge
+when generating test code. Always use web-first assertions that
+auto-wait. Never use manual waits or non-awaited assertions.
+
+LOCATOR PRIORITY (use in this order)
+1. page.getByRole('button', { name: 'Submit' })     <- best
+2. page.getByLabel('Email address')
+3. page.getByPlaceholder('Enter email')
+4. page.getByText('Welcome')
+5. page.getByAltText('logo')
+6. page.getByTitle('Close')
+7. page.getByTestId('submit-btn')
+8. page.locator('#id') or page.locator('.class')    <- last resort
+
+Chain locators to narrow scope:
+  page.getByRole('listitem').filter({ hasText: 'Product 2' })
+    .getByRole('button', { name: 'Add to cart' }).click()
+
+LOCATOR ASSERTIONS (always await, always web-first)
+Visibility:
+  await expect(locator).toBeVisible()
+  await expect(locator).toBeHidden()
+  await expect(locator).toBeInViewport()
+
+State:
+  await expect(locator).toBeEnabled()
+  await expect(locator).toBeDisabled()
+  await expect(locator).toBeChecked()
+  await expect(locator).not.toBeChecked()
+  await expect(locator).toBeFocused()
+  await expect(locator).toBeEditable()
+  await expect(locator).toBeEmpty()
+  await expect(locator).toBeAttached()
+
+Text content:
+  await expect(locator).toHaveText('exact text')
+  await expect(locator).toHaveText(/regex/)
+  await expect(locator).toContainText('partial')
+  await expect(locator).toContainText(['item1', 'item2'])
+
+Value and attributes:
+  await expect(locator).toHaveValue('input value')
+  await expect(locator).toHaveValues(['opt1', 'opt2'])  // multi-select
+  await expect(locator).toHaveAttribute('href', /pattern/)
+  await expect(locator).toHaveClass(/active/)
+  await expect(locator).toHaveCSS('color', 'rgb(0,0,0)')
+  await expect(locator).toHaveId('submit-btn')
+  await expect(locator).toHaveAccessibleName('Submit form')
+  await expect(locator).toHaveAccessibleDescription('...')
+
+Counting (PREFER toHaveCount over .count() to avoid flakiness):
+  await expect(locator).toHaveCount(3)
+  await expect(locator).toHaveCount(0)   // none exist
+  // Only use .count() when you need the actual number:
+  const n = await page.getByRole('button').count();
+  console.log(\`Found \${n} buttons\`);
+
+PAGE ASSERTIONS
+  await expect(page).toHaveTitle(/Playwright/)
+  await expect(page).toHaveTitle('Exact Title')
+  await expect(page).toHaveURL('https://example.com/dashboard')
+  await expect(page).toHaveURL(/\\/dashboard/)
+
+ACTIONS (Playwright auto-waits before each action)
+Navigation:
+  await page.goto('https://example.com')
+  await page.goBack()
+  await page.goForward()
+  await page.reload()
+
+Clicking:
+  await locator.click()
+  await locator.dblclick()
+  await locator.click({ button: 'right' })
+  await locator.click({ modifiers: ['Shift'] })
+
+Forms:
+  await locator.fill('text')           // clears then types
+  await locator.clear()
+  await locator.pressSequentially('slow typing', { delay: 50 })
+  await locator.selectOption('value')
+  await locator.selectOption({ label: 'Blue' })
+  await locator.check()
+  await locator.uncheck()
+  await locator.setInputFiles('path/to/file.pdf')
+
+Hover and focus:
+  await locator.hover()
+  await locator.focus()
+  await locator.blur()
+
+Keyboard:
+  await page.keyboard.press('Enter')
+  await page.keyboard.press('Tab')
+  await page.keyboard.press('Escape')
+  await page.keyboard.press('Control+A')
+
+Scroll:
+  await locator.scrollIntoViewIfNeeded()
+  await page.mouse.wheel(0, 500)
+
+BEST PRACTICES (from playwright.dev/docs/best-practices)
+DO use web-first assertions:
+   await expect(page.getByText('welcome')).toBeVisible()
+
+NEVER use synchronous assertions:
+   expect(await page.getByText('welcome').isVisible()).toBe(true)
+
+DO chain locators:
+   page.getByRole('listitem').filter({ hasText: 'Product 2' })
+     .getByRole('button', { name: 'Add to cart' })
+
+NEVER use fragile CSS/XPath selectors:
+   page.locator('button.buttonIcon.episode-actions-later')
+
+DO use role-based locators:
+   page.getByRole('button', { name: 'submit' })
+
+INTENT -> PATTERN MAPPING
+
+COUNTING:
+  "how many X" / "count X" / "number of X" / "return the count"
+  -> const n = await page.getByRole('X').count();
+    console.log(\`Found \${n} X elements\`);
+    expect(n).toBeGreaterThan(0);
+
+  "there are N X" / "exactly N X"
+  -> await expect(page.getByRole('X')).toHaveCount(N);
+
+  CRITICAL: Never use getByText("how many X") - count intent
+  means call .count() or toHaveCount(), not search for text.
+
+PRESENCE:
+  "X is present/visible/shown/exists"
+  -> await expect(locator).toBeVisible()
+
+  "X is hidden/not present/gone"
+  -> await expect(locator).toBeHidden()
+
+TEXT:
+  "text says X" / "shows X" / "message is X"
+  -> await expect(locator).toHaveText('X')
+
+  "contains X" / "includes X"
+  -> await expect(locator).toContainText('X')
+
+  "page title is X"
+  -> await expect(page).toHaveTitle(/X/i)
+
+  "heading says X"
+  -> await expect(page.getByRole('heading')).toContainText('X')
+
+  "error says X"
+  -> await expect(page.getByRole('alert')).toContainText('X')
+
+STATE:
+  "X is enabled/disabled"
+  -> await expect(locator).toBeEnabled() / toBeDisabled()
+
+  "X is checked/unchecked"
+  -> await expect(locator).toBeChecked() / not.toBeChecked()
+
+  "X has value Y"
+  -> await expect(locator).toHaveValue('Y')
+
+  "X is active / has class Y"
+  -> await expect(locator).toHaveClass(/Y/)
+
+NAVIGATION:
+  "redirects to X" / "goes to X" / "URL contains X"
+  -> await expect(page).toHaveURL(/X/)
+
+  "stays on same page"
+  -> await expect(page).toHaveURL(/currentPath/)
+
+  "opens new tab"
+  -> const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      locator.click()
+    ]);
+
+FORMS:
+  "form submits successfully"
+  -> fill fields + click submit + assert URL change or success message
+
+  "validation error shown"
+  -> submit empty + await expect(page.getByRole('alert')).toBeVisible()
+
+  "required field X"
+  -> submit without X + assert error message for X visible
+
+AUTH:
+  "login with valid credentials"
+  -> fill(CT_VAR_USERNAME) + fill(CT_VAR_PASSWORD) + click login
+    + await expect(page).toHaveURL(/dashboard|home|app/)
+
+  "login fails / invalid credentials"
+  -> fill bad values + click login
+    + await expect(page.getByRole('alert')).toBeVisible()
+
+  "logout works"
+  -> click logout + await expect(page).toHaveURL(/login|home/)
+
+THEME / VISUAL:
+  "dark mode / theme toggle"
+  -> await locator.click()
+    + await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark')
+    // OR: await expect(page.locator('body')).toHaveClass(/dark/)
+
+TIMING:
+  "X loads / X appears"
+  -> await expect(locator).toBeVisible({ timeout: 10000 })
+
+  "spinner disappears / loader gone"
+  -> await expect(spinner).toBeHidden({ timeout: 10000 })
+
+  "modal closes"
+  -> await expect(modal).toBeHidden()
+
+ACCESSIBILITY:
+  "has alt text"
+  -> await expect(page.locator('img')).toHaveAttribute('alt', /.+/)
+
+  "keyboard navigable"
+  -> await page.keyboard.press('Tab')
+    + await expect(firstFocusable).toBeFocused()
+
+CRITICAL RULES
+1. NEVER use intent words as locator text.
+   "count buttons" != getByText("count buttons")
+   "verify heading" != getByText("verify heading")
+
+2. ALWAYS use web-first assertions (await expect).
+   NEVER use: expect(await locator.isVisible()).toBe(true)
+
+3. For counting, prefer toHaveCount() over .count() unless
+   you need the actual number for logging.
+
+4. Auto-waiting: Playwright automatically waits for elements
+   to be actionable before click/fill/etc. Do not add
+   manual waitForTimeout() unless testing timing specifically.
+
+5. Use not. prefix for negative assertions:
+   await expect(locator).not.toBeVisible()
+   await expect(locator).not.toBeChecked()
+`.trim();
+var ADVANCED_DOC_MAP = {
+  upload: "https://playwright.dev/docs/input",
+  "file upload": "https://playwright.dev/docs/input",
+  intercept: "https://playwright.dev/docs/mock",
+  mock: "https://playwright.dev/docs/mock",
+  "api mock": "https://playwright.dev/docs/mock",
+  accessibility: "https://playwright.dev/docs/accessibility-testing",
+  "screen reader": "https://playwright.dev/docs/accessibility-testing",
+  visual: "https://playwright.dev/docs/screenshots",
+  screenshot: "https://playwright.dev/docs/screenshots",
+  mobile: "https://playwright.dev/docs/emulation",
+  responsive: "https://playwright.dev/docs/emulation",
+  viewport: "https://playwright.dev/docs/emulation",
+  network: "https://playwright.dev/docs/network",
+  "api call": "https://playwright.dev/docs/network",
+  iframe: "https://playwright.dev/docs/frames",
+  frame: "https://playwright.dev/docs/frames",
+  auth: "https://playwright.dev/docs/auth",
+  "sign in": "https://playwright.dev/docs/auth",
+  "stay logged": "https://playwright.dev/docs/auth",
+  cookie: "https://playwright.dev/docs/auth",
+  storage: "https://playwright.dev/docs/auth",
+  download: "https://playwright.dev/docs/downloads",
+  pdf: "https://playwright.dev/docs/downloads",
+  dialog: "https://playwright.dev/docs/dialogs",
+  alert: "https://playwright.dev/docs/dialogs",
+  confirm: "https://playwright.dev/docs/dialogs",
+  "new tab": "https://playwright.dev/docs/pages",
+  "new page": "https://playwright.dev/docs/pages",
+  popup: "https://playwright.dev/docs/pages"
+};
+async function fetchDocContext(intent) {
+  const intentLower = intent.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const [keyword, url] of Object.entries(ADVANCED_DOC_MAP)) {
+    if (intentLower.includes(keyword)) {
+      matched.add(url);
+    }
+  }
+  if (matched.size === 0) return "";
+  const fetched = [];
+  for (const url of matched) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      const html = await res.text();
+      const text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s{3,}/g, "\n\n").slice(0, 3e3);
+      fetched.push(`
+// From ${url}:
+${text}`);
+    } catch {
+    }
+  }
+  if (fetched.length === 0) return "";
+  return `
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${fetched.join("\n")}`;
+}
 function buildSystemMessage() {
   return `
-You are a senior QA engineer and test automation specialist.
+You are a senior software test architect with 10 years of Playwright experience.
+You translate user requirements into precise, minimal, executable test scenarios.
+
+RULE 1 - INTENT IS THE REQUIREMENT
+Parse the user's feature description into specific testable claims BEFORE examining page context.
+Generate scenarios for the user's intent, not for every element on the page.
+
+RULE 2 - GENERATE TESTS FOR THE INTENT, NOT THE PAGE INVENTORY
+Only generate tests for claims extracted from the intent.
+Never generate tests for page elements that were not requested.
+Page context improves selector quality and wording, but it does not define test scope.
+
+RULE 3 - SELECTOR HIERARCHY
+When choosing selectors, prefer:
+1. Exact page-context match when available
+2. getByRole() with text from the intent
+3. getByLabel() for form inputs
+4. getByText() with text from the intent
+5. getByPlaceholder() for inputs
+6. locator('#id') only when the id appears stable
+
+Tie-breaker when multiple elements match:
+1. Prefer the highest-confidence page-context match
+2. Prefer visible elements over hidden
+3. Prefer interactive elements over static elements
+4. If still ambiguous, use the first match and note it with a short comment in the step text
+
+RULE 4 - TITLE DISAMBIGUATION
+"verify title" means the main visible heading on the page.
+Use a heading assertion first.
+Do NOT treat "title" as the browser tab title unless the intent explicitly says "browser title", "tab title", or "page title".
+
+RULE 5 - PRESENCE-ONLY INTENTS
+For presence-only intents such as "verify X", "check X is present", or "X is visible":
+- Only assert visibility
+- Do NOT click the element
+- Do NOT assert redirects, state changes, or side effects
+
+RULE 6 - NEGATIVE CASES
+Generate negative scenarios only when the intent implies interaction:
+- Form testing: always include an invalid-input scenario
+- Authentication: always include a wrong-credentials scenario
+- Presence checks: no negative case needed
+- Button click: negative case only if the button can be disabled
+
+RULE 7 - SETUP DEPENDENCIES
+If authentication is required to reach the page:
+- Add setup steps using CT_VAR_USERNAME and CT_VAR_PASSWORD
+- Tag the scenario with @requires-auth
+- Mention the dependency in a short step or assertion note when needed
 
-Your job:
-- Receive context about a web feature or page
-- Generate high-quality, realistic UI test cases
-- Format them in strict Markdown that a downstream parser will process
+RULE 8 - TEST DATA
+Never use the literal word 'value' as a placeholder.
+When filling a field:
+- If the user context lists a matching CT_VAR_* variable, write it exactly as '\${CT_VAR_FIELDNAME}` + `'
+- Otherwise use a field-specific fallback such as 'test-username', 'test-email@example.com', 'test-password', or 'test-search'
 
-You MUST follow this format exactly for each test case:
+RULE 9 - SCOPE DISCIPLINE
+Match scenario count to intent complexity:
+- 1 to 2 claims: 1 to 2 scenarios maximum
+- 3 to 5 claims: 3 to 5 scenarios maximum
+- Full flow: 4 to 8 scenarios maximum
+Never exceed 8 scenarios.
+
+${RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE}
+
+COMMON TESTING VOCABULARY
+"verify/check X is present/visible" -> toBeVisible()
+"verify title/heading" -> heading is visible
+"button/link is present" -> button or link is visible
+"can click X" -> click then assert visible outcome
+"form submits" -> fill + click + assert success or URL
+"error shows" -> trigger error + assert error visible
+"redirects to X" -> URL contains or equals X
+"text says X" -> text equals or contains X
+"page loads" -> main heading or key element is visible
+
+OUTPUT FORMAT - EXACT MARKDOWN SCHEMA
+Output valid markdown in this exact format. No preamble. No explanation. Just the markdown.
+
+# {PREFIX}-001 - {scenario-slug} - {Human readable title} @tag1 @tag2
+
+## Steps
+1. Navigate to {url}
+2. {action verb} {target description}
+
+## Expected Results
+- {specific observable assertion}
+- {specific observable assertion}
+
+---
+
+# {PREFIX}-002 - {scenario-slug} - {Human readable title} @tag1 @tag2
 
-# <ID> \u2014 <Short title> @<tag1> @<tag2>
 ## Steps
-1. <user action>
-2. <user action>
+1. Navigate to {url}
+2. {action verb} {target description}
 
 ## Expected Results
-- <verifiable outcome>
-- <verifiable outcome>
-
-Rules:
-- ID must be PREFIX-NNN where NNN is zero-padded 3 digits starting from startIndex
-- Use 1\u20133 tags: @smoke @regression @auth @ui @critical @happy-path @negative
-- Steps = concrete user actions ("Click the 'Sign In' button", "Fill in email with 'user@example.com'")
-- When writing fill steps, always use meaningful values
-- Never use the literal word 'value' as a placeholder in any fill step
-- If the user context lists available CT_VAR_* variables for a field, reference them in steps as '\${CT_VAR_FIELDNAME}` + `'
-- If no CT_VAR_* variable is available for a field, use a field-based placeholder like 'test-username', 'test-email', 'test-password', or 'test-phone'
-- If you do not know the real value, use the pattern 'test-{fieldname}'
-- Expected Results = verifiable UI outcomes ("Error message 'Invalid credentials' is visible", "Page redirects to /dashboard")
-- Include both happy-path AND negative/edge-case tests
-- Do NOT explain or add preamble \u2014 output ONLY the test cases
-- No code blocks, no extra headings outside the pattern
+- {specific observable assertion}
+
+Rules for the markdown schema:
+- id format: PREFIX-NNN using the provided prefix and numbering
+- slug format: kebab-case, max 5 words, derived from the scenario subject
+- title: human readable and aligned to the user's intent
+- tags: include at least one of @smoke @regression @negative @happy-path plus a relevant domain tag such as @auth @ui @navigation @form @checkout
+- steps: numbered, start with Navigate, then actions, written in plain English
+- assertions: bullet points with observable outcomes only
+- never write "test passes" or "works correctly"
+- do NOT wrap the output in code fences
 `.trim();
 }
 function buildUserMessage(ctx) {
@@ -542,9 +930,12 @@ function buildUserMessage(ctx) {
   lines.push(`App / product description:`);
   lines.push(ctx.appDescription || "N/A");
   lines.push("");
-  lines.push(`Feature or page to test:`);
+  lines.push(`Primary test intent:`);
   lines.push(ctx.feature);
   lines.push("");
+  lines.push(`Interpret the feature text above as the source of truth.`);
+  lines.push(`Only generate scenarios for claims that are explicitly implied by that intent.`);
+  lines.push("");
   if (ctx.url) {
     lines.push(`Page URL: ${ctx.url}`);
     lines.push("");
@@ -588,9 +979,9 @@ function buildUserMessage(ctx) {
   }
   lines.push(`Test ID prefix: ${ctx.prefix}`);
   lines.push(`Start numbering from: ${String(ctx.startIndex).padStart(3, "0")}`);
-  lines.push(`Number of test cases: ${ctx.numCases}`);
+  lines.push(`Requested number of test cases: ${ctx.numCases}`);
   lines.push("");
-  lines.push(`Include a mix of: happy-path flows, validation/error cases, and edge cases.`);
+  lines.push(`Use the requested count only when it fits the intent complexity. Prefer fewer scenarios when the request is simple.`);
   lines.push(`Output ONLY the test cases. No explanation, no preamble.`);
   return lines.join("\n");
 }
@@ -645,7 +1036,8 @@ async function callOpenAiCompatible(apiKey, model, baseUrl, displayName, system,
 }
 async function generateTcMarkdownWithAi(ctx) {
   const providerConfig = resolveLlmProvider();
-  const system = buildSystemMessage();
+  const docContext = await fetchDocContext(ctx.feature);
+  const system = buildSystemMessage() + docContext;
   const user = buildUserMessage(ctx);
   console.log(`\u{1F916} Using ${providerConfig.displayName} (${providerConfig.model})`);
   if (providerConfig.transport === "anthropic") {
@@ -662,13 +1054,324 @@ async function generateTcMarkdownWithAi(ctx) {
 }
 
 // src/core/analyse.ts
+var RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2 = `
+RULE 10 - PLAYWRIGHT KNOWLEDGE BASE
+(sourced from playwright.dev official documentation)
+
+You are an expert in Playwright TypeScript. Apply this knowledge
+when generating test code. Always use web-first assertions that
+auto-wait. Never use manual waits or non-awaited assertions.
+
+LOCATOR PRIORITY (use in this order)
+1. page.getByRole('button', { name: 'Submit' })     <- best
+2. page.getByLabel('Email address')
+3. page.getByPlaceholder('Enter email')
+4. page.getByText('Welcome')
+5. page.getByAltText('logo')
+6. page.getByTitle('Close')
+7. page.getByTestId('submit-btn')
+8. page.locator('#id') or page.locator('.class')    <- last resort
+
+Chain locators to narrow scope:
+  page.getByRole('listitem').filter({ hasText: 'Product 2' })
+    .getByRole('button', { name: 'Add to cart' }).click()
+
+LOCATOR ASSERTIONS (always await, always web-first)
+Visibility:
+  await expect(locator).toBeVisible()
+  await expect(locator).toBeHidden()
+  await expect(locator).toBeInViewport()
+
+State:
+  await expect(locator).toBeEnabled()
+  await expect(locator).toBeDisabled()
+  await expect(locator).toBeChecked()
+  await expect(locator).not.toBeChecked()
+  await expect(locator).toBeFocused()
+  await expect(locator).toBeEditable()
+  await expect(locator).toBeEmpty()
+  await expect(locator).toBeAttached()
+
+Text content:
+  await expect(locator).toHaveText('exact text')
+  await expect(locator).toHaveText(/regex/)
+  await expect(locator).toContainText('partial')
+  await expect(locator).toContainText(['item1', 'item2'])
+
+Value and attributes:
+  await expect(locator).toHaveValue('input value')
+  await expect(locator).toHaveValues(['opt1', 'opt2'])  // multi-select
+  await expect(locator).toHaveAttribute('href', /pattern/)
+  await expect(locator).toHaveClass(/active/)
+  await expect(locator).toHaveCSS('color', 'rgb(0,0,0)')
+  await expect(locator).toHaveId('submit-btn')
+  await expect(locator).toHaveAccessibleName('Submit form')
+  await expect(locator).toHaveAccessibleDescription('...')
+
+Counting (PREFER toHaveCount over .count() to avoid flakiness):
+  await expect(locator).toHaveCount(3)
+  await expect(locator).toHaveCount(0)   // none exist
+  // Only use .count() when you need the actual number:
+  const n = await page.getByRole('button').count();
+  console.log(\`Found \${n} buttons\`);
+
+PAGE ASSERTIONS
+  await expect(page).toHaveTitle(/Playwright/)
+  await expect(page).toHaveTitle('Exact Title')
+  await expect(page).toHaveURL('https://example.com/dashboard')
+  await expect(page).toHaveURL(/\\/dashboard/)
+
+ACTIONS (Playwright auto-waits before each action)
+Navigation:
+  await page.goto('https://example.com')
+  await page.goBack()
+  await page.goForward()
+  await page.reload()
+
+Clicking:
+  await locator.click()
+  await locator.dblclick()
+  await locator.click({ button: 'right' })
+  await locator.click({ modifiers: ['Shift'] })
+
+Forms:
+  await locator.fill('text')           // clears then types
+  await locator.clear()
+  await locator.pressSequentially('slow typing', { delay: 50 })
+  await locator.selectOption('value')
+  await locator.selectOption({ label: 'Blue' })
+  await locator.check()
+  await locator.uncheck()
+  await locator.setInputFiles('path/to/file.pdf')
+
+Hover and focus:
+  await locator.hover()
+  await locator.focus()
+  await locator.blur()
+
+Keyboard:
+  await page.keyboard.press('Enter')
+  await page.keyboard.press('Tab')
+  await page.keyboard.press('Escape')
+  await page.keyboard.press('Control+A')
+
+Scroll:
+  await locator.scrollIntoViewIfNeeded()
+  await page.mouse.wheel(0, 500)
+
+BEST PRACTICES (from playwright.dev/docs/best-practices)
+DO use web-first assertions:
+   await expect(page.getByText('welcome')).toBeVisible()
+
+NEVER use synchronous assertions:
+   expect(await page.getByText('welcome').isVisible()).toBe(true)
+
+DO chain locators:
+   page.getByRole('listitem').filter({ hasText: 'Product 2' })
+     .getByRole('button', { name: 'Add to cart' })
+
+NEVER use fragile CSS/XPath selectors:
+   page.locator('button.buttonIcon.episode-actions-later')
+
+DO use role-based locators:
+   page.getByRole('button', { name: 'submit' })
+
+INTENT -> PATTERN MAPPING
+
+COUNTING:
+  "how many X" / "count X" / "number of X" / "return the count"
+  -> const n = await page.getByRole('X').count();
+    console.log(\`Found \${n} X elements\`);
+    expect(n).toBeGreaterThan(0);
+
+  "there are N X" / "exactly N X"
+  -> await expect(page.getByRole('X')).toHaveCount(N);
+
+  CRITICAL: Never use getByText("how many X") - count intent
+  means call .count() or toHaveCount(), not search for text.
+
+PRESENCE:
+  "X is present/visible/shown/exists"
+  -> await expect(locator).toBeVisible()
+
+  "X is hidden/not present/gone"
+  -> await expect(locator).toBeHidden()
+
+TEXT:
+  "text says X" / "shows X" / "message is X"
+  -> await expect(locator).toHaveText('X')
+
+  "contains X" / "includes X"
+  -> await expect(locator).toContainText('X')
+
+  "page title is X"
+  -> await expect(page).toHaveTitle(/X/i)
+
+  "heading says X"
+  -> await expect(page.getByRole('heading')).toContainText('X')
+
+  "error says X"
+  -> await expect(page.getByRole('alert')).toContainText('X')
+
+STATE:
+  "X is enabled/disabled"
+  -> await expect(locator).toBeEnabled() / toBeDisabled()
+
+  "X is checked/unchecked"
+  -> await expect(locator).toBeChecked() / not.toBeChecked()
+
+  "X has value Y"
+  -> await expect(locator).toHaveValue('Y')
+
+  "X is active / has class Y"
+  -> await expect(locator).toHaveClass(/Y/)
+
+NAVIGATION:
+  "redirects to X" / "goes to X" / "URL contains X"
+  -> await expect(page).toHaveURL(/X/)
+
+  "stays on same page"
+  -> await expect(page).toHaveURL(/currentPath/)
+
+  "opens new tab"
+  -> const [newPage] = await Promise.all([
+      context.waitForEvent('page'),
+      locator.click()
+    ]);
+
+FORMS:
+  "form submits successfully"
+  -> fill fields + click submit + assert URL change or success message
+
+  "validation error shown"
+  -> submit empty + await expect(page.getByRole('alert')).toBeVisible()
+
+  "required field X"
+  -> submit without X + assert error message for X visible
+
+AUTH:
+  "login with valid credentials"
+  -> fill(CT_VAR_USERNAME) + fill(CT_VAR_PASSWORD) + click login
+    + await expect(page).toHaveURL(/dashboard|home|app/)
+
+  "login fails / invalid credentials"
+  -> fill bad values + click login
+    + await expect(page.getByRole('alert')).toBeVisible()
+
+  "logout works"
+  -> click logout + await expect(page).toHaveURL(/login|home/)
+
+THEME / VISUAL:
+  "dark mode / theme toggle"
+  -> await locator.click()
+    + await expect(page.locator('html')).toHaveAttribute('data-theme', 'dark')
+    // OR: await expect(page.locator('body')).toHaveClass(/dark/)
+
+TIMING:
+  "X loads / X appears"
+  -> await expect(locator).toBeVisible({ timeout: 10000 })
+
+  "spinner disappears / loader gone"
+  -> await expect(spinner).toBeHidden({ timeout: 10000 })
+
+  "modal closes"
+  -> await expect(modal).toBeHidden()
+
+ACCESSIBILITY:
+  "has alt text"
+  -> await expect(page.locator('img')).toHaveAttribute('alt', /.+/)
+
+  "keyboard navigable"
+  -> await page.keyboard.press('Tab')
+    + await expect(firstFocusable).toBeFocused()
+
+CRITICAL RULES
+1. NEVER use intent words as locator text.
+   "count buttons" != getByText("count buttons")
+   "verify heading" != getByText("verify heading")
+
+2. ALWAYS use web-first assertions (await expect).
+   NEVER use: expect(await locator.isVisible()).toBe(true)
+
+3. For counting, prefer toHaveCount() over .count() unless
+   you need the actual number for logging.
+
+4. Auto-waiting: Playwright automatically waits for elements
+   to be actionable before click/fill/etc. Do not add
+   manual waitForTimeout() unless testing timing specifically.
+
+5. Use not. prefix for negative assertions:
+   await expect(locator).not.toBeVisible()
+   await expect(locator).not.toBeChecked()
+`.trim();
+var ADVANCED_DOC_MAP2 = {
+  upload: "https://playwright.dev/docs/input",
+  "file upload": "https://playwright.dev/docs/input",
+  intercept: "https://playwright.dev/docs/mock",
+  mock: "https://playwright.dev/docs/mock",
+  "api mock": "https://playwright.dev/docs/mock",
+  accessibility: "https://playwright.dev/docs/accessibility-testing",
+  "screen reader": "https://playwright.dev/docs/accessibility-testing",
+  visual: "https://playwright.dev/docs/screenshots",
+  screenshot: "https://playwright.dev/docs/screenshots",
+  mobile: "https://playwright.dev/docs/emulation",
+  responsive: "https://playwright.dev/docs/emulation",
+  viewport: "https://playwright.dev/docs/emulation",
+  network: "https://playwright.dev/docs/network",
+  "api call": "https://playwright.dev/docs/network",
+  iframe: "https://playwright.dev/docs/frames",
+  frame: "https://playwright.dev/docs/frames",
+  auth: "https://playwright.dev/docs/auth",
+  "sign in": "https://playwright.dev/docs/auth",
+  "stay logged": "https://playwright.dev/docs/auth",
+  cookie: "https://playwright.dev/docs/auth",
+  storage: "https://playwright.dev/docs/auth",
+  download: "https://playwright.dev/docs/downloads",
+  pdf: "https://playwright.dev/docs/downloads",
+  dialog: "https://playwright.dev/docs/dialogs",
+  alert: "https://playwright.dev/docs/dialogs",
+  confirm: "https://playwright.dev/docs/dialogs",
+  "new tab": "https://playwright.dev/docs/pages",
+  "new page": "https://playwright.dev/docs/pages",
+  popup: "https://playwright.dev/docs/pages"
+};
+async function fetchDocContext2(intent) {
+  const intentLower = intent.toLowerCase();
+  const matched = /* @__PURE__ */ new Set();
+  for (const [keyword, url] of Object.entries(ADVANCED_DOC_MAP2)) {
+    if (intentLower.includes(keyword)) {
+      matched.add(url);
+    }
+  }
+  if (matched.size === 0) return "";
+  const fetched = [];
+  for (const url of matched) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+      const html = await res.text();
+      const text = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s{3,}/g, "\n\n").slice(0, 3e3);
+      fetched.push(`
+// From ${url}:
+${text}`);
+    } catch {
+    }
+  }
+  if (fetched.length === 0) return "";
+  return `
+
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+ADDITIONAL PLAYWRIGHT DOCS (fetched for this intent)
+\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${fetched.join("\n")}`;
+}
 async function analyseElements(elementMap, options = {}) {
-  const { verbose = false } = options;
+  const { verbose = false, feature } = options;
   const providerConfig = resolveLlmProvider();
+  const requestedFeature = normalizeRequestedFeature(feature, elementMap);
   log(verbose, `
 [analyse] Sending capture to ${providerConfig.displayName} (${providerConfig.model})`);
-  const systemPrompt = buildSystemPrompt();
-  const userPrompt = buildUserPrompt(elementMap);
+  const docContext = await fetchDocContext2(requestedFeature);
+  const systemPrompt = buildSystemPrompt() + docContext;
+  const userPrompt = buildUserPrompt(elementMap, requestedFeature);
   const rawResponse = providerConfig.transport === "anthropic" ? await callAnthropic2(providerConfig.apiKey, providerConfig.model, systemPrompt, userPrompt) : await callOpenAiCompatible2(
     providerConfig.apiKey,
     providerConfig.model,
@@ -678,7 +1381,7 @@ async function analyseElements(elementMap, options = {}) {
     userPrompt
   );
   const parsed = parseAnalysisJson(rawResponse);
-  return sanitizeAnalysis(parsed, elementMap);
+  return sanitizeAnalysis(parsed, elementMap, requestedFeature);
 }
 function buildSystemPrompt() {
   return `
@@ -688,16 +1391,21 @@ Your job is to analyse a structured map of interactive elements extracted from a
 then produce a complete set of Playwright test scenarios.
 
 RULES:
-1. Use only selectors provided in the ElementMap.
+1. The user's feature description is the PRIMARY requirement. Generate scenarios that test what the user asked for.
 2. Every assertion must include an exact "playwright" field with a complete await expect(...) statement.
-3. Use clearly fake data like user@example.com.
-4. Include both happy-path and negative scenarios, but stay evidence-backed.
+3. Use captured elements as the first selector source. If the intent names text that was not captured, you may fall back to a safe Playwright selector derived from the intent such as getByRole(), getByText(), getByLabel(), getByPlaceholder(), or locator('#id').
+4. Include happy-path and negative scenarios only when the intent implies interaction, and stay evidence-backed.
 5. Output only valid JSON matching the requested schema.
 6. Do not invent redirect targets, success pages, error text, password clearing, or security scenarios unless the capture explicitly supports them.
 7. If no status or alert region was captured, avoid scenarios that depend on unseen server-side validation messages.
-8. Prefer 3 to 5 realistic scenarios.
-9. The "selector" field must be the raw selector expression from the ElementMap, such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
-10. If a page clearly contains login or auth fields, do not create submit scenarios that only click the button. Include realistic fill steps for captured username/email and password inputs.
+8. Scope must match intent complexity. Simple 1 to 2 claim requests should produce only 1 to 2 scenarios.
+9. For presence-only intents such as "verify X" or "X is present", only assert visibility. Do not click and do not assert outcomes after clicking.
+${RULE_10_PLAYWRIGHT_KNOWLEDGE_BASE2}
+11. For fill steps, never use the literal word "value". If matching CT_VAR_* variables are listed in the prompt, use them in human-readable step text and use a realistic non-generic runtime value in the JSON value field. Otherwise use a field-specific fallback such as test-username or test-password.
+12. The "selector" field must be a raw selector expression such as locator("#username") or getByRole('button', { name: "Login" }). Never wrap selectors in page. or page.locator("...") inside JSON.
+13. Tie-breaker for multiple matching elements: prefer highest confidence, then interactive elements, then the first visible-looking candidate.
+14. If a page clearly contains login or auth fields, do not create submit scenarios that only click the button. Include realistic fill steps for captured username/email and password inputs when the intent asks for auth interaction.
+15. "verify title" means the main visible heading on the page, not the browser tab title, unless the intent explicitly says browser title, tab title, or page title.
 
 OUTPUT SCHEMA:
 {
@@ -734,9 +1442,16 @@ OUTPUT SCHEMA:
   "audioSummary": string
 }`.trim();
 }
-function buildUserPrompt(elementMap) {
+function buildUserPrompt(elementMap, feature) {
   const lines = [];
   const authElements = detectAuthElements(elementMap);
+  const availableCtVarKeys = getAvailableCtVarKeys2();
+  const intentProfile = buildIntentProfile(feature);
+  lines.push("USER INTENT");
+  lines.push(`Feature description: ${feature}`);
+  lines.push(`Intent mode: ${intentProfile.mode}`);
+  lines.push(`Maximum scenarios for this request: ${intentProfile.maxScenarios}`);
+  lines.push("");
   lines.push("PAGE INFORMATION");
   lines.push(`URL: ${elementMap.url}`);
   lines.push(`Title: ${elementMap.title}`);
@@ -762,6 +1477,13 @@ function buildUserPrompt(elementMap) {
     }
     lines.push("");
   }
+  if (availableCtVarKeys.length > 0) {
+    lines.push("AVAILABLE CT_VAR_* VARIABLES:");
+    for (const envKey of availableCtVarKeys) {
+      lines.push(`  - ${envKey}`);
+    }
+    lines.push("");
+  }
   const interactiveCount = elementMap.elements.filter((element) => element.category === "input" || element.category === "button" || element.category === "link").length;
   const statusCount = elementMap.elements.filter((element) => element.category === "status").length;
   lines.push("EVIDENCE CONSTRAINTS:");
@@ -769,6 +1491,7 @@ function buildUserPrompt(elementMap) {
   lines.push(`  - Status or alert regions captured: ${statusCount}`);
   lines.push("  - If no redirect target is explicitly captured, do not assert a destination path.");
   lines.push("  - If no status region was captured, avoid exact server-side credential error claims.");
+  lines.push("  - Generate scenarios only for the requested feature description.");
   if (authElements.usernameInput && authElements.passwordInput && authElements.submitButton) {
     lines.push("  - This page contains a captured auth form. Include fill steps for the username/email and password fields in credential-submission scenarios.");
     lines.push("  - For auth pages without captured post-submit evidence, prefer evidence-backed form-state assertions over invented success redirects.");
@@ -837,15 +1560,21 @@ ${raw.slice(0, 500)}`
     );
   }
 }
-function sanitizeAnalysis(analysis, elementMap) {
+function sanitizeAnalysis(analysis, elementMap, requestedFeature) {
   const selectors = /* @__PURE__ */ new Set();
   for (const element of elementMap.elements) {
     selectors.add(element.selector);
     for (const alt of element.selectorAlt) selectors.add(alt);
   }
   const rawScenarios = Array.isArray(analysis.scenarios) ? analysis.scenarios : [];
+  const intentProfile = buildIntentProfile(requestedFeature);
   const currentUrl = new URL(elementMap.url);
   const authElements = detectAuthElements(elementMap);
+  const resolvedFeature = requestedFeature || analysis.feature || inferFeatureName(elementMap);
+  const resolvedPrefix = (analysis.suggestedPrefix || inferPrefix({
+    featureText: resolvedFeature,
+    url: elementMap.url
+  })).toUpperCase();
   const knownPaths = /* @__PURE__ */ new Set([
     currentUrl.pathname,
     ...elementMap.elements.filter((element) => element.category === "link").map((element) => {
@@ -868,21 +1597,28 @@ function sanitizeAnalysis(analysis, elementMap) {
       if (!pathMatch) return true;
       return knownPaths.has(pathMatch[0]);
     })
-  })).filter((scenario) => scenario.assertions.length > 0).slice(0, 5);
-  const useAuthFallback = shouldUseAuthFallback(authElements, sanitizedScenarios);
-  const finalScenarios = useAuthFallback ? buildAuthFallbackScenarios(elementMap, analysis.suggestedPrefix || inferPrefix2(elementMap), authElements) : sanitizedScenarios.length > 0 ? sanitizedScenarios : buildFallbackScenarios(elementMap, analysis.suggestedPrefix || "FLOW");
+  })).filter((scenario) => scenario.assertions.length > 0);
+  const intentAlignedScenarios = applyIntentPolicy(
+    sanitizedScenarios,
+    elementMap,
+    intentProfile,
+    resolvedPrefix
+  ).slice(0, intentProfile.maxScenarios);
+  const useAuthFallback = shouldUseAuthFallback(authElements, intentAlignedScenarios, intentProfile);
+  const fallbackScenarios = intentProfile.mode === "presence" ? buildPresenceOnlyScenarios(elementMap, requestedFeature, resolvedPrefix) : useAuthFallback ? buildAuthFallbackScenarios(elementMap, resolvedPrefix, authElements) : buildFallbackScenarios(elementMap, resolvedPrefix);
+  const finalScenarios = useAuthFallback ? fallbackScenarios.slice(0, intentProfile.maxScenarios) : intentAlignedScenarios.length > 0 ? intentAlignedScenarios : fallbackScenarios.slice(0, intentProfile.maxScenarios);
   return {
     ...analysis,
     url: analysis.url || elementMap.url,
-    feature: analysis.feature || inferFeatureName(elementMap),
-    suggestedPrefix: (analysis.suggestedPrefix || inferPrefix2(elementMap)).toUpperCase(),
+    feature: resolvedFeature,
+    suggestedPrefix: resolvedPrefix,
     scenarios: finalScenarios,
     analysisNotes: [
       analysis.analysisNotes,
       useAuthFallback ? "Replaced low-evidence auth scenarios with deterministic evidence-backed auth coverage." : "",
       `Sanitized to ${finalScenarios.length} evidence-backed scenario(s) from ${rawScenarios.length} raw scenario(s).`
     ].filter(Boolean).join(" "),
-    audioSummary: analysis.audioSummary || buildAudioSummary(analysis.feature || inferFeatureName(elementMap), finalScenarios)
+    audioSummary: analysis.audioSummary || buildAudioSummary(resolvedFeature, finalScenarios)
   };
 }
 function normalizeScenario(candidate, selectors, url) {
@@ -902,20 +1638,28 @@ function normalizeScenario(candidate, selectors, url) {
 function normalizeStep(candidate, selectors) {
   if (!candidate) return null;
   const selector = String(candidate.selector ?? "").trim();
-  if (selector !== "page" && !selectors.has(selector)) return null;
+  if (!isAllowedSelector(selector, selectors)) return null;
   const action = String(candidate.action ?? "").trim();
   if (!["navigate", "fill", "click", "select", "check", "keyboard", "hover"].includes(action)) return null;
+  const rawValue = String(candidate.value ?? "");
+  const value = action === "fill" || action === "select" ? resolveFieldRuntimeValue(selector, rawValue) : rawValue;
+  const human = normalizeStepHuman(
+    String(candidate.human ?? "").trim() || defaultStepHuman(action, selector, value),
+    action,
+    selector,
+    value
+  );
   return {
     action,
     selector,
-    value: String(candidate.value ?? ""),
-    human: String(candidate.human ?? "").trim() || defaultStepHuman(action, selector, String(candidate.value ?? ""))
+    value,
+    human
   };
 }
 function normalizeAssertion(candidate, selectors) {
   if (!candidate) return null;
   const selector = String(candidate.selector ?? "").trim();
-  if (selector !== "page" && !selectors.has(selector)) return null;
+  if (!isAllowedSelector(selector, selectors)) return null;
   const assertion = {
     type: String(candidate.type ?? "visible").trim() || "visible",
     selector,
@@ -961,6 +1705,7 @@ function buildFallbackScenarios(elementMap, prefix) {
     });
   }
   if (emailInput && passwordInput && submitButton) {
+    const emailValue = resolveFieldRuntimeValue(emailInput.selector, "");
     scenarios.push({
       id: nextId(scenarios.length + 1),
       title: "Submitting without a password keeps the user on the form",
@@ -975,8 +1720,8 @@ function buildFallbackScenarios(elementMap, prefix) {
         {
           action: "fill",
           selector: emailInput.selector,
-          value: "user@example.com",
-          human: "Fill in the email field"
+          value: emailValue,
+          human: buildFillHuman("Fill in the email field", emailInput.selector, emailValue)
         },
         {
           action: "click",
@@ -1077,13 +1822,13 @@ function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
         action: "fill",
         selector: usernameInput.selector,
         value: usernameValue,
-        human: "Fill in the username field"
+        human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
       },
       {
         action: "fill",
         selector: passwordInput.selector,
         value: passwordValue,
-        human: "Fill in the password field"
+        human: buildFillHuman("Fill in the password field", passwordInput.selector, passwordValue)
       }
     ],
     assertions: [
@@ -1127,7 +1872,7 @@ function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
         action: "fill",
         selector: usernameInput.selector,
         value: usernameValue,
-        human: "Fill in the username field"
+        human: buildFillHuman("Fill in the username field", usernameInput.selector, usernameValue)
       },
       {
         action: "click",
@@ -1164,16 +1909,166 @@ function buildAuthFallbackScenarios(elementMap, prefix, authElements) {
   });
   return scenarios;
 }
+function normalizeRequestedFeature(feature, elementMap) {
+  return String(feature ?? "").trim() || inferFeatureName(elementMap);
+}
 function inferFeatureName(elementMap) {
   const heading = elementMap.elements.find((element) => element.category === "heading" && element.name);
   return heading?.name || elementMap.title || "Captured page";
 }
-function inferPrefix2(elementMap) {
-  const source = `${elementMap.title} ${elementMap.url}`.toLowerCase();
-  if (/\blogin|sign in|auth/.test(source)) return "AUTH";
-  if (/\bcheckout|cart|payment/.test(source)) return "CHK";
-  if (/\bdashboard/.test(source)) return "DASH";
-  return "FLOW";
+function getAvailableCtVarKeys2() {
+  return Object.keys(process.env).filter((key) => /^CT_VAR_[A-Z0-9_]+$/.test(key)).sort();
+}
+function buildIntentProfile(feature) {
+  const normalized = feature.toLowerCase();
+  const countIntent = /\b(?:how many|count|number of|return the count|exactly\s+\d+|there (?:is|are)\s+\d+)/.test(normalized);
+  const wantsHeading = /\b(?:title|heading)\b/.test(normalized) && !/\b(?:browser title|tab title|page title)\b/.test(normalized);
+  const presenceOnly = isPresenceOnlyIntent(normalized);
+  const authIntent = /\b(?:login|log in|sign in|auth|credentials?)\b/.test(normalized) && !presenceOnly;
+  const formIntent = /\b(?:form|submit|field|input|enter|fill|type)\b/.test(normalized) && !presenceOnly && !authIntent;
+  const flowIntent = /\b(?:flow|journey|checkout|purchase|complete|works?)\b/.test(normalized) && !presenceOnly && !authIntent && !formIntent;
+  const mode = countIntent ? "count" : presenceOnly ? "presence" : authIntent ? "auth" : formIntent ? "form" : flowIntent ? "flow" : "generic";
+  const claimCount = countIntentClaims(feature);
+  return {
+    feature,
+    mode,
+    maxScenarios: mode === "count" ? 1 : mode === "presence" ? Math.min(Math.max(claimCount, 1), 2) : mode === "auth" || mode === "form" ? Math.min(Math.max(claimCount, 3), 5) : mode === "flow" ? Math.min(Math.max(claimCount, 4), 6) : Math.min(Math.max(claimCount, 1), 3),
+    wantsHeading
+  };
+}
+function countIntentClaims(feature) {
+  const quoted = Array.from(feature.matchAll(/["“”']([^"“”']+)["“”']/g)).length;
+  const segments = feature.split(/\s+(?:and|&)\s+|,\s*/i).map((segment) => segment.trim()).filter(Boolean);
+  return Math.max(quoted, segments.length || 1);
+}
+function isPresenceOnlyIntent(normalizedFeature) {
+  const presenceWords = /\b(?:verify|check|confirm|ensure|present|visible|shown|showing|available|exists?|title|heading)\b/.test(normalizedFeature);
+  const actionWords = /\b(?:click|submit|fill|type|enter|login|log in|sign in|checkout|purchase|complete|flow|journey|error|invalid|disabled|enabled)\b/.test(normalizedFeature);
+  return presenceWords && !actionWords;
+}
+function applyIntentPolicy(scenarios, elementMap, intentProfile, prefix) {
+  if (intentProfile.mode === "count") {
+    return buildCountScenarios(elementMap, intentProfile.feature, prefix);
+  }
+  if (intentProfile.mode !== "presence") {
+    return scenarios.slice(0, intentProfile.maxScenarios);
+  }
+  return buildPresenceOnlyScenarios(elementMap, intentProfile.feature, prefix);
+}
+function buildCountScenarios(elementMap, feature, prefix) {
+  const normalized = feature.toLowerCase();
+  const countedElements = pickCountedElements(elementMap, normalized);
+  const selector = countSelectorForFeature(normalized, countedElements);
+  const count = countedElements.length;
+  return [{
+    id: `${prefix}-${String(1).padStart(3, "0")}`,
+    title: feature,
+    tags: ["@smoke", "@ui"],
+    steps: [
+      {
+        action: "navigate",
+        selector: "page",
+        value: elementMap.url,
+        human: `Navigate to ${elementMap.url}`
+      }
+    ],
+    assertions: [{
+      type: "count",
+      selector,
+      expected: String(count),
+      human: `There are exactly ${count} matching elements`,
+      playwright: `await expect(page.${selector}).toHaveCount(${count});`
+    }],
+    narrator: "We count only the element type requested by the user.",
+    codeLevel: "beginner"
+  }];
+}
+function buildPresenceOnlyScenarios(elementMap, feature, prefix) {
+  const claims = extractPresenceClaims(feature, elementMap);
+  if (claims.length === 0) return buildFallbackScenarios(elementMap, prefix).slice(0, 1);
+  return [{
+    id: `${prefix}-${String(1).padStart(3, "0")}`,
+    title: feature,
+    tags: ["@smoke", "@ui"],
+    steps: [
+      {
+        action: "navigate",
+        selector: "page",
+        value: elementMap.url,
+        human: `Navigate to ${elementMap.url}`
+      }
+    ],
+    assertions: claims.map((claim) => ({
+      type: "visible",
+      selector: claim.selector,
+      expected: "visible",
+      human: claim.human,
+      playwright: visibleAssertion(claim.selector)
+    })),
+    narrator: "We verify only the elements explicitly requested by the user.",
+    codeLevel: "beginner"
+  }];
+}
+function extractPresenceClaims(feature, elementMap) {
+  const segments = feature.split(/\s+(?:and|&)\s+|,\s*/i).map((segment) => segment.trim()).filter(Boolean);
+  const claims = [];
+  for (const segment of segments) {
+    const normalized = segment.toLowerCase();
+    if (/\b(?:title|heading)\b/.test(normalized) && !/\b(?:browser title|tab title|page title)\b/.test(normalized)) {
+      claims.push({
+        selector: `getByRole('heading')`,
+        human: `${chooseHeadingElement(elementMap)?.name || "Main page heading"} is visible`
+      });
+      continue;
+    }
+    const text = extractIntentLabel(segment);
+    if (!text) continue;
+    const match = findBestMatchingElement(elementMap, text, normalized);
+    const selector = match?.selector ?? buildFallbackSelector(text, normalized);
+    claims.push({
+      selector,
+      human: `${text} is visible`
+    });
+  }
+  return claims;
+}
+function chooseHeadingElement(elementMap) {
+  return rankElements(
+    elementMap.elements.filter((element) => element.category === "heading")
+  )[0];
+}
+function extractIntentLabel(segment) {
+  const unquoted = Array.from(segment.matchAll(/["“”']([^"“”']+)["“”']/g)).map((match) => match[1].trim());
+  if (unquoted.length > 0) return unquoted[0];
+  return segment.replace(/\b(?:verify|check|confirm|ensure)\b/gi, " ").replace(/\b(?:the|a|an)\b/gi, " ").replace(/\b(?:is|are|be|should be)\b/gi, " ").replace(/\b(?:present|visible|shown|showing|available|exists?)\b/gi, " ").replace(/\b(?:button|link|cta|label|text)\b/gi, " ").replace(/[.?!,:;]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function findBestMatchingElement(elementMap, text, segment) {
+  const preferredCategory = /\bbutton\b/.test(segment) ? "button" : /\blink\b/.test(segment) ? "link" : /\bheading\b/.test(segment) ? "heading" : void 0;
+  const query = text.toLowerCase();
+  const candidates = elementMap.elements.filter((element) => {
+    if (preferredCategory && element.category !== preferredCategory) return false;
+    const haystack = `${element.name ?? ""} ${element.purpose}`.toLowerCase();
+    return haystack.includes(query);
+  });
+  return rankElements(candidates)[0];
+}
+function rankElements(elements) {
+  const confidenceWeight = (confidence) => confidence === "high" ? 3 : confidence === "medium" ? 2 : 1;
+  const interactiveWeight = (category) => category === "button" || category === "link" || category === "input" ? 2 : 1;
+  return [...elements].sort((left, right) => {
+    const confidenceDelta = confidenceWeight(right.confidence) - confidenceWeight(left.confidence);
+    if (confidenceDelta !== 0) return confidenceDelta;
+    const interactiveDelta = interactiveWeight(right.category) - interactiveWeight(left.category);
+    if (interactiveDelta !== 0) return interactiveDelta;
+    return 0;
+  });
+}
+function buildFallbackSelector(text, segment) {
+  const safeRegex = text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (/\bbutton\b/.test(segment)) return `getByRole('button', { name: /${safeRegex}/i })`;
+  if (/\blink\b/.test(segment)) return `getByRole('link', { name: /${safeRegex}/i })`;
+  if (/\b(?:title|heading)\b/.test(segment)) return `getByRole('heading', { name: /${safeRegex}/i })`;
+  return `getByText(${JSON.stringify(text)})`;
 }
 function buildAudioSummary(feature, scenarios) {
   return `We finished validating ${feature || "the captured page"} with ${scenarios.length} evidence-backed scenario${scenarios.length === 1 ? "" : "s"}.`;
@@ -1189,7 +2084,8 @@ function detectAuthElements(elementMap) {
   const heading = elementMap.elements.find((element) => element.category === "heading" && /login|sign in|auth/.test((element.name ?? "").toLowerCase())) ?? elementMap.elements.find((element) => element.category === "heading");
   return { usernameInput, passwordInput, submitButton, heading };
 }
-function shouldUseAuthFallback(authElements, scenarios) {
+function shouldUseAuthFallback(authElements, scenarios, intentProfile) {
+  if (intentProfile.mode !== "auth" && intentProfile.mode !== "form") return false;
   if (!authElements.usernameInput || !authElements.passwordInput || !authElements.submitButton) return false;
   if (scenarios.length === 0) return true;
   const hasCredentialEntry = scenarios.some((scenario) => {
@@ -1203,13 +2099,37 @@ function shouldUseAuthFallback(authElements, scenarios) {
 }
 function defaultStepHuman(action, selector, value) {
   if (action === "navigate") return `Navigate to ${value || "the page"}`;
-  if (action === "fill") return `Fill the field ${selector}`;
+  if (action === "fill") return buildFillHuman(`Fill the field ${selector}`, selector, value);
   if (action === "click") return `Click ${selector}`;
   if (action === "select") return `Select ${value} in ${selector}`;
   if (action === "check") return `Check ${selector}`;
   if (action === "keyboard") return `Press ${value}`;
   return `Interact with ${selector}`;
 }
+function normalizeStepHuman(human, action, selector, value) {
+  if (action !== "fill" && action !== "select") return human;
+  if (!value) return human;
+  const explicitTemplate = /\$\{CT_VAR_[A-Z0-9_]+\}/.test(human);
+  const quotedValue = human.match(/\bwith\s+['"`]([^'"`]+)['"`]/i)?.[1];
+  if (explicitTemplate) return human;
+  if (quotedValue && !isGenericFillValue(quotedValue)) return human;
+  const rewrittenBase = human.replace(/\s+with\s+['"`][^'"`]+['"`]\s*$/i, "").trim() || human;
+  return buildFillHuman(rewrittenBase, selector, value);
+}
+function pickCountedElements(elementMap, normalizedFeature) {
+  const category = /\bbutton/.test(normalizedFeature) ? "button" : /\blink/.test(normalizedFeature) ? "link" : /\bheading|title/.test(normalizedFeature) ? "heading" : /\binput|field|textbox|text box/.test(normalizedFeature) ? "input" : void 0;
+  if (category) {
+    return elementMap.elements.filter((element) => element.category === category);
+  }
+  return elementMap.elements.filter((element) => element.category === "button" || element.category === "link" || element.category === "input");
+}
+function countSelectorForFeature(normalizedFeature, elements) {
+  if (/\bbutton/.test(normalizedFeature)) return `getByRole('button')`;
+  if (/\blink/.test(normalizedFeature)) return `getByRole('link')`;
+  if (/\bheading|title/.test(normalizedFeature)) return `getByRole('heading')`;
+  if (/\binput|field|textbox|text box/.test(normalizedFeature)) return `getByRole('textbox')`;
+  return elements[0]?.selector ?? `locator('*')`;
+}
 function normalizePlaywrightAssertion(assertion) {
   const repaired = scopeBareSelectorsInAssertion(unwrapWrappedSelectorAssertion(assertion.playwright));
   if (repaired) return ensureStatement(repaired);
@@ -1264,10 +2184,54 @@ function valueAssertion(selector, value) {
   return `await expect(${selectorTarget(selector)}).toHaveValue(${JSON.stringify(value)});`;
 }
 function inferAuthValue(element, kind) {
-  if (kind === "password") return "Secret123!";
-  const haystack = `${element.name ?? ""} ${String(element.attributes.label ?? "")} ${String(element.attributes.name ?? "")}`.toLowerCase();
-  if (/email/.test(haystack)) return "user@example.com";
-  return "testuser";
+  if (kind === "password") return resolveFieldRuntimeValue(element.selector, "test-password");
+  return resolveFieldRuntimeValue(element.selector, "");
+}
+function buildFillHuman(base, selector, runtimeValue) {
+  const displayValue = resolveFieldDisplayValue(selector, runtimeValue);
+  return `${base} with '${displayValue}'`;
+}
+function resolveFieldRuntimeValue(selector, currentValue) {
+  if (currentValue && !isGenericFillValue(currentValue) && !extractCtVarTemplate(currentValue)) {
+    return currentValue;
+  }
+  const envKey = matchCtVarKey(selector);
+  if (envKey && process.env[envKey]) {
+    return String(process.env[envKey]);
+  }
+  return fallbackFieldValue(selector);
+}
+function resolveFieldDisplayValue(selector, runtimeValue) {
+  const envKey = matchCtVarKey(selector);
+  if (envKey) return `\${${envKey}}`;
+  return runtimeValue;
+}
+function matchCtVarKey(selectorOrText) {
+  const haystack = selectorOrText.toLowerCase();
+  const preferred = /\bemail\b/.test(haystack) ? "CT_VAR_EMAIL" : /\bpassword\b/.test(haystack) ? "CT_VAR_PASSWORD" : /\bsearch\b/.test(haystack) ? "CT_VAR_SEARCH" : /\bphone|tel\b/.test(haystack) ? "CT_VAR_PHONE" : /\bname\b/.test(haystack) ? "CT_VAR_NAME" : /\buser(?:name)?|login\b/.test(haystack) ? "CT_VAR_USERNAME" : void 0;
+  if (preferred && process.env[preferred] !== void 0) return preferred;
+  return getAvailableCtVarKeys2().find((key) => new RegExp(key.replace(/^CT_VAR_/, "").toLowerCase()).test(haystack));
+}
+function fallbackFieldValue(selectorOrText) {
+  const haystack = selectorOrText.toLowerCase();
+  if (/\bemail\b/.test(haystack)) return "test-email@example.com";
+  if (/\bpassword\b/.test(haystack)) return "test-password";
+  if (/\bsearch\b/.test(haystack)) return "test-search";
+  if (/\bphone|tel\b/.test(haystack)) return "test-phone";
+  if (/\bname\b/.test(haystack) && !/\buser(?:name)?\b/.test(haystack)) return "test-name";
+  if (/\buser(?:name)?|login\b/.test(haystack)) return "test-username";
+  return "test-input";
+}
+function isGenericFillValue(value) {
+  return /^(?:value|text|input|option|selection|selected value|default)$/i.test(value.trim());
+}
+function extractCtVarTemplate(value) {
+  return value.match(/^\$\{(CT_VAR_[A-Z0-9_]+)\}$/)?.[1];
+}
+function isAllowedSelector(selector, selectors) {
+  if (selector === "page") return true;
+  if (selectors.has(selector)) return true;
+  return /^(?:getByRole|getByText|getByLabel|getByPlaceholder|getByTestId)\(/.test(selector) || /^locator\((['"])(#.+?)\1\)$/.test(selector);
 }
 function ensureStatement(value) {
   const trimmed = String(value ?? "").trim();
@@ -1958,7 +2922,7 @@ function saveSpecPreview(analysis, outputDir = "tests/preview") {
       if (step.action === "hover") lines.push(`  await ${selector}.hover();`);
     }
     for (const assertion of scenario.assertions) {
-      lines.push(`  ${ensureStatement2(assertion.playwright)}`);
+      lines.push(`  ${renderPreviewAssertion(assertion.playwright, assertion.human)}`);
     }
     lines.push("});");
     lines.push("");
@@ -1982,6 +2946,15 @@ function ensureStatement2(value) {
   if (!trimmed) return "// TODO: add assertion";
   return trimmed.endsWith(";") ? trimmed : `${trimmed};`;
 }
+function renderPreviewAssertion(playwright, human) {
+  const statement = ensureStatement2(playwright);
+  const headingMatch = statement.match(/^await expect\(page\.getByRole\((['"])heading\1\)\)\.toBeVisible\(\);$/);
+  const visibleSubject = String(human ?? "").match(/^(.+?) is visible$/)?.[1]?.trim();
+  if (headingMatch && visibleSubject && !/main page heading/i.test(visibleSubject)) {
+    return `await expect(page.getByRole("heading", { name: ${JSON.stringify(visibleSubject)} })).toBeVisible();`;
+  }
+  return statement;
+}
 
 // src/commands/tc.ts
 function slugify2(text) {
@@ -2074,7 +3047,7 @@ async function runTcInteractive(params) {
           console.log("Capture-only mode requested. No test cases were generated.");
           return;
         }
-        const analysis = await analyseElements(elementMap, { verbose: true });
+        const analysis = await analyseElements(elementMap, { verbose: true, feature });
         printCaptureReport(elementMap, analysis);
         const previewPath = saveSpecPreview(analysis);
         if (previewPath) {