@test-bro/cli 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -40,6 +39,7 @@ __export(config_exports, {
   getConfigSummary: () => getConfigSummary,
   getToken: () => getToken,
   isAuthenticated: () => isAuthenticated,
+  overrideApiUrl: () => overrideApiUrl,
   readConfig: () => readConfig,
   removeActiveProject: () => removeActiveProject,
   removeApiKey: () => removeApiKey,
@@ -154,11 +154,14 @@ function removeActiveProject() {
   writeConfigRaw(config);
 }
 function getApiUrl() {
-  return readConfig().apiUrl;
+  return apiUrlOverride ?? readConfig().apiUrl;
 }
 function setApiUrl(apiUrl) {
   writeConfig({ apiUrl });
 }
+function overrideApiUrl(apiUrl) {
+  apiUrlOverride = apiUrl;
+}
 function isAuthenticated() {
   const token = getToken();
   return token !== void 0 && token.length > 0;
@@ -176,12 +179,12 @@ function getConfigSummary() {
     configPath: getConfigPath()
   };
 }
-var DEFAULT_CONFIG;
+var DEFAULT_CONFIG, apiUrlOverride;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
     DEFAULT_CONFIG = {
-      apiUrl: "https://www.testbro.dev"
+      apiUrl: "https://testbro.dev"
     };
   }
 });
@@ -198,6 +201,7 @@ __export(project_config_exports, {
   getProjectToken: () => getProjectToken,
   loadProjectConfig: () => loadProjectConfig,
   mergeWithCliOptions: () => mergeWithCliOptions,
+  resolveActiveEnvironment: () => resolveActiveEnvironment,
   substituteCredentials: () => substituteCredentials
 });
 import { existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
@@ -258,6 +262,13 @@ function getCredentialNames(config) {
   }
   return Object.keys(config.credentials);
 }
+function resolveActiveEnvironment(config, envName) {
+  if (!config?.environments) return null;
+  const name = envName || config.environment || "local";
+  const entry = config.environments[name];
+  if (!entry) return null;
+  return { name, entry };
+}
 function substituteCredentials(value, config) {
   if (!config?.credentials || !value.includes("{{credentials.")) {
     return value;
@@ -339,7 +350,7 @@ function mergeWithCliOptions(projectConfig, cliOptions) {
   return merged;
 }
 function getProjectConfigSummary() {
-  const { config, path: path9, error } = loadProjectConfig();
+  const { config, path: path10, error } = loadProjectConfig();
   let tokenSource = null;
   let token = null;
   if (process.env.TEST_BRO_TOKEN) {
@@ -357,7 +368,7 @@ function getProjectConfigSummary() {
     }
   }
   return {
-    projectConfigPath: path9,
+    projectConfigPath: path10,
     projectConfig: config,
     error,
     token,
@@ -365,7 +376,7 @@ function getProjectConfigSummary() {
     openRouterApiKey: getOpenRouterApiKey()
   };
 }
-var credentialSchema, localEnvironmentSchema, deduplicationConfigSchema, authStepSchema, authConfigSchema, projectConfigSchema, CONFIG_FILE_NAMES, CONFIG_TEMPLATE;
+var credentialSchema, deduplicationConfigSchema, authStepSchema, authConfigSchema, environmentEntrySchema, projectConfigSchema, CONFIG_FILE_NAMES, CONFIG_TEMPLATE;
 var init_project_config = __esm({
   "src/project-config.ts"() {
     "use strict";
@@ -373,11 +384,6 @@ var init_project_config = __esm({
       email: z.string().email(),
       password: z.string().min(1)
     });
-    localEnvironmentSchema = z.object({
-      name: z.string(),
-      baseUrl: z.string().url(),
-      variables: z.record(z.string()).optional()
-    });
     deduplicationConfigSchema = z.object({
       enabled: z.boolean().optional(),
       autoMerge: z.boolean().optional()
@@ -393,7 +399,16 @@ var init_project_config = __esm({
       steps: z.array(authStepSchema),
       credentials: z.record(z.string(), z.string()).optional(),
       storageStatePath: z.string().optional(),
-      maxAge: z.number().optional()
+      maxAge: z.number().optional(),
+      waitForUrl: z.string().optional()
+    });
+    environmentEntrySchema = z.object({
+      baseUrl: z.string().url(),
+      apiUrl: z.string().url().optional(),
+      credentials: z.record(z.string(), credentialSchema).optional(),
+      auth: authConfigSchema.optional(),
+      seed: z.string().optional(),
+      variables: z.record(z.string()).optional()
     });
     projectConfigSchema = z.object({
       $schema: z.string().optional(),
@@ -404,7 +419,7 @@ var init_project_config = __esm({
       headed: z.boolean().optional(),
       projectId: z.string().optional(),
       credentials: z.record(z.string(), credentialSchema).optional(),
-      environments: z.array(localEnvironmentSchema).optional(),
+      environments: z.record(z.string(), environmentEntrySchema).optional(),
       learnSelectors: z.boolean().optional(),
       verbose: z.boolean().optional(),
       deduplication: deduplicationConfigSchema.optional(),
@@ -428,6 +443,17 @@ var init_project_config = __esm({
           password: "password123"
         }
       },
+      environments: {
+        local: {
+          baseUrl: "http://localhost:3000",
+          credentials: {
+            default: {
+              email: "test@example.com",
+              password: "password123"
+            }
+          }
+        }
+      },
       deduplication: {
         enabled: true,
         autoMerge: false
@@ -439,7 +465,7 @@ var init_project_config = __esm({
 // src/index.ts
 import "dotenv/config";
 import { Command } from "commander";
-import chalk28 from "chalk";
+import chalk29 from "chalk";
 
 // src/commands/login.ts
 import chalk3 from "chalk";
@@ -616,6 +642,7 @@ async function apiRequestCore(endpoint, options = {}, authToken, requireAuth = t
   };
   if (token) {
     headers.Authorization = `Bearer ${token}`;
+    headers["x-api-key"] = token;
   }
   const response = await fetch(url, {
     ...options,
@@ -728,15 +755,6 @@ async function compareTestCases(projectId, testCases) {
     }
   );
 }
-async function saveLearnedSelectors(projectId, testCaseId, learnedSelectors) {
-  return apiRequest(
-    `/api/projects/${projectId}/test-cases/${testCaseId}/learn-selectors`,
-    {
-      method: "POST",
-      body: JSON.stringify({ learnedSelectors })
-    }
-  );
-}
 async function applyCorrections(projectId, testCaseId, corrections) {
   return apiRequest(
     `/api/projects/${projectId}/test-cases/${testCaseId}/apply-corrections`,
@@ -816,40 +834,50 @@ async function uploadArtifacts(runId, options) {
   }
   const token = getToken();
   if (!token) {
-    return {};
+    throw new Error("No API token found for artifact upload");
   }
-  try {
-    const apiUrl = getApiUrl();
-    const url = `${apiUrl}/api/runs/${runId}/artifacts`;
-    const formData = new FormData();
-    if (videoPath) {
-      const videoBuffer = fs2.readFileSync(videoPath);
-      const videoType = videoPath.endsWith(".mp4") ? "video/mp4" : "video/webm";
-      const videoBlob = new Blob([videoBuffer], { type: videoType });
-      const videoFileName = videoPath.split("/").pop() || "video.webm";
-      formData.append("video", videoBlob, videoFileName);
-    }
-    if (tracePath) {
-      const traceBuffer = fs2.readFileSync(tracePath);
-      const traceBlob = new Blob([traceBuffer], { type: "application/zip" });
-      const traceFileName = tracePath.split("/").pop() || "trace.zip";
-      formData.append("trace", traceBlob, traceFileName);
-    }
-    const response = await fetch(url, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`
-      },
-      body: formData
-    });
-    if (!response.ok) {
-      return {};
+  const apiUrl = getApiUrl();
+  const url = `${apiUrl}/api/runs/${runId}/artifacts`;
+  const formData = new FormData();
+  if (videoPath) {
+    const videoBuffer = fs2.readFileSync(videoPath);
+    const videoType = videoPath.endsWith(".mp4") ? "video/mp4" : "video/webm";
+    const videoBlob = new Blob([videoBuffer], { type: videoType });
+    const videoFileName = videoPath.split("/").pop() || "video.webm";
+    formData.append("video", videoBlob, videoFileName);
+  }
+  if (tracePath) {
+    const traceBuffer = fs2.readFileSync(tracePath);
+    const traceBlob = new Blob([traceBuffer], { type: "application/zip" });
+    const traceFileName = tracePath.split("/").pop() || "trace.zip";
+    formData.append("trace", traceBlob, traceFileName);
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`
+    },
+    body: formData
+  });
+  if (!response.ok) {
+    let details = "";
+    try {
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("application/json")) {
+        const errData = await response.json();
+        details = errData.error || JSON.stringify(errData.details || errData.data || "");
+      } else {
+        details = await response.text();
+      }
+    } catch {
+      details = "";
     }
-    const data = await response.json();
-    return data.data || {};
-  } catch {
-    return {};
+    throw new Error(
+      `Artifact upload failed (${response.status}${response.statusText ? ` ${response.statusText}` : ""})${details ? `: ${details}` : ""}`
+    );
   }
+  const data = await response.json();
+  return data.data || {};
 }
 async function listFeatures(projectId) {
   return apiRequest(`/api/projects/${projectId}/features`);
@@ -877,63 +905,102 @@ async function assignTestCaseToFeature(projectId, featureSlug, testCaseId) {
     }
   );
 }
-async function listSelectors(projectId, options) {
+async function listSelectorPages(projectId, options) {
   const params = new URLSearchParams();
-  if (options?.featureSlug) {
-    const { features } = await listFeatures(projectId);
-    const feature = features.find((f) => f.slug === options.featureSlug);
-    if (feature) {
-      params.set("featureId", feature.id);
-    } else {
-      return { selectors: [], total: 0, page: 1, limit: 50 };
-    }
-  }
-  if (options?.status) {
-    params.set("status", options.status);
-  }
+  if (options?.tag) params.set("tag", options.tag);
+  if (options?.search) params.set("search", options.search);
   const query = params.toString();
   return apiRequest(
-    `/api/projects/${projectId}/selectors${query ? `?${query}` : ""}`
+    `/api/projects/${projectId}/selector-pages${query ? `?${query}` : ""}`
+  );
+}
+async function resolveSelector(projectId, data) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-resolve`,
+    {
+      method: "POST",
+      body: JSON.stringify(data)
+    }
   );
 }
-async function bulkVerifySelectors(projectId, selectorIds) {
+async function learnSelectors(projectId, pageUrl, learnedElements) {
   return apiRequest(
-    `/api/projects/${projectId}/selectors/verify`,
+    `/api/projects/${projectId}/selector-learn`,
     {
       method: "POST",
-      body: JSON.stringify(selectorIds?.length ? { selectorIds } : {})
+      body: JSON.stringify({ pageUrl, learnedElements })
     }
   );
 }
-async function exportSelectors(projectId, options) {
+async function listSelectorElements(projectId, filters) {
   const params = new URLSearchParams();
-  params.set("format", options?.format ?? "json");
-  if (options?.status) params.set("status", options.status);
-  if (options?.featureId) params.set("featureId", options.featureId);
-  const format = options?.format ?? "json";
-  if (format === "csv") {
-    const apiUrl = getApiUrl();
-    const token = getToken();
-    const url = `${apiUrl}/api/projects/${projectId}/selectors/export?${params.toString()}`;
-    const response = await fetch(url, {
-      headers: {
-        "Content-Type": "application/json",
-        ...token ? { Authorization: `Bearer ${token}` } : {}
-      }
-    });
-    if (!response.ok) {
-      const data2 = await response.json().catch(() => ({ error: response.statusText }));
-      throw new ApiError(
-        data2.error || `Request failed: ${response.statusText}`,
-        response.status
-      );
+  if (filters?.pageId) params.set("pageId", filters.pageId);
+  if (filters?.status) params.set("status", filters.status);
+  if (filters?.tag) params.set("tag", filters.tag);
+  if (filters?.search) params.set("search", filters.search);
+  const query = params.toString();
+  return apiRequest(
+    `/api/projects/${projectId}/selector-elements${query ? `?${query}` : ""}`
+  );
+}
+async function getSelectorElementHistory(projectId, elementId, limit, offset) {
+  const params = new URLSearchParams();
+  if (limit) params.set("limit", String(limit));
+  if (offset) params.set("offset", String(offset));
+  const query = params.toString();
+  return apiRequest(
+    `/api/projects/${projectId}/selector-elements/${elementId}/history${query ? `?${query}` : ""}`
+  );
+}
+async function rollbackSelectorElement(projectId, elementId, historyId) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-elements/${elementId}/rollback`,
+    {
+      method: "POST",
+      body: JSON.stringify({ historyId })
+    }
+  );
+}
+async function exportSelectorLibrary(projectId) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-library/export`
+  );
+}
+async function importSelectorLibrary(projectId, data) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-library/import`,
+    {
+      method: "POST",
+      body: JSON.stringify(data)
+    }
+  );
+}
+async function createSelectorPage(projectId, data) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-pages`,
+    {
+      method: "POST",
+      body: JSON.stringify(data)
+    }
+  );
+}
+async function createSelectorSection(projectId, pageId, data) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-pages/${pageId}/sections`,
+    {
+      method: "POST",
+      body: JSON.stringify(data)
+    }
+  );
+}
+async function createSelectorElement(projectId, data) {
+  return apiRequest(
+    `/api/projects/${projectId}/selector-elements`,
+    {
+      method: "POST",
+      body: JSON.stringify(data)
     }
-    return await response.text();
-  }
-  const data = await apiRequest(
-    `/api/projects/${projectId}/selectors/export?${params.toString()}`
   );
-  return JSON.stringify(data.selectors, null, 2);
 }
 async function createDemoRun(projectId, data) {
   return apiRequest(
@@ -1034,10 +1101,10 @@ function extractValidationHints(details) {
       for (const issue of obj.issues) {
         if (typeof issue === "object" && issue !== null) {
           const i = issue;
-          const path9 = Array.isArray(i.path) ? i.path.join(".") : String(i.path ?? "");
+          const path10 = Array.isArray(i.path) ? i.path.join(".") : String(i.path ?? "");
           const message = typeof i.message === "string" ? i.message : "";
-          if (path9 && message) {
-            hints.push(`${path9}: ${message}`);
+          if (path10 && message) {
+            hints.push(`${path10}: ${message}`);
           } else if (message) {
             hints.push(message);
           }
@@ -1419,7 +1486,7 @@ async function quickstartCommand(options = {}) {
     console.log("");
     console.log(chalk5.yellow("  Please authenticate first:"));
     console.log("");
-    console.log(chalk5.dim("  1. Go to ") + chalk5.cyan("http://localhost:3024/dashboard/settings"));
+    console.log(chalk5.dim("  1. Go to ") + chalk5.cyan("https://testbro.dev/dashboard/settings"));
     console.log(chalk5.dim("  2. Create an API token"));
     console.log(chalk5.dim("  3. Run: ") + chalk5.cyan("testbro init") + chalk5.dim(" (or testbro login --token <your-token>)"));
     console.log("");
@@ -1434,7 +1501,7 @@ async function quickstartCommand(options = {}) {
     spinner.fail("Token is invalid or expired");
     console.log("");
     console.log(chalk5.yellow("  Please re-authenticate:"));
-    console.log(chalk5.dim("  1. Go to ") + chalk5.cyan("http://localhost:3024/dashboard/settings"));
+    console.log(chalk5.dim("  1. Go to ") + chalk5.cyan("https://testbro.dev/dashboard/settings"));
     console.log(chalk5.dim("  2. Create a new API token"));
     console.log(chalk5.dim("  3. Run: ") + chalk5.cyan("testbro init") + chalk5.dim(" (or testbro login --token <your-token>)"));
     console.log("");
@@ -1717,29 +1784,42 @@ async function resolveEnvironment(name, projectId, options = {}) {
   if (preferCloud) {
     return await resolveEnvironmentFromCloud(name, projectId) ?? resolveEnvironmentFromLocal(name);
   }
-  return resolveEnvironmentFromLocal(name) ?? (isAuthenticated2() ? resolveEnvironmentFromCloud(name, projectId) : null);
+  return resolveEnvironmentFromLocal(name) ?? (isAuthenticated() ? resolveEnvironmentFromCloud(name, projectId) : null);
 }
 async function resolveCredential(name, projectId, options = {}) {
   const { preferCloud = false } = options;
   if (preferCloud) {
     return await resolveCredentialFromCloud(name, projectId) ?? resolveCredentialFromLocal(name);
   }
-  return resolveCredentialFromLocal(name) ?? (isAuthenticated2() ? resolveCredentialFromCloud(name, projectId) : null);
+  return resolveCredentialFromLocal(name) ?? (isAuthenticated() ? resolveCredentialFromCloud(name, projectId) : null);
 }
 function resolveEnvironmentFromLocal(name) {
   const { config } = loadProjectConfig();
   if (!config?.environments) return null;
-  const match = config.environments.find(
-    (env) => env.name.toLowerCase() === name.toLowerCase()
+  const key = Object.keys(config.environments).find(
+    (k) => k.toLowerCase() === name.toLowerCase()
   );
-  if (!match) return null;
+  if (!key) return null;
+  const entry = config.environments[key];
   return {
-    name: match.name,
-    baseUrl: match.baseUrl,
-    variables: match.variables ?? {},
+    name: key,
+    baseUrl: entry.baseUrl,
+    variables: entry.variables ?? {},
     source: "local"
   };
 }
+function resolveEnvironmentConfig(envName, projectConfig) {
+  if (!projectConfig?.environments) return null;
+  const resolved = resolveActiveEnvironment(projectConfig, envName);
+  if (!resolved) return null;
+  return {
+    baseUrl: resolved.entry.baseUrl,
+    apiUrl: resolved.entry.apiUrl,
+    credentials: resolved.entry.credentials,
+    auth: resolved.entry.auth,
+    envName: resolved.name
+  };
+}
 async function resolveEnvironmentFromCloud(name, projectId) {
   try {
     const environments = await getProjectEnvironments(projectId);
@@ -1798,10 +1878,6 @@ async function resolveCredentialFromCloud(name, projectId) {
     throw error;
   }
 }
-function isAuthenticated2() {
-  const token = getToken();
-  return token !== void 0 && token.length > 0;
-}
 
 // src/commands/auth/auth-executor.ts
 import * as fs3 from "fs";
@@ -1875,7 +1951,7 @@ var AuthExecutor = class _AuthExecutor {
         );
         await _AuthExecutor.executeStep(page, resolvedStep);
       }
-      await page.waitForTimeout(2e3);
+      await _AuthExecutor.waitForAuthComplete(page, authConfig, loginUrl);
       await context.storageState({ path: statePath });
       return statePath;
     } finally {
@@ -2034,6 +2110,42 @@ var AuthExecutor = class _AuthExecutor {
       }
     }
   }
+  /**
+   * Wait for the authentication flow to fully complete after all steps.
+   *
+   * Handles redirect-based auth flows (e.g., NextAuth v5 server actions)
+   * where the session cookie is set during a redirect chain, not on the
+   * initial response. Uses three strategies in order:
+   *
+   * 1. If `waitForUrl` is configured, wait for that specific URL pattern
+   * 2. Otherwise, detect URL change from the login page (redirect completed)
+   * 3. Wait for network idle to ensure all Set-Cookie headers are processed
+   */
+  static async waitForAuthComplete(page, authConfig, loginUrl) {
+    const waitTimeout = 15e3;
+    if (authConfig.waitForUrl) {
+      try {
+        await page.waitForURL(authConfig.waitForUrl, {
+          timeout: waitTimeout,
+          waitUntil: "load"
+        });
+      } catch {
+      }
+    } else {
+      try {
+        await page.waitForURL(
+          (url) => url.toString() !== loginUrl,
+          { timeout: waitTimeout, waitUntil: "load" }
+        );
+      } catch {
+      }
+    }
+    try {
+      await page.waitForLoadState("networkidle", { timeout: 5e3 });
+    } catch {
+    }
+    await page.waitForTimeout(1e3);
+  }
   /**
    * Delete the cached storage state file.
    * @param statePath - Path to the storage state file
@@ -2733,8 +2845,8 @@ function stripLoginSteps(steps) {
   }
   return loginEndIndex > 0 ? steps.slice(loginEndIndex) : steps;
 }
-function convertToTestPlan(projectTestCases, runId, projectConfig) {
-  const authEnabled = !!projectConfig?.auth;
+function convertToTestPlan(projectTestCases, runId, projectConfig, authEnabled) {
+  const shouldStripLogin = authEnabled ?? !!projectConfig?.auth;
   const testCases = projectTestCases.map((ptc) => {
     const steps = ptc.steps.map((step, stepIndex) => {
       let target;
@@ -2772,7 +2884,7 @@ function convertToTestPlan(projectTestCases, runId, projectConfig) {
         assertion
       };
     });
-    const finalSteps = authEnabled ? stripLoginSteps(steps) : steps;
+    const finalSteps = shouldStripLogin ? stripLoginSteps(steps) : steps;
     return {
       id: ptc.id,
       name: ptc.name,
@@ -2799,8 +2911,11 @@ async function buildTestPlan(options) {
     generatedFromFile,
     fileGeneratedTestCases,
     projectConfig,
-    isPretty
+    isPretty,
+    environment,
+    authEnabled
   } = options;
+  const envName = environment || (remote ? "staging" : "local");
   const useProjectTestCases = !description && !generatedFromFile && projectId;
   if (generatedFromFile && fileGeneratedTestCases) {
     return buildFromGeneratedTestCases(
@@ -2808,9 +2923,10 @@ async function buildTestPlan(options) {
       file,
       projectId,
       url,
-      remote,
+      envName,
       projectConfig,
-      isPretty
+      isPretty,
+      authEnabled
     );
   }
   if (useProjectTestCases) {
@@ -2818,34 +2934,35 @@ async function buildTestPlan(options) {
       projectId,
       testCaseId,
       url,
-      remote,
+      envName,
       projectConfig,
-      isPretty
+      isPretty,
+      authEnabled
     );
   }
-  return buildFromDescription(description, url, remote, projectId, isPretty);
+  return buildFromDescription(description, url, envName, projectId, isPretty);
 }
-async function buildFromGeneratedTestCases(testCases, file, projectId, url, remote, projectConfig, isPretty) {
+async function buildFromGeneratedTestCases(testCases, file, projectId, url, envName, projectConfig, isPretty, authEnabled) {
   const { project: projectInfo } = await getProject(projectId);
   const createSpinnerInstance = isPretty ? createSpinner("Creating test run...").start() : null;
   const featureDesc = `Generated from: ${path4.basename(file)}`;
   const createResponse = await createRun(
     featureDesc,
     url,
-    remote ? "staging" : "local",
+    envName,
     projectId
   );
   const runId = createResponse.run.id;
   createSpinnerInstance?.succeed(
     `Test run created ${chalk9.dim(`(ID: ${runId.slice(0, 8)}...)`)}`
   );
-  const testPlan = convertToTestPlan(testCases, runId, projectConfig);
+  const testPlan = convertToTestPlan(testCases, runId, projectConfig, authEnabled);
   if (isPretty) {
     log.info(`Running ${testCases.length} generated test case${testCases.length === 1 ? "" : "s"}...`);
   }
   return { runId, testPlan };
 }
-async function buildFromProjectTestCases(projectId, testCaseId, url, remote, projectConfig, isPretty) {
+async function buildFromProjectTestCases(projectId, testCaseId, url, envName, projectConfig, isPretty, authEnabled) {
   const projectSpinner = isPretty ? createSpinner("Fetching project test cases...").start() : null;
   try {
     const { project: projectInfo } = await getProject(projectId);
@@ -2871,14 +2988,14 @@ async function buildFromProjectTestCases(projectId, testCaseId, url, remote, pro
     const createResponse = await createRun(
       featureDesc,
       url,
-      remote ? "staging" : "local",
+      envName,
       projectId
     );
     const runId = createResponse.run.id;
     createSpinnerInstance?.succeed(
       `Test run created ${chalk9.dim(`(ID: ${runId.slice(0, 8)}...)`)}`
     );
-    const testPlan = convertToTestPlan(projectTestCases, runId, projectConfig);
+    const testPlan = convertToTestPlan(projectTestCases, runId, projectConfig, authEnabled);
     return { runId, testPlan };
   } catch (error) {
     projectSpinner?.fail("Failed to fetch project");
@@ -2895,12 +3012,12 @@ async function buildFromProjectTestCases(projectId, testCaseId, url, remote, pro
     process.exit(1);
   }
 }
-async function buildFromDescription(description, url, remote, projectId, isPretty) {
+async function buildFromDescription(description, url, envName, projectId, isPretty) {
   const createSpinnerInstance = isPretty ? createSpinner("Creating test run...").start() : null;
   const createResponse = await createRun(
     description,
     url,
-    remote ? "staging" : "local",
+    envName,
     projectId
   );
   const runId = createResponse.run.id;
@@ -3434,6 +3551,17 @@ You are a GOAL-ORIENTED test agent. Each step describes an INTENT, not a rigid i
 - Always explain your reasoning when deviating from the original step description
 - If an element is below the fold, suggest scrolling first
 
+## Intent Safety Guardrails
+- NEVER click or fill a semantically unrelated element just to make progress.
+- If the requested target is not present, do NOT guess a random alternative action.
+- Preserve intent class when adapting. Examples:
+  - form input intent -> editable field
+  - navigation intent -> relevant nav control/link
+  - confirmation intent -> intended submit/confirm action
+- Prefer this fallback order when target is missing: **scroll -> wait -> navigate/click a clearly relevant entry point for the SAME intent class**.
+- Before acting, validate evidence from Available Elements and visible UI cues (role, label, testId, text). If evidence is weak or ambiguous, lower confidence or choose wait/scroll instead of a risky click.
+- If no relevant action is possible on the current page, return confidence 0 and explain why.
+
 Always respond with valid JSON only. Do not include any other text.`;
 var MAX_MEMORY_ENTRIES = 10;
 function formatStepMemory(memory) {
@@ -3497,7 +3625,9 @@ function generateFillPrompt(fieldDescription, textToEnter, availableElements, me
 Then type: "${textToEnter}"`,
     `IMPORTANT: For fill actions, you MUST target an <input>, <textarea>, or <select> element \u2014 NOT a link, button, div, or card.
 If a dialog or modal is open, look for input fields INSIDE the dialog, not behind it.
-Identify the input field and provide coordinates to click it before typing. Look for data-testid, name, or placeholder attributes for the best selector.`,
+Identify the input field and provide coordinates to click it before typing. Look for data-testid, name, or placeholder attributes for the best selector.
+If no editable field for this intent is visible, do NOT fill a non-input element.
+If input is unavailable in current state, choose a preparatory step that keeps the same intent class (e.g., open relevant form/screen), otherwise return confidence 0.`,
     availableElements,
     memoryContext
   );
@@ -3571,6 +3701,9 @@ Consider:
 - You may need to scroll to find the element
 - A modal or overlay may be blocking \u2014 close it first
 - The page may be in a different state than expected \u2014 adapt accordingly
+- Preserve intent class when adapting (input -> input, navigation -> navigation, assertion -> evidence)
+- Prefer preparatory actions (scroll/wait/open relevant surface) before risky substitutions
+- NEVER use an unrelated element as a substitute action
 - If the intent is truly impossible on this page, set confidence to 0
 
 Respond with the action you would take to achieve the intent.`
@@ -6044,6 +6177,7 @@ var HybridTestExecutor = class {
     this.videoDir = null;
     this.traceDir = null;
     this.traceFilePath = null;
+    this.libraryIndex = null;
     this.options = {
       baseUrl: options.baseUrl ?? "",
       headed: options.headed ?? false,
@@ -6055,6 +6189,9 @@ var HybridTestExecutor = class {
       storageStatePath: options.storageStatePath ?? "",
       actionModel: options.actionModel ?? DEFAULT_ACTION_MODEL2,
       assertionModel: options.assertionModel ?? DEFAULT_ASSERTION_MODEL2,
+      apiBaseUrl: options.apiBaseUrl ?? "",
+      apiToken: options.apiToken ?? "",
+      projectId: options.projectId ?? "",
       visionClientOptions: options.visionClientOptions,
       onStepComplete: options.onStepComplete,
       onTestCaseStart: options.onTestCaseStart,
@@ -6268,16 +6405,17 @@ var HybridTestExecutor = class {
    * Execute a single step with hybrid logic
    */
   async executeStep(step) {
-    const hasSelectors = (step.target?.suggestedStrategies?.length ?? 0) > 0;
+    const enrichedStep = this.enrichStepFromLibrary(step);
+    const hasSelectors = (enrichedStep.target?.suggestedStrategies?.length ?? 0) > 0;
     const hasAI = this.visionClient && this.aiExecutor;
-    if (step.action === "navigate" && step.value) {
-      return this.executeNavigate(step);
+    if (enrichedStep.action === "navigate" && enrichedStep.value) {
+      return this.executeNavigate(enrichedStep);
     }
     if (hasSelectors) {
-      const selectorResult = await this.trySelector(step);
+      const selectorResult = await this.trySelector(enrichedStep);
       if (selectorResult.success) {
         const result3 = {
-          stepId: step.id,
+          stepId: enrichedStep.id,
           status: "passed",
           method: "selector",
           duration: selectorResult.duration,
@@ -6287,22 +6425,12 @@ var HybridTestExecutor = class {
         return result3;
       }
       if (hasAI) {
-        this.options.onFallback?.(step.id, selectorResult.error || "Selector failed");
-        const aiLog = await this.executeWithAI(step);
+        this.options.onFallback?.(enrichedStep.id, selectorResult.error || "Selector failed");
+        const aiLog = await this.executeWithAI(enrichedStep);
         if (aiLog?.success) {
-          let learnedSelector;
-          if (this.options.learnFromFallback && aiLog.element) {
-            const strategies = generateSelectors(aiLog.element);
-            if (strategies.length > 0) {
-              learnedSelector = {
-                stepId: step.id,
-                elementDescription: aiLog.action.elementDescription || "",
-                strategies
-              };
-            }
-          }
+          const learnedSelector = this.learnFromAIResult(enrichedStep.id, aiLog);
           const result4 = {
-            stepId: step.id,
+            stepId: enrichedStep.id,
             status: "passed",
             method: "fallback",
             duration: (selectorResult.duration || 0) + aiLog.duration,
@@ -6315,7 +6443,7 @@ var HybridTestExecutor = class {
           return result4;
         }
         const result3 = {
-          stepId: step.id,
+          stepId: enrichedStep.id,
           status: "failed",
           method: "fallback",
           duration: (selectorResult.duration || 0) + (aiLog?.duration || 0),
@@ -6328,7 +6456,7 @@ var HybridTestExecutor = class {
         return result3;
       }
       const result2 = {
-        stepId: step.id,
+        stepId: enrichedStep.id,
         status: "failed",
         method: "selector",
         duration: selectorResult.duration,
@@ -6340,20 +6468,10 @@ var HybridTestExecutor = class {
       return result2;
     }
     if (hasAI) {
-      const aiLog = await this.executeWithAI(step);
-      let learnedSelector;
-      if (aiLog?.success && this.options.learnFromFallback && aiLog.element) {
-        const strategies = generateSelectors(aiLog.element);
-        if (strategies.length > 0) {
-          learnedSelector = {
-            stepId: step.id,
-            elementDescription: aiLog.action.elementDescription || "",
-            strategies
-          };
-        }
-      }
+      const aiLog = await this.executeWithAI(enrichedStep);
+      const learnedSelector = aiLog?.success ? this.learnFromAIResult(enrichedStep.id, aiLog) : void 0;
       const result2 = {
-        stepId: step.id,
+        stepId: enrichedStep.id,
         status: aiLog?.success ? "passed" : "failed",
         method: "ai",
         duration: aiLog?.duration || 0,
@@ -6365,7 +6483,7 @@ var HybridTestExecutor = class {
       return result2;
     }
     const result = {
-      stepId: step.id,
+      stepId: enrichedStep.id,
       status: "failed",
       method: "selector",
       duration: 0,
@@ -6470,6 +6588,7 @@ var HybridTestExecutor = class {
   async executeTestPlan(testPlan, options) {
     const sequential = options?.sequential ?? true;
     const results = [];
+    await this.fetchLibraryIndex();
     if (this.options.baseUrl && this.page) {
       await this.page.goto(this.options.baseUrl, {
         waitUntil: "domcontentloaded",
@@ -6493,6 +6612,174 @@ var HybridTestExecutor = class {
     }
     return results;
   }
+  /**
+   * Attempt to learn selectors from a successful AI execution.
+   * Returns a LearnedSelector if strategies were generated, undefined otherwise.
+   */
+  learnFromAIResult(stepId, aiLog) {
+    if (!this.options.learnFromFallback || !aiLog.element) return void 0;
+    const strategies = generateSelectors(aiLog.element);
+    if (strategies.length === 0) return void 0;
+    const elementDescription = aiLog.action.elementDescription || "";
+    if (this.page) {
+      const pageUrl = this.page.url();
+      const tagName = aiLog.element.tagName?.toLowerCase();
+      this.learnToLibrary(pageUrl, elementDescription, tagName, strategies).catch(() => {
+      });
+    }
+    return { stepId, elementDescription, strategies };
+  }
+  /**
+   * Call the selector-learn API to persist learned selectors to the library.
+   * Fire-and-forget: failures are logged but do not affect execution.
+   */
+  async learnToLibrary(pageUrl, elementDescription, elementRole, strategies) {
+    const { apiBaseUrl, apiToken, projectId } = this.options;
+    if (!apiBaseUrl || !apiToken || !projectId) return;
+    try {
+      const url = `${apiBaseUrl}/api/projects/${projectId}/selector-learn`;
+      await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiToken}`,
+          "x-api-key": apiToken
+        },
+        body: JSON.stringify({
+          pageUrl,
+          learnedElements: [
+            {
+              elementDescription,
+              elementRole,
+              strategies
+            }
+          ]
+        }),
+        signal: AbortSignal.timeout(1e4)
+      });
+    } catch {
+    }
+  }
+  /**
+   * Fetch the full library export and cache it for the duration of plan execution.
+   * Called once before executeTestPlan; failures are non-fatal.
+   */
+  async fetchLibraryIndex() {
+    const { apiBaseUrl, apiToken, projectId } = this.options;
+    if (!apiBaseUrl || !apiToken || !projectId) return;
+    try {
+      const url = `${apiBaseUrl}/api/projects/${projectId}/selector-library/export`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          "x-api-key": apiToken
+        },
+        signal: AbortSignal.timeout(15e3)
+      });
+      if (!response.ok) return;
+      const json = await response.json();
+      const exportData = json.data ?? json;
+      if (!Array.isArray(exportData?.pages)) return;
+      const pages = exportData.pages.map((p) => ({
+        urlPattern: p.urlPattern,
+        elements: (p.sections ?? []).flatMap(
+          (s) => (s.elements ?? []).map((e) => ({
+            name: e.name,
+            aliases: e.aliases ?? [],
+            elementRole: e.elementRole ?? null,
+            strategies: (e.strategies ?? []).map((st) => ({
+              type: st.type,
+              value: st.value,
+              playwrightLocator: st.playwrightLocator,
+              confidence: st.confidence ?? 0.8,
+              rank: st.rank ?? 0
+            }))
+          }))
+        )
+      }));
+      this.libraryIndex = { pages, fetchedAt: Date.now() };
+    } catch {
+    }
+  }
+  /**
+   * Enrich a test step's suggestedStrategies using the cached library index.
+   * Finds matching elements by description and injects their strategies.
+   */
+  enrichStepFromLibrary(step) {
+    if (!this.libraryIndex) return step;
+    if (step.action === "navigate") return step;
+    const description = step.target?.elementDescription || step.description;
+    if (!description) return step;
+    const currentUrl = this.page?.url() ?? "";
+    const descLower = description.toLowerCase().trim();
+    let matchingPages = this.libraryIndex.pages;
+    if (currentUrl) {
+      try {
+        const urlPath = new URL(currentUrl).pathname;
+        const exactPageMatch = matchingPages.filter(
+          (p) => urlPath === p.urlPattern || urlPath.startsWith(p.urlPattern)
+        );
+        if (exactPageMatch.length > 0) {
+          matchingPages = exactPageMatch;
+        }
+      } catch {
+      }
+    }
+    const allElements = matchingPages.flatMap((p) => p.elements);
+    if (allElements.length === 0) return step;
+    let bestMatch = null;
+    let bestScore = 0;
+    const THRESHOLD = 0.7;
+    for (const el of allElements) {
+      let score = 0;
+      const elNameLower = el.name.toLowerCase();
+      if (descLower === elNameLower) {
+        score = 1;
+      } else if (el.aliases.some((a) => a.toLowerCase() === descLower)) {
+        score = 0.95;
+      } else if (elNameLower.includes(descLower) || descLower.includes(elNameLower)) {
+        score = 0.8;
+      } else {
+        const descWords = descLower.split(/\s+/);
+        const nameWords = elNameLower.split(/\s+/);
+        const overlap = descWords.filter((w) => nameWords.includes(w)).length;
+        const maxWords = Math.max(descWords.length, nameWords.length);
+        if (maxWords > 0) {
+          score = 0.6 * (overlap / maxWords);
+        }
+      }
+      if (el.elementRole && descLower.includes(el.elementRole.toLowerCase())) {
+        score = Math.min(1, score + 0.1);
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = el;
+      }
+    }
+    if (!bestMatch || bestScore < THRESHOLD) return step;
+    const libraryStrategies = bestMatch.strategies.sort((a, b) => a.rank - b.rank).map((s) => ({
+      type: s.type,
+      value: s.value,
+      confidence: s.confidence,
+      playwrightLocator: s.playwrightLocator
+    }));
+    if (libraryStrategies.length === 0) return step;
+    const existingStrategies = step.target?.suggestedStrategies ?? [];
+    const existingKeys = new Set(existingStrategies.map((s) => `${s.type}:${s.value}`));
+    const mergedStrategies = [
+      ...libraryStrategies.filter((s) => !existingKeys.has(`${s.type}:${s.value}`)),
+      ...existingStrategies
+    ];
+    return {
+      ...step,
+      target: {
+        elementDescription: step.target?.elementDescription || description,
+        suggestedStrategies: mergedStrategies,
+        elementId: step.target?.elementId
+      }
+    };
+  }
   /**
    * Convert hybrid results to standard StepResult format
    */
@@ -6719,8 +7006,72 @@ function inferRoleFromDescription(description) {
   }
   return null;
 }
+function createLocatorFromPlaywrightString(page, playwrightLocator) {
+  try {
+    const testidMatch = playwrightLocator.match(/^getByTestId\(['"](.+?)['"]\)$/);
+    if (testidMatch) {
+      return {
+        locator: page.getByTestId(testidMatch[1]),
+        selectorString: `testid="${testidMatch[1]}"`
+      };
+    }
+    const roleWithNameMatch = playwrightLocator.match(
+      /^getByRole\(['"](.+?)['"],\s*\{\s*name:\s*['"](.+?)['"]\s*\}\)$/
+    );
+    if (roleWithNameMatch) {
+      return {
+        locator: page.getByRole(roleWithNameMatch[1], {
+          name: roleWithNameMatch[2]
+        }),
+        selectorString: `role=${roleWithNameMatch[1]}[name="${roleWithNameMatch[2]}"]`
+      };
+    }
+    const roleMatch = playwrightLocator.match(/^getByRole\(['"](.+?)['"]\)$/);
+    if (roleMatch) {
+      return {
+        locator: page.getByRole(roleMatch[1]),
+        selectorString: `role=${roleMatch[1]}`
+      };
+    }
+    const labelMatch = playwrightLocator.match(/^getByLabel\(['"](.+?)['"]\)$/);
+    if (labelMatch) {
+      return {
+        locator: page.getByLabel(labelMatch[1]),
+        selectorString: `label="${labelMatch[1]}"`
+      };
+    }
+    const placeholderMatch = playwrightLocator.match(/^getByPlaceholder\(['"](.+?)['"]\)$/);
+    if (placeholderMatch) {
+      return {
+        locator: page.getByPlaceholder(placeholderMatch[1]),
+        selectorString: `placeholder="${placeholderMatch[1]}"`
+      };
+    }
+    const textMatch = playwrightLocator.match(/^getByText\(['"](.+?)['"]\)$/);
+    if (textMatch) {
+      return {
+        locator: page.getByText(textMatch[1]),
+        selectorString: `text="${textMatch[1]}"`
+      };
+    }
+    const locatorMatch = playwrightLocator.match(/^locator\(['"](.+?)['"]\)$/);
+    if (locatorMatch) {
+      return {
+        locator: page.locator(locatorMatch[1]),
+        selectorString: `css=${locatorMatch[1]}`
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function createLocatorForStrategy(page, strategy, options) {
   const { exact = false } = options;
+  if (strategy.playwrightLocator) {
+    const result = createLocatorFromPlaywrightString(page, strategy.playwrightLocator);
+    if (result) return result;
+  }
   switch (strategy.type) {
     case "role": {
       const [role, ...nameParts] = strategy.value.split(":");
@@ -6799,7 +7150,7 @@ function sortStrategies(strategies) {
     return b.confidence - a.confidence;
   });
 }
-async function resolveSelector(page, hint, options = {}) {
+async function resolveSelector2(page, hint, options = {}) {
   const { timeout = 5e3, maxAttempts } = options;
   const attemptedStrategies = [];
   const sortedStrategies = sortStrategies(hint.suggestedStrategies);
@@ -6951,7 +7302,7 @@ async function resolveTarget(page, step, timeout) {
       step.target.elementDescription
     )
   };
-  return resolveSelector(page, hint, { timeout });
+  return resolveSelector2(page, hint, { timeout });
 }
 async function handleNavigate(page, step, options) {
   const { timeout = 3e4 } = options;
@@ -7629,6 +7980,7 @@ async function executeWithSelectors(testPlan, options) {
 
 // src/commands/run/executors/hybrid-executor.ts
 import chalk13 from "chalk";
+init_config();
 async function executeWithHybrid(testPlan, options) {
   const { url, headed, timeout, verbose, isPretty, recordVideo, recordTrace, storageStatePath, sequential } = options;
   const config = await getCliConfig().catch(() => null);
@@ -7640,6 +7992,8 @@ async function executeWithHybrid(testPlan, options) {
   }
   const learnedSelectors = [];
   const modelOverride = process.env.AI_MODEL;
+  const apiBaseUrl = getApiUrl();
+  const apiToken = getToken();
   const hybridExecutor = new HybridTestExecutor({
     baseUrl: url,
     headed,
@@ -7651,6 +8005,10 @@ async function executeWithHybrid(testPlan, options) {
     storageStatePath,
     actionModel: modelOverride || void 0,
     assertionModel: modelOverride || void 0,
+    // Selector Library integration: AI agent will call /selector-learn after successful fallbacks
+    apiBaseUrl: apiBaseUrl || void 0,
+    apiToken: apiToken || void 0,
+    projectId: options.projectId || void 0,
     visionClientOptions: apiKey ? {
       apiKey,
       timeout: 3e4
@@ -7962,8 +8320,8 @@ function displayHybridSummary(summary, results, isPretty) {
 // src/commands/run/executors/selector-learning.ts
 import chalk15 from "chalk";
 async function handleAISelectorLearning(learnedSelectors, options) {
-  const { projectId, testCaseId, learnSelectors, yes, verbose, isPretty } = options;
-  if (!learnSelectors) {
+  const { projectId, learnSelectors: shouldLearn, yes, verbose, isPretty, targetUrl } = options;
+  if (!shouldLearn) {
     return;
   }
   if (learnedSelectors.length === 0) {
@@ -7975,41 +8333,26 @@ async function handleAISelectorLearning(learnedSelectors, options) {
   if (isPretty) {
     displayLearnedSelectors(learnedSelectors, verbose);
   }
-  if (projectId && testCaseId) {
+  if (projectId) {
     let shouldSave = yes;
     if (!shouldSave && isPretty) {
       shouldSave = await promptConfirmation(
-        chalk15.yellow("Save learned selectors to test case?")
+        chalk15.yellow("Save learned selectors to library?")
       );
     }
     if (shouldSave) {
-      const saveSpinner = isPretty ? createSpinner("Saving learned selectors...").start() : null;
-      try {
-        const saveResult = await saveLearnedSelectors(
-          projectId,
-          testCaseId,
-          learnedSelectors
-        );
-        saveSpinner?.succeed(
-          `Saved selectors for ${saveResult.updatedSteps} step${saveResult.updatedSteps === 1 ? "" : "s"}`
-        );
-      } catch (saveError) {
-        saveSpinner?.fail("Failed to save learned selectors");
-        if (verbose && saveError instanceof Error) {
-          console.warn(chalk15.yellow(`  ${saveError.message}`));
-        }
-      }
+      await saveToLibrary(projectId, learnedSelectors, targetUrl, isPretty, verbose);
     } else if (isPretty) {
       log.dim("Selector learning skipped.");
     }
   } else if (isPretty) {
-    log.dim("Selectors displayed but not saved (no specific test case).");
-    log.dim("Use --project and --test-case to save selectors.");
+    log.dim("Selectors displayed but not saved (no project configured).");
+    log.dim("Use --project to save selectors to the library.");
   }
 }
 async function handleHybridSelectorLearning(learnedSelectors, options) {
-  const { projectId, testCaseId, learnSelectors, yes, verbose, isPretty } = options;
-  if (!learnSelectors) {
+  const { projectId, learnSelectors: shouldLearn, yes, verbose, isPretty, targetUrl } = options;
+  if (!shouldLearn) {
     return;
   }
   if (learnedSelectors.length === 0) {
@@ -8021,36 +8364,50 @@ async function handleHybridSelectorLearning(learnedSelectors, options) {
   if (isPretty) {
     displayLearnedSelectors(learnedSelectors, verbose);
   }
-  if (projectId && testCaseId) {
+  if (projectId) {
     let shouldSave = yes;
     if (!shouldSave && isPretty) {
       shouldSave = await promptConfirmation(
-        chalk15.yellow("Save learned selectors to test case?")
+        chalk15.yellow("Save learned selectors to library?")
       );
     }
     if (shouldSave) {
-      const saveSpinner = isPretty ? createSpinner("Saving learned selectors...").start() : null;
-      try {
-        const saveResult = await saveLearnedSelectors(
-          projectId,
-          testCaseId,
-          learnedSelectors
-        );
-        saveSpinner?.succeed(
-          `Saved selectors for ${saveResult.updatedSteps} step${saveResult.updatedSteps === 1 ? "" : "s"}`
-        );
-      } catch (saveError) {
-        saveSpinner?.fail("Failed to save learned selectors");
-        if (verbose && saveError instanceof Error) {
-          console.warn(chalk15.yellow(`  ${saveError.message}`));
-        }
-      }
+      await saveToLibrary(projectId, learnedSelectors, targetUrl, isPretty, verbose);
     } else if (isPretty) {
       log.dim("Selector learning skipped.");
     }
   } else if (isPretty) {
-    log.dim("Selectors displayed but not saved (no specific test case).");
-    log.dim("Use --project and --test-case to save selectors.");
+    log.dim("Selectors displayed but not saved (no project configured).");
+    log.dim("Use --project to save selectors to the library.");
+  }
+}
+async function saveToLibrary(projectId, learnedSelectors, targetUrl, isPretty, verbose) {
+  const saveSpinner = isPretty ? createSpinner("Saving selectors to library...").start() : null;
+  try {
+    const elements = learnedSelectors.map((ls) => ({
+      elementDescription: ls.elementDescription || "Unknown element",
+      strategies: ls.strategies.map((s) => ({
+        type: s.type || "css",
+        value: s.value || "",
+        playwrightLocator: s.playwrightLocator || s.value || "",
+        confidence: s.confidence ?? 0.8
+      }))
+    }));
+    const validElements = elements.filter((e) => e.strategies.length > 0);
+    const result = await learnSelectors(
+      projectId,
+      targetUrl || "",
+      validElements
+    );
+    const count = result.created.elements + result.updated.elements;
+    saveSpinner?.succeed(
+      `Saved ${count} selector${count === 1 ? "" : "s"} to library`
+    );
+  } catch (saveError) {
+    saveSpinner?.fail("Failed to save selectors to library");
+    if (verbose && saveError instanceof Error) {
+      console.warn(chalk15.yellow(`  ${saveError.message}`));
+    }
   }
 }
 
@@ -8070,7 +8427,7 @@ async function runCommand(options) {
     format = "pretty",
     verbose = false,
     timeout = 3e4,
-    learnSelectors = false,
+    learnSelectors: learnSelectors2 = false,
     yes = false,
     noDedup = false,
     autoMerge = false,
@@ -8092,10 +8449,31 @@ async function runCommand(options) {
   }
   const projectId = project || getActiveProject();
   let url = rawUrl;
-  if (envName) {
-    try {
-      if (isPretty) {
-        log.info(`Resolving environment "${envName}"...`);
+  let resolvedEnvName = envName || projectConfig?.environment || "local";
+  let envAuth = projectConfig?.auth;
+  const envConfig = resolveEnvironmentConfig(envName || projectConfig?.environment, projectConfig);
+  if (envConfig) {
+    if (!rawUrl) {
+      url = envConfig.baseUrl || rawUrl;
+    }
+    resolvedEnvName = envConfig.envName;
+    if (envConfig.auth) {
+      envAuth = envConfig.auth;
+    }
+    if (envConfig.apiUrl) {
+      overrideApiUrl(envConfig.apiUrl);
+    }
+    if (isPretty) {
+      log.info(`Using environment "${envConfig.envName}" ${chalk16.dim("(local)")}: ${chalk16.cyan(envConfig.baseUrl || "N/A")}`);
+      if (envConfig.apiUrl) {
+        log.info(`  API: ${chalk16.cyan(envConfig.apiUrl)}`);
+      }
+      log.newline();
+    }
+  } else if (envName) {
+    try {
+      if (isPretty) {
+        log.info(`Resolving environment "${envName}"...`);
       }
       const resolvedEnv = projectId ? await resolveEnvironment(envName, projectId) : null;
       if (!resolvedEnv) {
@@ -8145,11 +8523,10 @@ async function runCommand(options) {
     }
   }
   let storageStatePath;
-  const authConfig = projectConfig?.auth;
-  if (authConfig) {
-    const statePath = path7.resolve(authConfig.storageStatePath || DEFAULT_STATE_PATH);
-    const maxAge = authConfig.maxAge || DEFAULT_MAX_AGE;
-    const credentials = { ...authConfig.credentials };
+  if (envAuth) {
+    const statePath = path7.resolve(envAuth.storageStatePath || DEFAULT_STATE_PATH);
+    const maxAge = envAuth.maxAge || DEFAULT_MAX_AGE;
+    const credentials = { ...envAuth.credentials };
     if (AuthExecutor.hasFreshState(statePath, maxAge)) {
       if (isPretty) {
         log.dim("  Using cached auth state");
@@ -8161,7 +8538,7 @@ async function runCommand(options) {
       }
       try {
         const targetUrl = url || projectConfig?.baseUrl || "";
-        storageStatePath = await AuthExecutor.authenticate(authConfig, targetUrl, credentials);
+        storageStatePath = await AuthExecutor.authenticate(envAuth, targetUrl, credentials);
         if (isPretty) {
           console.log(chalk16.green("  \u2713 Authenticated"));
         }
@@ -8201,7 +8578,9 @@ async function runCommand(options) {
       generatedFromFile,
       fileGeneratedTestCases,
       projectConfig,
-      isPretty
+      isPretty,
+      environment: resolvedEnvName,
+      authEnabled: !!envAuth
     });
     await runTestExecution({
       testPlan,
@@ -8215,7 +8594,7 @@ async function runCommand(options) {
       reporter,
       projectId,
       testCaseId,
-      learnSelectors,
+      learnSelectors: learnSelectors2,
       yes,
       recordVideo,
       recordTrace,
@@ -8272,7 +8651,7 @@ async function handleFileOption(file, projectId, isPretty, verbose, noDedup, aut
   }
 }
 async function runTestExecution(options) {
-  const { testPlan, runId, mode, url, headed, timeout, verbose, isPretty, reporter, projectId, testCaseId, learnSelectors, yes, recordVideo, recordTrace, storageStatePath, sequential } = options;
+  const { testPlan, runId, mode, url, headed, timeout, verbose, isPretty, reporter, projectId, testCaseId, learnSelectors: learnSelectors2, yes, recordVideo, recordTrace, storageStatePath, sequential } = options;
   if (isPretty) {
     log.newline();
     const modeLabel = mode === "ai" ? chalk16.magenta("[AI Mode]") : mode === "hybrid" ? chalk16.yellow("[Hybrid Mode]") : chalk16.cyan("[Selector Mode]");
@@ -8299,15 +8678,15 @@ async function runTestExecution(options) {
       await submitAICorrections(aiResults.results, testPlan, projectId, isPretty, verbose);
     }
     const learnedSelectors = extractLearnedSelectors(aiResults.results);
-    await handleAISelectorLearning(learnedSelectors, { projectId, testCaseId, learnSelectors, yes, verbose, isPretty });
+    await handleAISelectorLearning(learnedSelectors, { projectId, testCaseId, learnSelectors: learnSelectors2, yes, verbose, isPretty, targetUrl: url });
   } else if (mode === "hybrid") {
-    const hybridResults = await executeWithHybrid(testPlan, { url, headed, timeout, verbose, isPretty, recordVideo, recordTrace, storageStatePath, sequential });
+    const hybridResults = await executeWithHybrid(testPlan, { url, headed, timeout, verbose, isPretty, recordVideo, recordTrace, storageStatePath, sequential, projectId });
     summary = hybridResults.summary;
     videoPath = hybridResults.videoPath;
     tracePath = hybridResults.tracePath;
     await submitHybridResults(runId, hybridResults.results, isPretty, verbose);
     displayHybridSummary(summary, hybridResults.results, isPretty);
-    await handleHybridSelectorLearning(hybridResults.learnedSelectors, { projectId, testCaseId, learnSelectors, yes, verbose, isPretty });
+    await handleHybridSelectorLearning(hybridResults.learnedSelectors, { projectId, testCaseId, learnSelectors: learnSelectors2, yes, verbose, isPretty, targetUrl: url });
   } else {
     const results = await executeWithSelectors(testPlan, { url, headed, timeout, isPretty, reporter, recordVideo, recordTrace, storageStatePath, sequential });
     summary = { passed: results.summary.passed, failed: results.summary.failed, total: results.summary.total };
@@ -8349,28 +8728,42 @@ async function runTestExecution(options) {
       if (isPretty) {
         if (uploadResult.videoUrl) {
           log.plain(`${chalk16.bold("Video URL:")} ${chalk16.cyan(uploadResult.videoUrl)}`);
+        } else if (videoPath) {
+          log.warn("Video upload completed without a Video URL. Keeping local file.");
+          log.dim(`Local video: ${videoPath}`);
         }
         if (uploadResult.traceUrl) {
           log.plain(`${chalk16.bold("Trace URL:")} ${chalk16.cyan(uploadResult.traceUrl)}`);
+        } else if (tracePath) {
+          log.warn("Trace upload completed without a Trace URL. Keeping local file.");
+          log.dim(`Local trace: ${tracePath}`);
         }
       }
-      if (videoPath) {
+      if (videoPath && uploadResult.videoUrl) {
         try {
           fs7.unlinkSync(videoPath);
           fs7.rmSync(path7.dirname(videoPath), { recursive: true, force: true });
         } catch {
         }
       }
-      if (tracePath) {
+      if (tracePath && uploadResult.traceUrl) {
         try {
           fs7.unlinkSync(tracePath);
           fs7.rmSync(path7.dirname(tracePath), { recursive: true, force: true });
         } catch {
         }
       }
-    } catch {
+    } catch (error) {
       if (isPretty) {
-        log.dim("  Warning: Failed to upload recordings");
+        const message = error instanceof Error ? error.message : String(error);
+        log.warn("Failed to upload recordings");
+        log.dim(`Reason: ${message}`);
+        if (videoPath) {
+          log.dim(`Local video kept: ${videoPath}`);
+        }
+        if (tracePath) {
+          log.dim(`Local trace kept: ${tracePath}`);
+        }
       }
     }
   }
@@ -9428,14 +9821,13 @@ async function featuresListCommand() {
     const maxSlugLen = Math.max(4, ...features.map((f) => f.slug.length));
     console.log(chalk24.bold("Features:"));
     console.log(
-      `  ${chalk24.dim("NAME".padEnd(maxNameLen))}  ${chalk24.dim("SLUG".padEnd(maxSlugLen))}  ${chalk24.dim("TEST CASES")}  ${chalk24.dim("SELECTORS")}`
+      `  ${chalk24.dim("NAME".padEnd(maxNameLen))}  ${chalk24.dim("SLUG".padEnd(maxSlugLen))}  ${chalk24.dim("TEST CASES")}`
     );
     for (const feature of features) {
       const name = feature.name.padEnd(maxNameLen);
       const slug = feature.slug.padEnd(maxSlugLen);
       const tcCount = String(feature.testCaseCount ?? 0).padStart(5);
-      const selCount = String(feature.verifiedSelectorCount ?? 0).padStart(5);
-      console.log(`  ${name}  ${chalk24.dim(slug)}  ${tcCount}       ${selCount}`);
+      console.log(`  ${name}  ${chalk24.dim(slug)}  ${tcCount}`);
     }
     log.newline();
   } catch (error) {
@@ -9496,113 +9888,590 @@ async function featuresAssignCommand(featureSlug, options) {
 // src/commands/selectors.ts
 import * as fs9 from "fs";
 import chalk25 from "chalk";
-var STATUS_COLORS = {
-  verified: chalk25.green,
-  unverified: chalk25.gray,
-  stale: chalk25.yellow,
-  broken: chalk25.red
-};
-async function selectorsListCommand(options) {
+async function findPageByUrl(projectId, urlPattern) {
+  const { pages } = await listSelectorPages(projectId);
+  return pages.find(
+    (p) => p.urlPattern === urlPattern || p.urlPattern === `/${urlPattern.replace(/^\//, "")}`
+  );
+}
+async function findElementByName(projectId, elementName, pageUrlPattern) {
+  let pageId;
+  if (pageUrlPattern) {
+    const page = await findPageByUrl(projectId, pageUrlPattern);
+    if (page) pageId = page.id;
+  }
+  const { elements } = await listSelectorElements(projectId, { pageId });
+  return elements.find(
+    (e) => e.name.toLowerCase() === elementName.toLowerCase()
+  );
+}
+async function selectorsPagesCommand(options) {
   const projectId = requireAuthAndProject();
-  const spinner = createSpinner("Fetching selectors...").start();
+  if (options.page) {
+    return selectorsPageDetailCommand(projectId, options.page);
+  }
+  const spinner = createSpinner("Fetching selector library...").start();
   try {
-    const { selectors } = await listSelectors(projectId, {
-      featureSlug: options.feature,
-      status: options.status
-    });
+    const { pages } = await listSelectorPages(projectId);
     spinner.succeed(
-      `Found ${selectors.length} selector${selectors.length === 1 ? "" : "s"}`
+      `Found ${pages.length} page${pages.length === 1 ? "" : "s"}`
     );
     log.newline();
-    if (selectors.length === 0) {
-      log.plain("No selectors found.");
+    if (pages.length === 0) {
+      log.plain("No selector pages found.");
       log.newline();
-      log.dim("Run tests to auto-discover selectors.");
+      log.dim("Run tests to auto-discover selectors, or add pages manually:");
+      log.dim('  testbro selectors add-page --name "Login Page" --url-pattern "/login"');
       log.newline();
       return;
     }
-    const maxElementLen = Math.max(
-      12,
-      ...selectors.map((s) => s.elementName.length)
-    );
-    const maxTypeLen = Math.max(
-      4,
-      ...selectors.map((s) => s.selectorType.length)
+    const { elements } = await listSelectorElements(projectId);
+    const pageElementCounts = /* @__PURE__ */ new Map();
+    const pageSectionIds = /* @__PURE__ */ new Map();
+    for (const el of elements) {
+      const pageUrl = el.section?.page?.urlPattern;
+      const pageId = el.section?.page?.id;
+      if (pageId) {
+        pageElementCounts.set(pageId, (pageElementCounts.get(pageId) || 0) + 1);
+        if (!pageSectionIds.has(pageId)) pageSectionIds.set(pageId, /* @__PURE__ */ new Set());
+        pageSectionIds.get(pageId).add(el.sectionId);
+      }
+    }
+    const maxNameLen = Math.max(4, ...pages.map((p) => p.name.length));
+    const maxUrlLen = Math.max(11, ...pages.map((p) => p.urlPattern.length));
+    console.log(chalk25.bold("Selector Pages:"));
+    console.log(
+      `  ${chalk25.dim("NAME".padEnd(maxNameLen))}  ${chalk25.dim("URL PATTERN".padEnd(maxUrlLen))}  ${chalk25.dim("SECTIONS")}  ${chalk25.dim("ELEMENTS")}`
     );
-    console.log(chalk25.bold("Verified Selectors:"));
+    for (const page of pages) {
+      const name = page.name.padEnd(maxNameLen);
+      const url = page.urlPattern.padEnd(maxUrlLen);
+      const sectionCount = page._count?.sections ?? 0;
+      const elementCount = pageElementCounts.get(page.id) ?? 0;
+      console.log(
+        `  ${name}  ${chalk25.dim(url)}  ${String(sectionCount).padStart(8)}  ${String(elementCount).padStart(8)}`
+      );
+    }
+    log.newline();
+  } catch (error) {
+    spinner.fail("Failed to fetch selector library");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsPageDetailCommand(projectId, pageUrlPattern) {
+  const spinner = createSpinner(`Fetching page "${pageUrlPattern}"...`).start();
+  try {
+    const page = await findPageByUrl(projectId, pageUrlPattern);
+    if (!page) {
+      spinner.fail(`Page with URL pattern "${pageUrlPattern}" not found`);
+      return;
+    }
+    const { elements } = await listSelectorElements(projectId, { pageId: page.id });
+    spinner.succeed(`${page.name} (${page.urlPattern})`);
+    log.newline();
+    if (elements.length === 0) {
+      log.plain("No elements found for this page.");
+      log.newline();
+      return;
+    }
+    const sectionMap = /* @__PURE__ */ new Map();
+    for (const el of elements) {
+      const sectionId = el.sectionId;
+      if (!sectionMap.has(sectionId)) sectionMap.set(sectionId, []);
+      sectionMap.get(sectionId).push(el);
+    }
+    const sectionNames = /* @__PURE__ */ new Map();
+    for (const el of elements) {
+      const sectionId = el.sectionId;
+      if (!sectionNames.has(sectionId)) {
+        sectionNames.set(sectionId, sectionId);
+      }
+    }
+    for (const [sectionId, sectionElements] of sectionMap) {
+      const sectionName = sectionNames.get(sectionId) || "Unknown Section";
+      console.log(`  ${chalk25.bold.underline(sectionName)}`);
+      for (const el of sectionElements) {
+        const topStrategy = el.strategies[0];
+        const strategyStr = topStrategy ? `${topStrategy.type}="${topStrategy.value}"` : chalk25.dim("no strategies");
+        const statusIcon2 = el.status === "active" ? icons.success : el.status === "broken" ? icons.fail : chalk25.yellow("~");
+        const totalSuccess = el.strategies.reduce((sum, s) => sum + s.successCount, 0);
+        console.log(
+          `    ${statusIcon2} ${el.name.padEnd(25)} ${chalk25.dim(strategyStr.padEnd(35))} ${chalk25.dim(`${totalSuccess} successes`)}`
+        );
+      }
+      log.newline();
+    }
+  } catch (error) {
+    spinner.fail("Failed to fetch page details");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsElementsCommand(options) {
+  const projectId = requireAuthAndProject();
+  const spinner = createSpinner("Fetching elements...").start();
+  try {
+    let pageId;
+    if (options.page) {
+      const page = await findPageByUrl(projectId, options.page);
+      if (page) pageId = page.id;
+    }
+    const { elements } = await listSelectorElements(projectId, {
+      pageId,
+      status: options.status,
+      tag: options.tag
+    });
+    spinner.succeed(`Found ${elements.length} element${elements.length === 1 ? "" : "s"}`);
+    log.newline();
+    if (elements.length === 0) {
+      log.plain("No elements found matching the criteria.");
+      log.newline();
+      return;
+    }
+    const maxNameLen = Math.max(4, ...elements.map((e) => e.name.length));
+    console.log(chalk25.bold("Elements:"));
     console.log(
-      `  ${chalk25.dim("ELEMENT NAME".padEnd(maxElementLen))}  ${chalk25.dim("TYPE".padEnd(maxTypeLen))}  ${chalk25.dim("STATUS".padEnd(10))}  ${chalk25.dim("LAST VERIFIED")}`
+      `  ${chalk25.dim("NAME".padEnd(maxNameLen))}  ${chalk25.dim("PAGE".padEnd(20))}  ${chalk25.dim("STATUS".padEnd(10))}  ${chalk25.dim("STRATEGIES")}  ${chalk25.dim("ROLE")}`
     );
-    for (const selector of selectors) {
-      const element = selector.elementName.padEnd(maxElementLen);
-      const type = selector.selectorType.padEnd(maxTypeLen);
-      const colorFn = STATUS_COLORS[selector.status] || chalk25.gray;
-      const status = colorFn(selector.status.padEnd(10));
-      const lastVerified = selector.lastVerifiedAt ? new Date(selector.lastVerifiedAt).toLocaleDateString() : "Never";
-      console.log(`  ${element}  ${type}  ${status}  ${chalk25.dim(lastVerified)}`);
+    for (const el of elements) {
+      const name = el.name.padEnd(maxNameLen);
+      const pageName = (el.section?.page?.urlPattern || "").padEnd(20);
+      const status = el.status.padEnd(10);
+      const stratCount = String(el.strategies.length).padStart(10);
+      const role = el.elementRole || "-";
+      const statusColor = el.status === "active" ? chalk25.green(status) : el.status === "broken" ? chalk25.red(status) : chalk25.yellow(status);
+      console.log(
+        `  ${name}  ${chalk25.dim(pageName)}  ${statusColor}  ${stratCount}  ${chalk25.dim(role)}`
+      );
     }
     log.newline();
   } catch (error) {
-    spinner.fail("Failed to fetch selectors");
+    spinner.fail("Failed to fetch elements");
     handleCliError(error);
     process.exit(1);
   }
 }
-async function selectorsVerifyCommand(options) {
+async function selectorsFindCommand(description) {
   const projectId = requireAuthAndProject();
-  const selectorIds = options.ids ? options.ids.split(",").map((id) => id.trim()).filter(Boolean) : void 0;
-  const label = selectorIds ? `Re-verifying ${selectorIds.length} selector${selectorIds.length === 1 ? "" : "s"}...` : "Re-verifying all selectors...";
-  const spinner = createSpinner(label).start();
+  const spinner = createSpinner("Searching...").start();
   try {
-    const result = await bulkVerifySelectors(projectId, selectorIds);
-    spinner.succeed("Verification complete");
+    const result = await resolveSelector(projectId, {
+      url: "/",
+      elementDescription: description
+    });
+    if (!result.matched) {
+      spinner.warn(`No match found (best score: ${((result.matchScore || 0) * 100).toFixed(0)}%)`);
+      log.newline();
+      if (result.element) {
+        const el2 = result.element;
+        log.dim(`Closest: ${el2.name} (score: ${((result.matchScore || 0) * 100).toFixed(0)}%)`);
+      }
+      log.newline();
+      return;
+    }
+    const el = result.element;
+    spinner.succeed(`MATCH (score: ${((result.matchScore || 0) * 100).toFixed(0)}%): ${el.name}`);
     log.newline();
-    console.log(chalk25.bold("Results:"));
-    console.log(`  ${chalk25.dim("Total re-verified:")} ${result.total}`);
-    console.log(`  ${chalk25.dim("Verified:")} ${chalk25.green(String(result.verified))}`);
-    console.log(`  ${chalk25.dim("Stale:")} ${chalk25.yellow(String(result.stale))}`);
+    if (result.strategies && result.strategies.length > 0) {
+      console.log(chalk25.bold("  Strategies:"));
+      for (const s of result.strategies) {
+        const successInfo = `rank=${s.rank}, confidence=${(s.confidence * 100).toFixed(0)}%`;
+        console.log(
+          `    [${s.rank}] ${s.type}="${s.value}"  ${chalk25.dim(`(${successInfo})`)}`
+        );
+      }
+    }
     log.newline();
   } catch (error) {
-    spinner.fail("Failed to verify selectors");
+    spinner.fail("Search failed");
     handleCliError(error);
     process.exit(1);
   }
 }
-async function selectorsExportCommand(options) {
+async function selectorsAddPageCommand(options) {
   const projectId = requireAuthAndProject();
-  const format = options.format === "csv" ? "csv" : "json";
-  const spinner = createSpinner(`Exporting selectors as ${format.toUpperCase()}...`).start();
+  if (!options.name || !options.urlPattern) {
+    log.error("Both --name and --url-pattern are required.");
+    process.exit(1);
+  }
+  const spinner = createSpinner("Creating page...").start();
   try {
-    let featureId;
-    if (options.feature) {
-      const { features } = await listFeatures(projectId);
-      const feature = features.find((f) => f.slug === options.feature);
-      if (!feature) {
-        spinner.fail(`Feature "${options.feature}" not found`);
-        process.exit(1);
+    const tags = options.tags ? options.tags.split(",").map((t) => t.trim()) : void 0;
+    const { page } = await createSelectorPage(projectId, {
+      name: options.name,
+      urlPattern: options.urlPattern,
+      tags
+    });
+    spinner.succeed(`Page created: ${page.name} (${page.urlPattern})`);
+    log.newline();
+  } catch (error) {
+    spinner.fail("Failed to create page");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsAddSectionCommand(options) {
+  const projectId = requireAuthAndProject();
+  if (!options.page || !options.name) {
+    log.error("Both --page and --name are required.");
+    process.exit(1);
+  }
+  const spinner = createSpinner("Creating section...").start();
+  try {
+    const page = await findPageByUrl(projectId, options.page);
+    if (!page) {
+      spinner.fail(`Page with URL pattern "${options.page}" not found`);
+      return;
+    }
+    await createSelectorSection(projectId, page.id, {
+      name: options.name
+    });
+    spinner.succeed(`Section created: ${options.name} (in ${page.name})`);
+    log.newline();
+  } catch (error) {
+    spinner.fail("Failed to create section");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+function parseStrategy(strategyStr) {
+  const match = strategyStr.match(/^(\w+)=(.+)$/);
+  if (!match) return null;
+  const type = match[1];
+  const value = match[2];
+  let playwrightLocator;
+  switch (type) {
+    case "label":
+      playwrightLocator = `getByLabel('${value}')`;
+      break;
+    case "testid":
+      playwrightLocator = `getByTestId('${value}')`;
+      break;
+    case "role":
+      playwrightLocator = value.includes(":") ? `getByRole('${value.split(":")[0]}', { name: '${value.split(":")[1]}' })` : `getByRole('${value}')`;
+      break;
+    case "placeholder":
+      playwrightLocator = `getByPlaceholder('${value}')`;
+      break;
+    case "text":
+      playwrightLocator = `getByText('${value}')`;
+      break;
+    case "css":
+      playwrightLocator = `locator('${value}')`;
+      break;
+    case "id":
+      playwrightLocator = `locator('#${value}')`;
+      break;
+    default:
+      playwrightLocator = `locator('${value}')`;
+  }
+  return { type, value, playwrightLocator };
+}
+async function selectorsAddElementCommand(options) {
+  const projectId = requireAuthAndProject();
+  if (!options.page || !options.section || !options.name) {
+    log.error("--page, --section, and --name are required.");
+    process.exit(1);
+  }
+  const spinner = createSpinner("Creating element...").start();
+  try {
+    const page = await findPageByUrl(projectId, options.page);
+    if (!page) {
+      spinner.fail(`Page with URL pattern "${options.page}" not found`);
+      return;
+    }
+    let sectionId;
+    const { section } = await createSelectorSection(projectId, page.id, {
+      name: options.section
+    }).catch(async () => {
+      const { elements: elems } = await listSelectorElements(projectId, { pageId: page.id });
+      throw new Error(`Section "${options.section}" could not be created or found.`);
+    });
+    sectionId = section.id;
+    const strategies = [];
+    const strategyInputs = Array.isArray(options.strategy) ? options.strategy : options.strategy ? [options.strategy] : [];
+    for (const s of strategyInputs) {
+      const parsed = parseStrategy(s);
+      if (parsed) {
+        strategies.push({ ...parsed, confidence: 0.8, source: "manual" });
       }
-      featureId = feature.id;
     }
-    const content = await exportSelectors(projectId, {
-      format,
-      status: options.status,
-      featureId
+    const { element } = await createSelectorElement(projectId, {
+      sectionId,
+      name: options.name,
+      elementRole: options.role,
+      strategies: strategies.length > 0 ? strategies : void 0
     });
-    if (options.output) {
-      fs9.writeFileSync(options.output, content, "utf-8");
-      spinner.succeed(`Exported to ${options.output}`);
-    } else {
-      spinner.succeed(`Selectors exported (${format.toUpperCase()})`);
+    spinner.succeed(`Element created: ${element.name} (${element.strategies.length} strategies)`);
+    log.newline();
+  } catch (error) {
+    spinner.fail("Failed to create element");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsHistoryCommand(options) {
+  const projectId = requireAuthAndProject();
+  if (!options.element) {
+    log.error("--element is required.");
+    process.exit(1);
+  }
+  const spinner = createSpinner("Fetching history...").start();
+  try {
+    const element = await findElementByName(projectId, options.element, options.page);
+    if (!element) {
+      spinner.fail(`Element "${options.element}" not found`);
+      return;
+    }
+    const { history, total } = await getSelectorElementHistory(
+      projectId,
+      element.id,
+      20
+    );
+    spinner.succeed(`History for "${element.name}" (${total} entries)`);
+    log.newline();
+    if (history.length === 0) {
+      log.plain("No history entries found.");
+      log.newline();
+      return;
+    }
+    console.log(chalk25.bold("History:"));
+    for (let i = 0; i < history.length; i++) {
+      const entry = history[i];
+      const date = new Date(entry.createdAt).toLocaleString();
+      const actionLabel = entry.action.replace(/_/g, " ");
+      const changedBy = entry.changedBy || "unknown";
+      const reason = entry.reason ? ` - ${entry.reason}` : "";
+      console.log(
+        `  ${chalk25.dim(`#${total - i}`)} ${chalk25.bold(actionLabel)}  ${chalk25.dim(date)}  by ${chalk25.cyan(changedBy)}${chalk25.dim(reason)}`
+      );
+      console.log(`     ${chalk25.dim(`ID: ${entry.id}`)}`);
+    }
+    log.newline();
+  } catch (error) {
+    spinner.fail("Failed to fetch history");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsRollbackCommand(options) {
+  const projectId = requireAuthAndProject();
+  if (!options.element || !options.version) {
+    log.error("--element and --version are required.");
+    process.exit(1);
+  }
+  const spinner = createSpinner("Rolling back...").start();
+  try {
+    const element = await findElementByName(projectId, options.element, options.page);
+    if (!element) {
+      spinner.fail(`Element "${options.element}" not found`);
+      return;
+    }
+    const { history, total } = await getSelectorElementHistory(
+      projectId,
+      element.id,
+      200
+      // fetch enough to find the version
+    );
+    const versionNum = parseInt(options.version, 10);
+    const entryIndex = versionNum - 1;
+    if (entryIndex < 0 || entryIndex >= history.length) {
+      spinner.fail(`Version ${versionNum} not found. Available: 1-${history.length}`);
+      return;
+    }
+    const historyEntry = history[entryIndex];
+    await rollbackSelectorElement(projectId, element.id, historyEntry.id);
+    spinner.succeed(`Rolled back "${element.name}" to version ${versionNum}`);
+    log.newline();
+  } catch (error) {
+    spinner.fail("Rollback failed");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsHealthCommand() {
+  const projectId = requireAuthAndProject();
+  const spinner = createSpinner("Checking selector health...").start();
+  try {
+    const { elements } = await listSelectorElements(projectId);
+    const total = elements.length;
+    const active = elements.filter((e) => e.status === "active").length;
+    const broken = elements.filter((e) => e.status === "broken").length;
+    const deprecated = elements.filter((e) => e.status === "deprecated").length;
+    const now = Date.now();
+    const sevenDaysMs = 7 * 24 * 60 * 60 * 1e3;
+    const stale = elements.filter((e) => {
+      if (e.status === "deprecated") return false;
+      if (e.strategies.length === 0) return true;
+      return e.strategies.every((s) => {
+        if (!s.lastUsedAt) return true;
+        return now - new Date(s.lastUsedAt).getTime() > sevenDaysMs;
+      });
+    });
+    spinner.succeed("Selector Library Health");
+    log.newline();
+    console.log(`  ${chalk25.bold("Total Elements:")} ${total}`);
+    console.log(
+      `  ${chalk25.green("Active:")} ${active}  |  ${chalk25.yellow("Stale:")} ${stale.length}  |  ${chalk25.red("Broken:")} ${broken}  |  ${chalk25.dim("Deprecated:")} ${deprecated}`
+    );
+    log.newline();
+    if (broken > 0) {
+      console.log(chalk25.bold.red("  BROKEN ELEMENTS:"));
+      const brokenElements = elements.filter((e) => e.status === "broken");
+      for (const el of brokenElements) {
+        const totalSuccess = el.strategies.reduce((sum, s) => sum + s.successCount, 0);
+        const totalFail = el.strategies.reduce((sum, s) => sum + s.failCount, 0);
+        const lastFailed = el.strategies.map((s) => s.lastFailedAt).filter(Boolean).sort().reverse()[0];
+        const failedAgo = lastFailed ? formatTimeAgo(new Date(lastFailed)) : "never";
+        const pageName = el.section?.page?.name || "Unknown";
+        console.log(
+          `    ${icons.fail} ${pageName} > ${el.name}  ${chalk25.dim(`(${totalSuccess}/${totalSuccess + totalFail} success, last failed ${failedAgo})`)}`
+        );
+      }
+      log.newline();
+    }
+    if (stale.length > 0) {
+      console.log(chalk25.bold.yellow("  STALE ELEMENTS:"));
+      for (const el of stale.slice(0, 10)) {
+        const lastUsed = el.strategies.map((s) => s.lastUsedAt).filter(Boolean).sort().reverse()[0];
+        const usedAgo = lastUsed ? formatTimeAgo(new Date(lastUsed)) : "never used";
+        const pageName = el.section?.page?.name || "Unknown";
+        console.log(
+          `    ${icons.warning} ${pageName} > ${el.name}  ${chalk25.dim(`(${usedAgo})`)}`
+        );
+      }
+      if (stale.length > 10) {
+        log.dim(`    ... and ${stale.length - 10} more`);
+      }
+      log.newline();
+    }
+  } catch (error) {
+    spinner.fail("Failed to check health");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsExportCommand(options) {
+  const projectId = requireAuthAndProject();
+  if (!options.output) {
+    log.error("--output is required.");
+    process.exit(1);
+  }
+  const spinner = createSpinner("Exporting selector library...").start();
+  try {
+    const exportData = await exportSelectorLibrary(projectId);
+    if (options.page) {
+      exportData.pages = exportData.pages.filter(
+        (p) => p.urlPattern === options.page || p.urlPattern === `/${options.page.replace(/^\//, "")}`
+      );
+    }
+    const json = JSON.stringify(exportData, null, 2);
+    fs9.writeFileSync(options.output, json, "utf-8");
+    const pageCount = exportData.pages.length;
+    const elementCount = exportData.pages.reduce(
+      (sum, p) => sum + p.sections.reduce(
+        (sSum, s) => sSum + s.elements.length,
+        0
+      ),
+      0
+    );
+    spinner.succeed(
+      `Exported ${pageCount} page${pageCount === 1 ? "" : "s"}, ${elementCount} element${elementCount === 1 ? "" : "s"} to ${options.output}`
+    );
+    log.newline();
+  } catch (error) {
+    spinner.fail("Export failed");
+    handleCliError(error);
+    process.exit(1);
+  }
+}
+async function selectorsImportCommand(options) {
+  const projectId = requireAuthAndProject();
+  if (!options.input) {
+    log.error("--input is required.");
+    process.exit(1);
+  }
+  if (!fs9.existsSync(options.input)) {
+    log.error(`File not found: ${options.input}`);
+    process.exit(1);
+  }
+  const spinner = createSpinner("Reading import file...").start();
+  try {
+    const raw = fs9.readFileSync(options.input, "utf-8");
+    const data = JSON.parse(raw);
+    if (!data.version || !Array.isArray(data.pages)) {
+      spinner.fail("Invalid import file format");
+      return;
+    }
+    const pageCount = data.pages.length;
+    const elementCount = data.pages.reduce(
+      (sum, p) => sum + p.sections.reduce(
+        (sSum, s) => sSum + s.elements.length,
+        0
+      ),
+      0
+    );
+    const strategyCount = data.pages.reduce(
+      (sum, p) => sum + p.sections.reduce(
+        (sSum, s) => sSum + s.elements.reduce(
+          (eSum, e) => eSum + e.strategies.length,
+          0
+        ),
+        0
+      ),
+      0
+    );
+    if (options.dryRun) {
+      spinner.succeed("Dry run - no changes will be made");
+      log.newline();
+      console.log(chalk25.bold("Import preview:"));
+      console.log(`  Pages:      ${pageCount}`);
+      console.log(`  Elements:   ${elementCount}`);
+      console.log(`  Strategies: ${strategyCount}`);
       log.newline();
-      console.log(content);
+      for (const page of data.pages) {
+        console.log(`  ${chalk25.bold(page.name)} (${page.urlPattern})`);
+        for (const section of page.sections) {
+          console.log(`    ${section.name}`);
+          for (const element of section.elements) {
+            console.log(`      ${element.name} (${element.strategies.length} strategies)`);
+          }
+        }
+      }
+      log.newline();
+      return;
     }
+    spinner.text("Importing...");
+    const result = await importSelectorLibrary(projectId, data);
+    spinner.succeed("Import complete");
+    log.newline();
+    console.log(chalk25.bold("Results:"));
+    console.log(`  Pages created:      ${result.imported.pages}`);
+    console.log(`  Sections created:   ${result.imported.sections}`);
+    console.log(`  Elements created:   ${result.imported.elements}`);
+    console.log(`  Strategies created: ${result.imported.strategies}`);
+    console.log(`  Skipped (duplicates): ${result.skipped}`);
     log.newline();
   } catch (error) {
-    spinner.fail("Failed to export selectors");
+    spinner.fail("Import failed");
     handleCliError(error);
     process.exit(1);
   }
 }
+async function selectorsListCommand(options) {
+  return selectorsPagesCommand({});
+}
+function formatTimeAgo(date) {
+  const now = Date.now();
+  const diff = now - date.getTime();
+  const minutes = Math.floor(diff / 6e4);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
 
 // src/commands/demo.ts
 import chalk26 from "chalk";
@@ -9879,10 +10748,245 @@ function formatStatus2(status) {
   }
 }
 
+// src/commands/upgrade.ts
+import { execSync } from "child_process";
+import chalk28 from "chalk";
+
+// package.json
+var package_default = {
+  name: "@test-bro/cli",
+  publishConfig: {
+    access: "public"
+  },
+  version: "0.1.3",
+  description: "TestBro CLI - AI-powered browser testing from your terminal",
+  type: "module",
+  bin: {
+    testbro: "dist/index.js"
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=18"
+  },
+  keywords: [
+    "testing",
+    "browser-testing",
+    "playwright",
+    "ai-testing",
+    "test-automation",
+    "e2e",
+    "qa"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/chernobelenkiy/test-bro.git",
+    directory: "apps/cli"
+  },
+  license: "MIT",
+  scripts: {
+    build: "tsup",
+    dev: "tsup --watch",
+    typecheck: "tsc --noEmit",
+    lint: "eslint src/",
+    test: "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  dependencies: {
+    commander: "^12.1.0",
+    chalk: "^5.3.0",
+    ora: "^8.1.1",
+    dotenv: "^16.4.7",
+    playwright: "^1.40.0",
+    zod: "^3.24.1"
+  },
+  devDependencies: {
+    "@testbro/core": "workspace:*",
+    "@testbro/runner": "workspace:*",
+    "@testbro/ai-agent": "workspace:*",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.0",
+    tsup: "^8.3.5",
+    typescript: "^5.7.2",
+    vitest: "^2.1.0"
+  }
+};
+
+// src/version.ts
+var CLI_VERSION = package_default.version;
+
+// src/version-check.ts
+init_config();
+import * as fs10 from "fs";
+import * as path9 from "path";
+var CACHE_FILE_NAME = "version-check.json";
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/@test-bro/cli/latest";
+var FETCH_TIMEOUT_MS = 5e3;
+function getCachePath() {
+  return path9.join(getConfigDir(), CACHE_FILE_NAME);
+}
+function readCache() {
+  try {
+    const cachePath = getCachePath();
+    if (!fs10.existsSync(cachePath)) {
+      return null;
+    }
+    const raw = fs10.readFileSync(cachePath, "utf-8");
+    const data = JSON.parse(raw);
+    const age = Date.now() - new Date(data.checkedAt).getTime();
+    if (age > CACHE_TTL_MS) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+function writeCache(latestVersion) {
+  try {
+    const configDir = getConfigDir();
+    if (!fs10.existsSync(configDir)) {
+      fs10.mkdirSync(configDir, { recursive: true, mode: 448 });
+    }
+    const data = {
+      latestVersion,
+      checkedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    fs10.writeFileSync(getCachePath(), JSON.stringify(data, null, 2), {
+      encoding: "utf-8",
+      mode: 384
+    });
+  } catch {
+  }
+}
+async function fetchLatestVersion() {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    const response = await fetch(NPM_REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" }
+    });
+    clearTimeout(timeout);
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    return data.version ?? null;
+  } catch {
+    return null;
+  }
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const na = pa[i] ?? 0;
+    const nb = pb[i] ?? 0;
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}
+async function checkForUpdate(currentVersion) {
+  const cached = readCache();
+  if (cached) {
+    if (compareSemver(currentVersion, cached.latestVersion) < 0) {
+      return cached.latestVersion;
+    }
+    return null;
+  }
+  const latest = await fetchLatestVersion();
+  if (!latest) {
+    return null;
+  }
+  writeCache(latest);
+  if (compareSemver(currentVersion, latest) < 0) {
+    return latest;
+  }
+  return null;
+}
+function startVersionCheck(currentVersion) {
+  const checkPromise = checkForUpdate(currentVersion).catch(() => null);
+  return async () => {
+    try {
+      const latestVersion = await checkPromise;
+      if (latestVersion) {
+        const chalk30 = (await import("chalk")).default;
+        console.log(
+          chalk30.yellow(
+            `
+Update available: ${currentVersion} \u2192 ${latestVersion}. Run \`testbro upgrade\` to update.`
+          )
+        );
+      }
+    } catch {
+    }
+  };
+}
+
+// src/commands/upgrade.ts
+async function upgradeCommand() {
+  console.log(chalk28.bold("TestBro CLI Upgrade"));
+  console.log("");
+  console.log(`  Current version: ${chalk28.dim(CLI_VERSION)}`);
+  console.log(chalk28.dim("  Checking npm registry..."));
+  const latestVersion = await fetchLatestVersion();
+  if (!latestVersion) {
+    console.log(
+      chalk28.red(
+        "  Failed to check npm registry. Please check your internet connection."
+      )
+    );
+    process.exit(1);
+  }
+  console.log(`  Latest version:  ${chalk28.green(latestVersion)}`);
+  console.log("");
+  if (compareSemver(CLI_VERSION, latestVersion) >= 0) {
+    console.log(chalk28.green("  You are already on the latest version."));
+    return;
+  }
+  console.log(
+    chalk28.yellow(
+      `  Upgrading ${CLI_VERSION} \u2192 ${latestVersion}...`
+    )
+  );
+  console.log("");
+  try {
+    execSync("npm install -g @test-bro/cli@latest", {
+      stdio: "inherit"
+    });
+    writeCache(latestVersion);
+    console.log("");
+    console.log(
+      chalk28.green(
+        `  Successfully upgraded to @test-bro/cli@${latestVersion}`
+      )
+    );
+  } catch {
+    console.log("");
+    console.log(
+      chalk28.red(
+        "  Upgrade failed. You may need to run with sudo or fix npm permissions."
+      )
+    );
+    console.log(
+      chalk28.dim(
+        "  Try: sudo npm install -g @test-bro/cli@latest"
+      )
+    );
+    process.exit(1);
+  }
+}
+
 // src/index.ts
 var program = new Command();
-program.name("testbro").description("AI-powered browser testing from your terminal").version("0.1.0");
-program.command("login").description("Authenticate with TestBro using an API token").argument("[email]", "Your email address (deprecated - use --token instead)").option("-t, --token <token>", "API token for authentication").option("-u, --url <url>", "API URL (default: http://localhost:3024)").action(async (email, options) => {
+program.name("testbro").description("AI-powered browser testing from your terminal").version(CLI_VERSION);
+program.command("login").description("Authenticate with TestBro using an API token").argument("[email]", "Your email address (deprecated - use --token instead)").option("-t, --token <token>", "API token for authentication").option("-u, --url <url>", "API URL (default: https://testbro.dev)").action(async (email, options) => {
   try {
     await loginCommand(email, { token: options.token, url: options.url });
   } catch (error) {
@@ -9985,7 +11089,7 @@ program.command("generate").description("Generate test cases from a file or desc
 program.command("run").description("Run tests against a URL").option("-u, --url <url>", "Target URL to test (or use baseUrl from test-bro.config.json)").option("--file <path>", "Path to file (AC/PRD) to generate and run tests from").option("-d, --description <text>", "Feature description to test").option("-p, --project <id>", "Project ID to use test cases from (overrides active)").option("-t, --test-case <id>", "Run specific test case only").option("-m, --mode <mode>", "Execution mode: selector (default), ai, or hybrid", "selector").option("--headed", "Run browser in headed mode (visible)", false).option("--remote", "Run tests on remote staging environment", false).option("-f, --format <format>", "Output format: pretty or json", "pretty").option("-v, --verbose", "Show verbose output", false).option("--timeout <ms>", "Timeout per step in milliseconds", "30000").option("--learn-selectors", "Learn selectors from AI actions", false).option("--yes", "Auto-confirm selector learning", false).option("--no-dedup", "Skip deduplication check when using --file").option("--auto-merge", "Auto-apply smart merge without prompting when using --file").option("--record-video", "Record video of the test execution", false).option("--record-trace", "Capture Playwright trace for debugging", false).option("-e, --env <name>", "Use a named environment (fetches baseUrl from API)").option("--credential <name>", "Use a named credential from the vault").option("--no-sequential", "Run test cases independently (re-navigate for each)").action(async (options) => {
   if (options.url && !validateUrl(options.url)) {
     displayError("Invalid URL format", `Provided URL: ${options.url}`);
-    console.log(chalk28.dim('  Example: testbro run --url https://example.com --description "..."'));
+    console.log(chalk29.dim('  Example: testbro run --url https://example.com --description "..."'));
     process.exit(1);
   }
   if (options.description) {
@@ -10118,8 +11222,8 @@ featuresCmd.command("assign").description("Assign a test case to a feature by sl
     process.exit(1);
   }
 });
-var selectorsCmd = program.command("selectors").description("List and manage verified selectors");
-selectorsCmd.option("-f, --feature <slug>", "Filter by feature slug").option("-s, --status <status>", "Filter by status (verified, unverified, stale, broken)").action(async (options) => {
+var selectorsCmd = program.command("selectors").description("Browse and manage the selector library");
+selectorsCmd.option("-v, --verbose", "Show sections and elements").action(async (options) => {
   try {
     await selectorsListCommand(options);
   } catch (error) {
@@ -10130,9 +11234,9 @@ selectorsCmd.option("-f, --feature <slug>", "Filter by feature slug").option("-s
     process.exit(1);
   }
 });
-selectorsCmd.command("verify").description("Bulk re-verify selectors (refreshes lastVerifiedAt)").option("--ids <ids>", "Comma-separated selector IDs to verify (default: all)").action(async (options) => {
+selectorsCmd.command("pages").description("List selector pages or show details for a specific page").option("-p, --page <urlPattern>", "Show detail tree for a specific page URL pattern").action(async (options) => {
   try {
-    await selectorsVerifyCommand(options);
+    await selectorsPagesCommand(options);
   } catch (error) {
     if (error instanceof Error) {
       displayError(error.message);
@@ -10141,7 +11245,95 @@ selectorsCmd.command("verify").description("Bulk re-verify selectors (refreshes
     process.exit(1);
   }
 });
-selectorsCmd.command("export").description("Export selectors as JSON or CSV").option("--format <format>", "Output format: json or csv", "json").option("--output <file>", "Write output to file instead of stdout").option("-s, --status <status>", "Filter by status (verified, stale, all)").option("-f, --feature <slug>", "Filter by feature slug").action(async (options) => {
+selectorsCmd.command("elements").description("List elements with optional filters").option("-p, --page <urlPattern>", "Filter by page URL pattern").option("-s, --status <status>", "Filter by status (active, broken, deprecated)").option("-t, --tag <tag>", "Filter by tag").action(async (options) => {
+  try {
+    await selectorsElementsCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("find <description>").description("Fuzzy search for an element by description").action(async (description) => {
+  try {
+    await selectorsFindCommand(description);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("add-page").description("Add a new page to the selector library").requiredOption("-n, --name <name>", "Page name").requiredOption("--url-pattern <pattern>", "URL pattern for the page").option("--tags <tags>", "Comma-separated tags").action(async (options) => {
+  try {
+    await selectorsAddPageCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("add-section").description("Add a section to an existing page").requiredOption("-p, --page <urlPattern>", "Parent page URL pattern").requiredOption("-n, --name <name>", "Section name").action(async (options) => {
+  try {
+    await selectorsAddSectionCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("add-element").description("Add an element to a page section").requiredOption("-p, --page <urlPattern>", "Page URL pattern").requiredOption("--section <name>", "Section name").requiredOption("-n, --name <name>", "Element name").option("-r, --role <role>", "Element role (e.g. textbox, button)").option("-s, --strategy <strategies...>", "Strategies (e.g. label=Email testid=email-input)").action(async (options) => {
+  try {
+    await selectorsAddElementCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("history").description("Show change history for an element").requiredOption("-e, --element <name>", "Element name").option("-p, --page <urlPattern>", "Page URL pattern to narrow search").action(async (options) => {
+  try {
+    await selectorsHistoryCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("rollback").description("Rollback an element to a previous version").requiredOption("-e, --element <name>", "Element name").requiredOption("--version <n>", "Version number to rollback to (1 = most recent)").option("-p, --page <urlPattern>", "Page URL pattern to narrow search").action(async (options) => {
+  try {
+    await selectorsRollbackCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("health").description("Show health summary of the selector library").action(async () => {
+  try {
+    await selectorsHealthCommand();
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
+selectorsCmd.command("export").description("Export the selector library to a JSON file").requiredOption("-o, --output <path>", "Output file path").option("-p, --page <urlPattern>", "Export only a specific page").action(async (options) => {
   try {
     await selectorsExportCommand(options);
   } catch (error) {
@@ -10152,6 +11344,17 @@ selectorsCmd.command("export").description("Export selectors as JSON or CSV").op
     process.exit(1);
   }
 });
+selectorsCmd.command("import").description("Import a selector library from a JSON file").requiredOption("-i, --input <path>", "Input file path").option("--dry-run", "Preview the import without making changes").action(async (options) => {
+  try {
+    await selectorsImportCommand(options);
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
 var demoCmd = program.command("demo").description("Record and manage demo runs");
 demoCmd.action(async () => {
   try {
@@ -10231,6 +11434,17 @@ releasesCmd.command("unpublish").description("Unpublish a release note (revert t
     process.exit(1);
   }
 });
+program.command("upgrade").description("Upgrade TestBro CLI to the latest version").action(async () => {
+  try {
+    await upgradeCommand();
+  } catch (error) {
+    if (error instanceof Error) {
+      displayError(error.message);
+    }
+    printErrorHints(error);
+    process.exit(1);
+  }
+});
 var configCmd = program.command("config").description("Show or update configuration");
 function displayConfig() {
   const { getConfigSummary: getConfigSummary2 } = (init_config(), __toCommonJS(config_exports));
@@ -10241,72 +11455,90 @@ function displayConfig() {
   const userConfig = getConfigSummary2();
   const projectConfigInfo = getProjectConfigSummary2();
   console.log("");
-  console.log(chalk28.bold("TestBro Configuration"));
+  console.log(chalk29.bold("TestBro Configuration"));
   console.log("");
-  console.log(chalk28.underline("User Config") + chalk28.dim(` (~/.testbro/config.json)`));
-  console.log(`  ${chalk28.dim("Path:")} ${userConfig.configPath}`);
-  console.log(`  ${chalk28.dim("API URL:")} ${userConfig.apiUrl}`);
+  console.log(chalk29.underline("User Config") + chalk29.dim(` (~/.testbro/config.json)`));
+  console.log(`  ${chalk29.dim("Path:")} ${userConfig.configPath}`);
+  console.log(`  ${chalk29.dim("API URL:")} ${userConfig.apiUrl}`);
   console.log(
-    `  ${chalk28.dim("Authenticated:")} ${userConfig.authenticated ? chalk28.green("Yes") : chalk28.yellow("No")}`
+    `  ${chalk29.dim("Authenticated:")} ${userConfig.authenticated ? chalk29.green("Yes") : chalk29.yellow("No")}`
   );
   if (userConfig.activeProjectId) {
-    console.log(`  ${chalk28.dim("Active Project:")} ${userConfig.activeProjectId}`);
+    console.log(`  ${chalk29.dim("Active Project:")} ${userConfig.activeProjectId}`);
   }
   console.log("");
-  console.log(chalk28.underline("Project Config") + chalk28.dim(` (test-bro.config.json)`));
+  console.log(chalk29.underline("Project Config") + chalk29.dim(` (test-bro.config.json)`));
   if (projectConfigInfo.projectConfigPath) {
-    console.log(`  ${chalk28.dim("Path:")} ${projectConfigInfo.projectConfigPath}`);
+    console.log(`  ${chalk29.dim("Path:")} ${projectConfigInfo.projectConfigPath}`);
     if (projectConfigInfo.error) {
-      console.log(`  ${chalk28.red("Error:")} ${projectConfigInfo.error}`);
+      console.log(`  ${chalk29.red("Error:")} ${projectConfigInfo.error}`);
     } else if (projectConfigInfo.projectConfig) {
       const pc = projectConfigInfo.projectConfig;
       if (pc.baseUrl) {
-        console.log(`  ${chalk28.dim("Base URL:")} ${pc.baseUrl}`);
+        console.log(`  ${chalk29.dim("Base URL:")} ${pc.baseUrl}`);
       }
       if (pc.environment) {
-        console.log(`  ${chalk28.dim("Environment:")} ${pc.environment}`);
+        console.log(`  ${chalk29.dim("Environment:")} ${pc.environment}`);
       }
       if (pc.mode) {
-        console.log(`  ${chalk28.dim("Mode:")} ${pc.mode}`);
+        console.log(`  ${chalk29.dim("Mode:")} ${pc.mode}`);
       }
       if (pc.timeout) {
-        console.log(`  ${chalk28.dim("Timeout:")} ${pc.timeout}ms`);
+        console.log(`  ${chalk29.dim("Timeout:")} ${pc.timeout}ms`);
       }
       if (pc.headed !== void 0) {
-        console.log(`  ${chalk28.dim("Headed:")} ${pc.headed}`);
+        console.log(`  ${chalk29.dim("Headed:")} ${pc.headed}`);
       }
       if (pc.projectId) {
-        console.log(`  ${chalk28.dim("Project ID:")} ${pc.projectId}`);
+        console.log(`  ${chalk29.dim("Project ID:")} ${pc.projectId}`);
       }
       const credNames = getCredentialNames2(pc);
       if (credNames.length > 0) {
-        console.log(`  ${chalk28.dim("Credentials:")} ${credNames.join(", ")}`);
+        console.log(`  ${chalk29.dim("Credentials:")} ${credNames.join(", ")}`);
       }
       if (pc.deduplication) {
         const dedupEnabled = pc.deduplication.enabled !== false;
         const autoMerge = pc.deduplication.autoMerge === true;
-        console.log(`  ${chalk28.dim("Deduplication:")} ${dedupEnabled ? chalk28.green("enabled") : chalk28.yellow("disabled")}${autoMerge ? chalk28.dim(" (auto-merge)") : ""}`);
+        console.log(`  ${chalk29.dim("Deduplication:")} ${dedupEnabled ? chalk29.green("enabled") : chalk29.yellow("disabled")}${autoMerge ? chalk29.dim(" (auto-merge)") : ""}`);
+      }
+      if (pc.environments && Object.keys(pc.environments).length > 0) {
+        const envNames = Object.keys(pc.environments);
+        const activeEnv = pc.environment || "local";
+        console.log(`  ${chalk29.dim("Environments:")} ${envNames.map((name) => name === activeEnv ? chalk29.green(name + " *") : name).join(", ")}`);
+        const activeEntry = pc.environments[activeEnv];
+        if (activeEntry) {
+          console.log(`  ${chalk29.dim("Active env URL:")} ${activeEntry.baseUrl}`);
+          if (activeEntry.apiUrl) {
+            console.log(`  ${chalk29.dim("Active env API:")} ${activeEntry.apiUrl}`);
+          }
+          if (activeEntry.credentials) {
+            console.log(`  ${chalk29.dim("Active env credentials:")} ${Object.keys(activeEntry.credentials).join(", ")}`);
+          }
+          if (activeEntry.auth) {
+            console.log(`  ${chalk29.dim("Active env auth:")} ${chalk29.green("configured")} ${chalk29.dim(`(${activeEntry.auth.loginUrl})`)}`);
+          }
+        }
       }
     }
   } else {
-    console.log(`  ${chalk28.dim("Not found")}`);
+    console.log(`  ${chalk29.dim("Not found")}`);
   }
   console.log("");
-  console.log(chalk28.underline("Authentication"));
+  console.log(chalk29.underline("Authentication"));
   if (projectConfigInfo.token) {
     const maskedToken = projectConfigInfo.token.length > 8 ? `${projectConfigInfo.token.slice(0, 4)}...${projectConfigInfo.token.slice(-4)}` : "****";
-    const sourceLabel = projectConfigInfo.tokenSource === "env" ? chalk28.cyan("(from TEST_BRO_TOKEN env)") : chalk28.dim("(from user config)");
-    console.log(`  ${chalk28.dim("Token:")} ${maskedToken} ${sourceLabel}`);
+    const sourceLabel = projectConfigInfo.tokenSource === "env" ? chalk29.cyan("(from TEST_BRO_TOKEN env)") : chalk29.dim("(from user config)");
+    console.log(`  ${chalk29.dim("Token:")} ${maskedToken} ${sourceLabel}`);
   } else {
-    console.log(`  ${chalk28.yellow("No token configured")}`);
-    console.log(chalk28.dim("  Set via: testbro init (or testbro login --token <token>)"));
-    console.log(chalk28.dim("  Or set TEST_BRO_TOKEN environment variable"));
+    console.log(`  ${chalk29.yellow("No token configured")}`);
+    console.log(chalk29.dim("  Set via: testbro init (or testbro login --token <token>)"));
+    console.log(chalk29.dim("  Or set TEST_BRO_TOKEN environment variable"));
   }
   if (projectConfigInfo.openRouterApiKey) {
     const maskedKey = projectConfigInfo.openRouterApiKey.length > 8 ? `${projectConfigInfo.openRouterApiKey.slice(0, 6)}...${projectConfigInfo.openRouterApiKey.slice(-4)}` : "****";
-    console.log(`  ${chalk28.dim("OpenRouter API Key:")} ${maskedKey} ${chalk28.cyan("(from OPENROUTER_API_KEY env)")}`);
+    console.log(`  ${chalk29.dim("OpenRouter API Key:")} ${maskedKey} ${chalk29.cyan("(from OPENROUTER_API_KEY env)")}`);
   } else {
-    console.log(`  ${chalk28.dim("OpenRouter API Key:")} ${chalk28.yellow("Not set")} ${chalk28.dim("(required for AI mode)")}`);
+    console.log(`  ${chalk29.dim("OpenRouter API Key:")} ${chalk29.yellow("Not set")} ${chalk29.dim("(required for AI mode)")}`);
   }
   console.log("");
 }
@@ -10320,11 +11552,11 @@ configCmd.command("init").description("Create a test-bro.config.json template in
   try {
     const { createConfigFile: createConfigFile2 } = (init_project_config(), __toCommonJS(project_config_exports));
     const configPath = createConfigFile2();
-    console.log(chalk28.green(`Created ${configPath}`));
+    console.log(chalk29.green(`Created ${configPath}`));
     console.log("");
-    console.log(chalk28.dim("Edit this file to configure your project settings."));
-    console.log(chalk28.dim("Note: Never store tokens in this file. Use .env or testbro login."));
-    console.log(chalk28.dim("Tip: Use 'testbro init' for interactive setup with authentication."));
+    console.log(chalk29.dim("Edit this file to configure your project settings."));
+    console.log(chalk29.dim("Note: Never store tokens in this file. Use .env or testbro login."));
+    console.log(chalk29.dim("Tip: Use 'testbro init' for interactive setup with authentication."));
   } catch (error) {
     if (error instanceof Error) {
       displayError(error.message);
@@ -10338,7 +11570,11 @@ configCmd.option("--api-url <url>", "Set the API URL in user config").hook("preA
   if (options.apiUrl) {
     const { setApiUrl: setApiUrl2 } = (init_config(), __toCommonJS(config_exports));
     setApiUrl2(options.apiUrl);
-    console.log(chalk28.green(`API URL updated to: ${options.apiUrl}`));
+    console.log(chalk29.green(`API URL updated to: ${options.apiUrl}`));
   }
 });
+var showVersionNotice = startVersionCheck(CLI_VERSION);
+program.hook("postAction", async () => {
+  await showVersionNotice();
+});
 program.parse();