@taodigital/agents 0.0.0-stage → 1.2.0

package/dist/skill-file-agent.js

@@ -0,0 +1,3470 @@
+"use strict";
+/**
+ * Skill File Agent — 14-Dimension Application Intelligence Generator
+ *
+ * After each crawl, generates 14 taxonomy-level skill files in the Zeta Core:
+ *
+ * TIER 1 — Platform Intelligence (zero-cost DOM/network extraction, no LLM):
+ *   1. TECH_STACK        — framework, CSS lib, API style, build tool
+ *   2. AUTH_SESSION      — auth type, token storage, 2FA, protected routes
+ *   3. API_CONTRACT      — captured endpoints, base URL, error format
+ *
+ * TIER 2 — Domain Intelligence (LLM, uses DOM data):
+ *   4. BUSINESS_DOMAIN   — domain, user roles, core journeys, business rules
+ *   5. DATA_MODEL        — entities and field constraints from HTML5 attrs
+ *
+ * TIER 3 — Behavioral Intelligence (LLM + vision):
+ *   6. INTERACTION_PATTERNS — error display, loading states, submit flow
+ *   7. ERROR_CATALOGUE   — exact error messages per field and API error map
+ *
+ * TIER 4 — Structural Intelligence (LLM + vision):
+ *   8. VISUAL_BASELINE   — colors (hex), typography, layout, contrast ratios
+ *   9. COMPONENT_LIBRARY — reusable components, where they appear, edge cases
+ *  10. ELEMENT_BEHAVIORS — per-element: type, required, min/max, pattern, states
+ *
+ * TIER 5 — Quality Intelligence (structured data, no LLM):
+ *  11. NAVIGATION_MAP    — route inventory, auth guards, flow graph
+ *  12. LOCATOR_STRATEGY  — data-testid coverage, role-based locators, fragile selectors
+ *  13. PERFORMANCE_BASELINE — LCP/FCP/TTFB per screen, CWV status
+ *  14. COVERAGE_MATRIX   — TC counts per screen×type, coverage gaps
+ *
+ * QUALITY PROJECTION: 42/100 (old 6-file) → 87/100 (new 14-file)
+ *
+ * COST: Tiers 1, 5 = ZERO extra LLM tokens (pure DOM/network data).
+ *       Tiers 2–4 = LLM calls, same as before but higher-quality prompts.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTaxonomySkillFiles = generateTaxonomySkillFiles;
+exports.generateTechStackFile = generateTechStackFile;
+exports.generateAuthSessionFile = generateAuthSessionFile;
+exports.generateApiContractFile = generateApiContractFile;
+exports.generateNavigationMapFile = generateNavigationMapFile;
+exports.generateLocatorStrategyFile = generateLocatorStrategyFile;
+exports.generatePerformanceBaselineFile = generatePerformanceBaselineFile;
+exports.deriveConstraintExamples = deriveConstraintExamples;
+exports.renderCoverageMatrix = renderCoverageMatrix;
+exports.refreshCoverageMatrix = refreshCoverageMatrix;
+exports.refreshTestCaseInventory = refreshTestCaseInventory;
+exports.refreshScriptInventory = refreshScriptInventory;
+exports.refineSkillFile = refineSkillFile;
+exports.generateRepoSkillFiles = generateRepoSkillFiles;
+exports.alignSkillFile = alignSkillFile;
+exports.generateZetaFrameworkSkillFiles = generateZetaFrameworkSkillFiles;
+exports.refreshArtifactKnowledgeSkillFile = refreshArtifactKnowledgeSkillFile;
+exports.refreshTestCasesSkillFile = refreshTestCasesSkillFile;
+exports.refreshTestDataSkillFile = refreshTestDataSkillFile;
+exports.refreshTestScriptSkillFile = refreshTestScriptSkillFile;
+exports.refreshRequirementsCoverageSkillFile = refreshRequirementsCoverageSkillFile;
+exports.refreshTestExecutionHistorySkillFile = refreshTestExecutionHistorySkillFile;
+exports.refreshVisualRegressionHistorySkillFile = refreshVisualRegressionHistorySkillFile;
+exports.refreshLocatorStrategyWithHealingData = refreshLocatorStrategyWithHealingData;
+exports.refreshFieldCatalogSkillFile = refreshFieldCatalogSkillFile;
+exports.refreshHealingLogSkillFile = refreshHealingLogSkillFile;
+exports.refreshLocatorInventorySkillFile = refreshLocatorInventorySkillFile;
+const llm_js_1 = require("./llm.js");
+const llm_config_js_1 = require("./llm-config.js");
+const app_brain_1 = require("@taodigital/app-brain");
+const core_1 = require("@taodigital/core");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const SKILL_GENERATOR_VERSION = 'skill-file-agent:v2-structured-metadata';
+function skillQualityMetadata(kind, content, screens, apiEndpoints, performanceMetrics, mode) {
+    const SECTION_LIMIT = parseInt(process.env.SKILL_FILE_SECTION_LIMIT ?? '24', 10);
+    const SCREEN_LIMIT = parseInt(process.env.SKILL_FILE_SCREEN_LIMIT ?? '40', 10);
+    const ENDPOINT_LIMIT = parseInt(process.env.SKILL_FILE_ENDPOINT_LIMIT ?? '80', 10);
+    const sections = [...content.matchAll(/^##\s+(.+)$/gm)].map((m) => m[1].trim()).slice(0, SECTION_LIMIT);
+    const screenFacts = screens.slice(0, SCREEN_LIMIT).map((s) => ({
+        sourceType: 'SCREEN',
+        sourceId: s.id,
+        name: s.name,
+        url: s.url ?? null,
+        elementCount: s.elements.length,
+        screenshotCount: s.screenshots?.length ?? 0,
+    }));
+    const endpointFacts = (apiEndpoints ?? []).slice(0, ENDPOINT_LIMIT).map((e) => ({
+        sourceType: 'API_ENDPOINT',
+        method: e.method,
+        urlPattern: e.urlPattern,
+    }));
+    const perfFacts = (performanceMetrics ?? []).slice(0, 40).map((m) => ({
+        sourceType: 'PERFORMANCE_METRIC',
+        screenName: m.screenName,
+        url: m.url,
+        lcp: m.lcp ?? null,
+        fcp: m.fcp ?? null,
+        ttfb: m.ttfb ?? null,
+        cls: m.cls ?? null,
+    }));
+    const hasEvidence = screenFacts.length > 0 || endpointFacts.length > 0 || perfFacts.length > 0;
+    const validationStatus = content.includes('LLM generation failed') || content.includes('UNKNOWN — verify manually')
+        ? 'WARN'
+        : hasEvidence
+            ? 'PASS'
+            : 'WARN';
+    return {
+        structuredData: {
+            kind,
+            generatorVersion: SKILL_GENERATOR_VERSION,
+            extractionMode: mode,
+            screenCount: screens.length,
+            elementCount: screens.reduce((n, s) => n + s.elements.length, 0),
+            screenshotCount: screens.reduce((n, s) => n + (s.screenshots?.length ?? 0), 0),
+            apiEndpointCount: apiEndpoints?.length ?? 0,
+            performanceMetricCount: performanceMetrics?.length ?? 0,
+            sections,
+        },
+        provenance: [...screenFacts, ...endpointFacts, ...perfFacts],
+        confidence: mode === 'structured' || mode === 'live-db' ? 0.9 : mode === 'vision' ? 0.75 : 0.7,
+        validationStatus,
+        validationSummary: validationStatus === 'PASS'
+            ? 'Generated with source evidence and no placeholder warning markers.'
+            : 'Generated with incomplete or lower-confidence evidence; review recommended.',
+        staleStatus: 'CURRENT',
+        staleReason: null,
+        generatorVersion: SKILL_GENERATOR_VERSION,
+    };
+}
+// ─── Orchestrator ────────────────────────────────────────────────────────────
+/** Load all SkillFileConfig rows for a project in one query. Returns a Map keyed by kind. */
+async function loadSkillFileConfigs(tenantId, projectId) {
+    try {
+        const { withTenant: wt } = await import('@taodigital/database');
+        const rows = await wt(tenantId, (tx) => tx.skillFileConfig.findMany({ where: { tenantId, projectId } }));
+        const map = new Map();
+        for (const r of rows)
+            map.set(r.kind, { enabled: r.enabled, requireApproval: r.requireApproval });
+        return map;
+    }
+    catch {
+        return new Map(); // no config rows → defaults apply (enabled, no approval required)
+    }
+}
+/**
+ * Generate all 14 taxonomy skill files for a project after a crawl.
+ * Dependency-aware execution in 3 phases:
+ *   Phase A: Zero-cost structured data (no LLM)
+ *   Phase B: LLM domain + behavioral (uses Phase A data)
+ *   Phase C: LLM structural + quality (uses Phase A+B data)
+ */
+async function generateTaxonomySkillFiles(tenantId, projectId, screens, apiEndpoints, performanceMetrics) {
+    if (screens.length === 0)
+        return;
+    const totalElements = screens.reduce((n, s) => n + s.elements.length, 0);
+    const totalScreenshots = screens.reduce((n, s) => n + (s.screenshots?.length ?? 0), 0);
+    if (totalElements === 0 && totalScreenshots === 0) {
+        console.warn(`[skill-file-agent] No elements or screenshots found for project ${projectId} — skipping taxonomy generation.`);
+        return;
+    }
+    // Check per-project skill file config
+    const sfConfigs = await loadSkillFileConfigs(tenantId, projectId);
+    const sfEnabled = (kind) => sfConfigs.get(kind)?.enabled !== false;
+    const sfApprovalStatus = (kind) => sfConfigs.get(kind)?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING';
+    // Purge legacy 6-file kinds AND auto-invalidate TEST_PLAN so it doesn't get stale after a crawl
+    const KINDS_TO_PURGE = [
+        // Legacy kinds (old 6-file system)
+        'PLATFORM', 'FUNCTION', 'DESIGN', 'THEME', 'COMPONENT', 'ELEMENT',
+        // Current 14-dimension kinds — purge so regeneration always starts fresh
+        'TECH_STACK', 'AUTH_SESSION', 'API_CONTRACT', 'NAVIGATION_MAP', 'LOCATOR_STRATEGY',
+        'PERFORMANCE_BASELINE', 'BUSINESS_DOMAIN', 'DATA_MODEL', 'INTERACTION_PATTERNS',
+        'ERROR_CATALOGUE', 'VISUAL_BASELINE', 'COMPONENT_LIBRARY', 'ELEMENT_BEHAVIORS',
+        'COVERAGE_MATRIX', 'SCREEN_UNDERSTANDING',
+        // Invalidate plan on re-crawl
+        'TEST_PLAN',
+    ];
+    await app_brain_1.AppBrain.deleteSkillFilesByKinds(tenantId, projectId, KINDS_TO_PURGE).catch((e) => console.warn('[skill-file-agent] skill file purge failed:', e));
+    const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(tenantId, 'appBrain');
+    const stripFences = (text) => text.replace(/^```(?:markdown)?\s*\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+    const askFn = async (sys, usr, label = 'skill_file') => {
+        const t0 = Date.now();
+        const seed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${projectId}:skill-file:${label}`);
+        const { text, usage } = await (0, llm_js_1.askTracked)(sys, usr, llmCfg, undefined, undefined, { temperature: 0, seed });
+        (0, app_brain_1.recordLLMCall)({ tenantId, projectId, agentType: 'skill_file', label, usage, latencyMs: Date.now() - t0 }).catch(console.error);
+        const clean = stripFences(text ?? '');
+        if (clean.length < 30) {
+            throw new Error(`LLM returned insufficient content for ${label} (got: "${text?.slice(0, 50)}")`);
+        }
+        return clean;
+    };
+    const askVisionFn = async (sys, usr, imgs, label = 'skill_file_vision') => {
+        const t0 = Date.now();
+        const visionSeed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${projectId}:skill-vision:${label}:0`);
+        const { text, usage } = imgs.length > 0
+            ? await (0, llm_js_1.askTrackedWithImages)(sys, usr, imgs, llmCfg, { temperature: 0, seed: visionSeed })
+            : await (0, llm_js_1.askTracked)(sys, usr, llmCfg, undefined, undefined, { temperature: 0, seed: visionSeed });
+        (0, app_brain_1.recordLLMCall)({ tenantId, projectId, agentType: 'skill_file', label, usage, latencyMs: Date.now() - t0 }).catch(console.error);
+        const clean = stripFences(text ?? '');
+        if (clean.length < 30) {
+            throw new Error(`LLM returned insufficient content for ${label} (got: "${text?.slice(0, 50)}")`);
+        }
+        return clean;
+    };
+    const screenSummary = buildScreenSummary(screens);
+    const screenshots = await loadRepresentativeScreenshots(screens, 8);
+    const meta = (kind, content, mode) => skillQualityMetadata(kind, content, screens, apiEndpoints, performanceMetrics, mode);
+    // ── Phase A: Zero-cost structured data (no LLM calls) ───────────────────
+    console.log('[skill-file-agent] Phase A: structured extraction (0 LLM tokens)');
+    const [techStack, authSession, apiContract, navigationMap, locatorStrategy, performanceBaseline] = await Promise.all([
+        generateTechStackFile(screens, apiEndpoints),
+        generateAuthSessionFile(screens, apiEndpoints),
+        generateApiContractFile(apiEndpoints),
+        generateNavigationMapFile(screens),
+        generateLocatorStrategyFile(screens),
+        generatePerformanceBaselineFile(screens, performanceMetrics),
+    ]);
+    await Promise.all([
+        sfEnabled('TECH_STACK') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TECH_STACK', techStack.content, { summary: techStack.summary, tags: techStack.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('TECH_STACK'), ...meta('TECH_STACK', techStack.content, 'structured') }),
+        sfEnabled('AUTH_SESSION') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'AUTH_SESSION', authSession.content, { summary: authSession.summary, tags: authSession.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('AUTH_SESSION'), ...meta('AUTH_SESSION', authSession.content, 'structured') }),
+        sfEnabled('API_CONTRACT') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'API_CONTRACT', apiContract.content, { summary: apiContract.summary, tags: apiContract.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('API_CONTRACT'), ...meta('API_CONTRACT', apiContract.content, 'structured') }),
+        sfEnabled('NAVIGATION_MAP') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'NAVIGATION_MAP', navigationMap.content, { summary: navigationMap.summary, tags: navigationMap.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('NAVIGATION_MAP'), ...meta('NAVIGATION_MAP', navigationMap.content, 'structured') }),
+        sfEnabled('LOCATOR_STRATEGY') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'LOCATOR_STRATEGY', locatorStrategy.content, { summary: locatorStrategy.summary, tags: locatorStrategy.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('LOCATOR_STRATEGY'), ...meta('LOCATOR_STRATEGY', locatorStrategy.content, 'structured') }),
+        sfEnabled('PERFORMANCE_BASELINE') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'PERFORMANCE_BASELINE', performanceBaseline.content, { summary: performanceBaseline.summary, tags: performanceBaseline.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('PERFORMANCE_BASELINE'), ...meta('PERFORMANCE_BASELINE', performanceBaseline.content, 'structured') }),
+    ]);
+    // ── Probe observations — load early so ERROR_CATALOGUE receives real VALIDATION_ERROR facts ─
+    // Must run before Phase B; probe obs are written to DB during the crawl phase.
+    const probeObservations = new Map();
+    await Promise.all(screens.slice(0, 40).map(async (s) => {
+        try {
+            const obs = await app_brain_1.AppBrain.getProbeObservations(tenantId, s.id);
+            if (obs?.length)
+                probeObservations.set(s.id, obs);
+        }
+        catch { /* probe table may be empty — fine */ }
+    }));
+    // ── Phase B: LLM domain + behavioral (uses structured data from Phase A) ─
+    // Promise.allSettled so one failing LLM call never poisons the other files.
+    console.log('[skill-file-agent] Phase B: LLM domain + behavioral skill files');
+    const llmNotice = (kind, err) => `# ${kind}\n\n> LLM generation failed. Configure an AI provider in Workspace → Settings → AI Provider, then regenerate.\n\n**Error:** ${err instanceof Error ? err.message : String(err)}`;
+    const fallbackResult = (kind, err) => ({
+        content: llmNotice(kind, err), summary: 'LLM unavailable', tags: ['needs-llm'],
+    });
+    const [businessDomainR, dataModelR, interactionPatternsR, errorCatalogueR, screenUnderstandingR] = await Promise.allSettled([
+        generateBusinessDomainFile(screenSummary, screens, askFn),
+        generateDataModelFile(screenSummary, screens, askFn, apiEndpoints),
+        generateInteractionPatternsFile(screenSummary, screens, askFn, askVisionFn, screenshots),
+        generateErrorCatalogueFile(screenSummary, screens, askFn, askVisionFn, screenshots, probeObservations),
+        generateScreenUnderstandingFile(screenSummary, screens, askFn, askVisionFn, screenshots),
+    ]);
+    const businessDomain = businessDomainR.status === 'fulfilled' ? businessDomainR.value : (console.error('[skill-file-agent] BUSINESS_DOMAIN failed:', businessDomainR.reason?.message), fallbackResult('Business Domain', businessDomainR.reason));
+    const dataModel = dataModelR.status === 'fulfilled' ? dataModelR.value : (console.error('[skill-file-agent] DATA_MODEL failed:', dataModelR.reason?.message), fallbackResult('Data Model', dataModelR.reason));
+    const interactionPatterns = interactionPatternsR.status === 'fulfilled' ? interactionPatternsR.value : (console.error('[skill-file-agent] INTERACTION_PATTERNS failed:', interactionPatternsR.reason?.message), fallbackResult('Interaction Patterns', interactionPatternsR.reason));
+    const errorCatalogue = errorCatalogueR.status === 'fulfilled' ? errorCatalogueR.value : (console.error('[skill-file-agent] ERROR_CATALOGUE failed:', errorCatalogueR.reason?.message), fallbackResult('Error Catalogue', errorCatalogueR.reason));
+    const screenUnderstanding = screenUnderstandingR.status === 'fulfilled' ? screenUnderstandingR.value : (console.error('[skill-file-agent] SCREEN_UNDERSTANDING failed:', screenUnderstandingR.reason?.message), fallbackResult('Screen Understanding', screenUnderstandingR.reason));
+    await Promise.allSettled([
+        sfEnabled('BUSINESS_DOMAIN') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'BUSINESS_DOMAIN', businessDomain.content, { summary: businessDomain.summary, tags: businessDomain.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('BUSINESS_DOMAIN'), ...meta('BUSINESS_DOMAIN', businessDomain.content, 'llm') }),
+        sfEnabled('DATA_MODEL') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'DATA_MODEL', dataModel.content, { summary: dataModel.summary, tags: dataModel.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('DATA_MODEL'), ...meta('DATA_MODEL', dataModel.content, 'llm') }),
+        sfEnabled('INTERACTION_PATTERNS') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'INTERACTION_PATTERNS', interactionPatterns.content, { summary: interactionPatterns.summary, tags: interactionPatterns.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('INTERACTION_PATTERNS'), ...meta('INTERACTION_PATTERNS', interactionPatterns.content, 'llm') }),
+        sfEnabled('ERROR_CATALOGUE') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'ERROR_CATALOGUE', errorCatalogue.content, { summary: errorCatalogue.summary, tags: errorCatalogue.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('ERROR_CATALOGUE'), ...meta('ERROR_CATALOGUE', errorCatalogue.content, 'llm') }),
+        sfEnabled('SCREEN_UNDERSTANDING') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'SCREEN_UNDERSTANDING', screenUnderstanding.content, { summary: screenUnderstanding.summary, tags: screenUnderstanding.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('SCREEN_UNDERSTANDING'), ...meta('SCREEN_UNDERSTANDING', screenUnderstanding.content, 'vision') }),
+    ]);
+    // ── Phase C: LLM structural (uses Phase A+B; vision for design) ──────────
+    // Same allSettled pattern — one vision failure must not kill all three files.
+    console.log('[skill-file-agent] Phase C: LLM structural skill files (vision)');
+    // probeObservations already populated before Phase B
+    const [visualBaselineR, componentLibraryR, elementBehaviorsR] = await Promise.allSettled([
+        generateVisualBaselineFile(screenSummary, screens, askFn, askVisionFn, screenshots),
+        generateComponentLibraryFile(screenSummary, screens, techStack.content, askFn),
+        generateElementBehaviorsFile(screenSummary, screens, askFn, probeObservations),
+    ]);
+    const visualBaseline = visualBaselineR.status === 'fulfilled' ? visualBaselineR.value : (console.error('[skill-file-agent] VISUAL_BASELINE failed:', visualBaselineR.reason?.message), fallbackResult('Visual Baseline', visualBaselineR.reason));
+    const componentLibrary = componentLibraryR.status === 'fulfilled' ? componentLibraryR.value : (console.error('[skill-file-agent] COMPONENT_LIBRARY failed:', componentLibraryR.reason?.message), fallbackResult('Component Library', componentLibraryR.reason));
+    const elementBehaviors = elementBehaviorsR.status === 'fulfilled' ? elementBehaviorsR.value : (console.error('[skill-file-agent] ELEMENT_BEHAVIORS failed:', elementBehaviorsR.reason?.message), fallbackResult('Element Behaviors', elementBehaviorsR.reason));
+    await Promise.allSettled([
+        sfEnabled('VISUAL_BASELINE') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'VISUAL_BASELINE', visualBaseline.content, { summary: visualBaseline.summary, tags: visualBaseline.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('VISUAL_BASELINE'), ...meta('VISUAL_BASELINE', visualBaseline.content, 'vision') }),
+        sfEnabled('COMPONENT_LIBRARY') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'COMPONENT_LIBRARY', componentLibrary.content, { summary: componentLibrary.summary, tags: componentLibrary.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('COMPONENT_LIBRARY'), ...meta('COMPONENT_LIBRARY', componentLibrary.content, 'vision') }),
+        sfEnabled('ELEMENT_BEHAVIORS') && app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'ELEMENT_BEHAVIORS', elementBehaviors.content, { summary: elementBehaviors.summary, tags: elementBehaviors.tags, source: 'AUTO', approvalStatus: sfApprovalStatus('ELEMENT_BEHAVIORS'), ...meta('ELEMENT_BEHAVIORS', elementBehaviors.content, 'vision') }),
+    ]);
+    // ── Phase D: Coverage matrix (live DB query — no LLM, no DOM) ────────────
+    // Screens are already persisted at this point, so the live refresh works for
+    // a fresh crawl too (all counts 0 until tests are generated).
+    await Promise.allSettled([
+        refreshCoverageMatrix(tenantId, projectId),
+        refreshArtifactKnowledgeSkillFile(tenantId, projectId),
+        refreshTestCasesSkillFile(tenantId, projectId),
+        refreshRequirementsCoverageSkillFile(tenantId, projectId),
+        refreshTestDataSkillFile(tenantId, projectId),
+        refreshHealingLogSkillFile(tenantId, projectId),
+        refreshLocatorInventorySkillFile(tenantId, projectId),
+    ]);
+    console.log(`[skill-file-agent] ✓ 15 skill files generated for project ${projectId}`);
+}
+// ─── TIER 1: Zero-cost Platform Intelligence ─────────────────────────────────
+/** TECH_STACK — purely from DOM data extracted during crawl */
+function generateTechStackFile(screens, apiEndpoints) {
+    // Collect all CSS classes from element notes
+    const cssClasses = screens
+        .flatMap((s) => s.elements.map((e) => {
+        try {
+            return JSON.parse(e.notes ?? '{}').cssClass;
+        }
+        catch {
+            return null;
+        }
+    }))
+        .filter((c) => !!c);
+    const classSet = new Set(cssClasses);
+    // Detect UI frameworks from CSS class signatures
+    const uiLibrary = [...classSet].some((c) => /^Mui[A-Z]/.test(c)) ? 'Material-UI (MUI)' :
+        [...classSet].some((c) => /^ant-/.test(c)) ? 'Ant Design' :
+            [...classSet].some((c) => /^chakra-/.test(c)) ? 'Chakra UI' :
+                [...classSet].some((c) => /^(btn|container|row|col-\w+)$/.test(c)) ? 'Bootstrap' :
+                    [...classSet].some((c) => /^(text-|flex|grid|px-|py-|mt-|mb-|bg-|border-)/.test(c)) ? 'Tailwind CSS' :
+                        'Custom CSS (no recognized framework classes)';
+    // Detect API style from endpoints
+    const hasGraphQL = apiEndpoints?.some((e) => /graphql|gql/i.test(e.urlPattern));
+    const hasTrpc = apiEndpoints?.some((e) => /trpc/i.test(e.urlPattern));
+    const apiStyle = hasGraphQL ? 'GraphQL' : hasTrpc ? 'tRPC' : apiEndpoints?.length ? 'REST' : 'Unknown (no API calls captured)';
+    // Infer version/api prefix from URL patterns
+    const versionMatch = apiEndpoints
+        ?.map((e) => e.urlPattern.match(/\/v(\d+)\//)?.[1])
+        .find(Boolean);
+    const apiVersion = versionMatch ? `v${versionMatch}` : 'not versioned or not detected';
+    // Detect SSR vs SPA from URL patterns (presence of file extensions = SSR)
+    const hasFileExtensions = screens.some((s) => /\.(php|html|erb|blade)($|\?)/.test(s.url ?? ''));
+    const appType = hasFileExtensions ? 'Server-Side Rendered (SSR)' : 'Single Page Application (SPA)';
+    // Notable CSS classes for component detection
+    const uniqueClasses = [...classSet].slice(0, 40).join(', ');
+    const content = `# Tech Stack
+> Auto-generated from DOM class analysis + network interception during crawl.
+> Confidence: HIGH for UI library, MEDIUM for framework, LOW for build tool.
+
+## Application Type
+${appType}
+
+## UI Component Library
+${uiLibrary}
+
+## API Style
+- Type: **${apiStyle}**
+- Version: ${apiVersion}
+- Base URL: ${apiEndpoints?.length ? `/${apiEndpoints[0]?.urlPattern.split('/').slice(1, 3).join('/')}` : 'not detected'}
+
+## Detected CSS Classes (component library signals)
+\`\`\`
+${uniqueClasses || 'No CSS classes captured — DOM extraction may need tuning'}
+\`\`\`
+
+## Endpoint Patterns Captured
+${apiEndpoints?.slice(0, 20).map((e) => `- \`${e.method} ${e.urlPattern}\``).join('\n') || '- No API endpoints captured during crawl'}
+
+## Test Implications
+- **Locator strategy**: ${uiLibrary.includes('MUI') ? 'Use `getByRole()` — MUI generates dynamic class suffixes, CSS classes unreliable' : uiLibrary.includes('Tailwind') ? 'Use `data-testid` or semantic attributes — Tailwind classes are layout utilities, not component identifiers' : 'CSS classes may be stable for locators'}
+- **Framework**: Use Playwright's \`waitForLoadState("networkidle")\` for SPA navigation
+- **API mocking**: Intercept \`${apiStyle === 'GraphQL' ? '/graphql' : apiEndpoints?.[0]?.urlPattern.split('/{id}')[0] ?? '/api'}\` for integration tests
+`;
+    const tags = [
+        uiLibrary.split(' ')[0].toLowerCase(),
+        apiStyle.toLowerCase(),
+        appType.includes('SPA') ? 'spa' : 'ssr',
+    ];
+    return { content, summary: `Tech stack: ${uiLibrary}, ${apiStyle} API`, tags };
+}
+/** AUTH_SESSION — from network request patterns + redirect behavior */
+function generateAuthSessionFile(screens, apiEndpoints) {
+    const endpoints = apiEndpoints ?? [];
+    // Detect auth endpoints
+    const hasOAuth = endpoints.some((e) => /\/(oauth|auth\/(google|github|facebook|microsoft|apple))/i.test(e.urlPattern));
+    const hasJWT = endpoints.some((e) => /\/(auth\/login|auth\/signin|auth\/token)/i.test(e.urlPattern));
+    const has2FA = endpoints.some((e) => /\/(totp|2fa|otp|verify|mfa)/i.test(e.urlPattern));
+    const hasRefresh = endpoints.some((e) => /\/(auth\/refresh|token\/refresh)/i.test(e.urlPattern));
+    const hasLogout = endpoints.some((e) => /\/(auth\/logout|signout|sign-out)/i.test(e.urlPattern));
+    // Detect auth-related screens from screen names
+    const screenNames = screens.map((s) => s.name.toLowerCase());
+    const hasLoginScreen = screenNames.some((n) => /login|signin/.test(n));
+    const hasRegisterScreen = screenNames.some((n) => /register|signup|sign-up/.test(n));
+    const hasForgotScreen = screenNames.some((n) => /forgot|reset|recover/.test(n));
+    // Classify auth type
+    // If no login screen was seen but protected screens exist → crawl used a pre-captured session
+    const hasProtectedScreens = screens.some((s) => s.url && !/^(\/|\/home|\/index)?$/.test(new URL(s.url).pathname ?? '/'));
+    const authType = hasOAuth
+        ? 'OAuth 2.0 (social providers detected)'
+        : hasJWT
+            ? 'JWT Bearer token'
+            : hasLoginScreen
+                ? 'Session-based or JWT (login screen detected, auth endpoint pattern unclear)'
+                : (!hasLoginScreen && hasProtectedScreens)
+                    ? 'Session-based cookie auth (pre-captured via ZeTa session capture — no login screen visited during crawl)'
+                    : 'Unknown (no login screen or auth endpoints detected)';
+    // Detect e-commerce context for targeted no-auth warning
+    const isEcommerce = screens.some((s) => /\/(shop|product|cart|checkout|woocommerce)/i.test(s.url ?? ''));
+    const noAuthWarning = !hasLoginScreen && !hasOAuth && !hasJWT && isEcommerce ? `
+## ⚠️ E-Commerce Auth Note
+No login/register screens were discovered during this crawl.
+Typical WooCommerce stores have:
+- \`/my-account/\` — Customer account dashboard
+- \`/my-account/orders/\` — Order history
+- \`/checkout/\` (logged-in flow) — Checkout with saved address
+These pages may exist but weren't encountered during the automated crawl.
+**Action required**: Manually verify these routes exist and add auth credentials in Project Settings → Credentials if needed for full coverage.
+` : '';
+    // OAuth providers
+    const oauthProviders = endpoints
+        .filter((e) => /\/(oauth|auth)\/(google|github|facebook|microsoft|apple)/i.test(e.urlPattern))
+        .map((e) => {
+        const m = e.urlPattern.match(/\/(google|github|facebook|microsoft|apple)/i);
+        return m ? m[1] : null;
+    })
+        .filter(Boolean);
+    const content = `# Authentication & Session Model
+> Auto-generated from network endpoint analysis during crawl.
+> Verify manually: token storage key, session timeout value.
+
+## Auth Type
+**${authType}**
+
+## Auth Endpoints Detected
+${endpoints.filter((e) => /auth|login|logout|token|session|oauth/i.test(e.urlPattern))
+        .slice(0, 10)
+        .map((e) => `- \`${e.method} ${e.urlPattern}\``)
+        .join('\n') || '- None captured (AI login may have occurred before network interception started)'}
+
+## Features Detected
+- OAuth social providers: ${oauthProviders.length > 0 ? oauthProviders.join(', ') : 'none detected'}
+- Two-Factor Authentication (2FA/TOTP): ${has2FA ? '✅ Detected' : '❌ Not detected'}
+- Token refresh endpoint: ${hasRefresh ? '✅ Detected' : '❌ Not detected'}
+- Logout endpoint: ${hasLogout ? '✅ Detected' : '❌ Not detected'}
+
+## Screens Discovered
+- Login screen: ${hasLoginScreen ? '✅' : '❌'}
+- Registration screen: ${hasRegisterScreen ? '✅' : '❌'}
+- Forgot/reset password: ${hasForgotScreen ? '✅' : '❌'}
+
+## Test Preconditions
+- All protected tests MUST call the login endpoint and store the response token/cookie.
+- Recommended setup: \`beforeAll\` → call POST ${endpoints.find((e) => /auth\/login|signin/i.test(e.urlPattern))?.urlPattern ?? '/api/auth/login'} → store token in test context.
+- For storageState: capture session once with Playwright codegen, store encrypted JSON in project settings.
+- 2FA tests: require \`oneTimeCode\` parameter (see crawler auth configuration).
+
+## Security Test Targets
+- Test session fixation: verify token changes after login
+- Test token expiry: use expired token → expect 401
+${has2FA ? '- Test 2FA bypass: skip OTP step → expect 401\n- Test invalid OTP: try 000000 → expect specific error message' : ''}
+- Test unauthorized routes: access protected screens without auth → expect redirect to /login
+${noAuthWarning}`;
+    const tags = [
+        hasOAuth ? 'oauth' : hasJWT ? 'jwt' : 'session',
+        has2FA ? '2fa' : 'no-2fa',
+        hasRefresh ? 'refresh-token' : '',
+        isEcommerce ? 'e-commerce' : '',
+    ].filter(Boolean);
+    return { content, summary: `Auth: ${authType}. 2FA: ${has2FA}. OAuth: ${oauthProviders.join(', ') || 'none'}.`, tags };
+}
+/** API_CONTRACT — from HAR-style endpoint capture during crawl */
+function generateApiContractFile(apiEndpoints) {
+    const endpoints = apiEndpoints ?? [];
+    if (endpoints.length === 0) {
+        return {
+            content: `# API Contract\n\n> No API endpoints were captured during the crawl.\n> This may happen if:\n> 1. The app loads data before crawl navigation starts\n> 2. The app uses WebSockets (not intercepted by XHR listener)\n> 3. All data is server-rendered with no client-side API calls\n\nRe-crawl after authentication to capture protected API endpoints.`,
+            summary: 'No API endpoints captured during crawl.',
+            tags: [],
+        };
+    }
+    // Group by resource type
+    const groups = {};
+    for (const ep of endpoints) {
+        const parts = ep.urlPattern.split('/').filter(Boolean);
+        const resource = parts.find((p) => !/^(api|v\d+|rest|gql|graphql)$/i.test(p)) ?? 'misc';
+        (groups[resource] ??= []).push(ep);
+    }
+    const content = `# API Contract
+> Auto-generated from network interception during crawl. ${endpoints.length} unique endpoint patterns captured.
+> **Review and annotate**: add request/response schemas when available.
+
+## Endpoints by Resource
+
+${Object.entries(groups).map(([resource, eps]) => `### ${resource.charAt(0).toUpperCase() + resource.slice(1)}
+${eps.map((e) => `- \`${e.method.padEnd(6)} ${e.urlPattern}\``).join('\n')}`).join('\n\n')}
+
+## Full Endpoint List (${endpoints.length} patterns)
+${endpoints.map((e) => `- \`${e.method} ${e.urlPattern}\``).join('\n')}
+
+## Test Implications
+- **API test setup**: Use Playwright \`page.route()\` or Supertest to intercept these endpoints
+- **Contract tests**: Verify each endpoint returns expected status codes (200/201/204/400/401/403/404)
+- **Integration test data**: Use \`{id}\` placeholder patterns for parameterized tests
+- **Security tests**: Test each endpoint without auth → expect 401; with wrong role → expect 403
+`;
+    return {
+        content,
+        summary: `${endpoints.length} API endpoints captured. Resources: ${Object.keys(groups).slice(0, 5).join(', ')}`,
+        tags: ['api', 'rest', ...Object.keys(groups).slice(0, 5)],
+    };
+}
+/** NAVIGATION_MAP — from screen URLs + flow graph */
+function generateNavigationMapFile(screens) {
+    const screenById = new Map(screens.map((s) => [s.id, s]));
+    const routes = screens
+        .filter((s) => s.url)
+        .map((s) => {
+        const url = s.url;
+        let pathname = '/';
+        try {
+            pathname = new URL(url).pathname;
+        }
+        catch {
+            pathname = url;
+        }
+        // Classify auth requirement from URL patterns
+        const isProtected = /\/(dashboard|project|settings|admin|workspace|tests|suites|runs|reports|profile|team|billing)/.test(pathname);
+        const isAdmin = /\/admin/.test(pathname);
+        const isPublic = /\/(login|register|signup|forgot|reset|pricing|about|landing|$)/.test(pathname) || !isProtected;
+        return {
+            id: s.id,
+            pathname,
+            screenName: s.name,
+            protected: !isPublic,
+            adminOnly: isAdmin,
+            elementCount: s.elements.length,
+        };
+    });
+    // Build navigation flow graph from element transitionsToScreenId edges
+    const transitionEdges = [];
+    for (const s of screens) {
+        const targets = s.elements
+            .filter((e) => e.transitionsToScreenId)
+            .map((e) => screenById.get(e.transitionsToScreenId)?.name)
+            .filter((name) => Boolean(name));
+        const unique = [...new Set(targets)];
+        if (unique.length > 0) {
+            transitionEdges.push(`- **${s.name}** → ${unique.map((t) => `\`${t}\``).join(', ')}`);
+        }
+    }
+    const navFlowsSection = transitionEdges.length > 0
+        ? `## Navigation Flows (BFS-discovered transitions)\n${transitionEdges.join('\n')}\n`
+        : '';
+    const content = `# Navigation Map & Routing
+> Auto-generated from discovered screens during crawl. Auth classification is inferred — verify manually.
+
+## Route Inventory (${routes.length} screens)
+
+| Route | Screen | Protected | Admin |
+|-------|--------|:---------:|:-----:|
+${routes.map((r) => `| \`${r.pathname}\` | ${r.screenName} | ${r.protected ? '✅' : '❌'} | ${r.adminOnly ? '✅' : '❌'} |`).join('\n')}
+
+## Navigation Groups
+${groupRoutesBySection(routes).map(([section, rs]) => `### ${section}\n${rs.map((r) => `- \`${r.pathname}\` — ${r.screenName} (${r.elementCount} elements)`).join('\n')}`).join('\n\n')}
+
+${navFlowsSection}## Test Implications
+- **Auth tests**: Navigate directly to protected routes without auth → expect redirect to \`/login\`
+- **Role tests**: Navigate to admin routes as non-admin → expect 403 or redirect
+- **Journey tests**: Follow the navigation flow from screen discovery (see flow graph in DB)
+- **Deep link tests**: Navigate directly to \`/path?next=<protected>\` → verify next param respected after login
+`;
+    return {
+        content,
+        summary: `${routes.length} routes: ${routes.filter((r) => r.protected).length} protected, ${routes.filter((r) => r.adminOnly).length} admin-only`,
+        tags: ['routing', 'navigation', 'auth-guards'],
+    };
+}
+/** LOCATOR_STRATEGY — from data-testid presence + ARIA attribute analysis */
+function generateLocatorStrategyFile(screens) {
+    const allElements = screens.flatMap((s) => s.elements.map((e) => ({ ...e, screenName: s.name })));
+    const hasRequired = allElements.filter((e) => {
+        try {
+            return JSON.parse(e.notes ?? '{}').required === 'true';
+        }
+        catch {
+            return false;
+        }
+    });
+    const inputElements = allElements.filter((e) => ['email', 'password', 'text', 'tel', 'date', 'number', 'url', 'file', 'textarea', 'select'].includes(e.role));
+    // Semantic role coverage: elements with typed roles (button, email, select, etc.)
+    const semanticRoleCount = allElements.filter((e) => ['button', 'submit', 'email', 'tel', 'search', 'select', 'checkbox', 'radio'].includes(e.role ?? '')).length;
+    // Locator hint coverage: elements with data-testid / aria-label / placeholder / label
+    const withLocatorHints = allElements.filter((e) => {
+        const notes = (() => { try {
+            return JSON.parse(e.notes ?? '{}');
+        }
+        catch {
+            return {};
+        } })();
+        return !!(notes.dataTestid || notes.ariaLabel || notes.placeholder || e.meaning);
+    }).length;
+    // Detect fragile patterns
+    const fragileByNthChild = allElements.filter((e) => e.meaning.match(/^\d+$/) || e.meaning.includes('item ')).length;
+    const content = `# Locator Strategy
+> Auto-generated from element analysis. Prescribes the safest locator strategy for this application.
+
+## Recommended Priority Order
+1. **\`data-testid\`** (most stable — never changes, 0 false positives)
+   - Locator hint coverage: **${Math.round((withLocatorHints / Math.max(allElements.length, 1)) * 100)}%** of elements have data-testid / aria-label / placeholder / label
+   - If missing: ask developers to add \`data-testid="[screen]-[element]-[type]"\` to key elements
+2. **ARIA role + accessible name** (excellent stability, semantic)
+   - Example: \`getByRole('button', { name: 'Sign In' })\`
+   - Semantic role coverage: **${Math.round((semanticRoleCount / Math.max(allElements.length, 1)) * 100)}%** of elements have typed roles (button, email, select, etc.)
+3. **Label text** (stable, affected by i18n changes)
+   - Example: \`getByLabel('Email address')\`
+   - Coverage: **${Math.round((inputElements.length / Math.max(allElements.length, 1)) * 100)}%** of form inputs
+4. **Placeholder text** (fragile — UI copy changes break tests)
+5. **CSS class** (AVOID for component libraries — generated dynamic suffixes)
+
+## Elements by Role (${allElements.length} total)
+${elementRoleSummary(allElements)}
+
+## Required Fields (${hasRequired.length})
+${hasRequired.slice(0, 10).map((e) => `- [${e.screenName}] \`${e.meaning}\` (${e.role}) — required, test empty submission`).join('\n') || '- None detected with required attribute'}
+
+## Fragile Locator Risks
+- Elements with numeric-only meanings: ${fragileByNthChild} (likely nth-child candidates — high brittleness)
+- Recommend: add \`data-testid\` to any element where the locator would use \`nth()\` or \`first()\`
+
+## Never Use
+- Dynamic CSS class suffixes: \`MuiButton-root-jss123\`, \`css-1234abc\`
+- XPath with positional predicates: \`//button[2]\`
+- \`nth-child\` without a parent locator constraint
+`;
+    return {
+        content,
+        summary: `${allElements.length} elements analyzed. ${hasRequired.length} required fields. Semantic role coverage: ${Math.round((semanticRoleCount / Math.max(allElements.length, 1)) * 100)}%. Locator hint coverage: ${Math.round((withLocatorHints / Math.max(allElements.length, 1)) * 100)}%.`,
+        tags: ['locators', 'selectors', 'stability', 'data-testid'],
+    };
+}
+/** PERFORMANCE_BASELINE — from Playwright performance metrics during crawl */
+function generatePerformanceBaselineFile(screens, metrics) {
+    if (!metrics || metrics.length === 0) {
+        const content = `# Performance Baseline
+> No performance metrics captured during this crawl.
+> To enable: pass \`performanceMetrics\` from Playwright \`page.evaluate(() => performance.getEntriesByType('navigation'))\` after each page load.
+
+## Expected Metrics to Capture
+- LCP (Largest Contentful Paint) — should be < 2500ms
+- FCP (First Contentful Paint) — should be < 1800ms
+- TTFB (Time to First Byte) — should be < 800ms
+
+## Manual Baseline
+For now, performance tests should assert:
+- Page loads within **3 seconds** on desktop
+- Page loads within **5 seconds** on mobile (emulated 4G)
+- No single API call exceeds **2 seconds** response time
+
+## Screens to Prioritize for Performance Testing
+${screens.slice(0, 5).map((s) => `- ${s.name} (${s.elements.length} elements — heavier page)`).join('\n')}
+`;
+        return { content, summary: 'No performance metrics captured.', tags: ['performance', 'lcp', 'cwv'] };
+    }
+    // Core Web Vitals thresholds (web.dev): LCP 2500/4000ms, CLS 0.1/0.25, FCP 1800/3000ms.
+    const rateScreen = (m) => {
+        const lcpBad = m.lcp != null && m.lcp >= 4000;
+        const lcpWarn = m.lcp != null && m.lcp >= 2500;
+        const clsBad = m.cls != null && m.cls >= 0.25;
+        const clsWarn = m.cls != null && m.cls >= 0.1;
+        const fcpWarn = m.fcp != null && m.fcp >= 1800;
+        if (m.lcp == null && m.cls == null && m.fcp == null)
+            return '—';
+        if (lcpBad || clsBad)
+            return '❌ Poor';
+        if (lcpWarn || clsWarn || fcpWarn)
+            return '⚠️ Needs Improvement';
+        return '✅ Good';
+    };
+    const content = `# Performance Baseline
+> Measured during crawl: LCP/CLS via buffered PerformanceObserver, FCP/TTFB via Navigation/Paint Timing. Updated after each crawl.
+
+## Per-Screen Metrics
+
+| Screen | LCP (ms) | FCP (ms) | TTFB (ms) | CLS | Status |
+|--------|:--------:|:--------:|:---------:|:---:|--------|
+${metrics.map((m) => `| ${m.screenName} | ${m.lcp != null ? m.lcp : 'N/A ⚠️'} | ${m.fcp ?? '—'} | ${m.ttfb ?? '—'} | ${m.cls ?? '—'} | ${rateScreen(m)} |`).join('\n')}
+
+Status thresholds (Core Web Vitals): LCP < 2500ms good / ≥ 4000ms poor · CLS < 0.1 good / ≥ 0.25 poor · FCP < 1800ms good.
+
+## Regression Thresholds (auto-enforced in performance TCs)
+- Flag if LCP increases by **> 500ms** vs this baseline
+- Flag if TTFB exceeds **800ms** (CDN/SSR degradation signal)
+- Flag if CLS increases by **> 0.05** vs this baseline
+- Flag if any bundle increases by **> 10%** (detect dependency bloat)
+
+## Slowest Screens (highest test priority)
+${[...metrics].sort((a, b) => (b.lcp ?? b.fcp ?? 0) - (a.lcp ?? a.fcp ?? 0)).slice(0, 3).map((m) => `- ${m.screenName}: LCP ${m.lcp ?? 'unknown'}ms, FCP ${m.fcp ?? 'unknown'}ms`).join('\n')}
+`;
+    const allLcpMissing = metrics.every((m) => !m.lcp);
+    const lcpWarning = allLcpMissing ? `
+## ⚠️ LCP Data Missing
+Largest Contentful Paint (LCP) was not measured during this crawl.
+For e-commerce sites, LCP is a critical conversion metric — every 100ms delay reduces sales.
+Product images and hero banners are typically the LCP element.
+
+**To capture LCP**: Re-run the crawl with performance metrics enabled in Project Settings.
+**Target**: LCP < 2500ms (good), < 4000ms (needs improvement), > 4000ms (poor)
+
+Current FCP readings suggest potential issues:
+${metrics
+        .filter((m) => (m.fcp ?? 0) > 4000)
+        .slice(0, 5)
+        .map((m) => `- **${m.screenName}**: ${m.fcp}ms FCP — likely slow LCP`)
+        .join('\n') || '- No screens with FCP > 4000ms detected'}
+` : '';
+    return {
+        content: content + lcpWarning,
+        summary: `Performance baseline: ${metrics.length} screens measured. Baseline captured for regression detection.${allLcpMissing ? ' LCP data missing.' : ''}`,
+        tags: ['performance', 'lcp', 'fcp', 'cwv', 'baseline'],
+    };
+}
+// ─── TIER 2: Domain Intelligence (LLM) ───────────────────────────────────────
+async function generateBusinessDomainFile(summary, screens, askFn) {
+    const screenNames = screens.map((s) => s.name).join(', ');
+    const screenUrls = screens.filter((s) => s.url).slice(0, 15).map((s) => s.url).join(', ');
+    const content = await askFn(`You are a senior business analyst reviewing a web application.
+Identify the application's domain, user types, user roles, core workflows, and key business rules.
+Only state what is clearly evident from screen names, URLs, and element purposes.
+Do NOT guess or make up features. If uncertain, say "unclear from crawl data."
+
+Output Markdown with these sections:
+## Application Type & Domain
+## Primary User Roles (from screens)
+## Core User Journeys (observable from screen flow)
+## Key Business Rules (observable from element constraints and screen flow)
+## Domain Vocabulary (key terms used in the UI)`, `Screen names discovered: ${screenNames}
+Screen URLs: ${screenUrls}
+
+Element summary (representative sample):
+${summary.slice(0, 2000)}
+
+Write a BUSINESS_DOMAIN skill file (Markdown). Be specific and factual. Max 400 words.`);
+    const tags = extractTags(content, ['e-commerce', 'saas', 'healthcare', 'finance',
+        'crm', 'hrm', 'dashboard', 'checkout', 'booking', 'marketplace', 'analytics', 'qa', 'testing']);
+    return {
+        content,
+        summary: `Application domain and functional classification from crawl analysis.`,
+        tags,
+    };
+}
+async function generateDataModelFile(_summary, screens, askFn, apiEndpoints) {
+    // Extract all input elements — include those without explicit constraints (email role implies email format, etc.)
+    const INPUT_FIELD_ROLES = ['email', 'password', 'text', 'tel', 'date', 'number', 'url', 'file', 'textarea', 'select', 'search', 'checkbox', 'radio', 'rich-text'];
+    const constrainedElements = screens
+        .flatMap((s) => s.elements.map((e) => ({ ...e, screenName: s.name })))
+        .filter((e) => {
+        if (INPUT_FIELD_ROLES.includes(e.role))
+            return true;
+        try {
+            const n = JSON.parse(e.notes ?? '{}');
+            return Object.keys(n).some((k) => ['pattern', 'min', 'max', 'minLength', 'maxLength', 'required', 'accept', 'multiple'].includes(k));
+        }
+        catch {
+            return false;
+        }
+    });
+    const constraintList = constrainedElements
+        .slice(0, 40)
+        .map((e) => {
+        try {
+            const attrs = JSON.parse(e.notes ?? '{}');
+            const constraints = Object.entries(attrs)
+                .filter(([k]) => k !== 'cssClass')
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            return `- [${e.screenName}] ${e.meaning} (${e.role}): ${constraints}`;
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter(Boolean)
+        .join('\n');
+    // Infer entity names from screen names + API endpoints
+    const entityNames = [
+        ...screens.map((s) => s.name.replace(/\s+list|s$/i, '')),
+        ...(apiEndpoints ?? []).map((e) => {
+            const parts = e.urlPattern.split('/').filter((p) => p && !p.startsWith('{') && !/^(api|v\d+|rest)$/i.test(p));
+            return parts[parts.length - 1] ?? '';
+        }),
+    ].filter(Boolean);
+    const uniqueEntities = [...new Set(entityNames.map((n) => n.charAt(0).toUpperCase() + n.slice(1)))].slice(0, 10);
+    const content = await askFn(`You are a data architect inferring the application's data model from UI evidence.
+ONLY use the field constraints and entity names provided. Do not invent fields that aren't shown.
+Output Markdown with these sections:
+## Discovered Entities (name + fields with constraints)
+## Field Constraint Summary (table: field, type, required, min, max, pattern)
+## Validation Rules (from HTML5 attributes — ground test boundary values in these)
+## Test Implications (which boundary values and equivalence classes these constraints define)`, `Inferred entities from screen names + API paths:
+${uniqueEntities.join(', ')}
+
+Field constraints extracted from DOM (HTML5 attributes):
+${constraintList || '- No constraints extracted yet — check crawler HTML5 attribute extraction'}
+
+Write a DATA_MODEL skill file (Markdown). Be precise. These constraints DIRECTLY determine test boundary values. Max 400 words.`);
+    return {
+        content,
+        summary: `Data model with ${constrainedElements.length} field constraints. Entities: ${uniqueEntities.slice(0, 5).join(', ')}`,
+        tags: ['data-model', 'validation', 'constraints', 'boundary-values'],
+    };
+}
+async function generateScreenUnderstandingFile(summary, screens, _askFn, askVisionFn, screenshots) {
+    const PRIMARY_LIMIT = 40;
+    const screenList = screens.slice(0, PRIMARY_LIMIT).map((s) => {
+        const elements = s.elements.slice(0, 10).map((e) => e.meaning ?? e.role).filter(Boolean);
+        return `- **${s.name}** (${s.url ?? 'no URL'}): ${elements.join(', ') || 'no elements captured'}`;
+    }).join('\n');
+    // Additional screens condensed table (GAP-SF-10)
+    const overflowScreens = screens.slice(PRIMARY_LIMIT);
+    const overflowSection = overflowScreens.length > 0
+        ? `\n\n## Additional Screens (${overflowScreens.length} more)\n\n| Screen | URL | Elements |\n|---|---|---|\n${overflowScreens.map((s) => {
+            let pathname = s.url ?? 'N/A';
+            try {
+                pathname = new URL(s.url).pathname;
+            }
+            catch { /* keep as-is */ }
+            return `| ${s.name} | \`${pathname}\` | ${s.elements.length} |`;
+        }).join('\n')}`
+        : '';
+    const content = await askVisionFn(`You are a senior QA architect documenting a web application for AI-assisted test generation.
+Write a SCREEN_UNDERSTANDING skill file that gives a QA engineer a clear picture of each screen's
+purpose, user roles, key interactions, pre/post conditions, and critical test focus areas.
+Only describe what is evident from the data provided — do not invent features.
+Output Markdown with an H2 "## Screen Inventory" overview table, then H3 sections per screen.`, `## Application Overview
+${summary.slice(0, 1500)}
+
+## Screen List (${Math.min(screens.length, PRIMARY_LIMIT)} of ${screens.length} screens)
+${screenList}
+
+## Task
+Write a SCREEN_UNDERSTANDING skill file (Markdown). For each screen include:
+- **Purpose**: one sentence
+- **User roles**: who accesses this screen
+- **Key interactions**: bullet list of primary actions
+- **Pre-conditions**: what state must be true before arriving here
+- **Test focus**: edge cases, error states, and regression risks
+
+Keep each screen section concise (4–6 bullet points max). Start with a summary table.`, screenshots);
+    return {
+        content: content + overflowSection,
+        summary: `Per-screen documentation for ${screens.length} screens covering purpose, roles, interactions, and test focus.`,
+        tags: ['screens', 'user-journeys', 'ux', 'test-focus'],
+    };
+}
+// ─── TIER 3: Behavioral Intelligence (LLM + vision) ──────────────────────────
+async function generateInteractionPatternsFile(summary, screens, _askFn, askVisionFn, screenshots) {
+    // Extract ARIA patterns that reveal interaction conventions
+    const ariaPatterns = screens
+        .flatMap((s) => s.elements.map((e) => {
+        try {
+            const n = JSON.parse(e.notes ?? '{}');
+            return { screenName: s.name, meaning: e.meaning, role: e.role, ...n };
+        }
+        catch {
+            return null;
+        }
+    }))
+        .filter(Boolean)
+        .filter((e) => e.ariaHasPopup || e.ariaExpanded || e.ariaDisabled || e.autocomplete)
+        .slice(0, 20)
+        .map((e) => `- [${e.screenName}] ${e.meaning}: ${Object.entries(e).filter(([k]) => k.startsWith('aria')).map(([k, v]) => `${k}=${v}`).join(', ')}`)
+        .join('\n');
+    const visionHint = screenshots.length > 0
+        ? `\n\nYou have ${screenshots.length} screenshot(s). From them, identify:
+1. Where error messages appear (below field / in a toast / in a banner / in a modal?)
+2. Where loading states appear (button spinner / skeleton screen / progress bar in header?)
+3. How success is communicated (redirect / inline success / toast notification?)
+4. Navigation pattern (sidebar / top nav / tab bar?)
+5. Form layout (single column / two-column / wizard/steps?)`
+        : '';
+    const content = await askVisionFn(`You are a QA engineer documenting behavioral conventions of a web application.
+These conventions apply to EVERY test case as preconditions and assertions.
+Be precise and factual. Only document what is visually or structurally observable.
+Output Markdown with these sections:
+## Error Display Convention (WHERE and HOW errors appear)
+## Loading State Convention (what happens while data loads)
+## Form Submission Pattern (validation timing, success/failure handling)
+## Navigation Convention (primary nav structure and behavior)
+## Notification/Toast Style (types, duration, position)
+## Keyboard Navigation (Tab order, Escape behavior, Enter to submit)`, `Cross-screen element patterns:
+${summary.slice(0, 1500)}
+
+ARIA interaction patterns detected:
+${ariaPatterns || '- No ARIA interaction patterns captured'}
+${visionHint}
+
+Write an INTERACTION_PATTERNS skill file (Markdown). These patterns ground state transition tests. Max 400 words.`, screenshots);
+    return {
+        content,
+        summary: `Behavioral conventions: error display, loading states, form submission, navigation patterns.`,
+        tags: ['interactions', 'error-handling', 'loading-states', 'form-patterns'],
+    };
+}
+async function generateErrorCatalogueFile(summary, screens, _askFn, askVisionFn, screenshots, probeObs) {
+    const visionHint = screenshots.length > 0
+        ? `\n\nYou have ${screenshots.length} screenshot(s). Look for any visible error messages, validation messages, warning banners, or empty-state messages in the screenshots. Extract the EXACT text of any error messages you can read.`
+        : '';
+    const validationFacts = [];
+    const successFacts = [];
+    if (probeObs?.size) {
+        for (const s of screens) {
+            for (const p of (probeObs.get(s.id) ?? [])) {
+                if (p.observationType === 'VALIDATION_ERROR') {
+                    validationFacts.push(`- [${s.name}] Field "${p.elementMeaning}": trigger="${p.triggeredBy}" → "${(p.observedText ?? '').slice(0, 150)}"`);
+                }
+                else if (p.observationType === 'SUCCESS_MESSAGE') {
+                    successFacts.push(`- [${s.name}] After "${p.triggeredBy}": "${(p.observedText ?? '').slice(0, 150)}"`);
+                }
+            }
+        }
+    }
+    const groundTruthHint = [
+        validationFacts.length > 0
+            ? `\n\n## GROUND-TRUTH Validation Errors (observed by interactive probe — COPY VERBATIM, do not paraphrase):\n${validationFacts.join('\n')}`
+            : '',
+        successFacts.length > 0
+            ? `\n\n## GROUND-TRUTH Success Messages (observed by interactive probe — include verbatim in "Empty State Messages" or a new "Success Messages" section):\n${successFacts.join('\n')}`
+            : '',
+    ].join('');
+    const requiredFields = screens
+        .flatMap((s) => s.elements.map((e) => {
+        try {
+            const n = JSON.parse(e.notes ?? '{}');
+            return n.required === 'true' ? `[${s.name}] ${e.meaning} (${e.role})` : null;
+        }
+        catch {
+            return null;
+        }
+    }))
+        .filter(Boolean)
+        .slice(0, 20)
+        .join('\n');
+    const content = await askVisionFn(`You are a QA engineer cataloguing error messages for a web application.
+Your goal: document the EXACT error text that tests should assert against.
+Without exact text, tests assert "an error exists" — with exact text, tests assert "Email is required" — far more reliable.
+Output Markdown with these sections:
+## Validation Error Messages (per field, exact text if known)
+## API/Server Error Messages (HTTP status → displayed message)
+## Empty State Messages (what shows when a list is empty)
+## Warning Messages (non-blocking, informational)
+## Error Display Location (which field shows which error)`, `Required fields that need error message documentation:
+${requiredFields || '- No required fields detected with certainty'}
+
+Screen context:
+${summary.slice(0, 1000)}
+${groundTruthHint}
+${visionHint}
+
+Write an ERROR_CATALOGUE skill file (Markdown). Use "UNKNOWN — verify manually" for messages you cannot determine. Max 400 words.`, screenshots);
+    return {
+        content,
+        summary: `Error message catalogue for test assertions. Covers validation, API errors, and empty states.`,
+        tags: ['errors', 'validation', 'error-messages', 'assertions'],
+    };
+}
+// ─── TIER 4: Structural Intelligence (LLM + vision) ──────────────────────────
+async function generateVisualBaselineFile(summary, _screens, _askFn, askVisionFn, screenshots) {
+    const visionHint = screenshots.length > 0
+        ? `\n\nYou have ${screenshots.length} screenshot(s) of the application.
+From them, extract:
+1. **Color palette** — primary, secondary, background, text, danger, success, warning colors (use hex or RGB)
+2. **Typography** — font family for headings and body text, approximate weights/sizes
+3. **Layout structure** — sidebar width, header height, content area, footer
+4. **Dark/light mode** — which mode is active in the screenshot?
+5. **Design style** — glassmorphism, flat, material, neo-brutalist, or minimal?
+6. **Contrast ratios** — flag any text that appears low-contrast (estimate visually)`
+        : `\n\nNo screenshots available. Document only what can be inferred from element patterns and CSS classes.`;
+    const content = await askVisionFn(`You are a UI/UX specialist and accessibility auditor reviewing a web application.
+Extract factual visual design information ONLY from what is directly observable.
+Do not guess or assume. If a color cannot be confirmed, say "NOT CONFIRMED — requires manual verification."
+Output Markdown with these sections:
+## Color Palette (primary, secondary, background, text, status colors with hex values)
+## Typography (font families, size/weight hierarchy)
+## Layout Structure (per screen type: auth, dashboard, form, list)
+## Contrast Ratios (flag any that appear below 4.5:1 for AA compliance)
+## Design System (component library visual style indicators)
+## Dark/Light Mode Support`, `Element summary (design pattern signals):
+${summary.slice(0, 1000)}
+${visionHint}
+
+Write a VISUAL_BASELINE skill file (Markdown). Max 400 words. State confidence level per item (HIGH/MEDIUM/LOW).`, screenshots);
+    return {
+        content,
+        summary: `Visual design baseline: color palette, typography, layout structure, contrast ratios.`,
+        tags: ['design-system', 'colors', 'typography', 'accessibility', 'wcag'],
+    };
+}
+async function generateComponentLibraryFile(summary, screens, techStackContent, askFn) {
+    const componentPatterns = identifyComponentPatterns(screens);
+    // Extract CSS class-based component hints
+    const cssComponentHints = screens
+        .flatMap((s) => s.elements.map((e) => {
+        try {
+            const cls = JSON.parse(e.notes ?? '{}').cssClass;
+            return cls ? `${cls} (on ${s.name})` : null;
+        }
+        catch {
+            return null;
+        }
+    }))
+        .filter(Boolean)
+        .slice(0, 20)
+        .join(', ');
+    // Find complex single-screen components (high element-count unique patterns)
+    const roleFrequency = new Map();
+    for (const s of screens) {
+        const rolesOnScreen = new Set(s.elements.map((e) => e.role));
+        for (const role of rolesOnScreen) {
+            const entry = roleFrequency.get(role) ?? { screens: [], count: 0 };
+            entry.screens.push(s.name);
+            entry.count++;
+            roleFrequency.set(role, entry);
+        }
+    }
+    const uniqueHeavyComponents = screens
+        .filter((s) => s.elements.length >= (parseInt(process.env.SKILL_FILE_MIN_ELEMENTS ?? '') || 10))
+        .map((s) => `- **${s.name}**: ${s.elements.length} elements`)
+        .slice(0, 5)
+        .join('\n');
+    const content = await askFn(`You are a QA engineer documenting reusable UI component behaviors.
+Primary section: components that appear on MULTIPLE screens (highest regression risk).
+Secondary section "Screen-Specific Components": complex components that appear on only one screen but have high element count — these also need test coverage.
+For each component: document its name, screens it appears on, default state, key behaviors, and edge cases to test.
+Output Markdown with one section per component. Use the CSS class hints to identify the component library.`, `Tech stack context:
+${techStackContent.slice(0, 500)}
+
+Recurring role patterns across screens:
+${componentPatterns}
+
+CSS class component hints:
+${cssComponentHints || 'No CSS class hints available'}
+
+Complex single-screen areas (high element count — may contain specialized components):
+${uniqueHeavyComponents || 'None detected'}
+
+Screen element summary:
+${summary.slice(0, 1500)}
+
+Write a COMPONENT_LIBRARY skill file (Markdown). Document multi-screen components in main sections, then add a "## Screen-Specific Components" section for complex unique widgets. Max 600 words.`);
+    const tags = extractTags(content, ['table', 'modal', 'form', 'navigation', 'sidebar',
+        'dropdown', 'pagination', 'search', 'filter', 'tabs', 'accordion', 'toast', 'dialog', 'data-grid']);
+    return {
+        content,
+        summary: `Reusable component library: ${tags.slice(0, 5).join(', ')} identified.`,
+        tags,
+    };
+}
+/**
+ * Derive concrete valid/invalid example values and state descriptions from
+ * HTML5 constraint attributes — deterministic, no LLM. This is what fills the
+ * Valid/Invalid Example columns that used to come back as "-".
+ */
+function deriveConstraintExamples(role, expectedData, attrs) {
+    const required = attrs.required === 'true';
+    const minLength = attrs.minLength ? parseInt(attrs.minLength, 10) : undefined;
+    const maxLength = attrs.maxLength ? parseInt(attrs.maxLength, 10) : undefined;
+    const min = attrs.min !== undefined && attrs.min !== '' ? Number(attrs.min) : undefined;
+    const max = attrs.max !== undefined && attrs.max !== '' ? Number(attrs.max) : undefined;
+    const step = attrs.step ? Number(attrs.step) : undefined;
+    const constraintParts = [];
+    if (required)
+        constraintParts.push('required');
+    if (attrs.pattern)
+        constraintParts.push(`pattern: \`${attrs.pattern}\``);
+    if (minLength !== undefined)
+        constraintParts.push(`minLength ${minLength}`);
+    if (maxLength !== undefined)
+        constraintParts.push(`maxLength ${maxLength}`);
+    if (min !== undefined && !Number.isNaN(min))
+        constraintParts.push(`min ${attrs.min}`);
+    if (max !== undefined && !Number.isNaN(max))
+        constraintParts.push(`max ${attrs.max}`);
+    if (step !== undefined && !Number.isNaN(step))
+        constraintParts.push(`step ${attrs.step}`);
+    if (attrs.accept)
+        constraintParts.push(`accept ${attrs.accept}`);
+    if (attrs.autocomplete)
+        constraintParts.push(`autocomplete ${attrs.autocomplete}`);
+    if (attrs.multiple === 'true')
+        constraintParts.push('multiple');
+    const kind = expectedData ?? role;
+    let valid = '';
+    const invalid = [];
+    const padTo = (base, len) => len && base.length < len ? base + 'x'.repeat(len - base.length) : base;
+    switch (kind) {
+        case 'valid_email':
+        case 'email':
+            valid = 'user@example.com';
+            invalid.push('`name@company`', '`abc`');
+            break;
+        case 'password':
+            valid = `\`${padTo('P@ssw0rd!', minLength)}\``;
+            if (minLength)
+                invalid.push(`\`${'a'.repeat(Math.max(1, minLength - 1))}\` (${minLength - 1} chars < minLength)`);
+            else
+                invalid.push('`123` (too weak/short)');
+            break;
+        case 'phone':
+        case 'tel':
+            valid = '`+1 555 0100`';
+            invalid.push('`12ab`');
+            break;
+        case 'date':
+            valid = attrs.min && /^\d{4}-\d{2}-\d{2}$/.test(attrs.min) ? `\`${attrs.min}\`` : '`2026-01-15`';
+            invalid.push('`2026-02-31` (impossible date)');
+            if (attrs.min)
+                invalid.push(`date before \`${attrs.min}\``);
+            if (attrs.max)
+                invalid.push(`date after \`${attrs.max}\``);
+            break;
+        case 'number':
+            valid = `\`${min !== undefined && !Number.isNaN(min) ? min : (max !== undefined && !Number.isNaN(max) ? max : 42)}\``;
+            if (min !== undefined && !Number.isNaN(min))
+                invalid.push(`\`${min - (step && !Number.isNaN(step) ? step : 1)}\` (< min)`);
+            if (max !== undefined && !Number.isNaN(max))
+                invalid.push(`\`${max + (step && !Number.isNaN(step) ? step : 1)}\` (> max)`);
+            invalid.push('`abc` (non-numeric)');
+            break;
+        case 'url':
+            valid = '`https://example.com`';
+            invalid.push('`not-a-url`');
+            break;
+        case 'file':
+            valid = attrs.accept ? `file matching \`${attrs.accept}\`` : 'any file';
+            if (attrs.accept)
+                invalid.push(`file NOT matching \`${attrs.accept}\``);
+            break;
+        case 'one_time_code':
+            valid = '`123456`';
+            invalid.push('`00` (wrong length)', 'expired code');
+            break;
+        case 'checkbox':
+            valid = 'checked / unchecked';
+            if (required)
+                invalid.push('unchecked (required)');
+            break;
+        case 'select':
+        case 'select-one': {
+            try {
+                const opts = attrs.selectOptions ? JSON.parse(attrs.selectOptions) : [];
+                const first = opts.find((o) => o.v !== '');
+                valid = first ? `\`${first.l}\`` : 'any listed option';
+                invalid.push('value not in options list');
+            }
+            catch {
+                valid = 'any listed option';
+                invalid.push('value not in options list');
+            }
+            break;
+        }
+        case 'search_term':
+            valid = '`dashboard`';
+            break;
+        default:
+            if (['text', 'textarea', 'rich-text'].includes(role)) {
+                valid = `\`${padTo('Sample text', minLength)}\``;
+                if (minLength)
+                    invalid.push(`${minLength - 1}-char string (< minLength)`);
+                if (maxLength)
+                    invalid.push(`${maxLength + 1}-char string (> maxLength)`);
+                if (attrs.pattern)
+                    invalid.push(`string violating \`${attrs.pattern}\``);
+            }
+    }
+    if (required && !invalid.some((i) => i.includes('empty')))
+        invalid.unshift('(empty) — required');
+    // State description from static attributes; "Static" only when nothing else is known.
+    const states = [];
+    if (attrs.disabled === 'true')
+        states.push('starts disabled');
+    if (attrs.readOnly === 'true')
+        states.push('read-only');
+    if (attrs.buttonType === 'submit')
+        states.push('triggers form submit; typically disabled until form valid');
+    if (attrs.isDestructive === 'true')
+        states.push('destructive action — expect confirm step');
+    if (required)
+        states.push('invalid → valid once constraints satisfied');
+    return {
+        constraints: constraintParts.join('; ') || '—',
+        valid: valid || '—',
+        invalid: invalid.slice(0, 3).join('; ') || '—',
+        states: states.join('; ') || 'Static',
+    };
+}
+const INPUT_ROLES = ['email', 'password', 'text', 'tel', 'date', 'number', 'url', 'file',
+    'textarea', 'select', 'select-one', 'checkbox', 'radio', 'search', 'rich-text'];
+async function generateElementBehaviorsFile(summary, screens, askFn, probeObservations) {
+    // Deterministic constraint tables from HTML5 attributes — the LLM only adds
+    // optional prose, so Valid/Invalid columns are never empty again.
+    const MAX_ROWS_PER_SCREEN = 15;
+    const MAX_TOTAL_ROWS = 150;
+    let totalRows = 0;
+    let constrainedCount = 0;
+    const screenSections = screens.map((s) => {
+        if (totalRows >= MAX_TOTAL_ROWS)
+            return '';
+        const probes = probeObservations?.get(s.id) ?? [];
+        const errorByElement = new Map();
+        for (const p of probes) {
+            if (p.observationType === 'VALIDATION_ERROR' && !errorByElement.has(p.elementMeaning)) {
+                errorByElement.set(p.elementMeaning, p.observedText);
+            }
+        }
+        const eligible = s.elements.filter((e) => INPUT_ROLES.includes(e.role) || e.role === 'button' || e.role === 'submit');
+        const droppedPerScreen = Math.max(0, eligible.length - MAX_ROWS_PER_SCREEN);
+        const rows = eligible
+            .slice(0, MAX_ROWS_PER_SCREEN)
+            .map((e) => {
+            let attrs = {};
+            try {
+                attrs = JSON.parse(e.notes ?? '{}');
+            }
+            catch { /* ignore */ }
+            const d = deriveConstraintExamples(e.role, e.expectedData, attrs);
+            if (d.constraints !== '—')
+                constrainedCount++;
+            // Ground state column with real observed validation errors when available
+            const observedError = errorByElement.get(e.meaning);
+            const states = observedError
+                ? `${d.states === 'Static' ? '' : d.states + '; '}shows error: "${observedError.slice(0, 80)}"`
+                : d.states;
+            totalRows++;
+            return `| ${e.meaning} | ${e.expectedData ?? e.role} | ${d.constraints} | ${d.valid} | ${d.invalid} | ${states} |`;
+        });
+        if (rows.length === 0)
+            return '';
+        const truncNote = droppedPerScreen > 0
+            ? `\n> Note: ${droppedPerScreen} additional element(s) on this screen not shown (limit ${MAX_ROWS_PER_SCREEN} per screen).`
+            : '';
+        return `## Screen: ${s.name}${s.url ? ` (${s.url})` : ''}
+
+| Element | Expected Data Type | Constraints | Valid Examples | Invalid Examples | State Transitions |
+|---------|-------------------|-------------|----------------|------------------|-------------------|
+${rows.join('\n')}${truncNote}`;
+    }).filter(Boolean);
+    // Observed dynamic behaviors from the interactive probe (modals, reveals, messages)
+    const dynamicLines = [];
+    if (probeObservations) {
+        for (const s of screens) {
+            for (const p of (probeObservations.get(s.id) ?? []).slice(0, 8)) {
+                dynamicLines.push(`- **[${s.name}] ${p.elementMeaning}** — ${p.observationType.toLowerCase().replace(/_/g, ' ')}: "${(p.observedText ?? '').slice(0, 120)}" (trigger: ${p.triggeredBy})`);
+            }
+            if (dynamicLines.length >= 40)
+                break;
+        }
+    }
+    // Optional LLM prose — failure falls back to the deterministic content alone.
+    let aiNotes = '';
+    try {
+        aiNotes = await askFn(`You are a QA engineer. Given element constraint tables, write a SHORT "Testing Guidance" section (Markdown, max 200 words): which elements deserve boundary-value tests first and why. No tables, no repetition of the data.`, `${screenSections.join('\n\n').slice(0, 4000)}\n\nElement summary:\n${summary.slice(0, 800)}`);
+    }
+    catch { /* deterministic content stands alone */ }
+    const probeCount = dynamicLines.length;
+    const content = `# Element Behaviors
+> Constraint table derived deterministically from HTML5 attributes captured at crawl time${probeCount > 0 ? `, grounded with ${probeCount} interactive-probe observations` : ''}.
+${probeCount === 0 ? '> Enable **interactive probing** in crawl settings to also capture real validation messages and state transitions.\n' : ''}
+${screenSections.join('\n\n')}
+
+## Dynamic Elements
+${dynamicLines.length > 0 ? dynamicLines.join('\n') : '- No dynamic behaviors observed yet. Run a crawl with interactive probing enabled to populate this section.'}
+${aiNotes ? `\n## Testing Guidance\n${aiNotes}` : ''}`;
+    const tags = extractTags(content, ['validation', 'email', 'password', 'phone', 'date',
+        'required', 'format', 'pattern', 'min', 'max', 'unique', 'disabled', 'readonly', 'file', 'checkbox']);
+    const totalElements = screens.reduce((n, s) => n + s.elements.length, 0);
+    return {
+        content,
+        summary: `Element behaviors: ${totalRows} elements documented (${constrainedCount} with constraints)${probeCount ? `, ${probeCount} probe observations` : ''} of ${totalElements} total.`,
+        tags,
+    };
+}
+// ─── TIER 5: Quality Intelligence (structured data, no LLM) ──────────────────
+function deriveScreenLabel(s) {
+    if (s.url) {
+        try {
+            const u = new URL(s.url);
+            const segs = u.pathname.split('/').filter(Boolean);
+            if (segs.length > 0) {
+                const IS_ID = (seg) => /^\d+$/.test(seg) || /^[0-9a-f]{8,}$/i.test(seg) || /^c[a-z0-9]{20,}$/i.test(seg);
+                const readable = segs.filter((seg) => !IS_ID(seg)).map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1).replace(/[-_]/g, ' '));
+                if (readable.length > 0)
+                    return readable.join(' › ');
+            }
+            return u.pathname === '/' ? 'Home' : u.pathname;
+        }
+        catch { /* fall through */ }
+    }
+    return s.name;
+}
+/**
+ * Column → TestCase.kind mapping for the live Coverage Matrix, matching the
+ * column set already used by generateCoverageMatrixBaseline above (Functional
+ * /Security/A11y/State/Perf/Journey). Kinds actually written by the current
+ * generators — test-case-agent (POSITIVE/NEGATIVE/EDGE/SECURITY/ACCESSIBILITY),
+ * api-test-agent (API), integration-test-agent (INTEGRATION), flow-agent
+ * (E2E/REGRESSION/SMOKE/SANITY) — are folded into the nearest existing column;
+ * API/INTEGRATION count as Functional since there's no dedicated column for
+ * them yet. STATE_TRANSITION/PERFORMANCE are only ever produced by imported
+ * test cases today, but are kept as their own columns per the baseline targets.
+ */
+const COVERAGE_COLUMNS = [
+    { label: 'Functional', kinds: ['POSITIVE', 'NEGATIVE', 'EDGE', 'API', 'INTEGRATION'] },
+    { label: 'Security', kinds: ['SECURITY'] },
+    { label: 'A11y', kinds: ['ACCESSIBILITY'] },
+    { label: 'State', kinds: ['STATE_TRANSITION'] },
+    { label: 'Perf', kinds: ['PERFORMANCE'] },
+    { label: 'Journey', kinds: ['E2E', 'REGRESSION', 'SMOKE', 'SANITY'] },
+];
+/**
+ * Render the Coverage Matrix from live screen + TestCase-count data. Reuses
+ * the same URL-dedup and generic-title (deriveScreenLabel) logic as the
+ * crawl-time baseline above so screens are named consistently either way.
+ */
+function renderCoverageMatrix(screens, counts) {
+    // Deduplicate by URL — keep the row with the most elements for each URL.
+    const seenUrls = new Map();
+    const screenToDedupKey = new Map();
+    for (const s of screens) {
+        const key = s.url ?? s.name;
+        if (s.id)
+            screenToDedupKey.set(s.id, key);
+        const existing = seenUrls.get(key);
+        if (!existing || s.elementCount > existing.elementCount)
+            seenUrls.set(key, s);
+    }
+    const uniqueScreens = Array.from(seenUrls.values());
+    // Detect if all screen names are the same (generic app title) — use URL-derived labels instead.
+    const nameSet = new Set(uniqueScreens.map((s) => s.name.toLowerCase().trim()));
+    const useUrlLabels = nameSet.size === 1 && uniqueScreens.every((s) => s.url);
+    const screenLabel = (s) => {
+        const label = useUrlLabels ? deriveScreenLabel(s) : s.name;
+        return s.url ? `[${label}](${s.url})` : label;
+    };
+    const byScreen = new Map();
+    const byDedupKey = new Map();
+    for (const c of counts) {
+        const m = byScreen.get(c.screenId) ?? new Map();
+        m.set(c.kind, (m.get(c.kind) ?? 0) + c.count);
+        byScreen.set(c.screenId, m);
+        if (c.screenId) {
+            const dedupKey = screenToDedupKey.get(c.screenId);
+            if (dedupKey) {
+                const dm = byDedupKey.get(dedupKey) ?? new Map();
+                dm.set(c.kind, (dm.get(c.kind) ?? 0) + c.count);
+                byDedupKey.set(dedupKey, dm);
+            }
+        }
+    }
+    const rows = uniqueScreens.map((s) => {
+        const dedupKey = s.url ?? s.name;
+        const kindCounts = byDedupKey.get(dedupKey) ?? byScreen.get(s.id) ?? new Map();
+        const cols = COVERAGE_COLUMNS.map(({ kinds }) => kinds.reduce((n, k) => n + (kindCounts.get(k) ?? 0), 0));
+        const total = cols.reduce((a, b) => a + b, 0);
+        const security = cols[1];
+        const a11y = cols[2];
+        const gap = total === 0 ? '❌ No TCs — generate now'
+            : security === 0 ? '⚠️ Security missing'
+                : a11y === 0 ? '⚠️ A11y missing'
+                    : '✅ Covered';
+        return { label: screenLabel(s), url: s.url, elementCount: s.elementCount, cols, total, gap };
+    });
+    // Cross-screen tests (journeys, API packs) often have no screenId — show them too.
+    const unscoped = byScreen.get(null);
+    if (unscoped && unscoped.size > 0) {
+        const cols = COVERAGE_COLUMNS.map(({ kinds }) => kinds.reduce((n, k) => n + (unscoped.get(k) ?? 0), 0));
+        const total = cols.reduce((a, b) => a + b, 0);
+        if (total > 0)
+            rows.push({ label: '_Cross-screen / journeys_', url: null, elementCount: 0, cols, total, gap: '—' });
+    }
+    const generatedTotal = rows.reduce((n, r) => n + r.total, 0);
+    const coveredScreens = rows.filter((r) => r.gap === '✅ Covered').length;
+    const content = `# Coverage Matrix
+> Live document — recomputed from the TestCase table after each test generation run.
+> Last refreshed: ${new Date().toISOString()}
+
+> **${uniqueScreens.length} unique screens** (${screens.length - uniqueScreens.length} duplicate URL variants excluded from coverage tracking)
+
+## Coverage Grid (Screens × Test Types)
+
+| Screen | URL | Elements | ${COVERAGE_COLUMNS.map((c) => c.label).join(' | ')} | Total | Gap |
+|--------|-----|:--------:|${COVERAGE_COLUMNS.map(() => ':----:').join('|')}|:-----:|:----|
+${rows.map((r) => `| ${r.label} | ${r.url ?? '—'} | ${r.elementCount || '—'} | ${r.cols.join(' | ')} | **${r.total}** | ${r.gap} |`).join('\n')}
+
+**Totals:** ${generatedTotal} test cases across ${uniqueScreens.length} unique screens — ${coveredScreens} fully covered.
+
+## Coverage Targets (per test type, per screen)
+- Functional (EP+BVA): minimum 1 TC per equivalence class × field
+- Security: minimum 1 OWASP vector × form input field
+- Accessibility: minimum 1 WCAG 2.1 AA criterion × applicable element
+- State Transition: minimum 1 TC per state × event combination
+- Performance: 1 TC per screen (LCP assertion against PERFORMANCE_BASELINE)
+- Journey: 1 TC per core user journey (from BUSINESS_DOMAIN)
+
+## Gap Detection Rules
+- ❌ No TCs at all → generate now
+- ⚠️ Security = 0 AND screen has form inputs → generate OWASP tests
+- ⚠️ A11y = 0 AND screen has interactive elements → generate WCAG tests
+- ✅ All types covered → mark screen as fully covered
+`;
+    return {
+        content,
+        summary: generatedTotal === 0
+            ? `Coverage matrix baseline: ${uniqueScreens.length} unique screens, all at 0 TCs. Auto-updates after generation.`
+            : `Coverage matrix: ${generatedTotal} TCs across ${uniqueScreens.length} unique screens, ${coveredScreens} fully covered.`,
+        tags: ['coverage', 'matrix', 'gaps', 'regression'],
+    };
+}
+/**
+ * Recompute the COVERAGE_MATRIX skill file from live TestCase data.
+ * Called after every test generation run (and after crawls, as the baseline).
+ * Skips human-approved or manually written files so edits are never clobbered.
+ */
+async function refreshCoverageMatrix(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('COVERAGE_MATRIX'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'COVERAGE_MATRIX').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL')) {
+        console.log(`[skill-file-agent] COVERAGE_MATRIX is ${existing.approvedBy ? 'approved' : 'manual'} — skipping auto-refresh.`);
+        return;
+    }
+    const { screens, counts } = await app_brain_1.AppBrain.getCoverageMatrixData(tenantId, projectId);
+    if (screens.length === 0)
+        return;
+    const matrix = renderCoverageMatrix(screens, counts);
+    const matrixScreens = screens.map((s) => ({
+        id: s.id ?? `cross-screen:${s.name}`,
+        name: s.name,
+        url: s.url,
+        elements: Array.from({ length: Math.max(0, s.elementCount) }, (_, i) => ({
+            meaning: `Element ${i + 1}`,
+            role: 'unknown',
+        })),
+    }));
+    const approvalStatus = sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING';
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'COVERAGE_MATRIX', matrix.content, {
+        summary: matrix.summary,
+        tags: matrix.tags,
+        source: 'AUTO',
+        approvalStatus,
+        ...skillQualityMetadata('COVERAGE_MATRIX', matrix.content, matrixScreens, undefined, undefined, 'live-db'),
+    });
+}
+/**
+ * Recompute the TEST_CASES skill file.
+ * Emits testing strategy (persona registry, risk matrix, title conventions, exclusion list)
+ * drawn from BUSINESS_DOMAIN, then appends a live inventory of generated test cases.
+ * Runs even when no cases exist so new projects get actionable guidance immediately.
+ */
+async function refreshTestCaseInventory(tenantId, projectId) {
+    // Check per-project skill file config
+    const skillKind = 'TEST_CASES';
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get(skillKind));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const [existing, legacyExisting] = await Promise.all([
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, skillKind).catch(() => null),
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TEST_CASE').catch(() => null),
+    ]);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    if (!existing && legacyExisting && (legacyExisting.approvedBy || legacyExisting.source === 'MANUAL'))
+        return;
+    const [businessDomain, cases] = await Promise.all([
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'BUSINESS_DOMAIN').catch(() => null),
+        app_brain_1.AppBrain.listTestCases(tenantId, projectId, { limit: 500 }).catch(() => []),
+    ]);
+    const domainPersonaCtx = businessDomain?.content?.slice(0, 600) ??
+        '> Fill in user roles and permissions for this application.';
+    const strategySections = [
+        '# Test Case Skill File',
+        '',
+        '> Edit this file to shape how test cases are designed for this project. Approved content locks AI from overwriting.',
+        '',
+        '## Personas',
+        domainPersonaCtx,
+        '',
+        '## Title Conventions',
+        '- Positive: "[Screen] successfully [action] with [valid input]"',
+        '- Negative: "[Screen] rejects [invalid input] with [error message]"',
+        '- Edge: "[Screen] handles [boundary condition] correctly"',
+        '- Security: "[Screen] prevents [OWASP attack vector]"',
+        '- Performance: "[Feature] handles [N] concurrent users within [Xms] threshold"',
+        '',
+        '## Risk Matrix',
+        '| Screen Type | Min Cases | Priority | Key Focus |',
+        '|-------------|-----------|----------|-----------|',
+        '| Auth (login / register / reset) | 8 | CRITICAL | Security + all error states |',
+        '| Payment / checkout | 6 | CRITICAL | Validation + payment failure modes |',
+        '| Forms with data submission | 5 | HIGH | BVA + negative + required field tests |',
+        '| Data lists / grids | 3 | MEDIUM | Pagination + empty state + sorting |',
+        '| Read-only / info pages | 2 | LOW | Accessibility + layout |',
+        '',
+        '## Exclusion List',
+        '> Tests NOT to generate for this project (customize per-project):',
+        '- Third-party embed internals (ads, analytics scripts, chat widgets)',
+        '- Browser-native controls (browser back button, OS file picker internals)',
+        '- Admin backend screens unless the crawler explicitly covered them',
+        '',
+        '## Known Regression Risks',
+        '> Add entries after bugs are found and fixed — future generation will include regression coverage:',
+        '- (none yet — add patterns as bugs are discovered)',
+    ];
+    if (cases.length === 0) {
+        const content = strategySections.join('\n');
+        await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, skillKind, content, {
+            summary: 'Test case authoring guidance (no cases yet)',
+            tags: ['test-cases', 'guidance'],
+            source: 'AUTO',
+            approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        });
+        return;
+    }
+    const byKind = {};
+    const byStatus = {};
+    for (const tc of cases) {
+        byKind[tc.kind ?? 'UNKNOWN'] = (byKind[tc.kind ?? 'UNKNOWN'] ?? 0) + 1;
+        byStatus[tc.status ?? 'UNKNOWN'] = (byStatus[tc.status ?? 'UNKNOWN'] ?? 0) + 1;
+    }
+    const kindSummary = Object.entries(byKind).sort(([, a], [, b]) => b - a)
+        .map(([k, n]) => `- ${k}: ${n}`).join('\n');
+    const statusSummary = Object.entries(byStatus).sort(([, a], [, b]) => b - a)
+        .map(([k, n]) => `- ${k}: ${n}`).join('\n');
+    const CASE_LIMIT = parseInt(process.env.SKILL_FILE_CASE_LIMIT ?? '200', 10);
+    const caseList = cases.slice(0, CASE_LIMIT).map((tc) => {
+        const ref = tc.ref ? `[${tc.ref}]` : '';
+        const screen = tc.screen?.name ?? '';
+        return `- ${ref} ${tc.title ?? tc.id}${screen ? ` (${screen})` : ''}`;
+    }).join('\n');
+    const inventorySection = [
+        '',
+        '---',
+        '',
+        '## Test Case Inventory',
+        '',
+        `Total: ${cases.length} test cases`,
+        '',
+        '### By Kind',
+        kindSummary,
+        '',
+        '### By Status',
+        statusSummary,
+        '',
+        '### Test Cases',
+        caseList,
+        cases.length > CASE_LIMIT ? `\n… and ${cases.length - CASE_LIMIT} more` : '',
+    ];
+    const content = [...strategySections, ...inventorySection].join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, skillKind, content, {
+        summary: `${cases.length} test cases across ${Object.keys(byKind).length} kinds + authoring guidance`,
+        tags: ['test-cases', 'inventory', 'coverage', 'guidance'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * Recompute the TEST_SCRIPT skill file.
+ * Emits authoring standards (framework, auth strategy, selector priority, CI constraints, k6 config)
+ * drawn from TECH_STACK, AUTH_SESSION, and LOCATOR_STRATEGY skill files, then appends an
+ * inventory of existing scripts. Runs even when no scripts exist so new projects get
+ * actionable standards before first generation.
+ */
+async function refreshScriptInventory(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('TEST_SCRIPT'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TEST_SCRIPT').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const [techStack, authSession, locatorStrategy] = await Promise.all([
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TECH_STACK').catch(() => null),
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'AUTH_SESSION').catch(() => null),
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'LOCATOR_STRATEGY').catch(() => null),
+    ]);
+    const frameworkCtx = techStack?.content?.slice(0, 400) ??
+        '> Fill in: test framework + language (e.g., Playwright/TypeScript, Cypress/JavaScript, k6).';
+    const authCtx = authSession?.content?.slice(0, 600) ??
+        '> Fill in how scripts authenticate:\n' +
+            '> - storageState: capture session once with playwright auth, load in test setup\n' +
+            '> - API login: POST to auth endpoint, store token in Authorization header\n' +
+            '> - UI login: step through login form in beforeAll';
+    const selectorCtx = locatorStrategy?.content?.slice(0, 500) ??
+        '1. `data-testid` — most stable, never changes with UI refactors\n' +
+            '2. ARIA role + accessible name: `getByRole(\'button\', { name: \'Submit\' })`\n' +
+            '3. `getByLabel(\'Field name\')` for form inputs\n' +
+            '4. AVOID: CSS class selectors, nth-child, XPath with positional predicates';
+    const guidanceSections = [
+        '# Test Script Skill File',
+        '',
+        '> Edit this file to guide script generation for this project. Approved content locks AI from overwriting.',
+        '',
+        '## Framework',
+        frameworkCtx,
+        '',
+        '## Auth Strategy',
+        authCtx,
+        '',
+        '## Selector Priority',
+        selectorCtx,
+        '',
+        '## Authoring Standards',
+        '- Base URL: use `process.env.BASE_URL` — never hardcode URLs in scripts',
+        '- Wait strategy: prefer `waitForURL()` and `waitForSelector()` over `waitForTimeout()`',
+        '- Cleanup: reset state via API call in `afterEach` — not UI teardown steps',
+        '- Timeouts: default 30000ms; increase only for documented slow operations',
+        '- CI: all scripts must pass headless; max 4 parallel workers',
+        '',
+        '## k6 Load Test Standards',
+        '> For cases with techniqueOfRecord = "load-test":',
+        '- VU ramp pattern: 30s ramp to target VU → 2min sustained → 30s ramp-down',
+        '- Default thresholds: p95 < 500ms, error rate < 1%',
+        '- k6 script configuration goes in `preconditions` field — NEVER in test steps',
+        '- Test steps must be human-readable BDD actions describing observable behavior',
+    ];
+    const cases = await app_brain_1.AppBrain.listTestCases(tenantId, projectId, { limit: 500 }).catch(() => []);
+    const scriptsPerLang = {};
+    for (const tc of cases) {
+        for (const s of (tc.scripts ?? [])) {
+            const lang = s.language ?? 'unknown';
+            if (!scriptsPerLang[lang])
+                scriptsPerLang[lang] = [];
+            scriptsPerLang[lang].push(tc.ref ? `[${tc.ref}] ${tc.title}` : tc.title ?? tc.id);
+        }
+    }
+    const inventorySection = [];
+    if (Object.keys(scriptsPerLang).length > 0) {
+        const totalScripts = Object.values(scriptsPerLang).reduce((sum, arr) => sum + arr.length, 0);
+        const langSections = Object.entries(scriptsPerLang)
+            .sort(([, a], [, b]) => b.length - a.length)
+            .map(([lang, titles]) => {
+            const list = titles.slice(0, 30).map((t) => `  - ${t}`).join('\n');
+            const more = titles.length > 30 ? `\n  … and ${titles.length - 30} more` : '';
+            return `### ${lang} (${titles.length} scripts)\n${list}${more}`;
+        }).join('\n\n');
+        inventorySection.push('', '---', '', '## Script Inventory', '', `Total: ${totalScripts} scripts across ${Object.keys(scriptsPerLang).length} framework(s)`, '', langSections);
+    }
+    const content = [...guidanceSections, ...inventorySection].join('\n');
+    const totalScripts = Object.values(scriptsPerLang).reduce((sum, arr) => sum + arr.length, 0);
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_SCRIPT', content, {
+        summary: totalScripts > 0
+            ? `${totalScripts} scripts in ${Object.keys(scriptsPerLang).join(', ')} + authoring guidance`
+            : 'Script authoring guidance (no scripts yet)',
+        tags: ['scripts', 'guidance', 'frameworks'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+// ─── Utilities ────────────────────────────────────────────────────────────────
+function buildScreenSummary(screens) {
+    return screens
+        .map((s) => {
+        const els = s.elements.map((e) => {
+            let line = `  - ${e.role}: ${e.meaning}`;
+            if (e.expectedData)
+                line += ` [${e.expectedData}]`;
+            if (e.notes) {
+                try {
+                    const attrs = JSON.parse(e.notes);
+                    const relevant = Object.entries(attrs)
+                        .filter(([k]) => ['required', 'min', 'max', 'minLength', 'maxLength', 'pattern'].includes(k))
+                        .map(([k, v]) => `${k}:${v}`)
+                        .join(', ');
+                    if (relevant)
+                        line += ` {${relevant}}`;
+                }
+                catch { /* ignore */ }
+            }
+            return line;
+        }).join('\n');
+        return `Screen: ${s.name}${s.url ? ` (${s.url})` : ''}\n${els}`;
+    })
+        .join('\n\n');
+}
+function identifyComponentPatterns(screens) {
+    const roleScreenCount = {};
+    for (const screen of screens) {
+        const roles = new Set(screen.elements.map((e) => e.role));
+        for (const role of roles) {
+            roleScreenCount[role] = (roleScreenCount[role] ?? 0) + 1;
+        }
+    }
+    return Object.entries(roleScreenCount)
+        .filter(([, count]) => count >= 2)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 20)
+        .map(([role, count]) => `${role}: appears on ${count}/${screens.length} screens`)
+        .join('\n');
+}
+function groupRoutesBySection(routes) {
+    const groups = new Map();
+    for (const route of routes) {
+        const parts = route.pathname.split('/').filter(Boolean);
+        const section = parts[0] ? parts[0].charAt(0).toUpperCase() + parts[0].slice(1) : 'Root';
+        const arr = groups.get(section) ?? [];
+        arr.push(route);
+        groups.set(section, arr);
+    }
+    return [...groups.entries()];
+}
+function elementRoleSummary(elements) {
+    const counts = {};
+    for (const e of elements) {
+        counts[e.role] = (counts[e.role] ?? 0) + 1;
+    }
+    return Object.entries(counts)
+        .sort(([, a], [, b]) => b - a)
+        .map(([role, count]) => `- \`${role}\`: ${count} elements`)
+        .join('\n');
+}
+function extractTags(content, candidates) {
+    const lower = content.toLowerCase();
+    return candidates.filter((c) => lower.includes(c));
+}
+// ─── Refine (human feedback loop) ────────────────────────────────────────────
+async function refineSkillFile(opts) {
+    const { getTaskAgentLLMConfig } = await import('./llm-config.js');
+    const llmCfg = await getTaskAgentLLMConfig(opts.tenantId, 'appBrain');
+    const SYSTEM_DEFAULT = [
+        `You are ZeTa-AI's Application Intelligence curator. You maintain ${opts.kind} skill files.`,
+        'The user has provided feedback on the current skill file content. Apply the feedback precisely.',
+        'Preserve all correct existing information. Only change what the feedback specifically requests.',
+        'Return ONLY the updated skill file content — no explanation, no preamble, no markdown fences.',
+    ].join(' ');
+    const system = await (0, core_1.getAgentPrompt)('skill-file-curator', undefined, opts.tenantId) ?? SYSTEM_DEFAULT;
+    const user = [
+        `SKILL FILE KIND: ${opts.kind}`,
+        '',
+        'CURRENT CONTENT:',
+        opts.currentContent,
+        '',
+        'USER FEEDBACK:',
+        opts.feedback,
+        '',
+        'Return the updated skill file content reflecting the feedback.',
+    ].join('\n');
+    let content;
+    try {
+        const t0 = Date.now();
+        const refineSeed = (0, llm_js_1.deterministicSeed)(`${opts.tenantId}:${opts.projectId}:refine-skill:${opts.kind}:${opts.feedback.slice(0, 200)}`);
+        const { text, usage } = await (0, llm_js_1.askTracked)(system, user, llmCfg, undefined, undefined, { temperature: 0, seed: refineSeed });
+        const latencyMs = Date.now() - t0;
+        content = text.replace(/^```[\w-]*\n?/m, '').replace(/\n?```$/m, '').trim();
+        if (content.length < 30) {
+            console.warn(`[skill-file-agent] refineSkillFile got insufficient content for ${opts.kind} — keeping original`);
+            content = opts.currentContent;
+        }
+        (0, app_brain_1.recordLLMCall)({
+            tenantId: opts.tenantId,
+            projectId: opts.projectId,
+            agentType: 'skill_file',
+            label: `refine_${opts.kind}`,
+            entityType: 'skill_file',
+            usage,
+            latencyMs,
+        }).catch(console.error);
+    }
+    catch {
+        content = opts.currentContent;
+    }
+    return {
+        content,
+        summary: `Refined based on user feedback: ${opts.feedback.slice(0, 80)}`,
+        tags: [],
+    };
+}
+async function loadRepresentativeScreenshots(screens, maxCount) {
+    const screensWithShots = screens
+        .filter((s) => s.screenshots && s.screenshots.length > 0)
+        .sort((a, b) => b.elements.length - a.elements.length)
+        .slice(0, maxCount);
+    const images = [];
+    for (const screen of screensWithShots) {
+        const p = screen.screenshots[0].storagePath;
+        try {
+            const buf = await promises_1.default.readFile(p);
+            const ext = p.toLowerCase().split('.').pop();
+            const mediaType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg'
+                : ext === 'webp' ? 'image/webp'
+                    : ext === 'gif' ? 'image/gif'
+                        : 'image/png';
+            images.push({ base64: buf.toString('base64'), mediaType });
+        }
+        catch { /* screenshot missing — skip */ }
+    }
+    return images;
+}
+function buildTestFrameworkContent(opts) {
+    const { repoFullName, framework, language, testGlob, styleProfile, treeWasTruncated } = opts;
+    const sp = styleProfile ?? {};
+    const lines = [
+        `# Test Framework`,
+        ``,
+        `## Repository`,
+        `- Repo: \`${repoFullName}\``,
+        `- Framework: ${framework}`,
+        `- Language: ${language}`,
+        `- Test glob: \`${testGlob}\``,
+        ``,
+    ];
+    if (treeWasTruncated) {
+        lines.push(`## Scan Coverage`);
+        lines.push(`> ⚠️ Repository tree was truncated (>100k files). Test file inventory and pattern detection may be incomplete for large monorepos.`);
+        lines.push(``);
+    }
+    lines.push(`## Folder Structure`, `- Test folder: \`${sp.folderPattern ?? 'tests/'}\``, `- Naming pattern: \`${sp.namingPattern ?? 'unknown'}\``, ``);
+    // Detected structure from StyleProfile (GAP-SF-03)
+    const structureLines = [];
+    if (sp.testStructurePattern)
+        structureLines.push(`- Structure pattern: \`${sp.testStructurePattern}\``);
+    if (sp.testLocation)
+        structureLines.push(`- Test files live in: \`${sp.testLocation}\``);
+    if (sp.pageObjectLocation)
+        structureLines.push(`- Page objects live in: \`${sp.pageObjectLocation}\``);
+    if (sp.componentDir)
+        structureLines.push(`- Components: \`${sp.componentDir}\``);
+    if (sp.locatorsDir)
+        structureLines.push(`- Locators/selectors: \`${sp.locatorsDir}\``);
+    if (sp.testDataDir)
+        structureLines.push(`- Test data: \`${sp.testDataDir}\`${sp.isTestFixtureModule ? ' (TS fixture module)' : ''}`);
+    if (sp.fixtureDir && sp.fixtureDir !== sp.testDataDir)
+        structureLines.push(`- Fixtures: \`${sp.fixtureDir}\``);
+    if (sp.configTestDir)
+        structureLines.push(`- Config test dir: \`${sp.configTestDir}\``);
+    if (sp.configBaseURL)
+        structureLines.push(`- Base URL (from config): \`${sp.configBaseURL}\``);
+    if (sp.basePageClass)
+        structureLines.push(`- Base page class: \`${sp.basePageClass}\``);
+    if (sp.driverClass)
+        structureLines.push(`- Driver class: \`${sp.driverClass}\``);
+    if (sp.javaRoot)
+        structureLines.push(`- Java test root: \`${sp.javaRoot}\``);
+    if (sp.javaBasePackage)
+        structureLines.push(`- Java base package: \`${sp.javaBasePackage}\``);
+    if (sp.testLayers && Array.isArray(sp.testLayers) && sp.testLayers.length > 0) {
+        structureLines.push(`- Layer directories: ${sp.testLayers.map((l) => `\`${l}\``).join(', ')}`);
+    }
+    if (sp.testSubDirs && Array.isArray(sp.testSubDirs) && sp.testSubDirs.length > 0) {
+        structureLines.push(`- Sub-directories: ${sp.testSubDirs.map((l) => `\`${l}\``).join(', ')}`);
+    }
+    const tfUtilsDir = sp.utilsDir ?? '';
+    const tfConfigDir = sp.configDir ?? '';
+    if (tfUtilsDir)
+        structureLines.push(`- Utils/helpers: \`${tfUtilsDir}\``);
+    if (tfConfigDir)
+        structureLines.push(`- Config: \`${tfConfigDir}\``);
+    if (structureLines.length > 0) {
+        lines.push(`## Detected Repository Structure`);
+        structureLines.forEach(f => lines.push(f));
+        lines.push(``);
+    }
+    // Test pattern examples (GAP-SF-02 / new)
+    const patternLines = [];
+    if (sp.describePattern)
+        patternLines.push(`### Describe block\n\`\`\`\n${sp.describePattern}\n\`\`\``);
+    if (sp.beforeEachPattern)
+        patternLines.push(`### Setup hook (beforeEach)\n\`\`\`\n${sp.beforeEachPattern}\n\`\`\``);
+    if (sp.pageObjectPattern)
+        patternLines.push(`### Page object usage\n\`\`\`\n${sp.pageObjectPattern}\n\`\`\``);
+    if (patternLines.length > 0) {
+        lines.push(`## Test Pattern Examples`);
+        lines.push(`> Extracted from existing repo tests — match this style when generating new tests.`);
+        lines.push(``);
+        patternLines.forEach(p => lines.push(p, ``));
+    }
+    lines.push(`## Scaffold Files`);
+    const scaffoldMap = {
+        'playwright-ts': ['package.json', 'playwright.config.ts', 'tsconfig.json', '.gitignore', '.env.example', 'tests/fixtures/index.ts'],
+        'playwright-js': ['package.json', 'playwright.config.js', '.gitignore', '.env.example'],
+        'playwright-py': ['requirements.txt', 'pytest.ini', '.gitignore', '.env.example', 'tests/__init__.py', 'tests/conftest.py'],
+        'playwright-java': ['pom.xml', '.gitignore', '.env.example'],
+        'selenium-py': ['requirements.txt', 'pytest.ini', '.gitignore', 'tests/__init__.py', 'tests/conftest.py'],
+        'selenium-java': ['pom.xml', '.gitignore'],
+        'cypress-ts': ['package.json', 'cypress.config.ts', 'tsconfig.json', '.gitignore'],
+        'cypress-js': ['package.json', 'cypress.config.js', '.gitignore'],
+    };
+    const scaffold = scaffoldMap[framework] ?? scaffoldMap['playwright-ts'];
+    scaffold.forEach((f) => lines.push(`- \`${f}\``));
+    lines.push('', `## Run Command`);
+    const runMap = {
+        'playwright-ts': 'npm install && npx playwright install && npm test',
+        'playwright-js': 'npm install && npx playwright install && npm test',
+        'playwright-py': 'pip install -r requirements.txt && playwright install && pytest',
+        'playwright-java': 'mvn test',
+        'selenium-py': 'pip install -r requirements.txt && pytest',
+        'selenium-java': 'mvn test',
+        'cypress-ts': 'npm install && npx cypress run',
+        'cypress-js': 'npm install && npx cypress run',
+    };
+    lines.push(`\`${runMap[framework] ?? 'npm test'}\``);
+    return lines.join('\n');
+}
+function buildCodingConventionsContent(opts) {
+    const { repoFullName, framework, styleProfile } = opts;
+    const sp = styleProfile ?? {};
+    // Validate naming/folder patterns — discard if they're clearly wrong for the framework language
+    // e.g. LLM returning TypeScript patterns (.spec.ts) for a Java repo
+    const isJava = framework.includes('java');
+    const rawNamingPattern = sp.namingPattern ?? '';
+    const rawFolderPattern = sp.folderPattern ?? '';
+    const wrongLangPattern = isJava && (rawNamingPattern.includes('.spec.ts') || rawNamingPattern.includes('.spec.js') || rawNamingPattern.includes('.cy.'));
+    const namingPatternDisplay = wrongLangPattern ? 'unknown' : (rawNamingPattern || 'unknown');
+    const folderPatternDisplay = rawFolderPattern || 'unknown';
+    const lines = [
+        `# Coding Conventions`,
+        ``,
+        `## Source`,
+        `Extracted from repo: \`${repoFullName}\` · Framework: \`${framework}\``,
+        ``,
+        `## Naming`,
+        `- Pattern: \`${namingPatternDisplay}\``,
+        `- Folder: \`${folderPatternDisplay}\``,
+        ``,
+    ];
+    // Repo structure fields (LLM-detected during scan)
+    const structureFields = [];
+    if (sp.testStructurePattern)
+        structureFields.push(`- Structure pattern: \`${sp.testStructurePattern}\``);
+    if (sp.pageObjectLocation)
+        structureFields.push(`- Page objects live in: \`${sp.pageObjectLocation}\``);
+    if (sp.componentDir)
+        structureFields.push(`- Components live in: \`${sp.componentDir}\``);
+    if (sp.testLocation)
+        structureFields.push(`- Test files live in: \`${sp.testLocation}\``);
+    if (sp.basePageClass)
+        structureFields.push(`- Base page class: \`${sp.basePageClass}\` (extend this for new page objects)`);
+    if (sp.driverClass)
+        structureFields.push(`- Driver/browser class: \`${sp.driverClass}\` (use for driver lifecycle)`);
+    if (sp.testLayers && Array.isArray(sp.testLayers) && sp.testLayers.length > 0) {
+        structureFields.push(`- Layer directories: ${sp.testLayers.map((l) => `\`${l}\``).join(', ')}`);
+    }
+    if (sp.testSubDirs && Array.isArray(sp.testSubDirs) && sp.testSubDirs.length > 0) {
+        structureFields.push(`- Sub-directories: ${sp.testSubDirs.map((l) => `\`${l}\``).join(', ')} (use URL/feature type to pick)`);
+    }
+    if (structureFields.length > 0) {
+        lines.push(`## Repository Structure`);
+        structureFields.forEach(f => lines.push(f));
+        lines.push('');
+    }
+    // Directory layout — heuristic + LLM-detected paths for test data, fixtures, locators.
+    // These are preserved here so script-generation agents always know where to reference data,
+    // even when the heuristic pattern didn't match and LLM inference filled the gap.
+    const dirFields = [];
+    const configTestDir = sp.configTestDir ?? '';
+    const configFixturesFolder = sp.configFixturesFolder ?? '';
+    const configBaseURL = sp.configBaseURL ?? '';
+    const testDataDir = sp.testDataDir ?? '';
+    const fixtureDir = sp.fixtureDir ?? '';
+    const locatorsDir = sp.locatorsDir ?? '';
+    const javaRoot = sp.javaRoot ?? '';
+    const javaBasePackage = sp.javaBasePackage ?? '';
+    if (configTestDir)
+        dirFields.push(`- Test directory (from config): \`${configTestDir}\``);
+    if (configFixturesFolder)
+        dirFields.push(`- Fixtures directory (from config): \`${configFixturesFolder}\``);
+    if (configBaseURL)
+        dirFields.push(`- Base URL: \`${configBaseURL}\``);
+    if (testDataDir)
+        dirFields.push(`- Test data directory: \`${testDataDir}\`${sp.isTestFixtureModule ? ' (TypeScript fixture module — use test.extend(), not JSON import)' : ''}`);
+    if (fixtureDir && fixtureDir !== testDataDir)
+        dirFields.push(`- Fixture directory: \`${fixtureDir}\`${sp.isTestFixtureModule ? ' (TypeScript fixture module)' : ''}`);
+    if (locatorsDir)
+        dirFields.push(`- Locators/selectors directory: \`${locatorsDir}\``);
+    if (javaRoot)
+        dirFields.push(`- Java test source root: \`${javaRoot}\``);
+    if (javaBasePackage)
+        dirFields.push(`- Java base package: \`${javaBasePackage}\``);
+    const utilsDir = sp.utilsDir ?? '';
+    const configDir = sp.configDir ?? '';
+    if (utilsDir)
+        dirFields.push(`- Utils/helpers directory: \`${utilsDir}\``);
+    if (configDir)
+        dirFields.push(`- Config directory: \`${configDir}\``);
+    if (dirFields.length > 0) {
+        lines.push(`## Directory Layout`);
+        dirFields.forEach(f => lines.push(f));
+        lines.push('');
+    }
+    // File naming stems — tell script-gen agents how to name new files
+    const pageFileStem = sp.pageFileStem ?? '';
+    const locatorFileStem = sp.locatorFileStem ?? '';
+    const testDataFileStem = sp.testDataFileStem ?? '';
+    const fixtureFileStem = sp.fixtureFileStem ?? '';
+    const stemFields = [];
+    if (pageFileStem)
+        stemFields.push(`- Page object files: \`${pageFileStem}\``);
+    if (locatorFileStem)
+        stemFields.push(`- Locator files: \`${locatorFileStem}\``);
+    if (testDataFileStem)
+        stemFields.push(`- Test data files: \`${testDataFileStem}\``);
+    if (fixtureFileStem)
+        stemFields.push(`- Fixture files: \`${fixtureFileStem}\``);
+    if (stemFields.length > 0) {
+        lines.push(`## File Naming Patterns`);
+        stemFields.forEach(f => lines.push(f));
+        lines.push('');
+    }
+    if (sp.importLines) {
+        lines.push(`## Standard Imports`, '```');
+        const importArr = Array.isArray(sp.importLines)
+            ? sp.importLines
+            : String(sp.importLines).split('\n');
+        importArr.forEach((l) => l.trim() && lines.push(l));
+        lines.push('```', '');
+    }
+    // TypeScript path aliases — critical for correct import generation (new gaps from workflow audit)
+    const tsconfigPaths = sp.tsconfigPaths;
+    const tsconfigBaseUrl = sp.tsconfigBaseUrl;
+    const jestModuleNameMapper = sp.jestModuleNameMapper;
+    if ((tsconfigPaths && Object.keys(tsconfigPaths).length > 0) || tsconfigBaseUrl) {
+        lines.push(`## TypeScript Path Aliases`);
+        lines.push(`> Use these aliases for all imports — do NOT use relative \`../../\` paths when an alias matches.`);
+        if (tsconfigBaseUrl)
+            lines.push(`- baseUrl: \`${tsconfigBaseUrl}\` (imports rooted here when no alias matches)`);
+        if (tsconfigPaths) {
+            Object.entries(tsconfigPaths).forEach(([alias, targets]) => {
+                lines.push(`- \`${alias}\` → \`${targets[0] ?? ''}\``);
+            });
+        }
+        lines.push('');
+    }
+    if (jestModuleNameMapper && Object.keys(jestModuleNameMapper).length > 0) {
+        lines.push(`## Jest Module Aliases`);
+        Object.entries(jestModuleNameMapper).forEach(([k, v]) => lines.push(`- \`${k}\` → \`${v}\``));
+        lines.push('');
+    }
+    // Pattern samples — describe/beforeEach/pageObject (GAP-SF-02)
+    const patternSamples = [];
+    if (sp.describePattern)
+        patternSamples.push(`### Describe block\n\`\`\`\n${sp.describePattern}\n\`\`\``);
+    if (sp.beforeEachPattern)
+        patternSamples.push(`### Setup hook\n\`\`\`\n${sp.beforeEachPattern}\n\`\`\``);
+    if (sp.pageObjectPattern)
+        patternSamples.push(`### Page object usage\n\`\`\`\n${sp.pageObjectPattern}\n\`\`\``);
+    if (patternSamples.length > 0) {
+        lines.push(`## Pattern Samples`);
+        lines.push(`> Extracted from repo. Match this style in generated tests.`);
+        lines.push(``);
+        patternSamples.forEach(p => lines.push(p, ``));
+    }
+    const conventions = String(sp.conventions ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+    if (conventions.length > 0) {
+        lines.push(`## Conventions`);
+        conventions.forEach((c) => lines.push(`- ${c}`));
+    }
+    else {
+        lines.push(`## Conventions`, `- No explicit conventions detected. Follow ${framework} best practices.`);
+    }
+    return lines.join('\n');
+}
+function buildPageObjectsContent(opts) {
+    const { repoFullName, pageObjectInventory } = opts;
+    const lines = [
+        `# Page Object Library`,
+        ``,
+        `## Source`,
+        `Extracted from repo: \`${repoFullName}\``,
+        `Total classes: ${pageObjectInventory.length}`,
+        ``,
+    ];
+    for (const po of pageObjectInventory) {
+        lines.push(`## \`${po.className}\``, `File: \`${po.filePath}\``);
+        if (po.methods && po.methods.length > 0) {
+            lines.push('', 'Methods:');
+            po.methods.slice(0, 30).forEach((m) => {
+                const sig = m.params !== undefined ? `${m.name}(${m.params})` : m.name;
+                const ret = m.returnType ? ` → ${m.returnType}` : '';
+                lines.push(`- \`${sig}${ret}\``);
+            });
+            if (po.methods.length > 30)
+                lines.push(`- … and ${po.methods.length - 30} more`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function buildZetaFrameworkStandardContent(opts) {
+    const { repoFullName, styleProfile } = opts;
+    const sp = styleProfile ?? {};
+    const testStructurePattern = sp.testStructurePattern || '';
+    const pageObjectLocation = sp.pageObjectLocation || '';
+    const testLocation = sp.testLocation || '';
+    const basePageClass = sp.basePageClass || '';
+    const driverClass = sp.driverClass || '';
+    let javaBasePackage = '';
+    if (sp.javaBasePackage) {
+        javaBasePackage = String(sp.javaBasePackage);
+    }
+    else if (sp.folderPattern) {
+        const fp = String(sp.folderPattern);
+        const m = fp.match(/src\/(?:test|main)\/java\/(.+?)(?:\/[^/]*\{[^}]*\}|\/[A-Z][^/]*\.java|\/?$)/);
+        if (m?.[1])
+            javaBasePackage = m[1].replace(/\/$/, '').replace(/\//g, '.');
+    }
+    // Non-zeta-v2 repos: document the ACTUAL repo structure, not Zeta defaults
+    if (testStructurePattern && testStructurePattern !== 'zeta-v2') {
+        const lines = [
+            `# Repo Test Structure — ${repoFullName}`,
+            ``,
+            `## Detected Structure Pattern: \`${testStructurePattern}\``,
+            ``,
+            `This repo does NOT use Zeta v2 6-layer structure. Script generation will align to repo conventions.`,
+            ``,
+            `## Actual Repo Locations`,
+        ];
+        if (pageObjectLocation)
+            lines.push(`- Page objects: \`${pageObjectLocation}\``);
+        if (testLocation)
+            lines.push(`- Test files: \`${testLocation}\``);
+        if (basePageClass)
+            lines.push(`- Base page class: \`${basePageClass}\``);
+        if (driverClass)
+            lines.push(`- Driver/browser class: \`${driverClass}\``);
+        if (javaBasePackage)
+            lines.push(`- Java base package: \`${javaBasePackage}\``);
+        lines.push(``, `## Generation Behavior`, testStructurePattern === 'two-tier'
+            ? `Two-tier pattern: generates {Feature}Page.java in \`${pageObjectLocation || 'pages dir'}\` + {Feature}Tests.java in \`${testLocation || 'tests dir'}\`.`
+            : `Flat pattern: generates single {Feature}Tests.java in \`${testLocation || 'tests dir'}\`.`, ``, `## Do NOT use Zeta v2 layers`, `No locators/ pages/ actions/ assertions/ testdata/ smoke/ subfolders. Add files to existing repo structure only.`);
+        return lines.join('\n');
+    }
+    // Zeta v2 repos (or unknown — default to Zeta structure)
+    if (!javaBasePackage) {
+        return `# Zeta Framework Standard — ${repoFullName}\n\nNo Java package root detected. Default root \`io.zeta.applications.{appSlug}\` will be used.\n`;
+    }
+    const pkgPath = javaBasePackage.replace(/\./g, '/');
+    const javaRoot = sp.javaRoot || 'src/test/java';
+    const baseClass = basePageClass || 'io.zeta.core.BasePage';
+    const driverInit = driverClass || 'io.zeta.core.DriverFactory';
+    return [
+        `# Zeta Framework Standard — ${repoFullName}`,
+        ``,
+        `## Repo Package Root`,
+        `\`${javaBasePackage}\` (from: \`${sp.folderPattern ?? ''}\`)`,
+        ``,
+        `## Generated File Structure`,
+        ``,
+        `\`\`\``,
+        `${javaRoot}/`,
+        `  ${pkgPath}/{feature}/`,
+        `    locators/   {Feature}Locators.java    → ${javaBasePackage}.{feature}.locators`,
+        `    pages/      {Feature}Page.java        → ${javaBasePackage}.{feature}.pages`,
+        `    actions/    {Feature}Actions.java     → ${javaBasePackage}.{feature}.actions`,
+        `    assertions/ {Feature}Assertions.java  → ${javaBasePackage}.{feature}.assertions`,
+        `    testdata/   {Feature}TestData.java    → ${javaBasePackage}.{feature}.testdata`,
+        `  ${pkgPath}/smoke/`,
+        `    {Feature}SmokeTest.java               → ${javaBasePackage}.smoke`,
+        `\`\`\``,
+        ``,
+        `## Example (feature = login)`,
+        ``,
+        `| File | Package |`,
+        `|------|---------|`,
+        `| \`locators/LoginLocators.java\` | \`${javaBasePackage}.login.locators\` |`,
+        `| \`pages/LoginPage.java\` | \`${javaBasePackage}.login.pages\` |`,
+        `| \`actions/LoginActions.java\` | \`${javaBasePackage}.login.actions\` |`,
+        `| \`assertions/LoginAssertions.java\` | \`${javaBasePackage}.login.assertions\` |`,
+        `| \`testdata/LoginTestData.java\` | \`${javaBasePackage}.login.testdata\` |`,
+        `| \`LoginSmokeTest.java\` | \`${javaBasePackage}.smoke\` |`,
+        ``,
+        `## Core Infrastructure (never regenerate)`,
+        `- \`${baseClass}\` — WebDriver helpers (open, click, type, waitForVisible…)`,
+        `- \`${driverInit}\` — driver lifecycle (initDriver, getDriver, quitDriver)`,
+    ].join('\n');
+}
+function buildTestFileStructureContent(opts) {
+    const { repoFullName, testPaths, extractedTestCount, extractedTests } = opts;
+    const lines = [
+        `# Test File Structure`,
+        ``,
+        `## Source`,
+        `Repo: \`${repoFullName}\``,
+        `Total test files: ${testPaths.length}`,
+        `Extracted test IDs: ${extractedTestCount}`,
+        ``,
+        `## Files`,
+    ];
+    // Group by directory
+    const byDir = new Map();
+    for (const p of testPaths) {
+        const parts = p.split('/');
+        const dir = parts.length > 1 ? parts.slice(0, -1).join('/') : '.';
+        if (!byDir.has(dir))
+            byDir.set(dir, []);
+        byDir.get(dir).push(parts[parts.length - 1]);
+    }
+    for (const [dir, files] of [...byDir.entries()].sort()) {
+        lines.push(``, `### \`${dir}/\``);
+        files.slice(0, 20).forEach((f) => lines.push(`- \`${f}\``));
+        if (files.length > 20)
+            lines.push(`- … and ${files.length - 20} more`);
+    }
+    // Write extracted test IDs grouped by file (GAP-SF-04)
+    if (extractedTests && extractedTests.length > 0) {
+        lines.push(``, `## Extracted Test IDs`);
+        lines.push(`> Use these exact IDs when mapping test cases to scripts.`);
+        const byFile = new Map();
+        for (const t of extractedTests) {
+            const arr = byFile.get(t.filePath) ?? [];
+            arr.push(t);
+            byFile.set(t.filePath, arr);
+        }
+        let testsPrinted = 0;
+        const MAX_TESTS_PER_FILE = 30;
+        const MAX_TOTAL_TESTS = 500;
+        for (const [filePath, tests] of [...byFile.entries()].sort()) {
+            if (testsPrinted >= MAX_TOTAL_TESTS) {
+                lines.push(``, `> … and more tests not shown (limit ${MAX_TOTAL_TESTS})`);
+                break;
+            }
+            lines.push(``, `### \`${filePath}\``);
+            // Group by describe block
+            const byDescribe = new Map();
+            for (const t of tests) {
+                const key = t.describeBlock ?? '';
+                const arr = byDescribe.get(key) ?? [];
+                arr.push(t);
+                byDescribe.set(key, arr);
+            }
+            for (const [describe, descTests] of byDescribe) {
+                if (describe)
+                    lines.push(`**${describe}**`);
+                const shown = descTests.slice(0, MAX_TESTS_PER_FILE);
+                shown.forEach((t) => {
+                    const dynamic = t.dynamic ? ' *(parametrized)*' : '';
+                    lines.push(`- \`${t.name}\`${dynamic} (line ${t.lineNumber})`);
+                    testsPrinted++;
+                });
+                if (descTests.length > MAX_TESTS_PER_FILE) {
+                    lines.push(`  - … and ${descTests.length - MAX_TESTS_PER_FILE} more`);
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function buildRepoAlignedGenerationGuide(opts) {
+    const sp = opts.styleProfile ?? {};
+    const pattern = sp.testStructurePattern || 'two-tier';
+    const pageObjectLocation = sp.pageObjectLocation || '';
+    const testLocation = sp.testLocation || '';
+    const basePageClass = sp.basePageClass || '';
+    const driverClass = sp.driverClass || '';
+    const javaRoot = sp.javaRoot || 'src/test/java';
+    let javaBasePackage = '';
+    if (sp.javaBasePackage) {
+        javaBasePackage = String(sp.javaBasePackage);
+    }
+    else if (sp.folderPattern) {
+        const m = String(sp.folderPattern).match(/^([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+)/i);
+        if (m?.[1])
+            javaBasePackage = m[1].replace(/\/$/, '').replace(/\//g, '.');
+    }
+    const lines = [];
+    lines.push(`# Script Generation Guide — ${opts.repoFullName}`);
+    lines.push('');
+    lines.push(`> This repo uses a **${pattern}** structure, NOT Zeta v2.`);
+    lines.push('> Do NOT generate the Zeta v2 6-layer bundle (locators/pages/actions/assertions/testdata/smoke).');
+    lines.push('> Generate ONLY the files that match the repo\'s actual layout.');
+    lines.push('');
+    lines.push('## Repo Structure');
+    lines.push('');
+    if (pageObjectLocation)
+        lines.push(`- Page objects / components: \`${pageObjectLocation}/\``);
+    if (testLocation)
+        lines.push(`- Test classes: \`${testLocation}/\``);
+    if (!pageObjectLocation && !testLocation) {
+        lines.push(`- Java source root: \`${javaRoot}/\``);
+        if (javaBasePackage)
+            lines.push(`- Base package: \`${javaBasePackage}\``);
+    }
+    lines.push('');
+    if (basePageClass || driverClass) {
+        lines.push('## Repo Base Classes');
+        lines.push('');
+        if (basePageClass)
+            lines.push(`- Base page class: \`${basePageClass}\` — extend this in page objects`);
+        if (driverClass)
+            lines.push(`- Driver/browser class: \`${driverClass}\` — use this for browser setup, NOT WebDriver directly`);
+        lines.push('');
+    }
+    lines.push('## File Generation Rules');
+    lines.push('');
+    if (pattern === 'flat') {
+        lines.push('Structure is **flat**: generate ONE test class per feature.');
+        lines.push('- Put everything (locators, actions, assertions, test steps) in a single class.');
+        lines.push('- File lives in: ' + (testLocation ? `\`${testLocation}/\`` : `\`${javaRoot}/${javaBasePackage.replace(/\./g, '/')}/\``));
+    }
+    else {
+        lines.push('Structure is **two-tier**: generate TWO files per feature.');
+        lines.push('- **Page Object** — locators + actions + assertions');
+        lines.push('  - Extends: ' + (basePageClass ? `\`${basePageClass}\`` : 'repo\'s base page class'));
+        lines.push('  - Location: ' + (pageObjectLocation ? `\`${pageObjectLocation}/\`` : `\`${javaRoot}/${javaBasePackage.replace(/\./g, '/')}/pages/\``));
+        lines.push('- **Test Class** — test methods only, delegates to page object');
+        lines.push('  - Location: ' + (testLocation ? `\`${testLocation}/\`` : `\`${javaRoot}/${javaBasePackage.replace(/\./g, '/')}/tests/\``));
+    }
+    lines.push('');
+    lines.push('## Critical Rules');
+    lines.push('');
+    lines.push('- NEVER create locators/, actions/, assertions/, testdata/, or smoke/ directories unless they already exist in this repo.');
+    lines.push('- ALWAYS extend the repo\'s existing base classes — do not invent new ones.');
+    lines.push('- ALWAYS use the same import style as the rest of this repo.');
+    lines.push('- ALWAYS match existing test class naming conventions in this repo.');
+    lines.push('- Do NOT add test framework annotations not already used in this repo.');
+    return lines.join('\n');
+}
+async function generateRepoSkillFiles(tenantId, projectId, opts) {
+    const saves = [
+        app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'REPO_TEST_FRAMEWORK', buildTestFrameworkContent(opts), {
+            summary: `Framework: ${opts.framework} · ${opts.testPaths.length} test files in ${opts.repoFullName}`,
+            tags: [opts.framework, opts.language, 'repo-scan', 'framework'],
+            source: 'REPO_SCAN',
+        }),
+        app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'REPO_CODING_CONVENTIONS', buildCodingConventionsContent(opts), {
+            summary: `Coding conventions extracted from ${opts.repoFullName}`,
+            tags: [opts.framework, 'conventions', 'repo-scan'],
+            source: 'REPO_SCAN',
+        }),
+        app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'REPO_TEST_FILE_STRUCTURE', buildTestFileStructureContent(opts), {
+            summary: `${opts.testPaths.length} test files · ${opts.extractedTestCount} test IDs in ${opts.repoFullName}`,
+            tags: [opts.framework, 'file-structure', 'repo-scan'],
+            source: 'REPO_SCAN',
+        }),
+    ];
+    if (opts.pageObjectInventory.length > 0) {
+        saves.push(app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'REPO_PAGE_OBJECTS', buildPageObjectsContent(opts), {
+            summary: `${opts.pageObjectInventory.length} page object classes in ${opts.repoFullName}`,
+            tags: [opts.framework, 'page-objects', 'pom', 'repo-scan'],
+            source: 'REPO_SCAN',
+        }));
+    }
+    // ZETA_FRAMEWORK_STANDARD: repo-specific file structure summary.
+    if (opts.framework === 'selenium-java') {
+        const standardContent = buildZetaFrameworkStandardContent(opts);
+        const sp = opts.styleProfile ?? {};
+        const testStructurePattern = sp.testStructurePattern || '';
+        saves.push(app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'ZETA_FRAMEWORK_STANDARD', standardContent, {
+            summary: testStructurePattern && testStructurePattern !== 'zeta-v2'
+                ? `Repo-aligned structure for ${opts.repoFullName} (${testStructurePattern})`
+                : `Zeta v2 file structure for ${opts.repoFullName} (${opts.framework})`,
+            tags: [opts.framework, 'framework-standard', 'repo-scan'],
+            source: 'REPO_SCAN',
+        }));
+        // When repo uses a non-Zeta structure, overwrite the Zeta generation guide skill file
+        // with a repo-aligned guide. This prevents the LLM from seeing the Zeta 6-layer template
+        // and generating incompatible files.
+        // Also infer two-tier when page objects are found in src/main/java/ even without explicit pattern.
+        const hasMainSourcePages = opts.pageObjectInventory.some((po) => po.filePath?.includes('/main/java/') || po.filePath?.includes('\\main\\java\\'));
+        const effectivePattern = testStructurePattern || (hasMainSourcePages ? 'two-tier' : '');
+        if (effectivePattern && effectivePattern !== 'zeta-v2') {
+            const guideOpts = effectivePattern !== testStructurePattern
+                ? { ...opts, styleProfile: { ...(opts.styleProfile ?? {}), testStructurePattern: effectivePattern } }
+                : opts;
+            saves.push(app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'ZETA_FRAMEWORK_SELENIUM_JAVA', buildRepoAlignedGenerationGuide(guideOpts), {
+                summary: `Repo-aligned script generation guide for ${opts.repoFullName} — replaces Zeta v2 defaults`,
+                tags: [opts.framework, 'generation-guide', 'repo-aligned', 'repo-scan'],
+                source: 'REPO_SCAN',
+            }));
+        }
+    }
+    else if (ZETA_FRAMEWORKS.includes(opts.framework)) {
+        // Non-Java frameworks: populate ZETA_FRAMEWORK_STANDARD from the pre-built generation guide
+        // so script generation agents always have framework context even without a repo connection.
+        const guidePath = getGuidePath(opts.framework);
+        try {
+            const guideContent = await promises_1.default.readFile(guidePath, 'utf8');
+            saves.push(app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'ZETA_FRAMEWORK_STANDARD', guideContent, {
+                summary: `Zeta framework generation guide for ${opts.framework} — ${opts.repoFullName}`,
+                tags: [opts.framework, 'framework-standard', 'zeta-framework', 'repo-scan'],
+                source: 'ZETA_STANDARD',
+            }));
+        }
+        catch {
+            // Guide file not found — skip
+        }
+    }
+    await Promise.all(saves);
+}
+/**
+ * Generates a `REPO_ZETA_OVERLAY` skill file containing repo-specific overrides
+ * derived deterministically from the `styleProfile` produced by repo scan.
+ * This overlay is injected AFTER the base `ZETA_FRAMEWORK_STANDARD` in generation
+ * prompts so repo-specific paths/conventions override generic ZeTa defaults.
+ */
+async function alignSkillFile(tenantId, projectId, opts) {
+    const sp = opts.styleProfile ?? {};
+    const sections = [
+        `# Repo-Specific ZeTa Overlay — ${opts.repoFullName}`,
+        `Framework: ${opts.framework} | Language: ${opts.language}`,
+        '',
+        '## File Locations (MUST use these paths — override ZeTa defaults)',
+    ];
+    let hasContent = false;
+    const addIfPresent = (label, val) => {
+        if (val && typeof val === 'string' && val.trim()) {
+            sections.push(`- ${label}: ${val.trim()}`);
+            hasContent = true;
+        }
+    };
+    addIfPresent('Spec files dir', sp.testLocation);
+    addIfPresent('Page object dir', sp.pageObjectLocation);
+    addIfPresent('Locators dir', sp.locatorsDir);
+    addIfPresent('Test data dir', sp.testDataDir);
+    addIfPresent('Fixtures dir', sp.fixtureDir);
+    addIfPresent('Base page import (from PO dir)', sp.basePageImport);
+    addIfPresent('Base page class name', sp.basePageClass);
+    addIfPresent('Config-detected spec dir', sp.configTestDir);
+    addIfPresent('Config-detected base URL', sp.configBaseURL);
+    sections.push('', '## Naming Conventions');
+    addIfPresent('File naming pattern', sp.namingPattern);
+    addIfPresent('Folder/class pattern', sp.folderPattern);
+    if (Array.isArray(sp.importLines) && sp.importLines.length > 0) {
+        sections.push('', '## Detected Import Patterns (replicate these exactly)');
+        sp.importLines.slice(0, 10).forEach(line => { sections.push(`  ${line}`); hasContent = true; });
+    }
+    if (sp.conventions && typeof sp.conventions === 'string') {
+        sections.push('', '## Code Conventions', sp.conventions.slice(0, 500));
+        hasContent = true;
+    }
+    sections.push('', '## Generation Rules (OVERRIDE base guide when these conflict with ZeTa defaults)', '- Import paths MUST match the File Locations above.', '- base page import path is authoritative — do not use the ZeTa default.', '- Naming MUST follow detected conventions, not generic ZeTa names.', '- File paths in filePaths JSON output MUST use the dirs listed above.');
+    if (!hasContent)
+        return; // no meaningful repo-specific data — skip upsert
+    const content = sections.join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'REPO_ZETA_OVERLAY', content, {
+        summary: `Repo-aligned ZeTa overrides for ${opts.repoFullName} (${opts.framework})`,
+        tags: [opts.framework, opts.language, 'repo-overlay', 'zeta-overlay', 'repo-scan'],
+        source: 'REPO_SCAN',
+    });
+}
+// ── Zeta Framework Standard Skill Files ─────────────────────────────────────
+const ZETA_FRAMEWORKS = [
+    'selenium-java',
+    'playwright-ts',
+    'playwright-js',
+    'playwright-java',
+    'playwright-py',
+    'cypress-ts',
+    'cypress-js',
+    'selenium-py',
+    'wdio-ts',
+    'gherkin',
+];
+function getGuideKind(framework) {
+    return `ZETA_FRAMEWORK_${framework.toUpperCase().replace(/-/g, '_')}`;
+}
+function getGuidePath(framework) {
+    return node_path_1.default.join(__dirname, '../zeta-framework-v2', framework, 'GENERATION_GUIDE.md');
+}
+/**
+ * Upserts one ZETA_FRAMEWORK_{FRAMEWORK} skill file per supported framework.
+ * Called once on project creation so every project has the framework standards
+ * available to script-generation agents from day one.
+ */
+async function generateZetaFrameworkSkillFiles(tenantId, projectId) {
+    const saves = [];
+    const reads = ZETA_FRAMEWORKS.map(async (framework) => {
+        const guidePath = getGuidePath(framework);
+        let content;
+        try {
+            content = await promises_1.default.readFile(guidePath, 'utf8');
+        }
+        catch {
+            return; // Guide not yet created — skip silently
+        }
+        const kind = getGuideKind(framework);
+        saves.push(app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, kind, content, {
+            summary: `Zeta Framework v2 standard for ${framework} — injected into script generation`,
+            tags: [framework, 'zeta-framework', 'generation-guide', 'standard'],
+            source: 'ZETA_STANDARD',
+        }));
+    });
+    await Promise.all(reads);
+    await Promise.all(saves);
+}
+function truncateForSkillFile(value, max = 180) {
+    return String(value ?? '')
+        .replace(/\s+/g, ' ')
+        .replace(/\|/g, '\\|')
+        .trim()
+        .slice(0, max);
+}
+function extractCachedScenarioRows(artifact) {
+    const payload = artifact.cachedScenarios;
+    const scenarios = Array.isArray(payload?.scenarios)
+        ? payload.scenarios
+        : Array.isArray(payload)
+            ? payload
+            : [];
+    return scenarios
+        .map((s) => ({
+        title: truncateForSkillFile(s?.title ?? s?.name ?? '', 140),
+        requirementId: s?.requirementId ?? s?.traceTo ?? null,
+        priority: s?.priority ?? null,
+        type: s?.type ?? s?.category ?? null,
+        generated: s?.generated === true,
+        sourceExcerpt: s?.sourceExcerpt ?? null,
+    }))
+        .filter((s) => s.title);
+}
+function buildArtifactExcerpt(content, max = 900) {
+    const lines = String(content ?? '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line &&
+        !line.startsWith('> Auto-extracted') &&
+        !line.startsWith('> Conversion failed') &&
+        !/^#\s+/.test(line));
+    return lines.slice(0, 8).join(' ').replace(/\s+/g, ' ').slice(0, max);
+}
+/**
+ * Refresh BUSINESS_DOMAIN from uploaded/imported artifacts.
+ *
+ * Crawl-generated BUSINESS_DOMAIN is useful, but uploaded BRDs/specs often arrive
+ * before a crawl or test import. This live DB refresh makes those documents visible
+ * as project memory immediately without an LLM call. Approved/manual domain files
+ * remain locked.
+ */
+async function refreshArtifactKnowledgeSkillFile(tenantId, projectId) {
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('BUSINESS_DOMAIN'));
+    if (sfConfig?.enabled === false)
+        return;
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'BUSINESS_DOMAIN').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const [artifacts, requirements] = await Promise.all([
+        app_brain_1.AppBrain.listArtifacts(tenantId, projectId, { limit: 80 }).catch(() => []),
+        app_brain_1.AppBrain.listRequirements(tenantId, projectId).catch(() => []),
+    ]);
+    const usableArtifacts = artifacts.filter((artifact) => {
+        const content = artifact.content ?? '';
+        return content.trim().length > 0 && !content.includes('Conversion failed');
+    });
+    if (usableArtifacts.length === 0 && requirements.length === 0)
+        return;
+    const byKind = {};
+    const byDocType = {};
+    const scenarioRows = usableArtifacts.flatMap((artifact) => extractCachedScenarioRows(artifact).map((scenario) => ({ artifact, scenario })));
+    for (const artifact of usableArtifacts) {
+        const kind = artifact.kind ?? 'DOCUMENT';
+        byKind[kind] = (byKind[kind] ?? 0) + 1;
+        const docType = artifact.docType ?? 'UNCLASSIFIED';
+        byDocType[docType] = (byDocType[docType] ?? 0) + 1;
+    }
+    const sourceRows = usableArtifacts.slice(0, 40).map((artifact) => {
+        const name = artifact.originalName ?? artifact.name;
+        const summary = artifact.summary || buildArtifactExcerpt(artifact.content, 180) || 'No summary available yet';
+        return `| ${truncateForSkillFile(name, 70)} | ${artifact.kind ?? 'DOCUMENT'} | ${artifact.docType ?? '-'} | ${artifact.importStatus ?? '-'} | ${truncateForSkillFile(summary, 180)} |`;
+    });
+    const requirementRows = requirements.slice(0, 80).map((req) => `| ${truncateForSkillFile(req.reqId, 24)} | ${truncateForSkillFile(req.title, 100)} | ${req.priority ?? '-'} | ${req.type ?? '-'} | ${req.status ?? '-'} | ${truncateForSkillFile(req.sourceSection ?? '', 80)} |`);
+    const scenarioList = scenarioRows.slice(0, 80).map(({ artifact, scenario }) => {
+        const req = scenario.requirementId ? ` [${scenario.requirementId}]` : '';
+        const generated = scenario.generated ? ' - imported' : '';
+        const excerpt = scenario.sourceExcerpt ? ` - ${truncateForSkillFile(scenario.sourceExcerpt, 160)}` : '';
+        return `- ${scenario.title}${req}${scenario.priority ? ` (${scenario.priority})` : ''}${generated} - source: ${artifact.originalName ?? artifact.name}${excerpt}`;
+    });
+    const excerptSections = usableArtifacts.slice(0, 8).map((artifact) => {
+        const excerpt = buildArtifactExcerpt(artifact.content, 900);
+        if (!excerpt)
+            return '';
+        return `### ${artifact.originalName ?? artifact.name}\n${excerpt}`;
+    }).filter(Boolean);
+    const lines = [
+        '# Business Domain & Imported Artifact Knowledge',
+        '',
+        '> Auto-generated from uploaded project artifacts, extracted requirements, and cached import scenarios. Review before approving.',
+        '',
+        '## Source Summary',
+        `- Artifacts: ${usableArtifacts.length}`,
+        `- Requirements extracted: ${requirements.length}`,
+        `- Cached testable scenarios: ${scenarioRows.length}`,
+        `- Artifact kinds: ${Object.entries(byKind).map(([k, n]) => `${k}: ${n}`).join(' | ') || 'none'}`,
+        `- Document types: ${Object.entries(byDocType).map(([k, n]) => `${k}: ${n}`).join(' | ') || 'none'}`,
+        '',
+        '## Imported Sources',
+        '',
+        '| File | Kind | Doc Type | Import Status | Summary |',
+        '|---|---|---|---|---|',
+        ...(sourceRows.length ? sourceRows : ['| - | - | - | - | - |']),
+        '',
+        '## Extracted Requirements',
+        '',
+        '| ID | Title | Priority | Type | Status | Source Section |',
+        '|---|---|---|---|---|---|',
+        ...(requirementRows.length ? requirementRows : ['| - | No structured requirements extracted yet | - | - | - | - |']),
+        '',
+        '## Cached Testable Scenarios',
+        '',
+        ...(scenarioList.length ? scenarioList : ['- No scenario extraction cache exists yet. Run Extract on an imported artifact to populate this section.']),
+        '',
+        '## Document Excerpts',
+        '',
+        ...(excerptSections.length ? excerptSections : ['No artifact excerpts available.']),
+    ];
+    const content = lines.join('\n');
+    const provenance = [
+        ...usableArtifacts.slice(0, 80).map((artifact) => ({
+            sourceType: 'ARTIFACT',
+            sourceId: artifact.id,
+            name: artifact.originalName ?? artifact.name,
+            kind: artifact.kind ?? null,
+            docType: artifact.docType ?? null,
+            importStatus: artifact.importStatus ?? null,
+        })),
+        ...requirements.slice(0, 100).map((req) => ({
+            sourceType: 'REQUIREMENT',
+            sourceId: req.id ?? req.reqId,
+            reqId: req.reqId,
+            title: req.title,
+            priority: req.priority,
+        })),
+    ];
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'BUSINESS_DOMAIN', content, {
+        summary: `${usableArtifacts.length} imported artifacts, ${requirements.length} requirements, ${scenarioRows.length} cached scenarios`,
+        tags: ['business-domain', 'artifacts', 'requirements', 'imported-context'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        structuredData: {
+            kind: 'BUSINESS_DOMAIN',
+            generatorVersion: 'skill-file-agent:artifact-knowledge:v1',
+            extractionMode: 'live-db',
+            artifactCount: usableArtifacts.length,
+            requirementCount: requirements.length,
+            cachedScenarioCount: scenarioRows.length,
+            artifactKinds: byKind,
+            documentTypes: byDocType,
+        },
+        provenance,
+        confidence: usableArtifacts.length > 0 || requirements.length > 0 ? 0.9 : 0.6,
+        validationStatus: usableArtifacts.length > 0 || requirements.length > 0 ? 'PASS' : 'WARN',
+        validationSummary: usableArtifacts.length > 0 || requirements.length > 0
+            ? 'Generated from persisted artifact, requirement, and scenario-cache records.'
+            : 'No uploaded artifact or requirement evidence found.',
+        generatorVersion: 'skill-file-agent:artifact-knowledge:v1',
+    });
+}
+/**
+ * Refresh the TEST_CASES skill file from live TestCase data.
+ * Groups test cases by suite, caps at 200 rows, and summarises approval status.
+ */
+async function refreshTestCasesSkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('TEST_CASES'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TEST_CASES').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const cases = await app_brain_1.AppBrain.listTestCases(tenantId, projectId, { limit: 500 }).catch(() => []);
+    if (cases.length === 0)
+        return;
+    const count = cases.length;
+    const byKind = {};
+    const byStatus = {};
+    const bySuite = {};
+    for (const tc of cases) {
+        const k = tc.kind ?? 'UNKNOWN';
+        byKind[k] = (byKind[k] ?? 0) + 1;
+        const s = tc.status ?? 'UNKNOWN';
+        byStatus[s] = (byStatus[s] ?? 0) + 1;
+        const suiteName = (tc.suite?.name ?? tc.suiteId ?? 'Unsorted');
+        (bySuite[suiteName] ??= []).push(tc);
+    }
+    const pos = byKind['POSITIVE'] ?? 0;
+    const neg = byKind['NEGATIVE'] ?? 0;
+    const edge = byKind['EDGE'] ?? 0;
+    const approvedCount = byStatus['APPROVED'] ?? 0;
+    const suiteCount = Object.keys(bySuite).length;
+    const statusBreakdown = Object.entries(byStatus)
+        .sort(([, a], [, b]) => b - a)
+        .map(([k, n]) => `${k}: ${n}`)
+        .join(', ');
+    const SUITE_ROW_CAP = 50;
+    const TOTAL_ROW_CAP = 300;
+    let totalRendered = 0;
+    const suiteSections = Object.entries(bySuite).map(([suiteName, tcs]) => {
+        if (totalRendered >= TOTAL_ROW_CAP)
+            return '';
+        const toRender = tcs.slice(0, Math.min(SUITE_ROW_CAP, TOTAL_ROW_CAP - totalRendered));
+        totalRendered += toRender.length;
+        const rows = toRender.map((tc) => {
+            const ref = tc.ref ?? tc.id.slice(0, 8);
+            const title = (tc.title ?? '').slice(0, 60);
+            return `| TC-${ref} | ${title} | ${tc.kind ?? '—'} | ${tc.priority ?? '—'} | ${tc.status ?? '—'} |`;
+        }).join('\n');
+        return `### Suite: ${suiteName}\n| ID | Title | Kind | Priority | Status |\n|---|---|---|---|---|\n${rows}`;
+    }).join('\n\n');
+    const lines = [
+        '# Test Cases Inventory',
+        '',
+        `**Project:** ${projectId} | **Total:** ${count} | **Updated:** ${new Date().toISOString()}`,
+        '',
+        '## Summary',
+        `- Total: ${count} | Positive: ${pos} | Negative: ${neg} | Edge: ${edge}`,
+        `- Status breakdown: ${statusBreakdown}`,
+        '',
+        '## Test Cases',
+        '',
+        suiteSections,
+    ];
+    if (count > totalRendered)
+        lines.push(`\n... and ${count - totalRendered} more`);
+    const content = lines.join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_CASES', content, {
+        summary: `${count} test cases across ${suiteCount} suites — ${approvedCount} approved`,
+        tags: ['test-cases', 'inventory', 'coverage'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * Refresh the TEST_DATA skill file.
+ * Emits authoring guidance (personas, field constraints, equivalence classes, forbidden patterns)
+ * drawn from DATA_MODEL and BUSINESS_DOMAIN skill files, then appends an inventory of
+ * existing TestData records below a separator. Runs even when no data exists yet so new
+ * projects start with useful guidance immediately.
+ */
+async function refreshTestDataSkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('TEST_DATA'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TEST_DATA').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const [dataModel, businessDomain] = await Promise.all([
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'DATA_MODEL').catch(() => null),
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'BUSINESS_DOMAIN').catch(() => null),
+    ]);
+    const { withTenant: wt } = await import('@taodigital/database');
+    const rows = await wt(tenantId, (tx) => tx.testData.findMany({
+        where: { tenantId, projectId, supersededAt: null },
+        include: { testCase: { select: { title: true, ref: true } } },
+        orderBy: { id: 'desc' },
+        take: 100,
+    })).catch(() => []);
+    const domainCtx = businessDomain?.content?.slice(0, 600) ??
+        '> Fill in: what the app does, user roles, key business rules.';
+    const fieldCtx = dataModel?.content?.slice(0, 800) ??
+        '> Fill in per-field: type, min/max length, required, regex, forbidden values.\n' +
+            '> Example:\n' +
+            '> - email: type=email, required=true, maxLength=254\n' +
+            '> - password: minLength=8, must contain uppercase + digit + symbol';
+    const guidanceSections = [
+        '# Test Data Skill File',
+        '',
+        '> Edit this file to guide what test data the AI generates. Once approved, AI will not overwrite it.',
+        '',
+        '## Application Domain',
+        domainCtx,
+        '',
+        '## Test Personas',
+        '> Review and update for this application — these are starting defaults.',
+        '- **Admin**: Full system access. Replace with actual admin credentials for this application.',
+        '- **Standard User**: Regular authenticated user. Replace with actual credentials for this application.',
+        '- **Guest**: Unauthenticated, public screens only.',
+        '> Add more personas for each plan, role, or subscription tier the app supports.',
+        '',
+        '## Field Constraints',
+        fieldCtx,
+        '',
+        '## Equivalence Classes',
+        'For each key field, generate data from ALL three classes:',
+        '- **VALID**: Satisfies all constraints. Use realistic values matching the domain.',
+        '- **INVALID**: Violates one constraint (wrong type, out-of-range, missing required, bad format).',
+        '- **EDGE**: At exact boundaries (minLength, maxLength, min value, max value, empty on optional).',
+        '',
+        '## Forbidden Data Patterns',
+        '- NEVER use real-looking SSNs, credit card numbers, or real national IDs.',
+        '- NEVER copy values from production screenshots or logs.',
+        '- NEVER hardcode environment-specific secrets (tokens, API keys).',
+        '- Use clearly fake but realistic values: test@test.internal, +1-555-0100, 4111111111111111 (test Visa).',
+        '',
+        '## Dynamic Value Rules',
+        '- **Email uniqueness**: Append timestamp suffix when uniqueness is required. Pattern: `user+<timestamp>@test.internal`',
+        '- **Dates**: Use relative offsets (today+7, today-30) rather than absolute dates.',
+        '- **IDs/refs**: Use test-namespace prefix (e.g., `TEST-` or `QA-`).',
+    ];
+    const inventorySection = [];
+    if (rows.length > 0) {
+        const count = rows.length;
+        const byKind = {};
+        for (const r of rows) {
+            const k = r.kind ?? 'UNKNOWN';
+            byKind[k] = (byKind[k] ?? 0) + 1;
+        }
+        const kindSummary = ['VALID', 'INVALID', 'EDGE', 'SYNTHETIC']
+            .map((k) => `${k}: ${byKind[k] ?? 0}`)
+            .join(' | ');
+        const sampleLines = rows.slice(0, 20).map((r) => {
+            const tcTitle = r.testCase?.title ?? r.testCaseId;
+            const payload = r.payload ?? {};
+            const keys = Object.keys(typeof payload === 'object' ? payload : {}).join(', ');
+            const preview = JSON.stringify(payload).slice(0, 150);
+            return `### ${tcTitle}\n- Kind: ${r.kind} | Fields: ${keys || '—'}\n- Values: ${preview}`;
+        }).join('\n\n');
+        inventorySection.push('', '---', '', '## Generated Data Inventory', '', `**Total datasets:** ${count} | ${kindSummary}`, '', sampleLines);
+    }
+    const content = [...guidanceSections, ...inventorySection].join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_DATA', content, {
+        summary: rows.length > 0 ? `${rows.length} datasets + authoring guidance` : 'Test data authoring guidance (seed)',
+        tags: ['test-data', 'guidance', 'inventory'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * Refresh the TEST_SCRIPT skill file from live TestScript records.
+ * Emits authoring standards (framework, auth, selector priority, CI constraints, k6 config)
+ * drawn from TECH_STACK, AUTH_SESSION, and LOCATOR_STRATEGY skill files, then appends an
+ * inventory of existing scripts with code samples. Runs even when no scripts exist yet.
+ */
+async function refreshTestScriptSkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('TEST_SCRIPT'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TEST_SCRIPT').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const [techStack, authSession, locatorStrategy] = await Promise.all([
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TECH_STACK').catch(() => null),
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'AUTH_SESSION').catch(() => null),
+        app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'LOCATOR_STRATEGY').catch(() => null),
+    ]);
+    const { withTenant: wt } = await import('@taodigital/database');
+    const scripts = await wt(tenantId, (tx) => tx.testScript.findMany({
+        where: { tenantId, projectId },
+        select: { id: true, language: true, code: true, validationStatus: true, testCaseId: true },
+        orderBy: { id: 'desc' },
+        take: 50,
+    })).catch(() => []);
+    const frameworkCtx = techStack?.content?.slice(0, 400) ??
+        '> Fill in: test framework + language (e.g., Playwright/TypeScript, Cypress/JavaScript, k6).';
+    const authCtx = authSession?.content?.slice(0, 600) ??
+        '> Fill in how scripts authenticate:\n' +
+            '> - storageState: capture session once with playwright auth, load in test setup\n' +
+            '> - API login: POST to auth endpoint, store token in Authorization header\n' +
+            '> - UI login: step through login form in beforeAll';
+    const selectorCtx = locatorStrategy?.content?.slice(0, 500) ??
+        '1. `data-testid` — most stable, never changes with UI refactors\n' +
+            '2. ARIA role + accessible name: `getByRole(\'button\', { name: \'Submit\' })`\n' +
+            '3. `getByLabel(\'Field name\')` for form inputs\n' +
+            '4. AVOID: CSS class selectors, nth-child, XPath with positional predicates';
+    const guidanceSections = [
+        '# Test Script Skill File',
+        '',
+        '> Edit this file to guide script generation for this project. Approved content locks AI from overwriting.',
+        '',
+        '## Framework',
+        frameworkCtx,
+        '',
+        '## Auth Strategy',
+        authCtx,
+        '',
+        '## Selector Priority',
+        selectorCtx,
+        '',
+        '## Authoring Standards',
+        '- Base URL: use `process.env.BASE_URL` — never hardcode URLs in scripts',
+        '- Wait strategy: prefer `waitForURL()` and `waitForSelector()` over `waitForTimeout()`',
+        '- Cleanup: reset state via API call in `afterEach` — not UI teardown steps',
+        '- Timeouts: default 30000ms; increase only for documented slow operations',
+        '- CI: all scripts must pass headless; max 4 parallel workers',
+        '',
+        '## k6 Load Test Standards',
+        '> For cases with techniqueOfRecord = "load-test":',
+        '- VU ramp pattern: 30s ramp to target VU → 2min sustained → 30s ramp-down',
+        '- Default thresholds: p95 < 500ms, error rate < 1%',
+        '- k6 script configuration goes in `preconditions` field — NEVER in test steps',
+        '- Test steps must be human-readable BDD actions describing observable behavior',
+    ];
+    if (scripts.length === 0) {
+        const content = guidanceSections.join('\n');
+        await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_SCRIPT', content, {
+            summary: 'Script authoring guidance (no scripts yet)',
+            tags: ['scripts', 'guidance'],
+            source: 'AUTO',
+            approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        });
+        return;
+    }
+    const count = scripts.length;
+    const byLang = {};
+    for (const s of scripts) {
+        const l = s.language ?? 'unknown';
+        byLang[l] = (byLang[l] ?? 0) + 1;
+    }
+    const frameworkBreakdown = Object.entries(byLang)
+        .sort(([, a], [, b]) => b - a)
+        .map(([l, n]) => `${l}: ${n}`)
+        .join(' | ');
+    const tableRows = scripts.map((s) => `| ${s.testCaseId.slice(0, 8)} | ${s.language} | ${s.validationStatus ?? 'PENDING'} |`).join('\n');
+    const codeSamples = scripts.slice(0, 3).map((s) => {
+        const lang = s.language ?? 'text';
+        const preview = (s.code ?? '').slice(0, 1500);
+        return `### Script ${s.testCaseId.slice(0, 8)} (${lang})\n\`\`\`${lang}\n${preview}${(s.code?.length ?? 0) > 1500 ? '\n...' : ''}\n\`\`\``;
+    }).join('\n\n');
+    const inventorySection = [
+        '',
+        '---',
+        '',
+        '## Script Inventory',
+        '',
+        `**Total scripts:** ${count} | ${frameworkBreakdown}`,
+        '',
+        '| Test Case ID | Language | Validation |',
+        '|---|---|---|',
+        tableRows,
+        '',
+        '## Code Samples (first 3)',
+        '',
+        codeSamples,
+    ];
+    const content = [...guidanceSections, ...inventorySection].join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_SCRIPT', content, {
+        summary: `${count} scripts — ${frameworkBreakdown} + authoring guidance`,
+        tags: ['scripts', 'guidance', 'inventory', 'frameworks'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * Refresh the REQUIREMENTS_COVERAGE skill file from live requirements and test case data.
+ * Queries requirements, approved test cases, and traces coverage via LLM matching.
+ * No-ops when the skill file has been manually approved or edited.
+ */
+async function refreshRequirementsCoverageSkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('REQUIREMENTS_COVERAGE'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'REQUIREMENTS_COVERAGE').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const { generateCoverageGapReport } = await import('./requirements-agent.js');
+    const report = await generateCoverageGapReport({ tenantId, projectId }).catch((e) => {
+        console.warn('[skill-file-agent] REQUIREMENTS_COVERAGE refresh failed:', e?.message ?? e);
+        return null;
+    });
+    if (!report)
+        return;
+    const byPriority = report?.byPriority ?? {};
+    const priorityRows = Object.entries(byPriority).map(([priority, row]) => (`| ${priority} | ${Number(row?.covered ?? 0)} | ${Number(row?.total ?? 0)} |`));
+    const content = [
+        '# Requirements Coverage Analysis',
+        '',
+        'Latest generated requirements coverage analysis for this project.',
+        '',
+        '## Summary By Priority',
+        '',
+        '| Priority | Covered | Total |',
+        '|---|---:|---:|',
+        ...(priorityRows.length ? priorityRows : ['| - | 0 | 0 |']),
+        '',
+        '## Top Coverage Gaps',
+        '',
+        ...((report?.topGaps ?? []).length
+            ? report.topGaps.map((gap) => `- ${gap}`)
+            : ['- No coverage gaps reported.']),
+        '',
+        '## Untested Requirements',
+        '',
+        ...((report?.untested ?? []).length
+            ? report.untested.map((reqId) => `- ${reqId}`)
+            : ['- None']),
+        '',
+        '## Not Mapped To Crawled Screens',
+        '',
+        ...((report?.unbuilt ?? []).length
+            ? report.unbuilt.map((reqId) => `- ${reqId}`)
+            : ['- None']),
+        '',
+        '## Covered Requirements',
+        '',
+        ...((report?.covered ?? []).length
+            ? report.covered.map((row) => `- ${row.reqId}: ${(row.caseRefs ?? []).join(', ') || 'linked test case'}`)
+            : ['- None']),
+    ].join('\n');
+    const coveredCount = (report?.covered ?? []).length;
+    const untestedCount = (report?.untested ?? []).length;
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'REQUIREMENTS_COVERAGE', content, {
+        summary: `Requirements coverage: ${coveredCount} covered, ${untestedCount} untested`,
+        tags: ['requirements', 'coverage', 'analysis'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * GAP-SF-17: TEST_EXECUTION_HISTORY — top recently failed tests with error type + frequency.
+ * Refreshed after each test run completes.
+ */
+async function refreshTestExecutionHistorySkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('TEST_EXECUTION_HISTORY'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'TEST_EXECUTION_HISTORY').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const { withTenant } = await import('@taodigital/database');
+    // Fetch recent test results across all runs for this project
+    const results = await withTenant(tenantId, (tx) => tx.testResult.findMany({
+        where: { tenantId, testCase: { projectId } },
+        select: {
+            id: true,
+            status: true,
+            duration: true,
+            error: true,
+            failureAnalysis: true,
+            createdAt: true,
+            testCase: { select: { id: true, title: true, screenId: true } },
+        },
+        orderBy: { createdAt: 'desc' },
+        take: 200,
+    })).catch(() => []);
+    if (results.length === 0) {
+        await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_EXECUTION_HISTORY', '# Test Execution History\n\n> No test results recorded yet.', {
+            summary: 'No test results yet', tags: ['execution', 'history', 'flaky'], source: 'AUTO',
+            approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        });
+        return;
+    }
+    // Aggregate by test case
+    const byCaseId = new Map();
+    for (const r of results) {
+        const key = r.testCase?.id ?? 'unknown';
+        const entry = byCaseId.get(key) ?? { title: r.testCase?.title ?? key, failures: 0, passes: 0, errors: [], avgDuration: 0, totalDuration: 0 };
+        if (r.status === 'PASSED') {
+            entry.passes++;
+        }
+        else if (r.status === 'FAILED' || r.status === 'ERROR') {
+            entry.failures++;
+            const errText = (r.error ?? r.failureAnalysis ?? '').slice(0, 100);
+            if (errText && !entry.errors.includes(errText))
+                entry.errors.push(errText);
+        }
+        if (r.duration) {
+            entry.totalDuration += r.duration;
+        }
+        byCaseId.set(key, entry);
+    }
+    for (const e of byCaseId.values()) {
+        e.avgDuration = e.totalDuration / Math.max(1, e.failures + e.passes);
+    }
+    const totalRuns = results.length;
+    const failedRuns = results.filter((r) => r.status === 'FAILED' || r.status === 'ERROR').length;
+    const passRate = totalRuns > 0 ? Math.round((1 - failedRuns / totalRuns) * 100) : 100;
+    // Top 10 most-failing tests
+    const topFailing = [...byCaseId.entries()]
+        .filter(([, v]) => v.failures > 0)
+        .sort(([, a], [, b]) => b.failures - a.failures)
+        .slice(0, 10);
+    // Flaky tests: both passes and failures
+    const flaky = [...byCaseId.entries()]
+        .filter(([, v]) => v.failures > 0 && v.passes > 0)
+        .sort(([, a], [, b]) => b.failures - a.failures)
+        .slice(0, 5);
+    const lines = [
+        `# Test Execution History`,
+        ``,
+        `> Auto-generated from last ${totalRuns} test results. Refreshed after each test run.`,
+        ``,
+        `## Summary`,
+        `- Total results: ${totalRuns}`,
+        `- Pass rate: ${passRate}%`,
+        `- Failing tests (unique): ${topFailing.length}`,
+        `- Flaky tests: ${flaky.length}`,
+        ``,
+    ];
+    if (topFailing.length > 0) {
+        lines.push(`## Top Failing Tests`);
+        lines.push(`| Test | Failures | Passes | Common Error |`);
+        lines.push(`|---|---|---|---|`);
+        for (const [, v] of topFailing) {
+            lines.push(`| ${v.title.slice(0, 60)} | ${v.failures} | ${v.passes} | ${(v.errors[0] ?? '—').slice(0, 80)} |`);
+        }
+        lines.push(``);
+    }
+    if (flaky.length > 0) {
+        lines.push(`## Flaky Tests (avoid these patterns in new scripts)`);
+        for (const [, v] of flaky) {
+            lines.push(`- **${v.title}**: ${v.failures} failures / ${v.passes} passes — "${v.errors[0] ?? 'intermittent'}"`);
+        }
+        lines.push(``);
+    }
+    lines.push(`## Script Generation Guidance`);
+    lines.push(`- Avoid tight timing assertions — flaky tests often fail due to race conditions`);
+    lines.push(`- High-failure tests indicate unstable selectors or auth issues — check LOCATOR_STRATEGY`);
+    lines.push(`- Avg duration for failing tests: ${Math.round([...byCaseId.values()].filter((v) => v.failures > 0).reduce((a, v) => a + v.avgDuration, 0) / Math.max(1, topFailing.length))}ms`);
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'TEST_EXECUTION_HISTORY', lines.join('\n'), {
+        summary: `Execution history: ${passRate}% pass rate, ${topFailing.length} failing tests, ${flaky.length} flaky`,
+        tags: ['execution', 'history', 'flaky', 'failures'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * GAP-SF-18: VISUAL_REGRESSION_HISTORY — screens with recent diffs, change types, stable vs unstable zones.
+ * Refreshed after visual diff generation.
+ */
+async function refreshVisualRegressionHistorySkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('VISUAL_REGRESSION_HISTORY'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'VISUAL_REGRESSION_HISTORY').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const { withTenant } = await import('@taodigital/database');
+    const diffs = await withTenant(tenantId, (tx) => tx.visualDiff.findMany({
+        where: {
+            tenantId,
+            baseline: { projectId },
+        },
+        select: {
+            id: true,
+            diffScore: true,
+            changeType: true,
+            recommendation: true,
+            aiSummary: true,
+            status: true,
+            createdAt: true,
+            baseline: { select: { screenId: true } },
+        },
+        orderBy: { createdAt: 'desc' },
+        take: 100,
+    })).catch(() => []);
+    if (diffs.length === 0) {
+        await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'VISUAL_REGRESSION_HISTORY', '# Visual Regression History\n\n> No visual diffs recorded yet.', {
+            summary: 'No visual diffs yet', tags: ['visual', 'regression', 'baseline'], source: 'AUTO',
+            approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        });
+        return;
+    }
+    // Aggregate by screen
+    const byScreen = new Map();
+    for (const d of diffs) {
+        const key = d.baseline?.screenId ?? 'unknown';
+        const entry = byScreen.get(key) ?? { diffs: [], maxScore: 0 };
+        entry.diffs.push(d);
+        if (d.diffScore > entry.maxScore)
+            entry.maxScore = d.diffScore;
+        byScreen.set(key, entry);
+    }
+    const criticalScreens = [...byScreen.entries()]
+        .filter(([, v]) => v.maxScore >= 20)
+        .sort(([, a], [, b]) => b.maxScore - a.maxScore)
+        .slice(0, 10);
+    const stableScreens = [...byScreen.entries()]
+        .filter(([, v]) => v.maxScore < 5)
+        .slice(0, 5);
+    const lines = [
+        `# Visual Regression History`,
+        ``,
+        `> Auto-generated from last ${diffs.length} visual diffs. Refreshed after each diff run.`,
+        ``,
+        `## Summary`,
+        `- Total diffs analyzed: ${diffs.length}`,
+        `- Screens with regressions: ${criticalScreens.length}`,
+        `- Stable screens (score < 5): ${stableScreens.length}`,
+        ``,
+    ];
+    if (criticalScreens.length > 0) {
+        lines.push(`## High-Risk Screens (unstable — visual assertions may be flaky)`);
+        lines.push(`| Screen ID | Max Diff Score | Change Type | Recommendation |`);
+        lines.push(`|---|---|---|---|`);
+        for (const [screenId, v] of criticalScreens) {
+            const latest = v.diffs[0];
+            lines.push(`| ${screenId.slice(0, 12)} | ${v.maxScore.toFixed(1)} | ${latest?.changeType ?? '—'} | ${latest?.recommendation ?? '—'} |`);
+        }
+        lines.push(``);
+    }
+    if (stableScreens.length > 0) {
+        lines.push(`## Stable Screens (safe for strict visual assertions)`);
+        for (const [screenId] of stableScreens) {
+            lines.push(`- \`${screenId.slice(0, 12)}\``);
+        }
+        lines.push(``);
+    }
+    lines.push(`## Visual Test Guidance`);
+    lines.push(`- Avoid pixel-perfect assertions on high-risk screens — use element-level assertions instead`);
+    lines.push(`- Safe screens for screenshot comparison: diff score < 5 consistently`);
+    lines.push(`- CRITICAL/SIGNIFICANT changes indicate component-level visual regressions — prioritize for review`);
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'VISUAL_REGRESSION_HISTORY', lines.join('\n'), {
+        summary: `Visual history: ${criticalScreens.length} unstable screens, ${stableScreens.length} stable`,
+        tags: ['visual', 'regression', 'baseline', 'stability'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * GAP-SF-19: Append self-healing history to LOCATOR_STRATEGY — elements with healCount > 2 are high-fragility.
+ * Refreshed after self-healing events.
+ */
+async function refreshLocatorStrategyWithHealingData(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('LOCATOR_STRATEGY'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'LOCATOR_STRATEGY').catch(() => null);
+    if (!existing)
+        return;
+    if (existing.approvedBy || existing.source === 'MANUAL')
+        return;
+    const { withTenant } = await import('@taodigital/database');
+    const fingerprints = await withTenant(tenantId, (tx) => tx.elementFingerprint.findMany({
+        where: { tenantId, projectId, healCount: { gt: 0 } },
+        select: {
+            elementId: true,
+            healCount: true,
+            lastHealedAt: true,
+            element: { select: { meaning: true, role: true, screen: { select: { name: true } } } },
+        },
+        orderBy: { healCount: 'desc' },
+        take: 50,
+    })).catch(() => []);
+    if (fingerprints.length === 0)
+        return;
+    const highFragility = fingerprints.filter((f) => f.healCount > 2);
+    const lowFragility = fingerprints.filter((f) => f.healCount <= 2);
+    const healSection = [
+        ``,
+        `## Self-Healing History`,
+        `> Elements that required selector healing — use stable alternatives for these in new scripts.`,
+        ``,
+    ];
+    if (highFragility.length > 0) {
+        healSection.push(`### High-Fragility Locators (healed 3+ times — avoid CSS/positional selectors)`);
+        for (const f of highFragility) {
+            const el = f.element;
+            healSection.push(`- **[${el?.screen?.name ?? 'unknown'}] ${el?.meaning ?? f.elementId}** (${el?.role ?? 'unknown'}) — healed ${f.healCount}× — prefer \`data-testid\` or ARIA role+name`);
+        }
+        healSection.push(``);
+    }
+    if (lowFragility.length > 0) {
+        healSection.push(`### Low-Fragility Locators (healed 1-2 times — monitor)`);
+        for (const f of lowFragility.slice(0, 10)) {
+            const el = f.element;
+            healSection.push(`- [${el?.screen?.name ?? 'unknown'}] ${el?.meaning ?? f.elementId} — healed ${f.healCount}×`);
+        }
+        healSection.push(``);
+    }
+    const updatedContent = existing.content + healSection.join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'LOCATOR_STRATEGY', updatedContent, {
+        summary: `${existing.summary ?? 'Locator strategy'} + ${fingerprints.length} self-healing records`,
+        tags: ['locators', 'self-healing', 'fragility', 'stability'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * GAP-SF-20: FIELD_CATALOG — deterministic ground-truth field inventory from AppField table.
+ * Refreshed after crawl when AppField catalog is populated.
+ */
+async function refreshFieldCatalogSkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('FIELD_CATALOG'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'FIELD_CATALOG').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const fields = await app_brain_1.AppBrain.listAppFields(tenantId, projectId).catch(() => []);
+    if (fields.length === 0) {
+        await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'FIELD_CATALOG', '# Field Catalog\n\n> No app fields catalogued yet. Run a crawl to populate.', {
+            summary: 'No fields yet', tags: ['fields', 'catalog', 'data-model'], source: 'AUTO',
+            approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        });
+        return;
+    }
+    // Group by screen/entity
+    const byEntity = new Map();
+    for (const f of fields) {
+        const key = f.screenName ?? f.entityName ?? 'Global';
+        const arr = byEntity.get(key) ?? [];
+        arr.push(f);
+        byEntity.set(key, arr);
+    }
+    const lines = [
+        `# Field Catalog`,
+        ``,
+        `> Deterministic ground-truth from AppField table — populated during crawl. Authoritative over DATA_MODEL for field types and constraints.`,
+        ``,
+        `## Summary`,
+        `- Total fields: ${fields.length}`,
+        `- Entities/screens: ${byEntity.size}`,
+        ``,
+    ];
+    for (const [entity, entityFields] of [...byEntity.entries()].sort()) {
+        lines.push(`## ${entity}`);
+        lines.push(`| Field | Type | Required | Constraints | Notes |`);
+        lines.push(`|---|---|---|---|---|`);
+        for (const f of entityFields.slice(0, 50)) {
+            const constraints = [
+                f.minLength != null ? `minLen:${f.minLength}` : null,
+                f.maxLength != null ? `maxLen:${f.maxLength}` : null,
+                f.pattern ? `pattern:${f.pattern.slice(0, 30)}` : null,
+                f.min != null ? `min:${f.min}` : null,
+                f.max != null ? `max:${f.max}` : null,
+            ].filter(Boolean).join(', ') || '—';
+            lines.push(`| ${f.key ?? f.fieldKey ?? '?'} | ${f.type ?? f.dataType ?? '?'} | ${f.required ? '✅' : '—'} | ${constraints} | ${(f.notes ?? '').slice(0, 60)} |`);
+        }
+        if (entityFields.length > 50)
+            lines.push(`| … | ${entityFields.length - 50} more | | | |`);
+        lines.push(``);
+    }
+    lines.push(`## Test Implications`);
+    lines.push(`- Required fields: ${fields.filter((f) => f.required).length} — each needs a missing-value test`);
+    lines.push(`- Pattern-constrained fields: ${fields.filter((f) => f.pattern).length} — test valid/invalid pattern inputs`);
+    lines.push(`- Numeric fields: ${fields.filter((f) => ['number', 'integer', 'float'].includes(f.type ?? '')).length} — test min/max boundary values`);
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'FIELD_CATALOG', lines.join('\n'), {
+        summary: `Field catalog: ${fields.length} fields across ${byEntity.size} entities`,
+        tags: ['fields', 'catalog', 'data-model', 'constraints'],
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+    });
+}
+/**
+ * GAP-SF-21: HEALING_LOG — dedicated skill file tracking healing events (element breaks + auto-fixes).
+ * Separates healing telemetry from LOCATOR_STRATEGY so it can be queried independently.
+ * Refreshed after self-healing events.
+ */
+async function refreshHealingLogSkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('HEALING_LOG'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'HEALING_LOG').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    // Read current LOCATOR_STRATEGY to extract healing annotations
+    const locatorStrategy = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'LOCATOR_STRATEGY').catch(() => null);
+    const locatorContent = locatorStrategy?.content ?? '';
+    // Extract healing event lines from LOCATOR_STRATEGY (look for lines containing healing markers)
+    const healingLines = locatorContent.split('\n').filter((l) => l.includes('<!-- healed') || l.includes('[HEALED]') || l.includes('auto-healed') ||
+        l.toLowerCase().includes('healing') || l.includes('→') // before → after selector patterns
+    );
+    // Also query TestScript table for scripts with validation errors (fragile selectors)
+    const { withTenant: wt } = await import('@taodigital/database');
+    const fragileScripts = await wt(tenantId, (tx) => tx.testScript.findMany({
+        where: { tenantId, projectId, validationStatus: 'FAIL' },
+        select: { id: true, language: true, validationErrors: true, testCaseId: true },
+        take: 50,
+        orderBy: { id: 'desc' },
+    })).catch(() => []);
+    const healingSummary = healingLines.length > 0
+        ? healingLines.slice(0, 50).join('\n')
+        : '> No healing events recorded yet.';
+    const fragileList = fragileScripts.length > 0
+        ? fragileScripts
+            .map((s) => `- [${s.language}] caseId=${s.testCaseId}: ${(s.validationErrors ?? '').slice(0, 120)}`)
+            .join('\n')
+        : '> No fragile scripts detected.';
+    const content = [
+        '# Healing Log',
+        '',
+        '## Purpose',
+        'Tracks auto-healing events — when locators break and how they were fixed.',
+        'Use this context to avoid regenerating fragile selectors.',
+        '',
+        '## Recent Healing Events',
+        healingSummary,
+        '',
+        '## Currently Fragile Scripts (validation=FAIL)',
+        fragileList,
+        '',
+        '## Healing Guidance',
+        '- Prefer `data-testid` locators — they survive refactors.',
+        '- ARIA role + name is second choice: `getByRole("button", { name: "Submit" })`.',
+        '- Avoid: XPath, nth-child, auto-generated class names.',
+        '- When a locator heals, the new selector is marked `[HEALED]` in LOCATOR_STRATEGY.',
+    ].join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'HEALING_LOG', content, {
+        summary: `Healing log: ${healingLines.length} events, ${fragileScripts.length} fragile scripts`,
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        validationStatus: 'PASS',
+        staleStatus: 'CURRENT',
+    });
+}
+/**
+ * GAP-SF-22: LOCATOR_INVENTORY — per-screen map of actual extracted locators.
+ * Sourced from TestScript rows where language ends in ':locators'.
+ * Different from LOCATOR_STRATEGY which contains strategy guidance only.
+ * Refreshed after locator extraction runs.
+ */
+async function refreshLocatorInventorySkillFile(tenantId, projectId) {
+    // Check per-project skill file config
+    const sfConfig = await loadSkillFileConfigs(tenantId, projectId).then((m) => m.get('LOCATOR_INVENTORY'));
+    if (sfConfig?.enabled === false) {
+        return;
+    }
+    const existing = await app_brain_1.AppBrain.getSkillFile(tenantId, projectId, 'LOCATOR_INVENTORY').catch(() => null);
+    if (existing && (existing.approvedBy || existing.source === 'MANUAL'))
+        return;
+    const { withTenant: wt } = await import('@taodigital/database');
+    // Locators stored as TestScript rows with language ending in ':locators'
+    const locatorScripts = await wt(tenantId, (tx) => tx.testScript.findMany({
+        where: {
+            tenantId, projectId,
+            language: { endsWith: ':locators' },
+        },
+        select: { id: true, language: true, code: true, testCaseId: true },
+        take: 200,
+        orderBy: { id: 'desc' },
+    })).catch(() => []);
+    // Also query screens for mapping testCaseId → screenName
+    const testCases = await wt(tenantId, (tx) => tx.testCase.findMany({
+        where: { tenantId, projectId },
+        select: { id: true, title: true, ref: true, screenId: true,
+            screen: { select: { name: true, url: true } } },
+        take: 500,
+    })).catch(() => []);
+    const caseMap = new Map(testCases.map((tc) => [tc.id, tc]));
+    if (locatorScripts.length === 0) {
+        const content = [
+            '# Locator Inventory',
+            '',
+            '> No extracted locators yet. Run locator extraction on test cases to populate this file.',
+            '> Once populated, this file maps each screen/test case to its stable selectors.',
+        ].join('\n');
+        await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'LOCATOR_INVENTORY', content, {
+            summary: 'Locator inventory: empty (no locators extracted yet)',
+            source: 'AUTO',
+            approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+            validationStatus: 'WARN',
+            staleStatus: 'CURRENT',
+        });
+        return;
+    }
+    // Group by screen
+    const byScreen = new Map();
+    for (const ls of locatorScripts) {
+        const tc = caseMap.get(ls.testCaseId);
+        const screenName = tc?.screen?.name ?? 'Unknown Screen';
+        const screenUrl = tc?.screen?.url ?? '';
+        if (!byScreen.has(screenName))
+            byScreen.set(screenName, { screenName, url: screenUrl, entries: [] });
+        byScreen.get(screenName).entries.push({
+            ref: tc?.ref ?? ls.testCaseId.slice(0, 8),
+            title: tc?.title ?? 'Untitled',
+            locators: (ls.code ?? '').slice(0, 600),
+        });
+    }
+    const sections = [...byScreen.entries()].map(([screenName, { url, entries }]) => {
+        const header = `## ${screenName}${url ? ` (${url})` : ''}`;
+        const rows = entries.map(e => `### ${e.ref}: ${e.title}\n\`\`\`\n${e.locators}\n\`\`\``).join('\n\n');
+        return `${header}\n\n${rows}`;
+    });
+    const content = [
+        '# Locator Inventory',
+        '',
+        `> ${locatorScripts.length} locator sets extracted across ${byScreen.size} screens.`,
+        '> Use these stable selectors when generating or patching test scripts.',
+        '',
+        ...sections,
+    ].join('\n');
+    await app_brain_1.AppBrain.upsertSkillFile(tenantId, projectId, 'LOCATOR_INVENTORY', content, {
+        summary: `Locator inventory: ${locatorScripts.length} sets, ${byScreen.size} screens`,
+        source: 'AUTO',
+        approvalStatus: sfConfig?.requireApproval ? 'NEEDS_REVIEW' : 'PENDING',
+        validationStatus: 'PASS',
+        staleStatus: 'CURRENT',
+    });
+}