@xbrowser/cli 0.16.0 → 1.0.2

package/dist/cli.js

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 import {
   SessionRecorder
-} from "./chunk-KDYXFLAC.js";
+} from "./chunk-ACFE6PKF.js";
+import {
+  addKnownIssue,
+  getKnowledgePath,
+  init_site_knowledge,
+  listSiteKnowledge,
+  readSiteKnowledge,
+  readSiteKnowledgeMarkdown
+} from "./chunk-OZKD3W4X.js";
 import {
   closeAllSessions,
   closeEphemeralContext,
@@ -17,7 +25,8 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-2ONMTDLK.js";
+} from "./chunk-CAFNSGYM.js";
+import "./chunk-BBMRDUYQ.js";
 import {
   forwardCommandLog,
   forwardNetworkAnalyze,
@@ -38,7 +47,6 @@ import {
   forwardRecordSummary,
   forwardReplay,
   forwardSessionClose,
-  forwardSessionCreate,
   forwardSessionList,
   forwardViewerCheckSelector,
   getDaemonConfig,
@@ -46,10 +54,11 @@ import {
   killAllDaemonProcesses,
   startDaemonProcess,
   stopDaemonProcess
-} from "./chunk-ATFTAKMN.js";
+} from "./chunk-Q4IGYTKR.js";
+import "./chunk-KFQGP6VL.js";
 
 // src/router.ts
-import { parseArgs, outputFormatter as outputFormatter2, isCommandResult as isCommandResult2, helpGenerator as helpGenerator2 } from "@dyyz1993/xcli-core";
+import { parseArgs, outputFormatter as outputFormatter2, isCommandResult as isCommandResult2, helpGenerator as helpGenerator2, TipCollector as TipCollector2, normalizeTips as normalizeTips7, tip as makeTip } from "@dyyz1993/xcli-core";
 
 // src/utils/positional-params.ts
 import { unquote } from "@dyyz1993/xcli-core";
@@ -172,10 +181,13 @@ import {
   ok as ok25,
   fail as fail7,
   isCommandResult,
+  CompositeStorage,
+  TipCollector,
+  normalizeTips as normalizeTips6,
   configureArchiveStore,
   appendCommandToArchive,
   checkGuard,
-  PluginStorage
+  unquote as unquote2
 } from "@dyyz1993/xcli-core";
 
 // src/commands/navigation.ts
@@ -322,10 +334,18 @@ var urlCommand = registerCommand({
     return ok({ url: ctx.page.url() });
   }
 });
+registerCommand({
+  name: "open",
+  description: "Navigate to URL (alias for goto)",
+  scope: "page",
+  parameters: gotoCommand.parameters,
+  result: gotoCommand.result,
+  handler: gotoCommand.handler
+});
 
 // src/commands/interaction.ts
 import { z as z2 } from "zod";
-import { ok as ok2 } from "@dyyz1993/xcli-core";
+import { ok as ok2, normalizeTips } from "@dyyz1993/xcli-core";
 
 // src/lib/captcha.ts
 var CAPTCHA_SELECTORS = {
@@ -393,15 +413,15 @@ var clickCommand = registerCommand({
     let detectedNewPage;
     let cleanup;
     if (ctx.browserContext?.on) {
-      const pagePromise = new Promise((resolve16) => {
+      const pagePromise = new Promise((resolve10) => {
         const timer = setTimeout(() => {
           ctx.browserContext.off("page", handler);
-          resolve16(void 0);
+          resolve10(void 0);
         }, 3e3);
         const handler = (page2) => {
           clearTimeout(timer);
           ctx.browserContext.off("page", handler);
-          resolve16(page2);
+          resolve10(page2);
         };
         ctx.browserContext.on("page", handler);
       });
@@ -436,7 +456,7 @@ var clickCommand = registerCommand({
         selector: p.selector,
         newTab: { url: newUrl, title: newTitle }
       });
-      result.tips = [`\u65B0 Tab \u5DF2\u6253\u5F00: ${newTitle ? newTitle + " \u2014 " : ""}${newUrl}`];
+      result.tips = normalizeTips([`\u65B0 Tab \u5DF2\u6253\u5F00: ${newTitle ? newTitle + " \u2014 " : ""}${newUrl}`]);
       return result;
     }
     const captchaInfo = await detectCaptcha(page);
@@ -450,7 +470,7 @@ var clickCommand = registerCommand({
         tips.push(solved ? "\u2705 CAPTCHA solved!" : "\u274C CAPTCHA timeout");
       }
       const result = ok2({ selector: p.selector, captcha: captchaInfo });
-      result.tips = tips;
+      result.tips = normalizeTips(tips);
       return result;
     }
     return ok2({ selector: p.selector });
@@ -535,7 +555,7 @@ var pressCommand = registerCommand({
     key: z2.string()
   }),
   handler: async (p, ctx) => {
-    await ctx.page.press(p.selector || "body", p.key, { delay: p.delay, timeout: 1e4 });
+    await ctx.page.press(p.selector || "body", p.key, { timeout: 1e4 });
     return ok2({ key: p.key });
   }
 });
@@ -554,7 +574,7 @@ var selectCommand = registerCommand({
   }),
   handler: async (p, ctx) => {
     const values = typeof p.value === "string" ? [p.value] : p.value;
-    await ctx.page.selectOption(p.selector, values, { force: true, timeout: 1e4 });
+    await ctx.page.selectOption(p.selector, values);
     return ok2({ selector: p.selector, value: p.value });
   }
 });
@@ -570,7 +590,7 @@ var checkCommand = registerCommand({
     selector: z2.string()
   }),
   handler: async (p, ctx) => {
-    await ctx.page.check(p.selector, { force: true, timeout: 1e4 });
+    await ctx.page.check(p.selector, { timeout: 1e4 });
     return ok2({ selector: p.selector });
   }
 });
@@ -587,7 +607,7 @@ var hoverCommand = registerCommand({
     selector: z2.string()
   }),
   handler: async (p, ctx) => {
-    await ctx.page.hover(p.selector, { modifiers: p.modifiers, force: true, timeout: 1e4 });
+    await ctx.page.hover(p.selector, { timeout: 1e4 });
     return ok2({ selector: p.selector });
   }
 });
@@ -785,7 +805,7 @@ var mouseCommand = registerCommand({
 
 // src/commands/evaluate.ts
 import { z as z7 } from "zod";
-import { ok as ok7 } from "@dyyz1993/xcli-core";
+import { ok as ok7, normalizeTips as normalizeTips2 } from "@dyyz1993/xcli-core";
 var evaluateCommand = registerCommand({
   name: "eval",
   description: "Evaluate JavaScript expression in the browser",
@@ -806,10 +826,10 @@ var evaluateCommand = registerCommand({
     const result = await ctx.page.evaluate(p.expression);
     const response = ok7({ result });
     if (decision && decision.severity === "danger") {
-      response.tips = [
+      response.tips = normalizeTips2([
         `\u26A0\uFE0F CDP Firewall: ${decision.reason}`,
         `\u{1F4A1} Fix: ${decision.suggestion}`
-      ];
+      ]);
     }
     return response;
   }
@@ -932,7 +952,19 @@ var clearLocalStorageCommand = registerCommand({
 // src/commands/screenshot.ts
 import { z as z9 } from "zod";
 import { ok as ok9 } from "@dyyz1993/xcli-core";
-import { writeFileSync } from "fs";
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var SCREENSHOTS_DIR = join(homedir(), ".xbrowser", "screenshots");
+function ensureScreenshotsDir() {
+  mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+}
+function generateScreenshotPath(format) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).slice(2, 8);
+  const ext = format === "jpeg" ? "jpg" : "png";
+  return join(SCREENSHOTS_DIR, `screenshot-${timestamp}-${random}.${ext}`);
+}
 var screenshotCommand = registerCommand({
   name: "screenshot",
   description: "Take a screenshot of the page or element",
@@ -942,7 +974,8 @@ var screenshotCommand = registerCommand({
     selector: z9.string().optional(),
     type: z9.enum(["png", "jpeg"]).optional(),
     fullPage: z9.boolean().optional(),
-    output: z9.string().optional()
+    output: z9.string().optional(),
+    base64: z9.boolean().optional().describe("Return base64 data instead of file path")
   }),
   result: z9.union([
     z9.object({
@@ -957,8 +990,9 @@ var screenshotCommand = registerCommand({
     })
   ]),
   handler: async (p, ctx) => {
+    const format = p.type || "png";
     const options = {
-      type: p.type || "png",
+      type: format,
       fullPage: p.fullPage || false
     };
     let buffer;
@@ -971,13 +1005,23 @@ var screenshotCommand = registerCommand({
       writeFileSync(p.output, buffer);
       return ok9({
         output: p.output,
-        format: p.type || "png",
+        format,
+        size: buffer.length
+      });
+    }
+    if (p.base64) {
+      return ok9({
+        data: buffer.toString("base64"),
+        format,
         size: buffer.length
       });
     }
+    ensureScreenshotsDir();
+    const screenshotPath = generateScreenshotPath(format);
+    writeFileSync(screenshotPath, buffer);
     return ok9({
-      data: buffer.toString("base64"),
-      format: p.type || "png",
+      output: screenshotPath,
+      format,
       size: buffer.length
     });
   }
@@ -1159,7 +1203,7 @@ var consoleCheckCommand = registerCommand({
       await page.goto(p.url, { waitUntil: "domcontentloaded" });
     }
     const messages = await page.evaluate((args) => {
-      return new Promise((resolve16) => {
+      return new Promise((resolve10) => {
         const collected = [];
         const originalConsole = {
           log: console.log,
@@ -1226,7 +1270,7 @@ ${a.stack || ""}`;
           console.warn = originalConsole.warn;
           console.error = originalConsole.error;
           console.info = originalConsole.info;
-          resolve16(collected);
+          resolve10(collected);
         }, args.duration);
       });
     }, { duration: p.duration });
@@ -1575,6 +1619,19 @@ var healthCheckCommand = registerCommand({
 // src/commands/actions.ts
 import { z as z14 } from "zod";
 import { ok as ok14 } from "@dyyz1993/xcli-core";
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
+var SCREENSHOTS_DIR2 = join2(homedir2(), ".xbrowser", "screenshots");
+function ensureScreenshotsDir2() {
+  mkdirSync2(SCREENSHOTS_DIR2, { recursive: true });
+}
+function generateScreenshotPath2(format) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).slice(2, 8);
+  const ext = format === "jpeg" ? "jpg" : "png";
+  return join2(SCREENSHOTS_DIR2, `screenshot-${timestamp}-${random}.${ext}`);
+}
 var waitActionSchema = z14.object({
   type: z14.literal("wait"),
   milliseconds: z14.number().positive().optional(),
@@ -1592,7 +1649,8 @@ var screenshotActionSchema = z14.object({
   type: z14.literal("screenshot"),
   fullPage: z14.boolean().optional(),
   quality: z14.number().min(1).max(100).optional(),
-  viewport: z14.object({ width: z14.number().int().positive(), height: z14.number().int().positive() }).optional()
+  viewport: z14.object({ width: z14.number().int().positive(), height: z14.number().int().positive() }).optional(),
+  base64: z14.boolean().optional().describe("Return base64 data instead of file path")
 });
 var writeActionSchema = z14.object({
   type: z14.literal("write"),
@@ -1638,7 +1696,7 @@ async function executeAction(page, action) {
       if (action.selector) {
         await page.waitForSelector(action.selector, { timeout: 3e4 });
       } else if (action.milliseconds) {
-        await new Promise((resolve16) => setTimeout(resolve16, action.milliseconds));
+        await new Promise((resolve10) => setTimeout(resolve10, action.milliseconds));
       } else {
         throw new Error("wait action requires either milliseconds or selector");
       }
@@ -1659,7 +1717,13 @@ async function executeAction(page, action) {
         quality: action.quality ?? 80,
         ...action.viewport ? { clip: { x: 0, y: 0, ...action.viewport } } : {}
       });
-      return { type: "screenshot", result: buf.toString("base64") };
+      if (action.base64) {
+        return { type: "screenshot", result: buf.toString("base64"), base64: true };
+      }
+      ensureScreenshotsDir2();
+      const screenshotPath = generateScreenshotPath2("jpg");
+      writeFileSync2(screenshotPath, buf);
+      return { type: "screenshot", result: screenshotPath };
     }
     case "write":
       await page.keyboard.type(action.text);
@@ -1721,8 +1785,8 @@ var actionsCommand = registerCommand({
         results.push(result);
       }
     })();
-    const timeoutPromise = new Promise((resolve16) => {
-      setTimeout(resolve16, timeoutMs);
+    const timeoutPromise = new Promise((resolve10) => {
+      setTimeout(resolve10, timeoutMs);
     });
     await Promise.race([executionPromise, timeoutPromise]);
     const title = await ctx.page.title();
@@ -2116,7 +2180,7 @@ var scrapeCommand = registerCommand({
           await page.goto(p.url, { waitUntil: "commit", timeout: p.timeout });
           await page.waitForSelector("body", { timeout: p.timeout }).catch(() => {
           });
-          await page.waitForLoadState("networkidle", { timeout: Math.min(p.timeout, 8e3) }).catch(() => {
+          await page.waitForLoadState("networkidle", Math.min(p.timeout, 8e3)).catch(() => {
           });
           await page.waitForTimeout(p.waitAfterLoad > 0 ? p.waitAfterLoad : 2e3);
           if (p.selector) {
@@ -2396,11 +2460,11 @@ async function navigateForMap(page, url, timeout = 15e3) {
 }
 async function extractPageLinks(page, baseUrl) {
   await navigateForMap(page, baseUrl);
-  await new Promise((resolve16) => setTimeout(resolve16, 2e3));
+  await new Promise((resolve10) => setTimeout(resolve10, 2e3));
   await page.evaluate(() => {
     window.scrollTo(0, document.body.scrollHeight);
   });
-  await new Promise((resolve16) => setTimeout(resolve16, 1e3));
+  await new Promise((resolve10) => setTimeout(resolve10, 1e3));
   const origin = new URL(baseUrl).origin;
   const rawLinks = await page.evaluate((evalOrigin) => {
     return Array.from(document.querySelectorAll("a[href]")).map((a) => {
@@ -3121,7 +3185,7 @@ async function fetchFullContent(urls, timeout, cdpEndpoint) {
             const pg = await context.newPage();
             try {
               await pg.goto(url, { waitUntil: "domcontentloaded", timeout });
-              await pg.waitForLoadState("networkidle", { timeout }).catch(() => {
+              await pg.waitForLoadState("networkidle", timeout).catch(() => {
               });
               const html = await pg.content();
               contentMap.set(url, htmlToMarkdown(html, { onlyMainContent: true }));
@@ -3517,7 +3581,7 @@ var networkCommand = registerCommand({
         waitUntil: "domcontentloaded",
         timeout: p.timeout
       });
-      await page.waitForLoadState("networkidle", { timeout: p.timeout }).catch(() => {
+      await page.waitForLoadState("networkidle", p.timeout).catch(() => {
       });
       await page.waitForTimeout(p.wait);
       const totalCount = captures.length;
@@ -3826,7 +3890,25 @@ var ENGINE_KEY_ENUM = z20.enum(ALL_ENGINE_KEYS);
 
 // src/commands/snapshot.ts
 import { z as z21 } from "zod";
-import { ok as ok20, fail as fail4 } from "@dyyz1993/xcli-core";
+import { ok as ok20, fail as fail4, normalizeTips as normalizeTips3 } from "@dyyz1993/xcli-core";
+
+// src/runtime/ref-store.ts
+var sessions = /* @__PURE__ */ new Map();
+function normalizeAgentRef(ref) {
+  return ref.startsWith("@") ? ref.slice(1) : ref;
+}
+function replaceRefs(sessionKey2, screenHash, targets) {
+  sessions.set(sessionKey2, {
+    screenHash,
+    targets: new Map(targets.map((target) => [target.ref, target]))
+  });
+}
+function getRefTarget(sessionKey2, ref) {
+  const session = sessions.get(sessionKey2);
+  const target = session?.targets.get(normalizeAgentRef(ref));
+  if (!session || !target) return null;
+  return { screenHash: session.screenHash, target };
+}
 
 // src/utils/resolve-selector.ts
 function buildElementSelector(el) {
@@ -3999,9 +4081,9 @@ async function resolveSelectors(page, ariaSnapshot) {
   }
   return results;
 }
-var REF_ONLY = /^(e\d+)$/;
+var REF_ONLY = /^@?(e\d+)$/;
 var refCache = /* @__PURE__ */ new Map();
-async function resolveRefParams(page, params, selectorKeys, cache) {
+async function resolveRefParams(page, params, selectorKeys, cache, sessionId) {
   const tips = [];
   const newParams = { ...params };
   if (!selectorKeys || selectorKeys.length === 0) {
@@ -4010,7 +4092,17 @@ async function resolveRefParams(page, params, selectorKeys, cache) {
   for (const key of selectorKeys) {
     const val = params[key];
     if (typeof val !== "string" || !REF_ONLY.test(val)) continue;
-    const ref = val;
+    const match = val.match(REF_ONLY);
+    if (!match) continue;
+    const ref = normalizeAgentRef(match[1]);
+    if (sessionId) {
+      const runtimeTarget = getRefTarget(sessionId, ref);
+      if (runtimeTarget) {
+        tips.push(`ref=@${ref} (${key}) => ${runtimeTarget.target.selector}  (observe)`);
+        newParams[key] = runtimeTarget.target.selector;
+        continue;
+      }
+    }
     const activeCache = cache ?? refCache;
     const cached = activeCache.get(ref);
     if (cached) {
@@ -4039,9 +4131,9 @@ async function resolveRefParams(page, params, selectorKeys, cache) {
 }
 
 // src/utils/site-semantics.ts
-import { writeFileSync as writeFileSync2, mkdirSync, existsSync, readFileSync } from "fs";
-import { join, dirname } from "path";
-import { homedir } from "os";
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync, readFileSync } from "fs";
+import { join as join3, dirname } from "path";
+import { homedir as homedir3 } from "os";
 import { stringify, parse } from "yaml";
 import { execFile } from "child_process";
 var INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
@@ -4118,10 +4210,10 @@ function inferAction(role, label) {
   return {};
 }
 function getSemanticsDir() {
-  return join(homedir(), ".xbrowser", "site-semantics");
+  return join3(homedir3(), ".xbrowser", "site-semantics");
 }
 function getSemanticsPath(domain) {
-  return join(getSemanticsDir(), `${domain}.yaml`);
+  return join3(getSemanticsDir(), `${domain}.yaml`);
 }
 function extractDomain2(url) {
   try {
@@ -4158,9 +4250,9 @@ function saveSemantics(domain, pagePath, url, elements) {
   }
   site.updated_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync3(dir, { recursive: true });
   }
-  writeFileSync2(filePath, stringify(site, { lineWidth: 0 }));
+  writeFileSync3(filePath, stringify(site, { lineWidth: 0 }));
 }
 function loadSemantics(domain) {
   const filePath = getSemanticsPath(domain);
@@ -4230,25 +4322,25 @@ aria snapshot\uFF1A
 async function analyzeWithLLM(ariaSnapshot) {
   const piBin = process.env.PI_CLI_PATH || "pi";
   const prompt = LLM_PROMPT.replace("{snapshot}", ariaSnapshot.slice(0, 4e3));
-  return new Promise((resolve16) => {
+  return new Promise((resolve10) => {
     execFile(
       piBin,
       ["--provider", LLM_PROVIDER, "--model", LLM_MODEL, prompt],
       { timeout: LLM_TIMEOUT_MS, maxBuffer: 1024 * 1024 },
       (err, stdout, _stderr) => {
         if (err) {
-          resolve16(null);
+          resolve10(null);
           return;
         }
         const output = (stdout || "").trim();
         if (!output) {
-          resolve16(null);
+          resolve10(null);
           return;
         }
         try {
           const parsed = parse(output);
           if (!parsed || typeof parsed !== "object") {
-            resolve16(null);
+            resolve10(null);
             return;
           }
           const elements = {};
@@ -4263,9 +4355,9 @@ async function analyzeWithLLM(ariaSnapshot) {
               };
             }
           }
-          resolve16(Object.keys(elements).length > 0 ? elements : null);
+          resolve10(Object.keys(elements).length > 0 ? elements : null);
         } catch {
-          resolve16(null);
+          resolve10(null);
         }
       }
     );
@@ -4291,6 +4383,404 @@ async function enhanceSemanticsWithLLM(url, ariaSnapshot, ruleBasedElements) {
   saveSemantics(domain, pathKey, url, llmElements);
 }
 
+// src/runtime/agent-runtime.ts
+function sessionKey(sessionId) {
+  return sessionId || "default";
+}
+async function observePage(page, sessionId, options = {}) {
+  const [title, raw] = await Promise.all([
+    page.title().catch(() => ""),
+    page.evaluate(
+      ({ includeHidden, limit }) => {
+        function hash(input) {
+          let h = 2166136261;
+          for (let i = 0; i < input.length; i++) {
+            h ^= input.charCodeAt(i);
+            h = Math.imul(h, 16777619);
+          }
+          return (h >>> 0).toString(16);
+        }
+        function cssEscape(value) {
+          const css = globalThis.CSS;
+          return css?.escape ? css.escape(value) : value.replace(/["\\#.:,[\]>+~*]/g, "\\$&");
+        }
+        function isUnique(selector2) {
+          try {
+            return document.querySelectorAll(selector2).length === 1;
+          } catch {
+            return false;
+          }
+        }
+        function nthOfType(el) {
+          const tag = el.tagName.toLowerCase();
+          const parent = el.parentElement;
+          if (!parent) return tag;
+          const same = Array.from(parent.children).filter((child) => child.tagName === el.tagName);
+          if (same.length === 1) return tag;
+          return `${tag}:nth-of-type(${same.indexOf(el) + 1})`;
+        }
+        function selectorFor(el) {
+          const tag = el.tagName.toLowerCase();
+          const id = el.getAttribute("id");
+          if (id) {
+            const selector2 = `#${cssEscape(id)}`;
+            if (isUnique(selector2)) return selector2;
+          }
+          for (const attr of ["data-testid", "data-test", "data-qa", "name", "aria-label"]) {
+            const value = el.getAttribute(attr);
+            if (!value) continue;
+            const selector2 = `[${attr}="${cssEscape(value)}"]`;
+            if (isUnique(selector2)) return selector2;
+            const tagged = `${tag}${selector2}`;
+            if (isUnique(tagged)) return tagged;
+          }
+          const classes = Array.from(el.classList).slice(0, 3);
+          for (const cls of classes) {
+            const selector2 = `${tag}.${cssEscape(cls)}`;
+            if (isUnique(selector2)) return selector2;
+          }
+          const parts = [];
+          let cur = el;
+          while (cur && cur !== document.body && cur !== document.documentElement && parts.length < 6) {
+            parts.unshift(nthOfType(cur));
+            const selector2 = parts.join(" > ");
+            if (isUnique(selector2)) return selector2;
+            cur = cur.parentElement;
+          }
+          return parts.join(" > ") || tag;
+        }
+        function roleFor(el) {
+          const explicit = el.getAttribute("role");
+          if (explicit) return explicit;
+          const tag = el.tagName.toLowerCase();
+          if (tag === "a") return "link";
+          if (tag === "button") return "button";
+          if (tag === "select") return "combobox";
+          if (tag === "textarea") return "textbox";
+          if (tag === "input") {
+            const type = (el.getAttribute("type") || "text").toLowerCase();
+            if (type === "checkbox") return "checkbox";
+            if (type === "radio") return "radio";
+            if (type === "button" || type === "submit" || type === "reset") return "button";
+            return "textbox";
+          }
+          return tag;
+        }
+        function textName(el) {
+          const input = el;
+          const direct = el.getAttribute("aria-label") || el.getAttribute("placeholder") || el.getAttribute("title") || input.value || el.textContent || "";
+          return direct.replace(/\s+/g, " ").trim().slice(0, 120);
+        }
+        function actionsFor(role, editable) {
+          const actions = [];
+          if (editable) actions.push("fill", "type");
+          if (role === "combobox") actions.push("select");
+          if (role === "checkbox" || role === "radio") actions.push("check");
+          actions.push("click", "hover");
+          return Array.from(new Set(actions));
+        }
+        const selector = [
+          "a[href]",
+          "button",
+          "input",
+          "textarea",
+          "select",
+          "summary",
+          "label",
+          "[role]",
+          "[tabindex]",
+          '[contenteditable="true"]'
+        ].join(",");
+        const candidates = Array.from(document.querySelectorAll(selector));
+        const seen = /* @__PURE__ */ new Set();
+        const targets2 = [];
+        for (const el of candidates) {
+          const rect = el.getBoundingClientRect();
+          const style = window.getComputedStyle(el);
+          const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+          if (!includeHidden && !visible) continue;
+          const selectorValue = selectorFor(el);
+          if (!selectorValue || seen.has(selectorValue)) continue;
+          seen.add(selectorValue);
+          const input = el;
+          const tag = el.tagName.toLowerCase();
+          const role = roleFor(el);
+          const editable = tag === "textarea" || tag === "select" || tag === "input" && !["button", "submit", "reset", "checkbox", "radio"].includes((input.type || "").toLowerCase()) || el.isContentEditable;
+          const enabled = !input.disabled && el.getAttribute("aria-disabled") !== "true";
+          const checked = typeof input.checked === "boolean" && ["checkbox", "radio"].includes((input.type || "").toLowerCase()) ? input.checked : void 0;
+          targets2.push({
+            selector: selectorValue,
+            role,
+            name: textName(el),
+            tag,
+            visible,
+            enabled,
+            editable,
+            ...checked !== void 0 ? { checked } : {},
+            ...editable && input.value ? { value: input.value.slice(0, 120) } : {},
+            ...visible ? { box: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) } } : {},
+            actions: actionsFor(role, editable)
+          });
+          if (targets2.length >= limit) break;
+        }
+        const stateText = [
+          location.href,
+          document.title,
+          document.body?.innerText?.slice(0, 5e3) || ""
+        ].join("\n");
+        return { screenHash: hash(stateText), targets: targets2 };
+      },
+      { includeHidden: !!options.includeHidden, limit: options.limit ?? 80 }
+    )
+  ]);
+  const targets = raw.targets.map((target, index) => ({
+    ref: `e${index + 1}`,
+    ...target
+  }));
+  replaceRefs(sessionKey(sessionId), raw.screenHash, targets);
+  return {
+    url: page.url(),
+    title,
+    screenHash: raw.screenHash,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    targets
+  };
+}
+function quoteName(name) {
+  const cleaned = name.replace(/\s+/g, " ").trim();
+  if (!cleaned) return "";
+  return ` "${cleaned.replace(/"/g, '\\"')}"`;
+}
+function targetFlags(target) {
+  const flags = [target.role || target.tag];
+  if (!target.enabled) flags.push("disabled");
+  if (target.editable) flags.push("editable");
+  if (target.checked !== void 0) flags.push(target.checked ? "checked" : "unchecked");
+  return flags.join(" ");
+}
+function buildSelectorMap(observation) {
+  return Object.fromEntries(observation.targets.map((target) => [target.ref, target.selector]));
+}
+function formatObservationCompact(observation, options = {}) {
+  const lines = [
+    `Page: ${observation.title || "(untitled)"}`,
+    `URL: ${observation.url}`,
+    `Screen: ${observation.screenHash}`,
+    ""
+  ];
+  if (observation.targets.length === 0) {
+    lines.push("(no interactive targets)");
+  } else {
+    for (const target of observation.targets) {
+      lines.push(`@${target.ref} [${targetFlags(target)}]${quoteName(target.name)}`);
+    }
+  }
+  if (options.selectors && observation.targets.length > 0) {
+    lines.push("", "## Selectors");
+    lines.push(observation.targets.map((target) => `${target.ref}: ${target.selector}`).join(" | "));
+  }
+  return lines.join("\n");
+}
+async function getPageScreenHash(page) {
+  const observation = await page.evaluate(() => {
+    let h = 2166136261;
+    const input = [location.href, document.title, document.body?.innerText?.slice(0, 5e3) || ""].join("\n");
+    for (let i = 0; i < input.length; i++) {
+      h ^= input.charCodeAt(i);
+      h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(16);
+  });
+  return observation;
+}
+async function actionability(page, selector) {
+  return await page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (!el) return { ok: false, reason: "not_found" };
+    const rect = el.getBoundingClientRect();
+    const style = window.getComputedStyle(el);
+    const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+    if (!visible) return { ok: false, reason: "not_visible" };
+    const input = el;
+    const enabled = !input.disabled && el.getAttribute("aria-disabled") !== "true";
+    if (!enabled) return { ok: false, reason: "disabled" };
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const hit = document.elementFromPoint(cx, cy);
+    if (hit && hit !== el && !el.contains(hit) && !hit.contains(el)) {
+      return { ok: false, reason: "covered" };
+    }
+    return { ok: true };
+  }, selector);
+}
+async function actOnPage(page, sessionId, input) {
+  const normalizedRef = input.ref ? normalizeAgentRef(input.ref) : void 0;
+  const refMatch = normalizedRef ? getRefTarget(sessionKey(sessionId), normalizedRef) : null;
+  const selector = input.selector || refMatch?.target.selector;
+  if (!selector) {
+    return {
+      action: input.action,
+      selector: "",
+      ref: normalizedRef,
+      success: false,
+      reason: input.ref ? "unknown_ref" : "missing_target",
+      message: normalizedRef ? `Ref "${input.ref}" not found. Run observe again.` : "Provide ref or selector."
+    };
+  }
+  const hash = await getPageScreenHash(page).catch(() => void 0);
+  const stale = !!(refMatch && hash && hash !== refMatch.screenHash);
+  if (!input.force) {
+    const check = await actionability(page, selector);
+    if (!check.ok) {
+      return {
+        action: input.action,
+        selector,
+        ref: normalizedRef,
+        success: false,
+        reason: stale ? "stale_ref" : check.reason,
+        message: stale ? `Ref "${input.ref}" may be stale. Run observe again.` : `Target is not actionable: ${check.reason}`,
+        stale,
+        screenHash: hash,
+        target: refMatch?.target
+      };
+    }
+  }
+  const timeout = input.timeout ?? 1e4;
+  try {
+    switch (input.action) {
+      case "click":
+        await page.locator(selector).first().click({ timeout, force: !!input.force });
+        break;
+      case "fill":
+        if (input.value === void 0) throw new Error("fill requires value");
+        await page.locator(selector).first().fill(input.value, { timeout, force: !!input.force });
+        break;
+      case "type":
+        if (input.value === void 0) throw new Error("type requires value");
+        await page.locator(selector).first().pressSequentially(input.value, { timeout });
+        break;
+      case "press":
+        if (!input.key) throw new Error("press requires key");
+        await page.locator(selector).first().press(input.key, { timeout });
+        break;
+      case "select":
+        if (input.value === void 0) throw new Error("select requires value");
+        await page.locator(selector).first().selectOption(input.value);
+        break;
+      case "check":
+        await page.locator(selector).first().check({ timeout });
+        break;
+      case "hover":
+        await page.locator(selector).first().hover({ timeout });
+        break;
+      default: {
+        const neverAction = input.action;
+        throw new Error(`Unsupported action: ${neverAction}`);
+      }
+    }
+  } catch (error) {
+    return {
+      action: input.action,
+      selector,
+      ref: normalizedRef,
+      success: false,
+      reason: "browser_error",
+      message: error.message,
+      stale,
+      screenHash: hash,
+      target: refMatch?.target
+    };
+  }
+  return {
+    action: input.action,
+    selector,
+    ref: normalizedRef,
+    success: true,
+    stale,
+    screenHash: hash,
+    target: refMatch?.target
+  };
+}
+function matchUrlPattern(url, pattern) {
+  if (pattern.includes("*")) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(url);
+  }
+  return url.includes(pattern);
+}
+async function pollUntil(timeout, pollInterval, predicate) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt <= timeout) {
+    if (await predicate()) return true;
+    await new Promise((resolve10) => setTimeout(resolve10, pollInterval));
+  }
+  return false;
+}
+async function waitForPage(page, input) {
+  const timeout = input.timeout ?? 3e4;
+  const pollInterval = input.pollInterval ?? 200;
+  const startedAt = Date.now();
+  try {
+    if (input.selector) {
+      const state = input.state ?? "visible";
+      await page.locator(input.selector).first().waitFor({ state, timeout });
+      return { success: true, matched: "selector", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.text) {
+      await page.getByText(input.text).first().waitFor({ state: "visible", timeout });
+      return { success: true, matched: "text", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.url) {
+      const matched = await pollUntil(timeout, pollInterval, async () => matchUrlPattern(page.url(), input.url));
+      return {
+        success: matched,
+        matched: "url",
+        timeout,
+        elapsed: Date.now() - startedAt,
+        ...matched ? {} : { message: `Timed out waiting for URL pattern: ${input.url}` }
+      };
+    }
+    if (input.load) {
+      await page.waitForLoadState(input.load, timeout);
+      return { success: true, matched: "load", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.fn) {
+      await page.waitForFunction(input.fn, void 0, { timeout });
+      return { success: true, matched: "fn", timeout, elapsed: Date.now() - startedAt };
+    }
+    if (input.screenHashChanged) {
+      let screenHash = await getPageScreenHash(page);
+      const matched = await pollUntil(timeout, pollInterval, async () => {
+        screenHash = await getPageScreenHash(page);
+        return screenHash !== input.screenHashChanged;
+      });
+      return {
+        success: matched,
+        matched: "screenHashChanged",
+        timeout,
+        elapsed: Date.now() - startedAt,
+        screenHash,
+        ...matched ? {} : { message: `Timed out waiting for screen hash to change: ${input.screenHashChanged}` }
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      matched: input.selector ? "selector" : input.text ? "text" : input.url ? "url" : input.load ? "load" : input.fn ? "fn" : "screenHashChanged",
+      timeout,
+      elapsed: Date.now() - startedAt,
+      message: error.message
+    };
+  }
+  return {
+    success: false,
+    matched: "selector",
+    timeout,
+    elapsed: Date.now() - startedAt,
+    message: "Provide one wait predicate: selector, text, url, load, fn, or screenHashChanged."
+  };
+}
+
 // src/commands/snapshot.ts
 var snapshotCommand = registerCommand({
   name: "snapshot",
@@ -4300,7 +4790,14 @@ var snapshotCommand = registerCommand({
   parameters: z21.object({
     type: z21.enum(["aria", "text", "dom", "all"]).default("aria").describe("Snapshot type: aria (accessibility tree), text (visible text), dom (element summary), all (combined)"),
     selector: z21.string().optional().describe("Scope to a specific element"),
-    depth: z21.number().optional().default(6).describe("Max depth for DOM/aria tree")
+    depth: z21.number().optional().default(6).describe("Max depth for DOM/aria tree"),
+    interactive: z21.boolean().optional().default(false).describe("Return interactive agent refs only"),
+    interactiveOnly: z21.boolean().optional().default(false).describe("Alias for interactive"),
+    i: z21.boolean().optional().default(false).describe("Short alias for interactive"),
+    compact: z21.boolean().optional().default(false).describe("Include compact xbrowser style snapshot text"),
+    c: z21.boolean().optional().default(false).describe("Short alias for compact"),
+    selectors: z21.boolean().optional().default(false).describe("Include ref to CSS selector map"),
+    all: z21.boolean().optional().default(false).describe("Include hidden interactive targets when using interactive snapshot")
   }),
   result: z21.object({
     url: z21.string(),
@@ -4313,11 +4810,23 @@ var snapshotCommand = registerCommand({
     const page = ctx.page;
     const url = page.url();
     const title = await page.title().catch(() => "");
+    if (p.interactive || p.interactiveOnly || p.i || p.compact || p.c || p.selectors) {
+      const observation = await observePage(page, ctx.sessionId, {
+        includeHidden: p.all
+      });
+      if (p.selectors) observation.selectors = buildSelectorMap(observation);
+      if (p.compact || p.c || p.interactive || p.interactiveOnly || p.i) {
+        observation.compact = formatObservationCompact(observation, { selectors: p.selectors });
+      }
+      return ok20(observation, normalizeTips3([
+        `refs refreshed for ${observation.targets.length} targets; use click @e1 or fill @e2 "text"`
+      ]));
+    }
     if (p.type === "aria") {
       const aria = await captureAriaSnapshot(page, p.selector, p.depth);
       const tips = await buildRefTips(page, aria);
       persistSemantics(url, aria);
-      return ok20({ url, title, aria }, tips);
+      return ok20({ url, title, aria }, normalizeTips3(tips));
     }
     if (p.type === "text") {
       const text = await captureTextSnapshot(page, p.selector);
@@ -4335,7 +4844,7 @@ var snapshotCommand = registerCommand({
       ]);
       const tips = await buildRefTips(page, aria);
       persistSemantics(url, aria);
-      return ok20({ url, title, aria, text, dom }, tips);
+      return ok20({ url, title, aria, text, dom }, normalizeTips3(tips));
     }
     return fail4(`Unknown snapshot type: ${p.type}`);
   }
@@ -4363,10 +4872,10 @@ async function buildRefTips(page, aria) {
     return [];
   }
 }
-async function captureAriaSnapshot(page, selector, depth) {
+async function captureAriaSnapshot(page, selector, _depth) {
   try {
     const locator = selector ? page.locator(selector).first() : page.locator("body");
-    return await locator.ariaSnapshot({ depth });
+    return await locator.ariaSnapshot();
   } catch {
     try {
       return await page.locator("body").ariaSnapshot();
@@ -4377,7 +4886,7 @@ async function captureAriaSnapshot(page, selector, depth) {
 }
 async function captureTextSnapshot(page, selector) {
   if (selector) {
-    return await page.locator(selector).first().innerText({ timeout: 5e3 }).catch(() => "");
+    return await page.locator(selector).first().innerText().catch(() => "");
   }
   return await page.evaluate(() => document.body?.innerText || "").catch(() => "");
 }
@@ -4413,22 +4922,113 @@ async function captureDomSnapshot(page, selector, maxDepth) {
   ).catch(() => ({ tag: "error" }));
 }
 
-// src/commands/tab.ts
+// src/commands/agent.ts
 import { z as z22 } from "zod";
-import { ok as ok21, fail as fail5 } from "@dyyz1993/xcli-core";
-var TabParams = z22.object({
-  subcommand: z22.enum(["list", "new", "close", "switch"]),
-  url: z22.string().optional(),
-  index: z22.number().int().min(0).optional()
+import { ok as ok21, normalizeTips as normalizeTips4 } from "@dyyz1993/xcli-core";
+var observeCommand = registerCommand({
+  name: "observe",
+  description: "Observe the current page as structured agent targets with session refs",
+  scope: "page",
+  parameters: z22.object({
+    includeHidden: z22.boolean().optional().default(false).describe("Include hidden elements in the target list"),
+    limit: z22.number().int().positive().max(300).optional().default(80).describe("Maximum number of targets to return"),
+    compact: z22.boolean().optional().default(false).describe("Include compact xbrowser style snapshot text"),
+    selectors: z22.boolean().optional().default(false).describe("Include ref to stable CSS selector map")
+  }),
+  result: z22.object({
+    targets: z22.array(z22.record(z22.unknown())),
+    selectors: z22.record(z22.unknown()).optional(),
+    compact: z22.string().optional()
+  }).passthrough(),
+  handler: async (p, ctx) => {
+    const observation = await observePage(ctx.page, ctx.sessionId, {
+      includeHidden: p.includeHidden,
+      limit: p.limit
+    });
+    if (p.selectors) observation.selectors = buildSelectorMap(observation);
+    if (p.compact) observation.compact = formatObservationCompact(observation, { selectors: p.selectors });
+    return ok21(observation, normalizeTips4([
+      `refs refreshed for ${observation.targets.length} targets; use act --ref @e1 --action click or click @e1`
+    ]));
+  }
+});
+var actCommand = registerCommand({
+  name: "act",
+  description: "Perform an agent action using an observe ref or explicit selector",
+  scope: "element",
+  selectorParams: ["selector"],
+  parameters: z22.object({
+    action: z22.enum(["click", "fill", "type", "press", "select", "check", "hover"]).default("click"),
+    ref: z22.string().optional().describe("Session-scoped ref returned by observe, such as e1"),
+    selector: z22.string().optional().describe("CSS selector fallback when no ref is available"),
+    value: z22.string().optional().describe("Value for fill/type/select"),
+    key: z22.string().optional().describe("Key for press"),
+    force: z22.boolean().optional().default(false).describe("Bypass actionability checks"),
+    timeout: z22.number().optional().default(1e4).describe("Playwright action timeout in milliseconds")
+  }).refine((p) => !!p.ref || !!p.selector, {
+    message: "Either ref or selector is required"
+  }),
+  handler: async (p, ctx) => {
+    const result = await actOnPage(ctx.page, ctx.sessionId, { ...p });
+    if (!result.success) {
+      return {
+        success: false,
+        data: result,
+        message: result.message || result.reason || "Action failed",
+        tips: normalizeTips4(result.stale ? ["run observe again to refresh refs"] : [])
+      };
+    }
+    return ok21(result, normalizeTips4(result.stale ? ["ref screen hash changed; run observe if the next action is uncertain"] : []));
+  }
+});
+var waitForCommand = registerCommand({
+  name: "waitFor",
+  description: "Wait for agent predicates such as text, URL, load state, selector state, or screen hash changes",
+  scope: "page",
+  selectorParams: ["selector"],
+  parameters: z22.object({
+    selector: z22.string().optional().describe("CSS selector or observe ref to wait for"),
+    state: z22.enum(["attached", "detached", "visible", "hidden"]).optional().default("visible"),
+    text: z22.string().optional().describe("Visible text to wait for"),
+    url: z22.string().optional().describe("URL substring or glob pattern to wait for"),
+    load: z22.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Load state to wait for"),
+    fn: z22.string().optional().describe("JavaScript predicate to wait for"),
+    screenHashChanged: z22.string().optional().describe("Previous screenHash from observe"),
+    timeout: z22.number().optional().default(3e4),
+    pollInterval: z22.number().optional().default(200)
+  }).refine((p) => [p.selector, p.text, p.url, p.load, p.fn, p.screenHashChanged].filter(Boolean).length === 1, {
+    message: "Provide exactly one wait predicate: selector, text, url, load, fn, or screenHashChanged"
+  }),
+  handler: async (p, ctx) => {
+    const result = await waitForPage(ctx.page, { ...p });
+    if (!result.success) {
+      return {
+        success: false,
+        data: result,
+        message: result.message || `Timed out waiting for ${result.matched}`,
+        tips: []
+      };
+    }
+    return ok21(result);
+  }
+});
+
+// src/commands/tab.ts
+import { z as z23 } from "zod";
+import { ok as ok22, fail as fail5 } from "@dyyz1993/xcli-core";
+var TabParams = z23.object({
+  subcommand: z23.enum(["list", "new", "close", "switch"]),
+  url: z23.string().optional(),
+  index: z23.number().int().min(0).optional()
 });
 var tabCommand = registerCommand({
   name: "tab",
   description: "Manage browser tabs: list, new, close, switch",
   scope: "page",
   parameters: TabParams,
-  result: z22.object({
-    success: z22.boolean(),
-    data: z22.unknown()
+  result: z23.object({
+    success: z23.boolean(),
+    data: z23.unknown()
   }),
   handler: async (p, ctx) => {
     const pages = ctx.browserContext.pages();
@@ -4468,7 +5068,7 @@ function handleList(pages, ctx) {
       active: i === currentIndex
     };
   });
-  return ok21({ tabs, total: tabs.length, activeIndex: currentIndex });
+  return ok22({ tabs, total: tabs.length, activeIndex: currentIndex });
 }
 async function handleNew(p, _pages, ctx) {
   const newPage = await ctx.browserContext.newPage();
@@ -4490,7 +5090,7 @@ async function handleNew(p, _pages, ctx) {
   const title = await newPage.title().catch(() => "");
   const allPages = ctx.browserContext.pages();
   const newIndex = allPages.indexOf(newPage);
-  return ok21({
+  return ok22({
     index: newIndex >= 0 ? newIndex : allPages.length - 1,
     url: newPage.url(),
     title,
@@ -4518,7 +5118,7 @@ async function handleClose(p, pages, ctx) {
     }
     ctx.page = newActivePage;
   }
-  return ok21({
+  return ok22({
     closedIndex: closeIndex,
     total: remainingPages.length,
     activeIndex: isActivePage ? closeIndex < remainingPages.length ? closeIndex : remainingPages.length - 1 : pages.indexOf(ctx.page)
@@ -4540,7 +5140,7 @@ async function handleSwitch(p, pages, ctx) {
   }
   ctx.page = targetPage;
   const title = await targetPage.title().catch(() => "");
-  return ok21({
+  return ok22({
     index: p.index,
     url: targetPage.url(),
     title,
@@ -4549,12 +5149,13 @@ async function handleSwitch(p, pages, ctx) {
 }
 
 // src/commands/addinitscript.ts
-import { z as z23 } from "zod";
-import { ok as ok22 } from "@dyyz1993/xcli-core";
+import { z as z24 } from "zod";
+import { ok as ok23 } from "@dyyz1993/xcli-core";
 import { readFileSync as readFileSync2 } from "fs";
 
 // src/chain-parser.ts
-import { unquote as unquote2 } from "@dyyz1993/xcli-core";
+import { splitCommand, parseCommandArgs } from "@dyyz1993/xcli-core";
+import { registerCommandDefinition } from "@dyyz1993/xcli-core";
 function parseCommandChain(input, options) {
   const result = [];
   let currentPipeline = [];
@@ -4645,159 +5246,56 @@ function isSpaceAround(input, pos, tokenLen) {
   const after = pos + tokenLen < input.length && input[pos + tokenLen] === " ";
   return before && after;
 }
-function splitCommand(cmdStr) {
-  const parts = [];
-  let current = "";
-  let inQuote = null;
-  for (let i = 0; i < cmdStr.length; i++) {
-    const char = cmdStr[i];
-    if (!inQuote && (char === "'" || char === '"')) {
-      inQuote = char;
-      current += char;
-      continue;
-    }
-    if (inQuote && char === inQuote) {
-      inQuote = null;
-      current += char;
-      continue;
-    }
-    if (!inQuote && /\s/.test(char)) {
-      if (current.trim()) {
-        parts.push(current.trim());
-        current = "";
-      }
-      continue;
-    }
-    current += char;
-  }
-  if (current.trim()) {
-    parts.push(current.trim());
-  }
-  return parts;
-}
-var SHORT_FLAG_MAP = {
-  s: "selector",
-  v: "value"
-};
-function coerceValue2(raw) {
-  const v = unquote2(raw);
-  if (v === "true") return true;
-  if (v === "false") return false;
-  if (/^\d+$/.test(v)) return parseInt(v, 10);
-  if (/^\d+\.\d+$/.test(v)) return parseFloat(v);
-  if (v.startsWith("[") || v.startsWith("{")) {
-    try {
-      return JSON.parse(v);
-    } catch {
-      return v;
-    }
-  }
-  return v;
-}
-function parseCommandArgs(name, args) {
-  const definitions = getCommandDefinitions();
-  const def = definitions[name];
-  const positionalKeys = def ? def.positional : [];
-  const params = {};
-  let positionalIndex = 0;
-  for (let i = 0; i < args.length; i++) {
-    const raw = args[i];
-    const arg = unquote2(raw);
-    if (raw.startsWith("--")) {
-      const key = raw.slice(2);
-      const value = args[i + 1];
-      if (value && !value.startsWith("-")) {
-        params[key] = coerceValue2(value);
-        i++;
-      } else {
-        params[key] = true;
-      }
-    } else if (raw.startsWith("-") && raw.length === 2) {
-      const flag = raw[1];
-      const mappedKey = SHORT_FLAG_MAP[flag];
-      const value = args[i + 1];
-      if (mappedKey && value && !value.startsWith("-")) {
-        params[mappedKey] = coerceValue2(value);
-        i++;
-      } else if (value && !value.startsWith("-")) {
-        params[flag] = coerceValue2(value);
-        i++;
-      } else {
-        params[mappedKey || flag] = true;
-      }
-    } else {
-      if (positionalIndex < positionalKeys.length) {
-        const isLast = positionalIndex === positionalKeys.length - 1;
-        if (isLast && name === "eval") {
-          const remaining = args.slice(i).map(unquote2).join(" ");
-          params[positionalKeys[positionalIndex]] = remaining;
-          break;
-        }
-        params[positionalKeys[positionalIndex]] = arg;
-        positionalIndex++;
-      }
-    }
-  }
-  return { command: name, params };
-}
-var commandDefCache = {
-  goto: { positional: ["url"] },
-  click: { positional: ["selector"] },
-  fill: { positional: ["selector", "value"] },
-  type: { positional: ["selector", "text"] },
-  press: { positional: ["selector", "key"] },
-  select: { positional: ["selector", "value"] },
-  check: { positional: ["selector"] },
-  uncheck: { positional: ["selector"] },
-  hover: { positional: ["selector"] },
-  dblclick: { positional: ["selector"] },
-  wait: { positional: ["selector"] },
-  screenshot: { positional: [] },
-  eval: { positional: ["expression"] },
-  scroll: { positional: ["direction"] },
-  title: { positional: [] },
-  url: { positional: [] },
-  html: { positional: [] },
-  text: { positional: [] },
-  back: { positional: [] },
-  forward: { positional: [] },
-  refresh: { positional: [] },
-  console: { positional: [] },
-  network: { positional: [] },
-  perf: { positional: [] },
-  health: { positional: [] },
-  scrape: { positional: ["url"] },
-  structure: { positional: [] },
-  "get-cookies": { positional: [] },
-  "set-cookie": { positional: [] },
-  "clear-cookies": { positional: [] },
-  "get-local-storage": { positional: [] },
-  "set-local-storage": { positional: [] },
-  "clear-local-storage": { positional: [] },
-  "set-viewport": { positional: [] },
-  frames: { positional: [] },
-  frame: { positional: ["selector"] },
-  actions: { positional: ["url"] },
-  find: { positional: ["strategy", "value"] },
-  addinitscript: { positional: ["script"] },
-  tab: { positional: ["subcommand"] }
-};
-function getCommandDefinitions() {
-  return commandDefCache;
-}
-function registerCommandDefinition(name, positional) {
-  commandDefCache[name] = { positional };
-}
+registerCommandDefinition("goto", ["url"]);
+registerCommandDefinition("click", ["selector"]);
+registerCommandDefinition("fill", ["selector", "value"]);
+registerCommandDefinition("type", ["selector", "text"]);
+registerCommandDefinition("press", ["selector", "key"]);
+registerCommandDefinition("select", ["selector", "value"]);
+registerCommandDefinition("check", ["selector"]);
+registerCommandDefinition("uncheck", ["selector"]);
+registerCommandDefinition("hover", ["selector"]);
+registerCommandDefinition("dblclick", ["selector"]);
+registerCommandDefinition("wait", ["selector"]);
+registerCommandDefinition("screenshot", []);
+registerCommandDefinition("eval", ["expression"]);
+registerCommandDefinition("scroll", ["direction"]);
+registerCommandDefinition("title", []);
+registerCommandDefinition("url", []);
+registerCommandDefinition("html", []);
+registerCommandDefinition("text", []);
+registerCommandDefinition("back", []);
+registerCommandDefinition("forward", []);
+registerCommandDefinition("refresh", []);
+registerCommandDefinition("console", []);
+registerCommandDefinition("network", []);
+registerCommandDefinition("perf", []);
+registerCommandDefinition("health", []);
+registerCommandDefinition("scrape", ["url"]);
+registerCommandDefinition("structure", []);
+registerCommandDefinition("get-cookies", []);
+registerCommandDefinition("set-cookie", []);
+registerCommandDefinition("clear-cookies", []);
+registerCommandDefinition("get-local-storage", []);
+registerCommandDefinition("set-local-storage", []);
+registerCommandDefinition("clear-local-storage", []);
+registerCommandDefinition("set-viewport", []);
+registerCommandDefinition("frames", []);
+registerCommandDefinition("frame", ["selector"]);
+registerCommandDefinition("actions", ["url"]);
+registerCommandDefinition("find", ["strategy", "value", "operation"]);
+registerCommandDefinition("addinitscript", ["script"]);
+registerCommandDefinition("tab", ["subcommand"]);
 
 // src/commands/addinitscript.ts
-var InitScriptParams = z23.object({
-  script: z23.string().optional(),
-  file: z23.string().optional(),
-  stdin: z23.boolean().optional(),
-  name: z23.string().optional(),
-  list: z23.boolean().optional(),
-  remove: z23.string().optional(),
-  base64: z23.string().optional()
+var InitScriptParams = z24.object({
+  script: z24.string().optional(),
+  file: z24.string().optional(),
+  stdin: z24.boolean().optional(),
+  name: z24.string().optional(),
+  list: z24.boolean().optional(),
+  remove: z24.string().optional(),
+  base64: z24.string().optional()
 });
 var registeredScripts = /* @__PURE__ */ new Map();
 function resolveScriptContent(params) {
@@ -4817,12 +5315,12 @@ function resolveScriptContent(params) {
 }
 async function readStdin() {
   const { createReadStream } = await import("fs");
-  const { createInterface: createInterface2 } = await import("readline");
-  return new Promise((resolve16, reject) => {
+  const { createInterface } = await import("readline");
+  return new Promise((resolve10, reject) => {
     const lines = [];
-    const rl = createInterface2({ input: createReadStream("/dev/stdin") });
+    const rl = createInterface({ input: createReadStream("/dev/stdin") });
     rl.on("line", (line) => lines.push(line));
-    rl.on("close", () => resolve16(lines.join("\n")));
+    rl.on("close", () => resolve10(lines.join("\n")));
     rl.on("error", reject);
   });
 }
@@ -4831,6 +5329,15 @@ var addInitScriptCommand = registerCommand({
   description: "Add an initialization script that runs on every page load",
   scope: "page",
   parameters: InitScriptParams,
+  result: z24.object({
+    scripts: z24.array(z24.object({ name: z24.string(), size: z24.number(), preview: z24.string() })).optional(),
+    removed: z24.string().optional(),
+    existed: z24.boolean().optional(),
+    error: z24.string().optional(),
+    registered: z24.string().optional(),
+    hint: z24.string().optional(),
+    executedImmediately: z24.boolean().optional()
+  }).passthrough(),
   handler: async (params, ctx) => {
     if (params.list) {
       const scripts = Array.from(registeredScripts.entries()).map(([n, content2]) => ({
@@ -4838,15 +5345,15 @@ var addInitScriptCommand = registerCommand({
         size: content2.length,
         preview: content2.slice(0, 80)
       }));
-      return ok22({ scripts });
+      return ok23({ scripts });
     }
     if (params.remove) {
       const existed = registeredScripts.delete(params.remove);
-      return ok22({ removed: params.remove, existed });
+      return ok23({ removed: params.remove, existed });
     }
     let content = params.stdin ? await readStdin() : resolveScriptContent(params);
     if (!content) {
-      return ok22({ error: "No script content provided. Use --script, --file, --stdin, or --base64" });
+      return ok23({ error: "No script content provided. Use --script, --file, --stdin, or --base64" });
     }
     const scriptName = params.name ?? `script-${Date.now()}`;
     registeredScripts.set(scriptName, content);
@@ -4854,74 +5361,134 @@ var addInitScriptCommand = registerCommand({
     try {
       await ctx.page.evaluate(content);
     } catch {
-      return ok22({
+      return ok23({
         registered: scriptName,
         hint: "Script registered for future page loads; immediate execution skipped (page may not be ready)"
       });
     }
-    return ok22({ registered: scriptName, executedImmediately: true });
+    return ok23({ registered: scriptName, executedImmediately: true });
   }
 });
 registerCommandDefinition("addinitscript", ["script"]);
 
 // src/commands/find.ts
-import { z as z24 } from "zod";
-import { ok as ok23, fail as fail6 } from "@dyyz1993/xcli-core";
+import { z as z25 } from "zod";
+import { ok as ok24, fail as fail6, normalizeTips as normalizeTips5 } from "@dyyz1993/xcli-core";
+var actionSchema2 = z25.enum(["click", "fill", "type", "select", "hover", "check"]);
 var findCommand = registerCommand({
   name: "find",
   description: "Find elements by semantic strategy (text/role/label/placeholder/testid) and optionally perform an action",
   scope: "page",
-  parameters: z24.object({
-    strategy: z24.enum(["text", "role", "label", "placeholder", "testid"]),
-    value: z24.string(),
-    name: z24.string().optional(),
-    exact: z24.boolean().optional().default(false),
-    click: z24.boolean().optional().default(false),
-    fill: z24.string().optional(),
-    type: z24.string().optional(),
-    select: z24.string().optional(),
-    timeout: z24.number().optional().default(1e4)
+  parameters: z25.object({
+    strategy: z25.enum(["text", "role", "label", "placeholder", "testid", "alt", "title", "first", "last", "nth"]),
+    value: z25.string(),
+    name: z25.string().optional(),
+    exact: z25.boolean().optional().default(false),
+    operation: z25.string().optional().describe('Trailing operation syntax, e.g. click, fill "text", type "text"'),
+    action: actionSchema2.optional().describe("Action to perform when not using trailing operation syntax"),
+    actionValue: z25.string().optional().describe("Value for fill/type/select when using action"),
+    index: z25.number().int().optional().describe("Index for nth strategy"),
+    click: z25.boolean().optional().default(false),
+    fill: z25.string().optional(),
+    type: z25.string().optional(),
+    select: z25.string().optional(),
+    hover: z25.boolean().optional().default(false),
+    check: z25.boolean().optional().default(false),
+    timeout: z25.number().optional().default(1e4)
   }),
-  result: z24.object({
-    matched: z24.number(),
-    selector: z24.string(),
-    action: z24.string().optional()
+  result: z25.object({
+    matched: z25.number(),
+    selector: z25.string(),
+    action: z25.string().optional()
   }),
   handler: async (p, ctx) => {
     const page = ctx.page;
-    const locator = buildLocator(page, p.strategy, p.value, {
+    const normalized = normalizeFindParams({ ...p });
+    const parsedOperation = parseOperation(normalized.operation);
+    const actionName = parsedOperation.action || p.action || inferLegacyAction(p);
+    const actionValue = parsedOperation.value ?? p.actionValue ?? p.fill ?? p.type ?? p.select;
+    const locator = buildLocator(page, normalized.strategy, normalized.value, {
       name: p.name,
-      exact: p.exact
+      exact: p.exact,
+      index: normalized.index
     });
     const count = await locator.count();
     if (count === 0) {
       return fail6(`No element found with ${p.strategy}="${p.value}"`);
     }
     const tips = [];
-    const target = locator.first();
+    const target = selectTarget(locator, p.strategy);
     if (count > 1) {
-      tips.push(`\u26A0\uFE0F Matched ${count} elements, using first`);
+      tips.push(`\u26A0\uFE0F Matched ${count} elements, used first match. Use 'find nth <index> ${normalized.strategy} "${normalized.value}" ${actionName || "click"}' for a specific match.`);
     }
-    const selector = describeSelector(p.strategy, p.value, p.name);
-    let action;
-    if (p.click) {
+    const selector = describeSelector(normalized.strategy, normalized.value, p.name);
+    if (actionName === "click") {
       await target.click({ timeout: p.timeout, force: true });
-      action = "click";
-    } else if (p.fill !== void 0) {
-      await target.fill(p.fill, { timeout: p.timeout, force: true });
-      action = `fill("${p.fill}")`;
-    } else if (p.type !== void 0) {
-      await target.type(p.type, { delay: 10, timeout: p.timeout });
-      action = `type("${p.type}")`;
-    } else if (p.select !== void 0) {
-      await target.selectOption(p.select, { timeout: p.timeout, force: true });
-      action = `select("${p.select}")`;
-    }
-    const result = ok23({ matched: count, selector, action });
-    if (tips.length > 0) result.tips = tips;
-    return result;
+      return okWithTips({ matched: count, selector, action: "click" }, tips);
+    } else if (actionName === "fill") {
+      if (actionValue === void 0) return fail6("find fill requires a value");
+      await target.fill(actionValue, { timeout: p.timeout, force: true });
+      return okWithTips({ matched: count, selector, action: `fill("${actionValue}")` }, tips);
+    } else if (actionName === "type") {
+      if (actionValue === void 0) return fail6("find type requires a value");
+      await target.type(actionValue, { delay: 10, timeout: p.timeout });
+      return okWithTips({ matched: count, selector, action: `type("${actionValue}")` }, tips);
+    } else if (actionName === "select") {
+      if (actionValue === void 0) return fail6("find select requires a value");
+      await target.selectOption(actionValue);
+      return okWithTips({ matched: count, selector, action: `select("${actionValue}")` }, tips);
+    } else if (actionName === "hover") {
+      await target.hover({ timeout: p.timeout, force: true });
+      return okWithTips({ matched: count, selector, action: "hover" }, tips);
+    } else if (actionName === "check") {
+      await target.check({ timeout: p.timeout });
+      return okWithTips({ matched: count, selector, action: "check" }, tips);
+    }
+    return okWithTips({ matched: count, selector }, tips);
   }
 });
+function okWithTips(data, tips) {
+  const result = ok24(data);
+  if (tips.length > 0) result.tips = normalizeTips5(tips);
+  return result;
+}
+function parseOperation(operation) {
+  if (!operation) return {};
+  const match = operation.trim().match(/^(\S+)(?:\s+([\s\S]+))?$/);
+  if (!match) return {};
+  const maybeAction = match[1];
+  const parsed = actionSchema2.safeParse(maybeAction);
+  if (!parsed.success) return {};
+  const rawValue = match[2];
+  const value = rawValue?.replace(/^["']|["']$/g, "");
+  return { action: parsed.data, ...value !== void 0 ? { value } : {} };
+}
+function normalizeFindParams(p) {
+  if (p.strategy !== "nth") return { strategy: p.strategy, value: p.value, operation: p.operation, index: p.index };
+  const parsedIndex = Number(p.value);
+  if (!Number.isInteger(parsedIndex) || !p.operation) {
+    return { strategy: p.strategy, value: p.value, operation: p.operation, index: p.index };
+  }
+  const match = p.operation.trim().match(/^(\S+)(?:\s+([\s\S]+))?$/);
+  if (!match) {
+    return { strategy: p.strategy, value: p.value, operation: p.operation, index: parsedIndex };
+  }
+  return {
+    strategy: p.strategy,
+    value: match[1].replace(/^["']|["']$/g, ""),
+    ...match[2] ? { operation: match[2] } : {},
+    index: parsedIndex
+  };
+}
+function inferLegacyAction(p) {
+  if (p.click) return "click";
+  if (p.fill !== void 0) return "fill";
+  if (p.type !== void 0) return "type";
+  if (p.select !== void 0) return "select";
+  if (p.hover) return "hover";
+  if (p.check) return "check";
+  return void 0;
+}
 function buildLocator(page, strategy, value, opts) {
   switch (strategy) {
     case "text":
@@ -4934,10 +5501,24 @@ function buildLocator(page, strategy, value, opts) {
       return page.getByPlaceholder(value, { exact: opts.exact });
     case "testid":
       return page.getByTestId(value);
+    case "alt":
+      return page.getByAltText(value, { exact: opts.exact });
+    case "title":
+      return page.getByTitle(value, { exact: opts.exact });
+    case "first":
+      return page.locator(value).first();
+    case "last":
+      return page.locator(value).last();
+    case "nth":
+      return page.locator(value).nth(opts.index ?? 0);
     default:
       return page.getByText(value, { exact: opts.exact });
   }
 }
+function selectTarget(locator, strategy) {
+  if (strategy === "first" || strategy === "last" || strategy === "nth") return locator;
+  return locator.first();
+}
 function describeSelector(strategy, value, name) {
   switch (strategy) {
     case "role":
@@ -4950,6 +5531,16 @@ function describeSelector(strategy, value, name) {
       return `getByPlaceholder("${value}")`;
     case "testid":
       return `getByTestId("${value}")`;
+    case "alt":
+      return `getByAltText("${value}")`;
+    case "title":
+      return `getByTitle("${value}")`;
+    case "first":
+      return `first("${value}")`;
+    case "last":
+      return `last("${value}")`;
+    case "nth":
+      return `nth("${value}")`;
     default:
       return `${strategy}("${value}")`;
   }
@@ -5072,7 +5663,7 @@ async function detectCaptcha2(page) {
 }
 async function detectWarningText(page) {
   try {
-    const pageText = await page.textContent("body", { timeout: 1e3 }).catch(() => "") || "";
+    const pageText = await page.textContent("body").catch(() => "") || "";
     const lowerText = pageText.toLowerCase();
     for (const { text, severity } of WARNING_TEXTS) {
       if (lowerText.includes(text.toLowerCase())) {
@@ -5113,16 +5704,11 @@ async function detectWebdriverExposure(page) {
   try {
     const webdriver = await page.evaluate(() => {
       return {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        webdriver: window.navigator?.webdriver,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        webdriver: window.navigator && window.navigator instanceof Object ? window.navigator.webdriver : void 0,
         webdriverScriptFn: !!window.__webdriver_script_fn,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         webdriverEvaluate: !!window.__webdriver_evaluate,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         chrome: !!window.chrome,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        permissions: window.navigator?.permissions
+        permissions: window.navigator && window.navigator instanceof Object ? window.navigator.permissions : void 0
       };
     }).catch(() => null);
     if (!webdriver) {
@@ -5202,380 +5788,26 @@ function formatDetectionMessage(result) {
   Action: ${action}`;
 }
 
-// src/commands/promo.ts
-import { z as z25 } from "zod";
-import { ok as ok24 } from "@dyyz1993/xcli-core";
-import { existsSync as existsSync2, readFileSync as readFileSync8 } from "fs";
-import { resolve as resolve6 } from "path";
+// src/plugin/loader.ts
+import {
+  Core
+} from "@dyyz1993/xcli-core";
+import { resolve as resolve2 } from "path";
+import { existsSync as existsSync4, readdirSync } from "fs";
+import { homedir as homedir4 } from "os";
 
-// src/promo/devto.ts
-import { readFileSync as readFileSync3 } from "fs";
+// src/plugin/metadata-parser.ts
+import { existsSync as existsSync2 } from "fs";
 import { resolve } from "path";
-import { execSync } from "child_process";
-var DEVTO_NEW_URL = "https://dev.to/new";
-function ab(config) {
-  const parts = ["agent-browser"];
-  if (config.cdpEndpoint) parts.push("--cdp", config.cdpEndpoint);
-  if (config.session) parts.push("--session", config.session);
-  return parts.join(" ");
-}
-function extractTitleFromMarkdown(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  if (match) return match[1].trim();
-  const lines = content.split("\n").filter((l) => l.trim().length > 0);
-  return lines[0] ? lines[0].replace(/^#+\s*/, "").trim() : "Untitled";
-}
-function stripTitleFromMarkdown(content) {
-  return content.replace(/^#\s+.+$\n?/m, "").trim();
-}
-async function publishToDevto(config) {
-  const cli = ab(config);
-  try {
-    const filePath = resolve(config.file);
-    const raw = readFileSync3(filePath, "utf-8");
-    const title = config.title ?? extractTitleFromMarkdown(raw);
-    const body = stripTitleFromMarkdown(raw);
-    execSync(`${cli} open ${DEVTO_NEW_URL}`, { encoding: "utf-8", timeout: 3e4 });
-    const snapshot = execSync(`${cli} snapshot -i -s body`, { encoding: "utf-8", timeout: 15e3 });
-    if (snapshot.includes("Log in") && !snapshot.includes("Notifications")) {
-      const viewer = execSync(`${cli} viewer --json`, { encoding: "utf-8", timeout: 1e4 }).trim();
-      return {
-        success: false,
-        error: `Not logged in to Dev.to. Please log in via viewer: ${viewer}`,
-        platform: "devto"
-      };
-    }
-    execSync(`${cli} fill @e_title ${JSON.stringify(title)}`, { encoding: "utf-8", timeout: 1e4 });
-    const escapedBody = JSON.stringify(body);
-    execSync(`${cli} fill @e_content ${escapedBody}`, { encoding: "utf-8", timeout: 15e3 });
-    if (config.tags) {
-      const tags = config.tags.split(",").map((t) => t.trim()).slice(0, 4).join(", ");
-      execSync(`${cli} find text "tags" click`, { encoding: "utf-8", timeout: 1e4 });
-      execSync(`${cli} type ${JSON.stringify(tags)}`, { encoding: "utf-8", timeout: 1e4 });
-    }
-    execSync(`${cli} find text "Publish" click`, { encoding: "utf-8", timeout: 15e3 });
-    const postUrl = execSync(`${cli} get url`, { encoding: "utf-8", timeout: 15e3 }).trim();
-    if (postUrl && postUrl !== DEVTO_NEW_URL && postUrl.includes("dev.to")) {
-      return { success: true, url: postUrl, platform: "devto" };
-    }
-    return { success: true, url: postUrl || void 0, platform: "devto" };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { success: false, error: message, platform: "devto" };
-  }
-}
 
-// src/promo/medium.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { resolve as resolve2 } from "path";
-import { execSync as execSync2 } from "child_process";
-var MEDIUM_NEW_URL = "https://medium.com/new-story";
-function ab2(config) {
-  const parts = ["agent-browser"];
-  if (config.cdpEndpoint) parts.push("--cdp", config.cdpEndpoint);
-  if (config.session) parts.push("--session", config.session);
-  return parts.join(" ");
-}
-function extractTitleFromMarkdown2(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  if (match) return match[1].trim();
-  const lines = content.split("\n").filter((l) => l.trim().length > 0);
-  return lines[0] ? lines[0].replace(/^#+\s*/, "").trim() : "Untitled";
-}
-function markdownToPlainText(content) {
-  return content.replace(/^#+\s+.+$/gm, "").replace(/\*\*(.+?)\*\*/g, "$1").replace(/\*(.+?)\*/g, "$1").replace(/`(.+?)`/g, "$1").replace(/\[(.+?)\]\(.+?\)/g, "$1").replace(/!\[.*?\]\(.+?\)/g, "").trim();
-}
-async function publishToMedium(config) {
-  const cli = ab2(config);
+// src/utils/json-file.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
+function readJsonFile(filePath, defaultValue) {
   try {
-    const filePath = resolve2(config.file);
-    const raw = readFileSync4(filePath, "utf-8");
-    const title = config.title ?? extractTitleFromMarkdown2(raw);
-    const body = markdownToPlainText(raw);
-    execSync2(`${cli} open ${MEDIUM_NEW_URL}`, { encoding: "utf-8", timeout: 3e4 });
-    const snapshot = execSync2(`${cli} snapshot -i -s body`, { encoding: "utf-8", timeout: 15e3 });
-    if (snapshot.includes("Sign in") && !snapshot.includes("Write")) {
-      const viewer = execSync2(`${cli} viewer --json`, { encoding: "utf-8", timeout: 1e4 }).trim();
-      return {
-        success: false,
-        error: `Not logged in to Medium. Please log in via viewer: ${viewer}`,
-        platform: "medium"
-      };
-    }
-    execSync2(`${cli} click @e_title`, { encoding: "utf-8", timeout: 1e4 });
-    execSync2(`${cli} type ${JSON.stringify(title)}`, { encoding: "utf-8", timeout: 1e4 });
-    execSync2(`${cli} click @e_content`, { encoding: "utf-8", timeout: 1e4 });
-    const lines = body.split("\n");
-    for (const line of lines) {
-      execSync2(`${cli} type ${JSON.stringify(line)}`, { encoding: "utf-8", timeout: 1e4 });
-      execSync2(`${cli} keyboard Enter`, { encoding: "utf-8", timeout: 5e3 });
-    }
-    if (config.tags) {
-      execSync2(`${cli} find text "Tags" click`, { encoding: "utf-8", timeout: 1e4 });
-      const tags = config.tags.split(",").map((t) => t.trim()).join(", ");
-      execSync2(`${cli} type ${JSON.stringify(tags)}`, { encoding: "utf-8", timeout: 1e4 });
-    }
-    execSync2(`${cli} find text "Publish" click`, { encoding: "utf-8", timeout: 15e3 });
-    const postUrl = execSync2(`${cli} get url`, { encoding: "utf-8", timeout: 15e3 }).trim();
-    return { success: true, url: postUrl || void 0, platform: "medium" };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { success: false, error: message, platform: "medium" };
-  }
-}
-
-// src/promo/csdn.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { resolve as resolve3 } from "path";
-import { execSync as execSync3 } from "child_process";
-var CSDN_EDITOR_URL = "https://mp.csdn.net/mp_blog/creation/editor";
-function ab3(config) {
-  const parts = ["agent-browser"];
-  if (config.cdpEndpoint) parts.push("--cdp", config.cdpEndpoint);
-  if (config.session) parts.push("--session", config.session);
-  return parts.join(" ");
-}
-function extractTitleFromMarkdown3(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  if (match) return match[1].trim();
-  const lines = content.split("\n").filter((l) => l.trim().length > 0);
-  return lines[0] ? lines[0].replace(/^#+\s*/, "").trim() : "Untitled";
-}
-async function publishToCsdn(config) {
-  const cli = ab3(config);
-  try {
-    const filePath = resolve3(config.file);
-    const raw = readFileSync5(filePath, "utf-8");
-    const title = config.title ?? extractTitleFromMarkdown3(raw);
-    const body = raw.replace(/^#\s+.+$\n?/m, "").trim();
-    execSync3(`${cli} open ${CSDN_EDITOR_URL}`, { encoding: "utf-8", timeout: 3e4 });
-    const snapshot = execSync3(`${cli} snapshot -i -s body`, { encoding: "utf-8", timeout: 15e3 });
-    if (snapshot.includes("\u767B\u5F55") && !snapshot.includes("\u5199\u6587\u7AE0")) {
-      const viewer = execSync3(`${cli} viewer --json`, { encoding: "utf-8", timeout: 1e4 }).trim();
-      return {
-        success: false,
-        error: `Not logged in to CSDN. Please log in via viewer: ${viewer}`,
-        platform: "csdn"
-      };
-    }
-    execSync3(`${cli} fill @e_title ${JSON.stringify(title)}`, { encoding: "utf-8", timeout: 1e4 });
-    const escapedBody = JSON.stringify(body);
-    execSync3(`${cli} fill @e_content ${escapedBody}`, { encoding: "utf-8", timeout: 15e3 });
-    if (config.tags) {
-      const tags = config.tags.split(",").map((t) => t.trim());
-      for (const tag of tags) {
-        execSync3(`${cli} find text "\u6DFB\u52A0\u6807\u7B7E" click`, { encoding: "utf-8", timeout: 1e4 });
-        execSync3(`${cli} type ${JSON.stringify(tag)}`, { encoding: "utf-8", timeout: 1e4 });
-        execSync3(`${cli} keyboard Enter`, { encoding: "utf-8", timeout: 5e3 });
-      }
-    }
-    execSync3(`${cli} find text "\u53D1\u5E03" click`, { encoding: "utf-8", timeout: 15e3 });
-    const postUrl = execSync3(`${cli} get url`, { encoding: "utf-8", timeout: 15e3 }).trim();
-    return { success: true, url: postUrl || void 0, platform: "csdn" };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { success: false, error: message, platform: "csdn" };
-  }
-}
-
-// src/promo/juejin.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { resolve as resolve4 } from "path";
-import { execSync as execSync4 } from "child_process";
-var JUEJIN_EDITOR_URL = "https://juejin.cn/editor/draft/new";
-function ab4(config) {
-  const parts = ["agent-browser"];
-  if (config.cdpEndpoint) parts.push("--cdp", config.cdpEndpoint);
-  if (config.session) parts.push("--session", config.session);
-  return parts.join(" ");
-}
-function extractTitleFromMarkdown4(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  if (match) return match[1].trim();
-  const lines = content.split("\n").filter((l) => l.trim().length > 0);
-  return lines[0] ? lines[0].replace(/^#+\s*/, "").trim() : "Untitled";
-}
-async function publishToJuejin(config) {
-  const cli = ab4(config);
-  try {
-    const filePath = resolve4(config.file);
-    const raw = readFileSync6(filePath, "utf-8");
-    const title = config.title ?? extractTitleFromMarkdown4(raw);
-    const body = raw.replace(/^#\s+.+$\n?/m, "").trim();
-    execSync4(`${cli} open ${JUEJIN_EDITOR_URL}`, { encoding: "utf-8", timeout: 3e4 });
-    const snapshot = execSync4(`${cli} snapshot -i -s body`, { encoding: "utf-8", timeout: 15e3 });
-    if (snapshot.includes("\u767B\u5F55") && snapshot.includes("\u6CE8\u518C") && !snapshot.includes("\u521B\u4F5C\u8005\u4E2D\u5FC3")) {
-      const viewer = execSync4(`${cli} viewer --json`, { encoding: "utf-8", timeout: 1e4 }).trim();
-      return {
-        success: false,
-        error: `Not logged in to Juejin. Please log in via viewer: ${viewer}`,
-        platform: "juejin"
-      };
-    }
-    execSync4(`${cli} fill @e_title ${JSON.stringify(title)}`, { encoding: "utf-8", timeout: 1e4 });
-    const escapedBody = JSON.stringify(body);
-    execSync4(`${cli} fill @e_content ${escapedBody}`, { encoding: "utf-8", timeout: 15e3 });
-    if (config.tags) {
-      const tags = config.tags.split(",").map((t) => t.trim());
-      for (const tag of tags) {
-        execSync4(`${cli} find text "\u6DFB\u52A0\u6807\u7B7E" click`, { encoding: "utf-8", timeout: 1e4 });
-        execSync4(`${cli} type ${JSON.stringify(tag)}`, { encoding: "utf-8", timeout: 1e4 });
-        execSync4(`${cli} keyboard Enter`, { encoding: "utf-8", timeout: 5e3 });
-      }
-    }
-    execSync4(`${cli} find text "\u53D1\u5E03" click`, { encoding: "utf-8", timeout: 15e3 });
-    const postUrl = execSync4(`${cli} get url`, { encoding: "utf-8", timeout: 15e3 }).trim();
-    return { success: true, url: postUrl || void 0, platform: "juejin" };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { success: false, error: message, platform: "juejin" };
-  }
-}
-
-// src/promo/quora.ts
-import { readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve5 } from "path";
-import { execSync as execSync5 } from "child_process";
-function ab5(config) {
-  const parts = ["agent-browser"];
-  if (config.cdpEndpoint) parts.push("--cdp", config.cdpEndpoint);
-  if (config.session) parts.push("--session", config.session);
-  return parts.join(" ");
-}
-async function publishToQuora(config) {
-  const cli = ab5(config);
-  try {
-    if (!config.search) {
-      return {
-        success: false,
-        error: "Quora requires --search parameter to find relevant questions",
-        platform: "quora"
-      };
-    }
-    const filePath = resolve5(config.file);
-    const raw = readFileSync7(filePath, "utf-8");
-    const answer = raw.trim();
-    const searchUrl = `https://www.quora.com/search?q=${encodeURIComponent(config.search)}`;
-    execSync5(`${cli} open ${searchUrl}`, { encoding: "utf-8", timeout: 3e4 });
-    const snapshot = execSync5(`${cli} snapshot -i -s body`, { encoding: "utf-8", timeout: 15e3 });
-    if (!snapshot.includes("Add question")) {
-      const viewer = execSync5(`${cli} viewer --json`, { encoding: "utf-8", timeout: 1e4 }).trim();
-      return {
-        success: false,
-        error: `Not logged in to Quora. Please log in via viewer: ${viewer}`,
-        platform: "quora"
-      };
-    }
-    const answerMatch = snapshot.match(/Answer\s*(?:button|link)/i);
-    if (!answerMatch) {
-      return {
-        success: false,
-        error: "No answerable questions found for the given search query. Try a different search term.",
-        platform: "quora"
-      };
-    }
-    execSync5(`${cli} find text "Answer" click`, { encoding: "utf-8", timeout: 1e4 });
-    const escapedAnswer = JSON.stringify(answer);
-    execSync5(`${cli} fill @e_answer ${escapedAnswer}`, { encoding: "utf-8", timeout: 15e3 });
-    execSync5(`${cli} find text "Submit" click`, { encoding: "utf-8", timeout: 15e3 });
-    const postUrl = execSync5(`${cli} get url`, { encoding: "utf-8", timeout: 15e3 }).trim();
-    return { success: true, url: postUrl || void 0, platform: "quora" };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { success: false, error: message, platform: "quora" };
-  }
-}
-
-// src/promo/index.ts
-var PUBLISHERS = {
-  devto: publishToDevto,
-  medium: publishToMedium,
-  csdn: publishToCsdn,
-  juejin: publishToJuejin,
-  quora: publishToQuora
-};
-async function dispatchPromo(config) {
-  const publisher = PUBLISHERS[config.platform];
-  if (!publisher) {
-    return {
-      success: false,
-      error: `Unknown platform: ${config.platform}. Supported: ${Object.keys(PUBLISHERS).join(", ")}`,
-      platform: config.platform
-    };
-  }
-  return publisher(config);
-}
-
-// src/commands/promo.ts
-var promoParams = z25.object({
-  platform: z25.enum(["devto", "medium", "csdn", "juejin", "quora"]).describe("Target platform for promotion"),
-  file: z25.string().describe("Path to Markdown file to publish"),
-  tags: z25.string().optional().describe("Comma-separated tags"),
-  title: z25.string().optional().describe("Custom title (default: extracted from file first heading)"),
-  search: z25.string().optional().describe("Quora: search query to find questions"),
-  cdpEndpoint: z25.string().optional().describe("CDP endpoint for agent-browser"),
-  session: z25.string().optional().describe("agent-browser session name")
-}).refine(
-  (data) => data.platform !== "quora" || !!data.search,
-  { message: "Quora platform requires --search parameter" }
-).refine(
-  (data) => existsSync2(resolve6(data.file)),
-  { message: "File does not exist" }
-);
-var promoCommand = registerCommand({
-  name: "promo",
-  description: "Publish promotional articles to various platforms (devto, medium, csdn, juejin, quora)",
-  scope: "project",
-  parameters: promoParams,
-  result: z25.object({
-    success: z25.boolean(),
-    url: z25.string().optional(),
-    error: z25.string().optional(),
-    platform: z25.string()
-  }),
-  handler: async (p, _ctx) => {
-    const filePath = resolve6(p.file);
-    const content = readFileSync8(filePath, "utf-8");
-    if (content.trim().length === 0) {
-      return ok24({
-        success: false,
-        error: `File is empty: ${filePath}`,
-        platform: p.platform
-      });
-    }
-    const result = await dispatchPromo({
-      platform: p.platform,
-      file: filePath,
-      tags: p.tags,
-      title: p.title,
-      search: p.search,
-      cdpEndpoint: p.cdpEndpoint ?? _ctx.cdpEndpoint,
-      session: p.session ?? p.platform
-    });
-    return ok24(result);
-  }
-});
-
-// src/plugin/loader.ts
-import {
-  Core
-} from "@dyyz1993/xcli-core";
-import { resolve as resolve8 } from "path";
-import { existsSync as existsSync5, readdirSync } from "fs";
-import { homedir as homedir2 } from "os";
-
-// src/plugin/metadata-parser.ts
-import { existsSync as existsSync3 } from "fs";
-import { resolve as resolve7 } from "path";
-
-// src/utils/json-file.ts
-import { readFileSync as readFileSync9, writeFileSync as writeFileSync3 } from "fs";
-function readJsonFile(filePath, defaultValue) {
-  try {
-    const content = readFileSync9(filePath, "utf-8");
-    return JSON.parse(content);
-  } catch {
-    return defaultValue;
+    const content = readFileSync3(filePath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return defaultValue;
   }
 }
 
@@ -5583,8 +5815,8 @@ function readJsonFile(filePath, defaultValue) {
 var PluginMetadataParser = class {
   static XBROWSER_KEYWORDS = ["xbrowser", "xbrowser-plugin"];
   static parseFromPackageJson(pluginPath) {
-    const packageJsonPath = resolve7(pluginPath, "package.json");
-    if (!existsSync3(packageJsonPath)) {
+    const packageJsonPath = resolve(pluginPath, "package.json");
+    if (!existsSync2(packageJsonPath)) {
       return null;
     }
     const packageJson = readJsonFile(packageJsonPath, null);
@@ -5648,20 +5880,20 @@ var PluginMetadataParser = class {
 };
 
 // src/plugin/ensure-deps.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
-import { join as join2 } from "path";
-import { execSync as execSync6 } from "child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
+import { join as join4 } from "path";
+import { execSync } from "child_process";
 var SHARED_PLUGIN_DEPENDENCIES = {
   "zod": "^3.24.0",
   "@dyyz1993/xcli-core": "^0.12.1"
 };
 function ensurePluginDependencies(pluginsDir) {
-  const zodPath = join2(pluginsDir, "node_modules", "zod");
-  if (existsSync4(zodPath)) return;
-  mkdirSync2(pluginsDir, { recursive: true });
-  const pkgPath = join2(pluginsDir, "package.json");
+  const zodPath = join4(pluginsDir, "node_modules", "zod");
+  if (existsSync3(zodPath)) return;
+  mkdirSync4(pluginsDir, { recursive: true });
+  const pkgPath = join4(pluginsDir, "package.json");
   let pkg2 = {};
-  if (existsSync4(pkgPath)) {
+  if (existsSync3(pkgPath)) {
     try {
       pkg2 = readJsonFile(pkgPath, {});
     } catch {
@@ -5675,13 +5907,13 @@ function ensurePluginDependencies(pluginsDir) {
       needsInstall = true;
     }
   }
-  if (!needsInstall && existsSync4(join2(pluginsDir, "node_modules"))) return;
+  if (!needsInstall && existsSync3(join4(pluginsDir, "node_modules"))) return;
   pkg2.dependencies = existingDeps;
   pkg2.private = true;
   pkg2.description = pkg2.description || "xbrowser plugins \u2014 shared dependencies";
-  writeFileSync4(pkgPath, JSON.stringify(pkg2, null, 2) + "\n", "utf-8");
+  writeFileSync5(pkgPath, JSON.stringify(pkg2, null, 2) + "\n", "utf-8");
   try {
-    execSync6("npm install --production --no-package-lock --no-fund --no-audit", {
+    execSync("npm install --production --no-package-lock --no-fund --no-audit", {
       cwd: pluginsDir,
       stdio: "pipe",
       timeout: 6e4,
@@ -5692,6 +5924,165 @@ function ensurePluginDependencies(pluginsDir) {
   }
 }
 
+// src/plugin/contract.ts
+import {
+  unwrapZod,
+  fieldsFromZodObjectReflected,
+  zodTypeToContractType
+} from "@dyyz1993/xcli-core";
+function buildPluginContract(site) {
+  const commands = site.getAllCommands().map((command) => buildCommandContract(site.getCommand?.(command.name) || command, {
+    siteRequiresLogin: site.config?.requiresLogin
+  }));
+  return {
+    version: 2,
+    plugin: {
+      name: site.name,
+      url: site.url,
+      description: site.config?.description,
+      requiresLogin: site.config?.requiresLogin
+    },
+    commands
+  };
+}
+function buildCommandContract(command, options = {}) {
+  const extension = command.xbrowser || {};
+  const inferredFields = fieldsFromZodObject(command.parameters);
+  const fields = mergeFields(inferredFields, extension.form?.fields || []);
+  const positional = extension.positional || fields.filter((field) => field.positional).map((field) => field.name);
+  const requiresLogin = command.requiresLogin === true || options.siteRequiresLogin === true && command.name !== "login" && command.name !== "logout";
+  const capabilities = extension.capabilities || inferCapabilities(command.scope || "project", requiresLogin);
+  const outputSchema = command.result ? summarizeZod(command.result) : void 0;
+  return {
+    name: command.name,
+    description: command.description || "",
+    scope: command.scope || "project",
+    requiresLogin,
+    category: extension.category,
+    capabilities,
+    positional,
+    form: {
+      title: extension.form?.title || command.description || command.name,
+      description: extension.form?.description,
+      submitLabel: extension.form?.submitLabel || "Run",
+      fields
+    },
+    output: extension.output || (outputSchema ? { schema: outputSchema } : void 0)
+  };
+}
+function fieldsFromZodObject(schema) {
+  const reflected = fieldsFromZodObjectReflected(schema);
+  return reflected.map((field) => {
+    const widget = widgetFor(field.type, field.enum);
+    return {
+      name: field.name,
+      label: toLabel(field.name),
+      type: field.type,
+      widget,
+      required: field.required,
+      ...field.description ? { description: field.description } : {},
+      ...field.default !== void 0 ? { default: field.default } : {},
+      ...field.enum ? { enum: field.enum } : {},
+      ...field.type === "array" ? { multiple: true } : {}
+    };
+  });
+}
+function mergeFields(inferred, overrides) {
+  if (overrides.length === 0) return inferred;
+  const byName = new Map(inferred.map((field) => [field.name, field]));
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const override of overrides) {
+    if (!override.name) continue;
+    const base = byName.get(override.name) || {
+      name: override.name,
+      label: toLabel(override.name),
+      type: "string",
+      widget: "text",
+      required: false
+    };
+    merged.push({ ...base, ...override, name: override.name });
+    seen.add(override.name);
+  }
+  for (const field of inferred) {
+    if (!seen.has(field.name)) merged.push(field);
+  }
+  return merged;
+}
+function inferCapabilities(scope, requiresLogin) {
+  const caps = [];
+  if (scope === "page") caps.push("browser.page");
+  if (scope === "browser") caps.push("browser.context");
+  if (requiresLogin) caps.push("auth.login");
+  return caps;
+}
+function widgetFor(type, enumValues) {
+  if (enumValues) return "select";
+  if (type === "boolean") return "checkbox";
+  if (type === "number") return "number";
+  if (type === "array") return "multi-select";
+  if (type === "object") return "json";
+  return "text";
+}
+function summarizeZod(schema) {
+  const unwrapped = unwrapZod(schema);
+  if (unwrapped.typeName === "ZodArray") {
+    const def = unwrapped.schema?._def;
+    return {
+      type: "array",
+      items: summarizeZod(def?.type || def?.innerType)
+    };
+  }
+  const shape = getObjectShape(schema);
+  if (!shape) {
+    return {
+      type: zodTypeToContractType(unwrapped.typeName),
+      required: !unwrapped.optional,
+      ...unwrapped.description ? { description: unwrapped.description } : {}
+    };
+  }
+  return Object.fromEntries(
+    Object.entries(shape).map(([name, field]) => {
+      const inner = unwrapZod(field);
+      return [name, {
+        type: zodTypeToContractType(inner.typeName),
+        required: !inner.optional,
+        ...inner.description ? { description: inner.description } : {}
+      }];
+    })
+  );
+}
+function getObjectShape(schema) {
+  const zod = schema;
+  const shapeOrFn = zod?.shape ?? zod?._def?.shape;
+  if (!shapeOrFn) return void 0;
+  return typeof shapeOrFn === "function" ? shapeOrFn() : shapeOrFn;
+}
+function toLabel(name) {
+  return name.replace(/([A-Z])/g, " $1").replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim().replace(/^./, (char) => char.toUpperCase());
+}
+
+// src/plugin/login-required-patch.ts
+import { SiteInstanceImpl } from "@dyyz1993/xcli-core";
+var patched = false;
+function patchLoginRequired() {
+  if (patched) return;
+  patched = true;
+  const proto = SiteInstanceImpl.prototype;
+  const original = proto.command;
+  proto.command = function(name, cmd) {
+    const result = original.call(this, name, cmd);
+    const loginRequired = cmd.loginRequired;
+    if (loginRequired) {
+      const entry = this.commands.get(name);
+      if (entry) {
+        entry.loginRequired = loginRequired;
+      }
+    }
+    return result;
+  };
+}
+
 // src/plugin/loader.ts
 var DEFAULT_PLUGIN_DIRS = [".xcli/plugins", "../.xcli/plugins"];
 var XBrowserPluginLoader = class {
@@ -5699,6 +6090,7 @@ var XBrowserPluginLoader = class {
   loader;
   options;
   constructor(options) {
+    patchLoginRequired();
     this.options = options ?? {};
     const cwd = this.options.cwd || process.cwd();
     const coreConfig = {
@@ -5709,7 +6101,7 @@ var XBrowserPluginLoader = class {
       envPrefix: "XBROWSER",
       pluginDirs: [
         ...DEFAULT_PLUGIN_DIRS,
-        resolve8(cwd, ".xcli/plugins")
+        resolve2(cwd, ".xcli/plugins")
       ]
     };
     this.core = new Core(coreConfig);
@@ -5734,6 +6126,13 @@ var XBrowserPluginLoader = class {
   getLoadedPlugins() {
     return this.loader.getLoadedPlugins();
   }
+  getPluginContract(siteName, commandName) {
+    const site = this.core.loader.getSite(siteName);
+    if (!site) return void 0;
+    const contract = buildPluginContract(site);
+    if (!commandName) return contract;
+    return contract.commands.find((command) => command.name === commandName);
+  }
   async loadPlugin(pluginPath, id) {
     return this.loader.loadPlugin(pluginPath, id);
   }
@@ -5748,31 +6147,31 @@ var XBrowserPluginLoader = class {
   }
   async scanAndLoad() {
     const cwd = this.options.cwd || process.cwd();
-    const globalDir = this.options.globalDir || resolve8(homedir2(), ".xbrowser/plugins");
+    const globalDir = this.options.globalDir || resolve2(homedir4(), ".xbrowser/plugins");
     ensurePluginDependencies(globalDir);
     const dirs = [
-      resolve8(cwd, ".xcli/plugins"),
-      resolve8(cwd, "../.xcli/plugins"),
-      this.options.userDir || resolve8(homedir2(), ".xcli/plugins"),
+      resolve2(cwd, ".xcli/plugins"),
+      resolve2(cwd, "../.xcli/plugins"),
+      this.options.userDir || resolve2(homedir4(), ".xcli/plugins"),
       globalDir
     ];
     const loaded = [];
     const seen = /* @__PURE__ */ new Set();
     for (const dir of dirs) {
-      if (!existsSync5(dir)) continue;
+      if (!existsSync4(dir)) continue;
       const entries = readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         if (seen.has(entry.name)) continue;
         seen.add(entry.name);
-        const pluginDir = resolve8(dir, entry.name);
-        let indexPath = resolve8(pluginDir, "index.js");
-        if (!existsSync5(indexPath)) {
-          indexPath = resolve8(pluginDir, "index.ts");
+        const pluginDir = resolve2(dir, entry.name);
+        let indexPath = resolve2(pluginDir, "index.js");
+        if (!existsSync4(indexPath)) {
+          indexPath = resolve2(pluginDir, "index.ts");
         }
-        if (!existsSync5(indexPath)) continue;
+        if (!existsSync4(indexPath)) continue;
         try {
-          if (!existsSync5(resolve8(pluginDir, "package.json"))) {
+          if (!existsSync4(resolve2(pluginDir, "package.json"))) {
             console.warn(`\u26A0\uFE0F  Plugin "${entry.name}" has no package.json. Use "xbrowser create ${entry.name} --template static" for proper structure.`);
           } else {
             const metadata = PluginMetadataParser.parseFromPackageJson(pluginDir);
@@ -5810,6 +6209,110 @@ async function getPluginLoader() {
   return pluginLoader;
 }
 
+// src/utils/viewer-url.ts
+function buildViewerUrl(sessionName = "default") {
+  try {
+    const status = getDaemonProcessStatus();
+    if (!status.running) return void 0;
+    const port = status.port || getDaemonConfig().basePort;
+    return `http://localhost:${port}/preview/${encodeURIComponent(sessionName)}`;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/plugin/login-guard.ts
+async function checkPluginLoginRequired(options) {
+  const { site, command, commandName, ctx, page, sessionName } = options;
+  if (commandName === "login" || commandName === "logout") return { ok: true };
+  const loginConfig = site.config?.loginConfig;
+  const requiresLogin = command.requiresLogin === true || site.config?.requiresLogin === true || loginConfig?.requiresLogin === true;
+  if (!requiresLogin) return { ok: true };
+  const pluginName = site.name || "plugin";
+  if (typeof site.isLoggedIn === "function") {
+    try {
+      const loggedIn = await site.isLoggedIn(ctx);
+      if (loggedIn) return { ok: true };
+      return buildLoginRequired({
+        plugin: pluginName,
+        command: commandName,
+        reason: "plugin isLoggedIn returned false",
+        sessionName,
+        loginConfig
+      });
+    } catch {
+    }
+  }
+  if (page && loginConfig) {
+    const generic = await detectLoginFromPage(page, loginConfig);
+    if (generic === "logged-in") return { ok: true };
+    if (generic === "logged-out") {
+      return buildLoginRequired({
+        plugin: pluginName,
+        command: commandName,
+        reason: "generic loginConfig detected logged-out page",
+        sessionName,
+        loginConfig
+      });
+    }
+  }
+  return { ok: true };
+}
+function buildLoginRequired(options) {
+  const viewerUrl = buildViewerUrl(options.sessionName);
+  const loginUrl = options.loginConfig?.loginUrl;
+  const message = options.loginConfig?.loginPrompt || `Plugin "${options.plugin}" requires login before running "${options.command}".`;
+  const tips = [
+    message,
+    ...viewerUrl ? [`Open viewer to complete login: ${viewerUrl}`] : [],
+    ...loginUrl ? [`Login page: ${loginUrl}`] : [],
+    `After login, retry: xbrowser ${options.plugin} ${options.command} --session ${options.sessionName}`
+  ];
+  return {
+    ok: false,
+    data: {
+      code: "LOGIN_REQUIRED",
+      plugin: options.plugin,
+      command: options.command,
+      reason: options.reason,
+      ...viewerUrl ? { viewerUrl } : {},
+      ...loginUrl ? { loginUrl } : {}
+    },
+    message,
+    tips
+  };
+}
+async function detectLoginFromPage(page, config) {
+  const url = page.url();
+  if (config.loginUrls?.some((part) => url.includes(part))) return "logged-out";
+  const result = await page.evaluate((cfg) => {
+    const visible = (selector) => {
+      try {
+        const el = document.querySelector(selector);
+        if (!el) return false;
+        const rect = el.getBoundingClientRect();
+        const style = window.getComputedStyle(el);
+        return rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+      } catch {
+        return false;
+      }
+    };
+    if (cfg.loggedInSelectors?.some(visible)) return "logged-in";
+    if (cfg.loginSelectors?.some(visible)) return "logged-out";
+    const bodyText = document.body?.innerText || "";
+    const keywords = cfg.loginKeywords || [];
+    if (keywords.length > 0 && keywords.every((keyword) => bodyText.includes(keyword))) {
+      return "logged-out";
+    }
+    return "unknown";
+  }, {
+    loginSelectors: config.loginSelectors || [],
+    loginKeywords: config.loginKeywords || [],
+    loggedInSelectors: config.loggedInSelectors || []
+  });
+  return result;
+}
+
 // src/tips/dom-watcher.ts
 var DOM_WATCHER_SCRIPT = `
 (function() {
@@ -6189,7 +6692,7 @@ var TipsManager = class {
     }
   }
   debounce() {
-    return new Promise((resolve16) => setTimeout(resolve16, DEBOUNCE_MS));
+    return new Promise((resolve10) => setTimeout(resolve10, DEBOUNCE_MS));
   }
   formatTips(tips) {
     return tips.map((tip) => {
@@ -6217,33 +6720,105 @@ function getTipsManager() {
 }
 
 // src/hooks/loader.ts
-var builtinHooks = {
-  screenshot: () => import("./screenshot-MB6R7RSS.js").then((m) => m.screenshotHook)
+var FAIL_KEYWORDS = [
+  "\u767B\u5F55",
+  "login",
+  "Login",
+  "\u672A\u767B\u5F55",
+  "not logged in",
+  "cdp",
+  "CDP",
+  "\u9A8C\u8BC1\u7801",
+  "\u9A8C\u8BC1",
+  "captcha",
+  "\u9700\u8981\u767B\u5F55",
+  "requires login",
+  "blocked",
+  "403",
+  "404"
+];
+var HOOK_REGISTRY = {
+  viewer: {
+    name: "viewer",
+    onAfterCommand: async (ctx) => {
+      const result = ctx.result;
+      if (!result || result.success !== false) return void 0;
+      const msg = [
+        result.message,
+        ...result.tips || []
+      ].filter(Boolean).join(" ").toLowerCase();
+      if (!FAIL_KEYWORDS.some((k) => msg.includes(k))) return void 0;
+      const viewerUrl = buildViewerUrl();
+      if (!viewerUrl) return void 0;
+      const tips = result.tips || [];
+      if (!tips.some((t) => t.includes("viewer") || t.includes("Viewer"))) {
+        tips.push(`Open viewer: ${viewerUrl}`);
+      }
+      result.tips = tips;
+      result.viewerUrl = viewerUrl;
+      return void 0;
+    }
+  },
+  screenshot: {
+    name: "screenshot",
+    onAfterCommand: async (ctx) => {
+      try {
+        const buf = await ctx.page.screenshot({ type: "jpeg", quality: 40 }).catch(() => null);
+        if (!buf) return;
+        return { screenshot: { url: `data:image/jpeg;base64,${buf.toString("base64").slice(0, 50)}...` } };
+      } catch {
+        return;
+      }
+    }
+  },
+  recorder: {
+    name: "recorder",
+    onAfterCommand: async (ctx) => {
+      const ctxAny = ctx;
+      const logs = ctxAny.__commandLogs || [];
+      logs.push({
+        timestamp: Date.now(),
+        command: ctx.command,
+        params: JSON.parse(JSON.stringify(ctx.params)),
+        duration: ctx.duration
+      });
+      ctxAny.__commandLogs = logs;
+      return void 0;
+    }
+  }
 };
+var customHooks = {};
 async function loadHooks() {
-  const names = process.env.XBROWSER_HOOKS;
-  if (!names) return [];
+  const env = process.env.XBROWSER_HOOKS;
+  if (!env) return [];
+  const names = env.split(",").map((n) => n.trim()).filter(Boolean);
+  if (names.length === 0) return [];
   const hooks = [];
-  for (const name of names.split(",")) {
-    const trimmed = name.trim();
-    const factory = builtinHooks[trimmed];
-    if (factory) {
-      hooks.push(await factory());
+  for (const name of names) {
+    const hook = HOOK_REGISTRY[name];
+    if (hook) {
+      hooks.push(hook);
+      continue;
+    }
+    const customFactory = customHooks[name];
+    if (customFactory) {
+      const customHook = await customFactory();
+      if (customHook) hooks.push(customHook);
     }
   }
   return hooks;
 }
 
 // src/executor.ts
-import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir5 } from "os";
+import { join as join5 } from "path";
 var NAVIGATION_COMMANDS = /* @__PURE__ */ new Set(["goto", "back", "forward", "refresh"]);
 var snapshotHintShown = /* @__PURE__ */ new WeakSet();
-var STORAGE_DIR = join3(homedir3(), ".xbrowser", "storage");
+var CONFIG_DIR = join5(homedir5(), ".xbrowser");
 var storageCache = /* @__PURE__ */ new Map();
 function getPluginStorage(pluginName) {
   if (!storageCache.has(pluginName)) {
-    storageCache.set(pluginName, new PluginStorage(pluginName, STORAGE_DIR));
+    storageCache.set(pluginName, new CompositeStorage(pluginName, CONFIG_DIR, "xbrowser"));
   }
   return storageCache.get(pluginName);
 }
@@ -6251,7 +6826,7 @@ var archiveInitialized = false;
 function ensureArchiveInit() {
   if (!archiveInitialized) {
     try {
-      configureArchiveStore({ archiveDir: join3(homedir3(), ".xbrowser", "archives") });
+      configureArchiveStore({ archiveDir: join5(homedir5(), ".xbrowser", "archives") });
     } catch {
     }
     archiveInitialized = true;
@@ -6277,6 +6852,10 @@ async function guardCheck(commandName) {
 function errorResult(message) {
   return { ...fail7(message), duration: 0 };
 }
+function tipsToMessages(tips) {
+  if (!tips || tips.length === 0) return [];
+  return tips.map((t) => typeof t === "string" ? t : t.message);
+}
 var wsServer = null;
 function streamCommandEvent(sessionId, message) {
   if (!wsServer || !wsServer.getRunning()) return;
@@ -6304,7 +6883,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-GWBH6OJK.js");
+    const { findTargetPage } = await import("./browser-R56O3CW6.js");
     targetPageOverride = await findTargetPage(extraOpts.cdpEndpoint, _target);
     if (!targetPageOverride) {
       return errorResult(`Target "${_target}" not found. Use 'xbrowser targets --cdp ${extraOpts.cdpEndpoint}' to list available pages.`);
@@ -6321,7 +6900,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     params = result.data;
   }
   if (command.scope !== "cli" && !process.env.XBROWSER_DAEMON_WORKER) {
-    const { forwardExec } = await import("./daemon-client-XWSSQBEA.js");
+    const { forwardExec } = await import("./daemon-client-UZZEHHIV.js");
     const result = await forwardExec(commandName, params, sessionName, extraOpts?.cdpEndpoint);
     if (result) return result;
   }
@@ -6329,32 +6908,35 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   const existing = await findOrRestoreSession(sessionName, extraOpts?.cdpEndpoint);
   if (existing) {
     session = existing;
-    if (targetPageOverride && session.page) {
+    if (session.page) {
+      try {
+        await Promise.race([
+          session.page.evaluate(() => true),
+          new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 3e3))
+        ]);
+      } catch {
+        await closeSessionByName(session.name);
+        session = void 0;
+      }
+    }
+    if (session && targetPageOverride && session.page) {
       const currentUrl = session.page.url();
       if (currentUrl !== targetPageOverride.url) {
         await session.page.goto(targetPageOverride.url, { waitUntil: "domcontentloaded", timeout: 15e3 }).catch(() => {
         });
       }
     }
-  } else if ((command.scope === "page" || command.scope === "project") && params.url) {
+  } else if (command.scope !== "project") {
     session = await createSession(sessionName, params.url, {
       cdpEndpoint: extraOpts?.cdpEndpoint
     });
-  } else if (command.scope === "browser") {
-    session = await createSession(sessionName, void 0, {
-      cdpEndpoint: extraOpts?.cdpEndpoint
-    });
-  } else if (command.scope !== "project") {
-    return errorResult(
-      `Session '${sessionName}' not found. Run "xbrowser session open <url>" first.`
-    );
   }
   const ctx = {
     page: session?.page,
     browser: session?.context.browser(),
     browserContext: session?.context,
     sessionId: session?.id,
-    cdpEndpoint: extraOpts?.cdpEndpoint || session?.cdpEndpoint,
+    cdpEndpoint: session?.cdpEndpoint || extraOpts?.cdpEndpoint,
     args: [],
     options: {},
     cwd: process.cwd(),
@@ -6370,7 +6952,8 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     },
     config: {},
     site: {},
-    cliName: "xbrowser"
+    cliName: "xbrowser",
+    tips: new TipCollector()
   };
   const start = Date.now();
   if (session) {
@@ -6389,9 +6972,9 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   let refTips = [];
   if (session?.page && command.selectorParams && command.selectorParams.length > 0) {
     const cache = /* @__PURE__ */ new Map();
-    const resolved = await resolveRefParams(session.page, params, command.selectorParams, cache);
+    const resolved = await resolveRefParams(session.page, params, command.selectorParams, cache, session.id);
     if (resolved.tips.length > 0) {
-      refTips = resolved.tips;
+      refTips = normalizeTips6(resolved.tips);
       params = resolved.params;
     }
   }
@@ -6447,13 +7030,19 @@ async function executeCommand(commandName, params, sessionName = "default", extr
         snapshotHintShown.add(session);
         snapshotHint = "\u{1F4A1} \u4F7F\u7528 snapshot \u547D\u4EE4\u83B7\u53D6\u9875\u9762\u5FEB\u7167\u548C ref \u7F16\u53F7\uFF0C\u7136\u540E\u7528 ref \u5FEB\u901F\u5B9A\u4F4D\u5143\u7D20\uFF08\u5982 click --selector e1\uFF09";
       }
-      const merged = [...raw.tips || [], ...smartTips || [], ...snapshotHint ? [snapshotHint] : [], ...refTips];
+      const merged = [
+        ...raw.tips || [],
+        ...normalizeTips6(smartTips),
+        ...snapshotHint ? normalizeTips6([snapshotHint]) : [],
+        ...refTips
+      ];
       const isSuccess = raw.success !== false;
+      const mergedOrRaw = merged.length > 0 ? merged : raw.tips || [];
       recordArchive(session?.id, sessionName, {
         step: 0,
         command: commandName,
         params,
-        result: { success: isSuccess, data: raw.data, message: raw.message, tips: merged.length > 0 ? merged : raw.tips || [] },
+        result: { success: isSuccess, data: raw.data, message: raw.message, tips: tipsToMessages(mergedOrRaw) },
         toolCalls: [],
         duration,
         timestamp: start
@@ -6461,18 +7050,19 @@ async function executeCommand(commandName, params, sessionName = "default", extr
       if (isSuccess) {
         return { ...ok25(raw.data, merged.length > 0 ? merged : raw.tips), duration, ...hookOutputs ? { hookOutputs } : {} };
       }
-      return { success: false, data: raw.data, message: raw.message, tips: merged.length > 0 ? merged : raw.tips || [], duration, ...hookOutputs ? { hookOutputs } : {} };
+      return { success: false, data: raw.data, message: raw.message, tips: mergedOrRaw, duration, ...hookOutputs ? { hookOutputs } : {} };
     }
+    const smartTipNormalized = normalizeTips6(smartTips);
     recordArchive(session?.id, sessionName, {
       step: 0,
       command: commandName,
       params,
-      result: { success: true, data: raw, tips: smartTips || [] },
+      result: { success: true, data: raw, tips: tipsToMessages(smartTipNormalized) },
       toolCalls: [],
       duration,
       timestamp: start
     });
-    return { ...ok25(raw, smartTips), duration, ...hookOutputs ? { hookOutputs } : {} };
+    return { ...ok25(raw, smartTipNormalized), duration, ...hookOutputs ? { hookOutputs } : {} };
   } catch (err) {
     const end = Date.now();
     const duration = end - start;
@@ -6522,8 +7112,8 @@ async function executeChain(input, options) {
     });
   }
   try {
-    for (const pipeline2 of pipelines) {
-      const { type, pipeline: commands } = pipeline2;
+    for (const pipeline of pipelines) {
+      const { type, pipeline: commands } = pipeline;
       for (const cmdStr of commands) {
         const parts = splitCommand(cmdStr);
         if (parts.length === 0) continue;
@@ -6588,10 +7178,51 @@ async function executeChain(input, options) {
             },
             config: {},
             site,
-            cliName: "xbrowser"
+            cliName: "xbrowser",
+            tips: new TipCollector()
           };
           const start2 = Date.now();
           try {
+            const loginGuard = await checkPluginLoginRequired({
+              site,
+              command: cmdEntry,
+              commandName: subCommand,
+              ctx: pluginCtx,
+              page: session?.page,
+              sessionName
+            });
+            if (!loginGuard.ok) {
+              const duration3 = Date.now() - start2;
+              const data2 = loginGuard.data ?? null;
+              recordArchive(session.id, sessionName, {
+                step: results.length,
+                command: `${cmdName} ${subCommand}`,
+                params: pluginParams,
+                result: { success: false, data: data2, message: loginGuard.message, tips: loginGuard.tips || [] },
+                toolCalls: [],
+                duration: duration3,
+                timestamp: start2
+              });
+              results.push({
+                command: `${cmdName} ${subCommand}`,
+                raw: cmdStr,
+                success: false,
+                data: data2,
+                message: loginGuard.message,
+                tips: normalizeTips6(loginGuard.tips),
+                duration: duration3
+              });
+              if (type === "and") {
+                return {
+                  success: false,
+                  steps: results,
+                  totalDuration: Date.now() - totalStart,
+                  stoppedAt: results.length,
+                  stoppedReason: `Command '${cmdName} ${subCommand}' failed (&& chain): ${loginGuard.message}`
+                };
+              }
+              continue;
+            }
             const hooks = await loadHooks();
             if (hooks.length > 0) {
               await Promise.all(hooks.map((h) => h.onBeforeCommand?.({ page: session.page, command: `${cmdName} ${subCommand}`, params: pluginParams })));
@@ -6612,7 +7243,7 @@ async function executeChain(input, options) {
               step: results.length,
               command: `${cmdName} ${subCommand}`,
               params: pluginParams,
-              result: { success: true, data, tips: raw?.tips || [] },
+              result: { success: true, data, tips: tipsToMessages(raw?.tips) },
               toolCalls: [],
               duration: duration2,
               timestamp: start2
@@ -6663,7 +7294,7 @@ async function executeChain(input, options) {
           }
           continue;
         }
-        const { params } = parseCommandArgs(cmdName, cmdArgs);
+        const { params } = parseCommandArgs(cmdName, cmdArgs, unquote2);
         if (cmdName === "goto" && params.url) {
           const existing2 = await findOrRestoreSession(sessionName, options?.cdpEndpoint);
           if (!existing2) {
@@ -6724,15 +7355,6 @@ function isChainInput(input) {
 }
 
 // src/session/session-client.ts
-function sessionToInfo(s) {
-  return { id: s.id, name: s.name, url: s.page.url(), createdAt: s.createdAt, cdpEndpoint: s.cdpEndpoint };
-}
-async function openSession(name, url, options) {
-  const session = await createSession(name, url, { cdpEndpoint: options?.cdpEndpoint });
-  const info = sessionToInfo(session);
-  saveSessionDiskMeta(name, info);
-  return info;
-}
 async function closeSession(name) {
   await closeSessionByName(name);
 }
@@ -6746,53 +7368,22 @@ function handleSessionHelp() {
     "Usage: xbrowser session <command> [options]",
     "",
     "Commands:",
-    "  open <url> [--name <name>]  Open browser and create session",
     "  close [--name <name>]       Close session",
     "  list, ls                    List active sessions",
     "  kill [--name <name>]        Kill session forcefully",
+    "  kill-all                    Kill all sessions and daemon",
     "",
     "Options:",
     '  --name <name>  Session name (default: "default")',
     "",
+    "Note: Sessions are auto-created via --session global option.",
+    "",
     "Examples:",
-    "  xbrowser session open https://example.com",
-    "  xbrowser session open https://example.com --name mypage",
+    "  xbrowser goto https://example.com --session mypage",
     "  xbrowser session close --name mypage",
     "  xbrowser session list"
   ].join("\n");
 }
-var sessionOpenBuiltin = {
-  name: "session open",
-  description: "Open browser and create session",
-  help: {
-    usage: "xbrowser session open <url> [--name <name>]",
-    description: "Open URL and create a browser session",
-    options: [{ name: "--name <name>", description: 'Session name (default: "default")' }],
-    examples: [
-      { cmd: "xbrowser session open https://example.com", description: "Open example.com" },
-      {
-        cmd: "xbrowser session open https://example.com --name test",
-        description: "Open with custom name"
-      }
-    ]
-  },
-  execute: async (args, options) => {
-    const [url] = args;
-    const name = options["name"] || "default";
-    if (!url) {
-      console.log("Usage: xbrowser session open <url> [--name <name>]");
-      process.exit(1);
-    }
-    try {
-      const info = await openSession(name, url);
-      console.log(`Session "${info.name}" opened: ${info.url}`);
-      console.log(`ID: ${info.id}`);
-    } catch (e) {
-      console.error("Error:", e instanceof Error ? e.message : String(e));
-      process.exit(1);
-    }
-  }
-};
 var sessionCloseBuiltin = {
   name: "session close",
   description: "Close browser session",
@@ -6837,13 +7428,13 @@ var sessionListBuiltin = {
   },
   execute: async () => {
     try {
-      const sessions = await listSessions();
-      if (sessions.length === 0) {
+      const sessions2 = await listSessions();
+      if (sessions2.length === 0) {
         console.log("No active sessions");
         return;
       }
       console.log("Active sessions:");
-      for (const s of sessions) {
+      for (const s of sessions2) {
         console.log(`  ${s.name} (${s.id})`);
       }
     } catch (e) {
@@ -6874,22 +7465,17 @@ var sessionKillBuiltin = {
 };
 
 // src/config.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
-import { join as join4 } from "path";
-import { homedir as homedir4, tmpdir } from "os";
-function getConfigFile() {
-  return join4(homedir4() || tmpdir(), ".xbrowser", "config.json");
+import { homedir as homedir6, tmpdir } from "os";
+import { join as join6 } from "path";
+import { loadConfig as coreLoadConfig, saveConfig as coreSaveConfig } from "@dyyz1993/xcli-core";
+function getConfigSource() {
+  return { configDir: join6(homedir6() || tmpdir(), ".xbrowser") };
 }
 function loadConfig() {
-  const configFile = getConfigFile();
-  if (!existsSync6(configFile)) return {};
-  return readJsonFile(configFile, {});
+  return coreLoadConfig(getConfigSource());
 }
 function saveConfig(config) {
-  const dir = join4(homedir4() || tmpdir(), ".xbrowser");
-  const configFile = getConfigFile();
-  if (!existsSync6(dir)) mkdirSync3(dir, { recursive: true });
-  writeFileSync5(configFile, JSON.stringify(config, null, 2), "utf-8");
+  coreSaveConfig(getConfigSource(), config);
 }
 function getConfigValue(key) {
   return loadConfig()[key];
@@ -6997,38 +7583,69 @@ var configBuiltin = {
 
 // src/plugin/installer.ts
 import {
-  existsSync as existsSync13,
-  readdirSync as readdirSync3,
+  existsSync as existsSync10,
+  readdirSync as readdirSync2,
   mkdirSync as mkdirSync8,
-  rmSync as rmSync7
+  rmSync as rmSync6
 } from "fs";
-import { resolve as resolve15, basename as basename2 } from "path";
-import { homedir as homedir5 } from "os";
+import { resolve as resolve8, basename as basename2 } from "path";
+import { homedir as homedir7 } from "os";
 
 // src/plugin/install-sources/local.ts
-import { existsSync as existsSync8, cpSync as cpSync2, rmSync as rmSync2 } from "fs";
-import { resolve as resolve10 } from "path";
+import { existsSync as existsSync5, cpSync, rmSync } from "fs";
+import { resolve as resolve3 } from "path";
+import { verifyPlugin, safeCleanup } from "@dyyz1993/xcli-core";
+async function installFromLocal(source, name, targetDir) {
+  const srcPath = resolve3(source);
+  if (!existsSync5(srcPath)) {
+    throw new Error(`Local path does not exist: ${srcPath}`);
+  }
+  const tmpTarget = `${targetDir}-tmp-${Date.now()}`;
+  let warnings = [];
+  try {
+    cpSync(srcPath, tmpTarget, { recursive: true });
+    const verify = verifyPlugin(tmpTarget, { metadataField: "xbrowser" });
+    warnings = verify.warnings ?? [];
+    if (!verify.valid) {
+      safeCleanup(tmpTarget);
+      throw new Error(`Invalid plugin: ${verify.error}`);
+    }
+    if (existsSync5(targetDir)) {
+      rmSync(targetDir, { recursive: true, force: true });
+    }
+    cpSync(tmpTarget, targetDir, { recursive: true, force: true });
+    safeCleanup(tmpTarget);
+  } catch (err) {
+    safeCleanup(tmpTarget);
+    throw err;
+  }
+  return {
+    id: name,
+    name,
+    path: targetDir,
+    source: "local",
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    warnings
+  };
+}
 
-// src/plugin/install-utils.ts
+// src/plugin/install-sources/npm.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync6, rmSync as rmSync2, cpSync as cpSync2 } from "fs";
+import { resolve as resolve4, join as join7 } from "path";
+import { tmpdir as tmpdir2 } from "os";
 import {
-  existsSync as existsSync7,
-  readdirSync as readdirSync2,
-  cpSync,
-  rmSync,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync10,
-  createWriteStream
-} from "fs";
-import { resolve as resolve9 } from "path";
-import { execSync as execSync7 } from "child_process";
-import { pipeline } from "stream/promises";
-import { Readable } from "stream";
+  downloadToFile,
+  extractTarGz,
+  flattenPackageRoot,
+  verifyPlugin as verifyPlugin2,
+  safeCleanup as safeCleanup2
+} from "@dyyz1993/xcli-core";
 
 // src/utils/proxy-fetch.ts
-var patched = false;
+var patched2 = false;
 async function ensureProxyFetch() {
-  if (patched) return;
-  patched = true;
+  if (patched2) return;
+  patched2 = true;
   if (process.env.https_proxy && !process.env.HTTPS_PROXY) {
     process.env.HTTPS_PROXY = process.env.https_proxy;
   }
@@ -7068,113 +7685,7 @@ async function ensureProxyFetch() {
   }
 }
 
-// src/plugin/install-utils.ts
-async function downloadToFile(url, destPath) {
-  await ensureProxyFetch();
-  if (url.startsWith("file://")) {
-    const filePath = decodeURIComponent(new URL(url).pathname);
-    cpSync(filePath, destPath, { force: true });
-    return;
-  }
-  const res = await fetch(url);
-  if (!res.ok) {
-    throw new Error(`Download failed: HTTP ${res.status} from ${url}`);
-  }
-  if (!res.body) {
-    throw new Error(`No response body from ${url}`);
-  }
-  const nodeStream = Readable.fromWeb(res.body);
-  await pipeline(nodeStream, createWriteStream(destPath));
-}
-function extractTarGz(tarballPath, targetDir) {
-  mkdirSync4(targetDir, { recursive: true });
-  execSync7(`tar -xzf "${tarballPath}" -C "${targetDir}"`, { stdio: "pipe" });
-}
-function flattenPackageRoot(targetDir) {
-  const entries = readdirSync2(targetDir, { withFileTypes: true });
-  const dirs = entries.filter((e) => e.isDirectory());
-  const files = entries.filter((e) => !e.isDirectory());
-  if (dirs.length === 1 && files.length === 0) {
-    const pkgDir = resolve9(targetDir, dirs[0].name);
-    const items = readdirSync2(pkgDir);
-    for (const item of items) {
-      const src = resolve9(pkgDir, item);
-      const dst = resolve9(targetDir, item);
-      cpSync(src, dst, { recursive: true, force: true });
-    }
-    rmSync(pkgDir, { recursive: true, force: true });
-  }
-}
-async function verifyPlugin(dir) {
-  const warnings = [];
-  const indexPath = resolve9(dir, "index.ts");
-  if (!existsSync7(indexPath)) {
-    const indexJs = resolve9(dir, "index.js");
-    if (!existsSync7(indexJs)) {
-      return { valid: false, error: "No index.ts or index.js entry point found", warnings };
-    }
-  }
-  const pkgPath = resolve9(dir, "package.json");
-  if (!existsSync7(pkgPath)) {
-    warnings.push("No package.json found");
-  } else {
-    try {
-      const pkg2 = JSON.parse(readFileSync10(pkgPath, "utf-8"));
-      if (!pkg2.xbrowser) {
-        warnings.push("No xbrowser metadata in package.json");
-      }
-    } catch {
-      warnings.push("Invalid package.json");
-    }
-  }
-  return { valid: true, warnings };
-}
-function safeCleanup(dir) {
-  try {
-    rmSync(dir, { recursive: true, force: true });
-  } catch {
-  }
-}
-
-// src/plugin/install-sources/local.ts
-async function installFromLocal(source, name, targetDir) {
-  const srcPath = resolve10(source);
-  if (!existsSync8(srcPath)) {
-    throw new Error(`Local path does not exist: ${srcPath}`);
-  }
-  const tmpTarget = `${targetDir}-tmp-${Date.now()}`;
-  let warnings = [];
-  try {
-    cpSync2(srcPath, tmpTarget, { recursive: true });
-    const verify = await verifyPlugin(tmpTarget);
-    warnings = verify.warnings ?? [];
-    if (!verify.valid) {
-      safeCleanup(tmpTarget);
-      throw new Error(`Invalid plugin: ${verify.error}`);
-    }
-    if (existsSync8(targetDir)) {
-      rmSync2(targetDir, { recursive: true, force: true });
-    }
-    cpSync2(tmpTarget, targetDir, { recursive: true, force: true });
-    safeCleanup(tmpTarget);
-  } catch (err) {
-    safeCleanup(tmpTarget);
-    throw err;
-  }
-  return {
-    id: name,
-    name,
-    path: targetDir,
-    source: "local",
-    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    warnings
-  };
-}
-
 // src/plugin/install-sources/npm.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync6, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
-import { resolve as resolve11, join as join5 } from "path";
-import { tmpdir as tmpdir2 } from "os";
 async function installFromNpm(packageName, name, targetDir) {
   await ensureProxyFetch();
   const encodedName = encodeURIComponent(packageName);
@@ -7192,34 +7703,34 @@ async function installFromNpm(packageName, name, targetDir) {
     throw new Error(`No tarball URL for ${packageName}@${latestVersion}`);
   }
   const tarballUrl = versionMeta.dist.tarball;
-  const tmpDir = join5(tmpdir2(), `xbrowser-npm-${Date.now()}`);
+  const tmpDir = join7(tmpdir2(), `xbrowser-npm-${Date.now()}`);
   mkdirSync5(tmpDir, { recursive: true });
   let warnings = [];
   try {
-    const tarballPath = join5(tmpDir, `${name}.tgz`);
+    const tarballPath = join7(tmpDir, `${name}.tgz`);
     await downloadToFile(tarballUrl, tarballPath);
-    const extractDir = join5(tmpDir, "extracted");
+    const extractDir = join7(tmpDir, "extracted");
     extractTarGz(tarballPath, extractDir);
     flattenPackageRoot(extractDir);
-    const verify = await verifyPlugin(extractDir);
+    const verify = verifyPlugin2(extractDir, { metadataField: "xbrowser" });
     warnings = verify.warnings ?? [];
     if (!verify.valid) {
       throw new Error(`Invalid npm plugin: ${verify.error}`);
     }
-    if (existsSync9(targetDir)) {
-      rmSync3(targetDir, { recursive: true, force: true });
+    if (existsSync6(targetDir)) {
+      rmSync2(targetDir, { recursive: true, force: true });
     }
-    cpSync3(extractDir, targetDir, { recursive: true, force: true });
-    const pkgPath = resolve11(targetDir, "package.json");
-    if (existsSync9(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+    cpSync2(extractDir, targetDir, { recursive: true, force: true });
+    const pkgPath = resolve4(targetDir, "package.json");
+    if (existsSync6(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync4(pkgPath, "utf-8"));
       if (!pkg2._npmSource) {
         pkg2._npmSource = { name: packageName, version: latestVersion };
         writeFileSync6(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
-    safeCleanup(tmpDir);
+    safeCleanup2(tmpDir);
   }
   return {
     id: name,
@@ -7232,35 +7743,36 @@ async function installFromNpm(packageName, name, targetDir) {
 }
 
 // src/plugin/install-sources/git.ts
-import { existsSync as existsSync10, readFileSync as readFileSync12, writeFileSync as writeFileSync7, rmSync as rmSync4, cpSync as cpSync4 } from "fs";
-import { resolve as resolve12, join as join6 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync7, rmSync as rmSync3, cpSync as cpSync3 } from "fs";
+import { resolve as resolve5, join as join8 } from "path";
 import { tmpdir as tmpdir3 } from "os";
-import { execSync as execSync8 } from "child_process";
+import { execSync as execSync2 } from "child_process";
+import { verifyPlugin as verifyPlugin3, safeCleanup as safeCleanup3 } from "@dyyz1993/xcli-core";
 async function installFromGit(gitUrl, name, targetDir) {
-  const tmpDir = join6(tmpdir3(), `xbrowser-git-${Date.now()}`);
+  const tmpDir = join8(tmpdir3(), `xbrowser-git-${Date.now()}`);
   let warnings = [];
   try {
-    execSync8(`git clone --depth 1 "${gitUrl}" "${tmpDir}"`, { stdio: "pipe" });
-    const verify = await verifyPlugin(tmpDir);
+    execSync2(`git clone --depth 1 "${gitUrl}" "${tmpDir}"`, { stdio: "pipe" });
+    const verify = verifyPlugin3(tmpDir, { metadataField: "xbrowser" });
     warnings = verify.warnings ?? [];
     if (!verify.valid) {
       throw new Error(`Invalid git plugin: ${verify.error}`);
     }
-    if (existsSync10(targetDir)) {
-      rmSync4(targetDir, { recursive: true, force: true });
+    if (existsSync7(targetDir)) {
+      rmSync3(targetDir, { recursive: true, force: true });
     }
-    cpSync4(tmpDir, targetDir, { recursive: true, force: true });
-    rmSync4(resolve12(targetDir, ".git"), { recursive: true, force: true });
-    const pkgPath = resolve12(targetDir, "package.json");
-    if (existsSync10(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    cpSync3(tmpDir, targetDir, { recursive: true, force: true });
+    rmSync3(resolve5(targetDir, ".git"), { recursive: true, force: true });
+    const pkgPath = resolve5(targetDir, "package.json");
+    if (existsSync7(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync5(pkgPath, "utf-8"));
       if (!pkg2._gitSource) {
         pkg2._gitSource = { url: gitUrl };
         writeFileSync7(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
-    safeCleanup(tmpDir);
+    safeCleanup3(tmpDir);
   }
   return {
     id: name,
@@ -7273,39 +7785,46 @@ async function installFromGit(gitUrl, name, targetDir) {
 }
 
 // src/plugin/install-sources/url.ts
-import { existsSync as existsSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync8, mkdirSync as mkdirSync6, rmSync as rmSync5, cpSync as cpSync5 } from "fs";
-import { resolve as resolve13, join as join7, basename } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync8, rmSync as rmSync4, cpSync as cpSync4 } from "fs";
+import { resolve as resolve6, join as join9, basename } from "path";
 import { tmpdir as tmpdir4 } from "os";
+import {
+  downloadToFile as downloadToFile2,
+  extractTarGz as extractTarGz2,
+  flattenPackageRoot as flattenPackageRoot2,
+  verifyPlugin as verifyPlugin4,
+  safeCleanup as safeCleanup4
+} from "@dyyz1993/xcli-core";
 async function installFromUrl(url, name, targetDir) {
-  const tmpDir = join7(tmpdir4(), `xbrowser-url-${Date.now()}`);
+  const tmpDir = join9(tmpdir4(), `xbrowser-url-${Date.now()}`);
   mkdirSync6(tmpDir, { recursive: true });
   let warnings = [];
   try {
     const fileName = basename(new URL(url).pathname) || "plugin.tar.gz";
-    const tarballPath = join7(tmpDir, fileName);
-    await downloadToFile(url, tarballPath);
-    const extractDir = join7(tmpDir, "extracted");
-    extractTarGz(tarballPath, extractDir);
-    flattenPackageRoot(extractDir);
-    const verify = await verifyPlugin(extractDir);
+    const tarballPath = join9(tmpDir, fileName);
+    await downloadToFile2(url, tarballPath);
+    const extractDir = join9(tmpDir, "extracted");
+    extractTarGz2(tarballPath, extractDir);
+    flattenPackageRoot2(extractDir);
+    const verify = verifyPlugin4(extractDir, { metadataField: "xbrowser" });
     warnings = verify.warnings ?? [];
     if (!verify.valid) {
       throw new Error(`Invalid plugin from URL: ${verify.error}`);
     }
-    if (existsSync11(targetDir)) {
-      rmSync5(targetDir, { recursive: true, force: true });
+    if (existsSync8(targetDir)) {
+      rmSync4(targetDir, { recursive: true, force: true });
     }
-    cpSync5(extractDir, targetDir, { recursive: true, force: true });
-    const pkgPath = resolve13(targetDir, "package.json");
-    if (existsSync11(pkgPath)) {
-      const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+    cpSync4(extractDir, targetDir, { recursive: true, force: true });
+    const pkgPath = resolve6(targetDir, "package.json");
+    if (existsSync8(pkgPath)) {
+      const pkg2 = JSON.parse(readFileSync6(pkgPath, "utf-8"));
       if (!pkg2._urlSource) {
         pkg2._urlSource = { url };
         writeFileSync8(pkgPath, JSON.stringify(pkg2, null, 2));
       }
     }
   } finally {
-    safeCleanup(tmpDir);
+    safeCleanup4(tmpDir);
   }
   return {
     id: name,
@@ -7319,16 +7838,23 @@ async function installFromUrl(url, name, targetDir) {
 
 // src/plugin/install-sources/marketplace.ts
 import {
-  existsSync as existsSync12,
+  existsSync as existsSync9,
   mkdirSync as mkdirSync7,
   writeFileSync as writeFileSync9,
-  readFileSync as readFileSync14,
-  rmSync as rmSync6,
-  cpSync as cpSync6
+  readFileSync as readFileSync7,
+  rmSync as rmSync5,
+  cpSync as cpSync5
 } from "fs";
-import { resolve as resolve14, join as join8, dirname as dirname2 } from "path";
+import { resolve as resolve7, join as join10, dirname as dirname2 } from "path";
 import { tmpdir as tmpdir5 } from "os";
 import { gunzipSync } from "zlib";
+import {
+  downloadToFile as downloadToFile3,
+  extractTarGz as extractTarGz3,
+  flattenPackageRoot as flattenPackageRoot3,
+  verifyPlugin as verifyPlugin5,
+  safeCleanup as safeCleanup5
+} from "@dyyz1993/xcli-core";
 async function installFromMarketplace(pluginsDir, slug, options) {
   await ensureProxyFetch();
   const baseUrl = getMarketplaceUrl();
@@ -7343,24 +7869,24 @@ async function installFromMarketplace(pluginsDir, slug, options) {
   }
   const plugin = detailData.data;
   const name = options?.name || String(plugin.slug || slug);
-  const targetDir = resolve14(pluginsDir, name);
-  if (existsSync12(targetDir) && !options?.force) {
+  const targetDir = resolve7(pluginsDir, name);
+  if (existsSync9(targetDir) && !options?.force) {
     throw new Error(`Plugin "${name}" already exists. Use --force to overwrite.`);
   }
   mkdirSync7(targetDir, { recursive: true });
-  const tmpDir = join8(tmpdir5(), `xbrowser-marketplace-${Date.now()}`);
+  const tmpDir = join10(tmpdir5(), `xbrowser-marketplace-${Date.now()}`);
   mkdirSync7(tmpDir, { recursive: true });
   const realSlug = String(plugin.slug || slug);
   try {
     await downloadAndExtractMarketplaceTarball(baseUrl, realSlug, tmpDir, targetDir);
   } finally {
-    safeCleanup(tmpDir);
+    safeCleanup5(tmpDir);
   }
   writeMarketplacePackageJson(plugin, slug, name, baseUrl, targetDir);
   ensureIndexFile(plugin, name, targetDir);
-  const verify = await verifyPlugin(targetDir);
+  const verify = verifyPlugin5(targetDir, { metadataField: "xbrowser" });
   if (!verify.valid) {
-    safeCleanup(targetDir);
+    safeCleanup5(targetDir);
     throw new Error(`Invalid marketplace plugin: ${verify.error}`);
   }
   const trackUrl = `${baseUrl}/api/plugins/${realSlug}/install`;
@@ -7379,12 +7905,12 @@ function isManifestArray(data) {
   return Array.isArray(data) && data.length > 0 && typeof data[0].path === "string" && typeof data[0].content === "string";
 }
 function extractManifestToDir(manifest, targetDir) {
-  if (existsSync12(targetDir)) {
-    rmSync6(targetDir, { recursive: true, force: true });
+  if (existsSync9(targetDir)) {
+    rmSync5(targetDir, { recursive: true, force: true });
   }
   mkdirSync7(targetDir, { recursive: true });
   for (const file of manifest) {
-    const filePath = resolve14(targetDir, file.path);
+    const filePath = resolve7(targetDir, file.path);
     mkdirSync7(dirname2(filePath), { recursive: true });
     writeFileSync9(filePath, Buffer.from(file.content, "base64"));
   }
@@ -7411,21 +7937,21 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
   }
   if (tarballRes.status === 302 || tarballRes.headers.get("location")) {
     const redirectUrl = tarballRes.headers.get("location");
-    const tarballPath = join8(tmpDir, `${slug}.tar.gz`);
-    await downloadToFile(redirectUrl, tarballPath);
-    const buffer = readFileSync14(tarballPath);
+    const tarballPath = join10(tmpDir, `${slug}.tar.gz`);
+    await downloadToFile3(redirectUrl, tarballPath);
+    const buffer = readFileSync7(tarballPath);
     const manifest = tryParseAsGzippedManifest(buffer);
     if (manifest) {
       extractManifestToDir(manifest, targetDir);
       return;
     }
-    const extractDir = join8(tmpDir, "extracted");
-    extractTarGz(tarballPath, extractDir);
-    flattenPackageRoot(extractDir);
-    if (existsSync12(targetDir)) {
-      rmSync6(targetDir, { recursive: true, force: true });
+    const extractDir = join10(tmpDir, "extracted");
+    extractTarGz3(tarballPath, extractDir);
+    flattenPackageRoot3(extractDir);
+    if (existsSync9(targetDir)) {
+      rmSync5(targetDir, { recursive: true, force: true });
     }
-    cpSync6(extractDir, targetDir, { recursive: true, force: true });
+    cpSync5(extractDir, targetDir, { recursive: true, force: true });
   } else {
     const buffer = Buffer.from(await tarballRes.arrayBuffer());
     const manifest = tryParseAsGzippedManifest(buffer);
@@ -7433,16 +7959,16 @@ async function downloadAndExtractMarketplaceTarball(baseUrl, slug, tmpDir, targe
       extractManifestToDir(manifest, targetDir);
       return;
     }
-    const tarballPath = join8(tmpDir, `${slug}.tar.gz`);
+    const tarballPath = join10(tmpDir, `${slug}.tar.gz`);
     writeFileSync9(tarballPath, buffer);
     try {
-      const extractDir = join8(tmpDir, "extracted");
-      extractTarGz(tarballPath, extractDir);
-      flattenPackageRoot(extractDir);
-      if (existsSync12(targetDir)) {
-        rmSync6(targetDir, { recursive: true, force: true });
+      const extractDir = join10(tmpDir, "extracted");
+      extractTarGz3(tarballPath, extractDir);
+      flattenPackageRoot3(extractDir);
+      if (existsSync9(targetDir)) {
+        rmSync5(targetDir, { recursive: true, force: true });
       }
-      cpSync6(extractDir, targetDir, { recursive: true, force: true });
+      cpSync5(extractDir, targetDir, { recursive: true, force: true });
     } catch {
       throw new Error(
         `Downloaded tarball for "${slug}" is neither a gzipped JSON manifest nor a valid tar.gz archive.`
@@ -7474,12 +8000,12 @@ function writeMarketplacePackageJson(plugin, slug, name, baseUrl, targetDir) {
       url: baseUrl
     }
   };
-  const pkgPath = resolve14(targetDir, "package.json");
-  if (!existsSync12(pkgPath)) {
+  const pkgPath = resolve7(targetDir, "package.json");
+  if (!existsSync9(pkgPath)) {
     writeFileSync9(pkgPath, JSON.stringify(packageJson, null, 2));
   } else {
     try {
-      const existing = JSON.parse(readFileSync14(pkgPath, "utf-8"));
+      const existing = JSON.parse(readFileSync7(pkgPath, "utf-8"));
       const merged = {
         ...existing,
         xbrowser: { ...existing.xbrowser, ...packageJson.xbrowser },
@@ -7492,7 +8018,7 @@ function writeMarketplacePackageJson(plugin, slug, name, baseUrl, targetDir) {
   }
 }
 function ensureIndexFile(plugin, name, targetDir) {
-  if (!existsSync12(resolve14(targetDir, "index.ts")) && !existsSync12(resolve14(targetDir, "index.js"))) {
+  if (!existsSync9(resolve7(targetDir, "index.ts")) && !existsSync9(resolve7(targetDir, "index.js"))) {
     const commands = plugin.commands || [];
     const commandHandlers = commands.length > 0 ? commands.map((cmd) => {
       return [
@@ -7508,7 +8034,7 @@ function ensureIndexFile(plugin, name, targetDir) {
       `  });`
     ].join("\n");
     writeFileSync9(
-      resolve14(targetDir, "index.ts"),
+      resolve7(targetDir, "index.ts"),
       [
         `import type { XCLIAPI } from '@dyyz1993/xcli-core';`,
         ``,
@@ -7529,7 +8055,7 @@ function ensureIndexFile(plugin, name, targetDir) {
 var PluginInstaller = class {
   pluginsDir;
   constructor(pluginsDir) {
-    this.pluginsDir = pluginsDir || resolve15(homedir5(), ".xbrowser/plugins");
+    this.pluginsDir = pluginsDir || resolve8(homedir7(), ".xbrowser/plugins");
   }
   getPluginsDir() {
     return this.pluginsDir;
@@ -7545,8 +8071,8 @@ var PluginInstaller = class {
   async install(source, options) {
     const type = this.detectSourceType(source);
     const name = options?.name || this.deriveName(source, type);
-    const targetDir = resolve15(this.pluginsDir, name);
-    if (existsSync13(targetDir) && !options?.force) {
+    const targetDir = resolve8(this.pluginsDir, name);
+    if (existsSync10(targetDir) && !options?.force) {
       throw new Error(`Plugin "${name}" already exists. Use --force to overwrite.`);
     }
     mkdirSync8(targetDir, { recursive: true });
@@ -7606,11 +8132,11 @@ var PluginInstaller = class {
    * @throws If the plugin is not installed.
    */
   async uninstall(name) {
-    const targetDir = resolve15(this.pluginsDir, name);
-    if (!existsSync13(targetDir)) {
+    const targetDir = resolve8(this.pluginsDir, name);
+    if (!existsSync10(targetDir)) {
       throw new Error(`Plugin "${name}" not found`);
     }
-    rmSync7(targetDir, { recursive: true, force: true });
+    rmSync6(targetDir, { recursive: true, force: true });
   }
   /**
    * List all installed plugins with metadata.
@@ -7618,18 +8144,18 @@ var PluginInstaller = class {
    * @returns Array of installed plugin information.
    */
   async list(_options) {
-    if (!existsSync13(this.pluginsDir)) return [];
-    const entries = readdirSync3(this.pluginsDir, { withFileTypes: true });
+    if (!existsSync10(this.pluginsDir)) return [];
+    const entries = readdirSync2(this.pluginsDir, { withFileTypes: true });
     const plugins = [];
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const pluginPath = resolve15(this.pluginsDir, entry.name);
-      const indexPath = resolve15(pluginPath, "index.ts");
-      const indexJsPath = resolve15(pluginPath, "index.js");
-      if (!existsSync13(indexPath) && !existsSync13(indexJsPath)) continue;
+      const pluginPath = resolve8(this.pluginsDir, entry.name);
+      const indexPath = resolve8(pluginPath, "index.ts");
+      const indexJsPath = resolve8(pluginPath, "index.js");
+      if (!existsSync10(indexPath) && !existsSync10(indexJsPath)) continue;
       const metadata = PluginMetadataParser.parseFromPackageJson(pluginPath);
       let source = "local";
-      const pkg2 = readJsonFile(resolve15(pluginPath, "package.json"), {});
+      const pkg2 = readJsonFile(resolve8(pluginPath, "package.json"), {});
       if (pkg2._marketplace) source = "marketplace";
       else if (pkg2._npmSource) source = "npm";
       else if (pkg2._gitSource) source = "git";
@@ -7653,10 +8179,10 @@ var PluginInstaller = class {
     }
     if (source.startsWith("file://")) {
       const filePath = decodeURIComponent(new URL(source).pathname);
-      if (existsSync13(filePath)) return "url";
+      if (existsSync10(filePath)) return "url";
     }
     if (source.endsWith(".git") || source.includes("github.com/")) return "git";
-    if (existsSync13(resolve15(source))) return "local";
+    if (existsSync10(resolve8(source))) return "local";
     return "npm";
   }
   deriveName(source, type) {
@@ -7731,6 +8257,7 @@ function handlePluginHelp() {
     "  install <slug> --from-marketplace             Install from marketplace",
     "  uninstall <name>                              Uninstall a plugin",
     "  list [--json]                                 List installed plugins",
+    "  schema <name> [command] [--json]              Show plugin contract and command forms",
     "  reload <name>                                 Reload a plugin",
     "",
     "Examples:",
@@ -7739,6 +8266,7 @@ function handlePluginHelp() {
     "  xbrowser plugin install ./my-plugin",
     "  xbrowser plugin uninstall my-plugin",
     "  xbrowser plugin list",
+    "  xbrowser plugin schema my-plugin --json",
     "  xbrowser plugin reload my-plugin"
   ].join("\n");
 }
@@ -8488,7 +9016,7 @@ var previewBuiltin = {
       if (options.json) {
         outputResult({ running: false }, "json");
       } else {
-        console.log("Daemon is not running. Start with: xbrowser daemon start");
+        console.log("Daemon is not running. It will start automatically when needed.");
         console.log("");
         console.log("Preview is automatically available when the daemon is running.");
       }
@@ -8512,9 +9040,199 @@ var previewBuiltin = {
   }
 };
 
+// src/builtins/knowledge.ts
+init_site_knowledge();
+import { existsSync as existsSync12 } from "fs";
+var knowledgeBuiltin = {
+  name: "knowledge",
+  description: "View LLM-readable site knowledge base (selectors, forms, APIs)",
+  aliases: ["know"],
+  help: {
+    usage: "xbrowser knowledge <list|show|search|issue|path> [domain] [options]",
+    description: "Manage auto-generated site knowledge from recordings. Knowledge is stored at ~/.xbrowser/knowledge/{domain}.md and is designed for LLM consumption.",
+    options: [
+      { name: "list", description: "List all domains with knowledge bases" },
+      { name: "show <domain>", description: "Show full knowledge for a domain (markdown)" },
+      { name: "search <domain> <query>", description: "Search selectors/APIs by keyword" },
+      { name: "selectors <domain>", description: "List all selectors for a domain" },
+      { name: "api <domain>", description: "List all API endpoints for a domain" },
+      { name: "issue <domain> <text>", description: "Add a known issue to a domain" },
+      { name: "path <domain>", description: "Show file path for a domain's knowledge" }
+    ],
+    examples: [
+      { cmd: "xbrowser knowledge list", description: "List all known sites" },
+      { cmd: "xbrowser knowledge show juejin.cn", description: "Show juejin.cn knowledge" },
+      { cmd: "xbrowser knowledge search juejin.cn publish", description: 'Find selectors related to "publish"' },
+      { cmd: "xbrowser knowledge selectors juejin.cn", description: "List all selectors" },
+      { cmd: "xbrowser knowledge api juejin.cn", description: "List API endpoints" },
+      { cmd: 'xbrowser knowledge issue juejin.cn "Title selector changed"', description: "Report an issue" }
+    ]
+  },
+  execute: async (args, _options, _ctx) => {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "list") {
+      const domains = listSiteKnowledge();
+      if (domains.length === 0) {
+        console.log("No site knowledge bases found.");
+        console.log("Knowledge is auto-generated when you run `xbrowser record stop`.");
+        return;
+      }
+      console.log("Site Knowledge Bases:");
+      console.log("");
+      for (const domain of domains) {
+        const kb = readSiteKnowledge(domain);
+        if (kb) {
+          const pageCount = Object.keys(kb.pages).length;
+          const selCount = Object.values(kb.pages).reduce((sum, p) => sum + p.selectors.length, 0);
+          const apiCount = Object.keys(kb.apiEndpoints).length;
+          console.log(
+            `  ${domain} \u2014 ${kb.recordingCount} recordings, ${pageCount} pages, ${selCount} selectors, ${apiCount} APIs`
+          );
+        }
+      }
+      return;
+    }
+    if (subcommand === "show") {
+      const domain = rest[0];
+      if (!domain) {
+        console.error("Usage: xbrowser knowledge show <domain>");
+        process.exit(1);
+      }
+      const md = readSiteKnowledgeMarkdown(domain);
+      if (!md) {
+        console.error(`No knowledge base found for ${domain}`);
+        console.error("Run `xbrowser knowledge list` to see available domains.");
+        process.exit(1);
+      }
+      console.log(md);
+      return;
+    }
+    if (subcommand === "selectors") {
+      const domain = rest[0];
+      if (!domain) {
+        console.error("Usage: xbrowser knowledge selectors <domain>");
+        process.exit(1);
+      }
+      const kb = readSiteKnowledge(domain);
+      if (!kb) {
+        console.error(`No knowledge base found for ${domain}`);
+        process.exit(1);
+      }
+      console.log(`Selectors for ${domain} (${kb.recordingCount} recordings):`);
+      console.log("");
+      for (const [pagePath, page] of Object.entries(kb.pages)) {
+        if (page.selectors.length === 0) continue;
+        console.log(`  ${pagePath}:`);
+        for (const sel of page.selectors) {
+          const status = sel.status === "deprecated" ? " \u26A0\uFE0F" : "";
+          console.log(
+            `    ${sel.selector.padEnd(30)} ${sel.tag.padEnd(8)} ${sel.actionType.padEnd(10)} ${sel.confidence.padEnd(6)} ${sel.timesSeen}x${status}`
+          );
+          if (sel.description) console.log(`      \u2192 ${sel.description}`);
+        }
+        console.log("");
+      }
+      return;
+    }
+    if (subcommand === "api") {
+      const domain = rest[0];
+      if (!domain) {
+        console.error("Usage: xbrowser knowledge api <domain>");
+        process.exit(1);
+      }
+      const kb = readSiteKnowledge(domain);
+      if (!kb) {
+        console.error(`No knowledge base found for ${domain}`);
+        process.exit(1);
+      }
+      const endpoints = Object.values(kb.apiEndpoints);
+      if (endpoints.length === 0) {
+        console.log(`No API endpoints recorded for ${domain}`);
+        return;
+      }
+      console.log(`API Endpoints for ${domain}:`);
+      console.log("");
+      for (const ep of endpoints.sort((a, b) => b.timesSeen - a.timesSeen)) {
+        const params = ep.params.length > 0 ? ep.params.join(", ") : "-";
+        console.log(`  ${ep.method} ${ep.path}  (${ep.timesSeen}x)`);
+        console.log(`    Params: ${params}`);
+        if (ep.responseFields.length > 0) {
+          console.log(`    Response: ${ep.responseFields.slice(0, 5).join(", ")}`);
+        }
+        console.log("");
+      }
+      return;
+    }
+    if (subcommand === "search") {
+      const domain = rest[0];
+      const query = rest.slice(1).join(" ").toLowerCase();
+      if (!domain || !query) {
+        console.error("Usage: xbrowser knowledge search <domain> <query>");
+        process.exit(1);
+      }
+      const kb = readSiteKnowledge(domain);
+      if (!kb) {
+        console.error(`No knowledge base found for ${domain}`);
+        process.exit(1);
+      }
+      console.log(`Search results for "${query}" in ${domain}:`);
+      console.log("");
+      let found = 0;
+      for (const [pagePath, page] of Object.entries(kb.pages)) {
+        const matches = page.selectors.filter(
+          (s) => s.selector.toLowerCase().includes(query) || s.description.toLowerCase().includes(query) || (s.text || "").toLowerCase().includes(query)
+        );
+        for (const m of matches) {
+          console.log(`  [${pagePath}] ${m.selector} \u2192 ${m.description} (${m.actionType}, ${m.confidence}, ${m.timesSeen}x)`);
+          found++;
+        }
+      }
+      for (const ep of Object.values(kb.apiEndpoints)) {
+        if (ep.path.toLowerCase().includes(query) || ep.params.some((p) => p.toLowerCase().includes(query))) {
+          console.log(`  [API] ${ep.method} ${ep.path} (${ep.timesSeen}x)`);
+          found++;
+        }
+      }
+      if (found === 0) {
+        console.log("  No matches found.");
+      }
+      return;
+    }
+    if (subcommand === "issue") {
+      const domain = rest[0];
+      const text = rest.slice(1).join(" ");
+      if (!domain || !text) {
+        console.error("Usage: xbrowser knowledge issue <domain> <description>");
+        process.exit(1);
+      }
+      if (!readSiteKnowledge(domain)) {
+        console.error(`No knowledge base found for ${domain}`);
+        process.exit(1);
+      }
+      addKnownIssue(domain, text);
+      console.log(`Added issue to ${domain}: ${text}`);
+      return;
+    }
+    if (subcommand === "path") {
+      const domain = rest[0];
+      if (!domain) {
+        console.error("Usage: xbrowser knowledge path <domain>");
+        process.exit(1);
+      }
+      const mdPath = getKnowledgePath(domain, "md");
+      const jsonPath = getKnowledgePath(domain, "json");
+      console.log(`Markdown: ${mdPath} (${existsSync12(mdPath) ? "exists" : "not found"})`);
+      console.log(`JSON:     ${jsonPath} (${existsSync12(jsonPath) ? "exists" : "not found"})`);
+      return;
+    }
+    console.error(`Unknown subcommand: ${subcommand}`);
+    console.error("Usage: xbrowser knowledge <list|show|selectors|api|search|issue|path>");
+    process.exit(1);
+  }
+};
+
 // src/builtins/index.ts
 var allBuiltins = [
-  sessionOpenBuiltin,
   sessionCloseBuiltin,
   sessionListBuiltin,
   sessionKillBuiltin,
@@ -8525,7 +9243,8 @@ var allBuiltins = [
   pluginListBuiltin,
   pluginReloadBuiltin,
   createBuiltin,
-  previewBuiltin
+  previewBuiltin,
+  knowledgeBuiltin
 ];
 
 // src/utils/selector.ts
@@ -8748,7 +9467,8 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
   } else {
     switch (command) {
       case "goto":
-        if (!args[0]) outputError(`Usage: xbrowser goto <url>`);
+      case "open":
+        if (!args[0]) outputError(`Usage: xbrowser ${command} <url>`);
         cmdName = "goto";
         params = {
           url: /^https?:\/\//i.test(args[0]) || /^wss?:\/\//i.test(args[0]) ? args[0] : "https://" + args[0],
@@ -8760,7 +9480,9 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
         params = {
           fullPage: !!(options["full-page"] || options.fullPage),
           type: options.type,
-          selector: options.selector || options.s
+          selector: options.selector || options.s,
+          base64: !!options.base64,
+          output: options.output || options.o
         };
         break;
       case "eval":
@@ -8796,6 +9518,25 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
         cmdName = "text";
         params = { selector: options.selector || options.s };
         break;
+      case "find": {
+        if (!args[0] || !args[1]) {
+          outputError("Usage: xbrowser find <text|role|label|placeholder|testid|alt|title|first|last|nth> <value> [action] [--name <name>]");
+        }
+        const strategy = args[0];
+        const value = args[1];
+        const operation = args.slice(2).join(" ") || void 0;
+        cmdName = "find";
+        params = {
+          strategy,
+          value,
+          ...operation ? { operation } : {},
+          name: options.name,
+          exact: !!options.exact,
+          timeout: options.timeout ? Number(options.timeout) : void 0,
+          index: options.index ? Number(options.index) : void 0
+        };
+        break;
+      }
       case "back":
         cmdName = "back";
         params = {};
@@ -8818,7 +9559,7 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
         let parsedActions;
         if (options.action) {
           const actionList = Array.isArray(options.action) ? options.action : [options.action];
-          const { parseActionDsl } = await import("./parse-action-dsl-DRSPBALP.js");
+          const { parseActionDsl } = await import("./parse-action-dsl-UM333TL2.js");
           parsedActions = actionList.map((a) => parseActionDsl(a));
         } else if (options["actions-file"]) {
           const fs3 = await import("fs");
@@ -8946,36 +9687,27 @@ async function handleBrowserCommand(command, args, options, sessionName, mode, c
 }
 
 // src/cli/session-routes.ts
-import { homedir as homedir6 } from "os";
-import { join as join10 } from "path";
-import { readdirSync as readdirSync4, rmSync as rmSync8 } from "fs";
+import { homedir as homedir8 } from "os";
+import { join as join12 } from "path";
+import { readdirSync as readdirSync3, rmSync as rmSync7 } from "fs";
 function cleanSessionFiles() {
-  const dir = join10(homedir6(), ".xbrowser", "sessions");
+  const dir = join12(homedir8(), ".xbrowser", "sessions");
   let count = 0;
   try {
-    for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-      const p = join10(dir, entry.name);
-      rmSync8(p, { recursive: true, force: true });
+    for (const entry of readdirSync3(dir, { withFileTypes: true })) {
+      const p = join12(dir, entry.name);
+      rmSync7(p, { recursive: true, force: true });
       count++;
     }
   } catch {
   }
   return count;
 }
-async function handleSession(args, options, mode, cdpEndpoint) {
+async function handleSession(args, options, mode, _cdpEndpoint) {
   const sub = args[0];
   switch (sub) {
-    case "open": {
-      const url = args[1];
-      const name = options.name || process.env.XBROWSER_SESSION || "default";
-      if (!url)
-        outputError("Usage: xbrowser session open <url> [--name <name>] [--cdp <endpoint>]");
-      const info = await forwardSessionCreate(name, url, cdpEndpoint);
-      outputResult({ ok: true, ...info }, mode);
-      break;
-    }
     case "close": {
-      const name = options.name || process.env.XBROWSER_SESSION || "default";
+      const name = options.session || options.name || process.env.XBROWSER_SESSION || "default";
       try {
         await forwardSessionClose(name);
       } catch {
@@ -8987,16 +9719,16 @@ async function handleSession(args, options, mode, cdpEndpoint) {
     case "list":
     case "ls": {
       try {
-        const sessions = await forwardSessionList();
-        outputResult({ sessions }, mode);
+        const sessions2 = await forwardSessionList();
+        outputResult({ sessions: sessions2 }, mode);
       } catch {
-        const sessions = await listSessions();
-        outputResult({ sessions }, mode);
+        const sessions2 = await listSessions();
+        outputResult({ sessions: sessions2 }, mode);
       }
       break;
     }
     case "kill": {
-      const name = options.name || process.env.XBROWSER_SESSION || "default";
+      const name = options.session || options.name || process.env.XBROWSER_SESSION || "default";
       try {
         await forwardSessionClose(name);
       } catch {
@@ -9011,8 +9743,8 @@ async function handleSession(args, options, mode, cdpEndpoint) {
     }
     case "kill-all": {
       try {
-        const sessions = await forwardSessionList();
-        for (const s of sessions) {
+        const sessions2 = await forwardSessionList();
+        for (const s of sessions2) {
           try {
             await forwardSessionClose(s.name);
           } catch {
@@ -9039,15 +9771,28 @@ function getPluginLoader2() {
   if (!pluginLoader3) pluginLoader3 = new XBrowserPluginLoader();
   return pluginLoader3;
 }
-async function buildRuntimeCommandsMap() {
+async function buildRuntimePluginInfo() {
   const loader = await getPluginLoader();
   const sites = loader.getCore().loader.getSites();
   const map = /* @__PURE__ */ new Map();
   for (const site of sites) {
-    const cmds = site.getAllCommands().map((c) => c.name);
-    if (cmds.length > 0) {
-      map.set(site.name, cmds);
+    const cmds = site.getAllCommands();
+    const commandNames = cmds.map((c) => c.name);
+    if (commandNames.length === 0) continue;
+    const anySite = site;
+    const hasLoginHandler = typeof anySite.hasLoginCommand === "function" && anySite.hasLoginCommand();
+    const configRequiresLogin = !!site.config.requiresLogin;
+    const hasLogin = hasLoginHandler || configRequiresLogin;
+    let loggedIn = null;
+    if (hasLogin) {
+      try {
+        loggedIn = await site.isLoggedIn();
+      } catch {
+        loggedIn = null;
+      }
     }
+    const requiresLoginCommands = cmds.filter((c) => c.requiresLogin === true).map((c) => c.name);
+    map.set(site.name, { commands: commandNames, hasLogin, loggedIn, requiresLoginCommands });
   }
   return map;
 }
@@ -9211,6 +9956,54 @@ async function handlePluginInfo(args, options, mode) {
     console.error("\u67E5\u8BE2\u5931\u8D25:", err.message);
   }
 }
+async function handlePluginSchema(args, mode) {
+  const pluginName = args[0];
+  const commandName = args[1];
+  if (!pluginName) outputError("Usage: xbrowser plugin schema <name> [command] [--json]");
+  const loader = await getPluginLoader();
+  const contract = loader.getPluginContract(pluginName, commandName);
+  if (!contract) {
+    outputError(commandName ? `Command "${commandName}" not found in plugin "${pluginName}"` : `Plugin "${pluginName}" not found`);
+    return;
+  }
+  if (mode === "json") {
+    outputResult(contract, mode);
+    return;
+  }
+  if ("commands" in contract) {
+    printPluginContract(contract);
+  } else {
+    printCommandContract(pluginName, contract);
+  }
+}
+function printPluginContract(contract) {
+  console.log(`${contract.plugin.name} contract v${contract.version}`);
+  if (contract.plugin.description) console.log(contract.plugin.description);
+  console.log("");
+  for (const command of contract.commands) {
+    printCommandContract(contract.plugin.name, command);
+  }
+}
+function printCommandContract(pluginName, command) {
+  console.log(`${pluginName} ${command.name}`);
+  if (command.description) console.log(`  ${command.description}`);
+  console.log(`  scope: ${command.scope}`);
+  if (command.capabilities.length > 0) {
+    console.log(`  capabilities: ${command.capabilities.join(", ")}`);
+  }
+  if (command.positional.length > 0) {
+    console.log(`  positional: ${command.positional.join(", ")}`);
+  }
+  if (command.form.fields.length > 0) {
+    console.log("  fields:");
+    for (const field of command.form.fields) {
+      const required = field.required ? "required" : "optional";
+      const choices = field.enum ? ` [${field.enum.join("|")}]` : "";
+      console.log(`    --${field.name}: ${field.type}/${field.widget} ${required}${choices}`);
+    }
+  }
+  console.log("");
+}
 async function handlePlugin(args, options, mode) {
   const sub = args[0];
   const subArgs = args.slice(1);
@@ -9251,17 +10044,20 @@ async function handlePlugin(args, options, mode) {
     }
     case "list": {
       const plugins = await installer.list();
-      const runtimeCommands = await buildRuntimeCommandsMap();
+      const runtimeInfo = await buildRuntimePluginInfo();
       const enrichedPlugins = plugins.map((p) => {
         const metadata = p.metadata;
         const staticCommands = metadata?.commands;
-        const dynamicCommands = runtimeCommands.get(p.name);
-        const commands = dynamicCommands || staticCommands;
+        const rt = runtimeInfo.get(p.name);
+        const commands = rt?.commands || staticCommands;
         return {
           ...p,
           commands,
           version: metadata?.version,
-          description: metadata?.description
+          description: metadata?.description,
+          hasLogin: rt?.hasLogin ?? false,
+          loggedIn: rt?.loggedIn ?? null,
+          requiresLoginCommands: rt?.requiresLoginCommands ?? []
         };
       });
       if (mode === "json") {
@@ -9272,20 +10068,27 @@ async function handlePlugin(args, options, mode) {
           return;
         }
         for (const p of enrichedPlugins) {
+          const loginTag = p.hasLogin ? p.loggedIn ? " [logged in]" : " [need login]" : "";
           if (p.version && p.description) {
-            console.log(`${p.name} (${p.version}) - ${p.description}`);
+            console.log(`${p.name} (${p.version}) - ${p.description}${loginTag}`);
           } else {
-            console.log(p.name);
+            console.log(`${p.name}${loginTag}`);
           }
           if (p.commands && p.commands.length > 0) {
             console.log(`  ${p.commands.join(", ")}`);
           }
+          if (p.requiresLoginCommands.length > 0) {
+            console.log(`  requires login: ${p.requiresLoginCommands.join(", ")}`);
+          }
         }
         console.log(`
 Total: ${enrichedPlugins.length} plugins`);
       }
       break;
     }
+    case "schema":
+      await handlePluginSchema(subArgs, mode);
+      break;
     case "reload": {
       const name = subArgs[0];
       if (!name) outputError("Usage: xbrowser plugin reload <name>");
@@ -9343,7 +10146,7 @@ function handleDaemon(args, options, mode) {
       break;
     }
     default:
-      console.log("Usage: xbrowser daemon <start|stop|status> [--port <port>]");
+      console.log("Daemon starts automatically. No manual action needed.");
   }
 }
 
@@ -9354,7 +10157,8 @@ async function handleRecord(args, options, mode) {
     case "start": {
       const url = options.url;
       const sessionName = options.session || "default";
-      const result = await forwardRecordStart(sessionName, url);
+      const cdpEndpoint = options.cdp;
+      const result = await forwardRecordStart(sessionName, url, cdpEndpoint);
       if (!result.ok) {
         outputError(String(result.error || "Failed to start recording"));
         return;
@@ -9438,6 +10242,13 @@ async function handleRecord(args, options, mode) {
       outputResult(result, mode);
       break;
     }
+    case "generate-plugin": {
+      const sessionName = options.session || args[1] || "default";
+      const pluginName = options.name || "";
+      const outputDir = options.output || "";
+      await handleGeneratePlugin(sessionName, pluginName, outputDir);
+      break;
+    }
     default:
       console.log("Usage:");
       console.log("  xbrowser record start [--url <url>] [--session <name>]");
@@ -9445,6 +10256,7 @@ async function handleRecord(args, options, mode) {
       console.log("  xbrowser record status [--session <name>]");
       console.log("  xbrowser record summary [--session <name>] [--json]");
       console.log('  xbrowser record checkpoint --type <type> --hint "description" [--selector <sel>] [--session <name>]');
+      console.log("  xbrowser record generate-plugin [--session <name>] [--name <plugin>] [--output <dir>]");
       console.log("");
       console.log("Checkpoint types: dialog, captcha, login, iframe, slider, custom");
   }
@@ -9633,7 +10445,7 @@ async function handleConvert(args, _mode) {
   const fs3 = await import("fs");
   const path3 = await import("path");
   const { default: yaml } = await import("yaml");
-  const { generateJSScript, generatePythonScript, generateBashScript } = await import("./convert-4DUWZIKH.js");
+  const { generateJSScript, generatePythonScript, generateBashScript } = await import("./convert-LB3GJTLR.js");
   const content = fs3.readFileSync(filePath, "utf-8");
   const recording = yaml.parse(content);
   const ext = path3.extname(outputPath).toLowerCase();
@@ -9658,7 +10470,7 @@ async function handleExtract(args, _mode) {
     console.error("Usage: xbrowser extract <recording.yaml>");
     process.exit(1);
   }
-  const { extractAndSave, printExtractSummary } = await import("./extract-EGRXZSSK.js");
+  const { extractAndSave, printExtractSummary } = await import("./extract-BSYBM4MR.js");
   const { summary, outputPath } = extractAndSave(filePath);
   printExtractSummary(summary);
   console.log(`
@@ -9671,33 +10483,196 @@ async function handleFilter(args, _mode) {
     console.error("Usage: xbrowser filter <input.yaml> <output.yaml> [--exclude-types=type1,type2]");
     process.exit(1);
   }
-  const { filterRecording, parseExcludeTypes } = await import("./filter-OLAE26HN.js");
+  const { filterRecording, parseExcludeTypes } = await import("./filter-KCFO4RSV.js");
   const excludeTypes = parseExcludeTypes(args.slice(2));
   const result = filterRecording(filePath, outputPath, excludeTypes);
   console.log(`Filtered ${filePath} -> ${outputPath}`);
   console.log(`  Original: ${result.originalCount}, After: ${result.filteredCount}, Removed: ${result.removed} (${result.percentage}%)`);
 }
-
-// src/stdin.ts
-import { createInterface } from "readline";
-import { readFileSync as readFileSync15 } from "fs";
-async function readStdin2() {
-  if (process.stdin.isTTY) return [];
-  const lines = [];
-  const rl = createInterface({ input: process.stdin });
-  for await (const line of rl) {
-    const trimmed = line.trim();
-    if (trimmed && !trimmed.startsWith("#")) {
-      lines.push(trimmed);
+async function handleGeneratePlugin(sessionName, pluginName, outputDir) {
+  const { SessionRecorder: SessionRecorder2 } = await import("./session-recorder-RTDGURIJ.js");
+  const { readSiteKnowledge: readSiteKnowledge2, toMarkdown } = await import("./site-knowledge-SYC6VCDB.js");
+  const { mkdirSync: mkdirSync10, writeFileSync: writeFileSync11 } = await import("fs");
+  const { join: join13 } = await import("path");
+  const data = SessionRecorder2.readData(sessionName);
+  if (!data) {
+    outputError(`No recording found for session "${sessionName}". Run \`xbrowser record stop --session ${sessionName}\` first.`);
+    return;
+  }
+  let domain = "unknown";
+  try {
+    domain = new URL(data.startUrl).hostname.replace(/^www\./, "");
+  } catch {
+  }
+  const finalPluginName = pluginName || domain.split(".")[0] || "my-site";
+  const finalOutputDir = outputDir || join13(process.cwd(), ".xcli", "plugins", finalPluginName);
+  const knowledge = readSiteKnowledge2(domain);
+  const knowledgeMd = knowledge ? toMarkdown(knowledge) : "";
+  const pluginCode = generatePluginCode(finalPluginName, domain, data, knowledgeMd);
+  mkdirSync10(join13(finalOutputDir), { recursive: true });
+  writeFileSync11(join13(finalOutputDir, "index.ts"), pluginCode, "utf-8");
+  if (knowledgeMd) {
+    writeFileSync11(join13(finalOutputDir, "SITE_KNOWLEDGE.md"), knowledgeMd, "utf-8");
+  }
+  console.log("");
+  console.log("=== Plugin Generated ===");
+  console.log(`  Plugin:     ${finalPluginName}`);
+  console.log(`  Domain:     ${domain}`);
+  console.log(`  Output:     ${finalOutputDir}/index.ts`);
+  if (knowledgeMd) {
+    console.log(`  Knowledge:  ${finalOutputDir}/SITE_KNOWLEDGE.md`);
+  }
+  console.log(`  Actions:    ${data.actions.length}`);
+  console.log(`  APIs:       ${data.network.filter((n) => n.contentType.includes("json") || n.url.includes("/api/")).length}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  1. Review and edit:  ${finalOutputDir}/index.ts`);
+  console.log(`  2. Test:             xbrowser ${finalPluginName} <command>`);
+  console.log(`  3. Reference:        ${finalOutputDir}/SITE_KNOWLEDGE.md (for LLM)`);
+}
+function generatePluginCode(pluginName, domain, data, _knowledgeMd) {
+  const pagePaths = /* @__PURE__ */ new Set();
+  for (const action of data.actions) {
+    if (action.url) {
+      try {
+        pagePaths.add(new URL(action.url).pathname);
+      } catch {
+      }
+    }
+  }
+  const clickSelectors = [];
+  const inputSelectors = [];
+  for (const action of data.actions) {
+    const el = action.element;
+    if (!el) continue;
+    const sel = el.selector;
+    if (!sel) continue;
+    if (action.type === "click" && !clickSelectors.includes(sel)) {
+      clickSelectors.push(sel);
     }
+    if (action.type === "input" && !inputSelectors.some((s) => s.selector === sel)) {
+      inputSelectors.push({ selector: sel, placeholder: el.placeholder });
+    }
+  }
+  const apis = data.network.filter(
+    (n) => (n.contentType || "").includes("json") || n.url.includes("/api/")
+  );
+  const commands = [];
+  commands.push(`  site.command({
+    name: 'open',
+    description: 'Open ${domain}',
+    scope: 'browser',
+    handler: async (_p: Record<string, unknown>, ctx: CommandContext) => {
+      const page = ensurePage(ctx);
+      await page.goto('${data.startUrl}', { waitUntil: 'domcontentloaded' });
+      return ok({ url: page.url() });
+    },
+  });`);
+  if (inputSelectors.length > 0) {
+    const params = inputSelectors.slice(0, 5).map(
+      (s, i) => `    ${s.selector.replace(/[^a-zA-Z0-9]/g, "_").replace(/^_+/, "").toLowerCase() || `field${i}`}: z.string().describe('${s.placeholder || s.selector}'),`
+    ).join("\n");
+    const fills = inputSelectors.slice(0, 5).map(
+      (s) => `    await page.fill('${s.selector}', p.${s.selector.replace(/[^a-zA-Z0-9]/g, "_").replace(/^_+/, "").toLowerCase() || "field0"}');`
+    ).join("\n");
+    commands.push(`  site.command({
+    name: 'fill',
+    description: 'Fill form on ${domain}',
+    scope: 'page',
+    parameters: z.object({
+${params}
+    }),
+    handler: async (p: Record<string, unknown>, ctx: CommandContext) => {
+      const page = ensurePage(ctx);
+${fills}
+      return ok({ filled: true });
+    },
+  });`);
+  }
+  if (clickSelectors.length > 0) {
+    commands.push(`  site.command({
+    name: 'click',
+    description: 'Click element on ${domain}',
+    scope: 'page',
+    parameters: z.object({
+      selector: z.string().describe('CSS selector of element to click'),
+    }),
+    handler: async (p: Record<string, unknown>, ctx: CommandContext) => {
+      const page = ensurePage(ctx);
+      await page.click(p.selector as string);
+      return ok({ clicked: p.selector });
+    },
+  });`);
+  }
+  if (apis.length > 0) {
+    commands.push(`  site.command({
+    name: 'scrape',
+    description: 'Scrape data from ${domain}',
+    scope: 'page',
+    handler: async (_p: Record<string, unknown>, ctx: CommandContext) => {
+      const page = ensurePage(ctx);
+      const data = await page.evaluate(() => {
+        return {
+          title: document.title,
+          url: location.href,
+          content: document.body?.innerText?.substring(0, 5000) || '',
+        };
+      });
+      return ok(data);
+    },
+  });`);
   }
-  return lines;
+  return `/**
+ * ${pluginName} \u2014 Auto-generated plugin for ${domain}
+ *
+ * Generated from xbrowser recording session.
+ * Review and customize before using in production.
+ *
+ * Site Knowledge: See SITE_KNOWLEDGE.md for LLM-readable selector/API reference.
+ */
+
+import { z } from 'zod';
+import { ok } from '@dyyz1993/xcli-core';
+import { createSite, type CommandContext } from '@dyyz1993/xcli-core';
+
+interface XBPage {
+  url(): string;
+  goto(url: string, opts?: Record<string, unknown>): Promise<unknown>;
+  click(selector: string, opts?: Record<string, unknown>): Promise<unknown>;
+  fill(selector: string, value: string, opts?: Record<string, unknown>): Promise<unknown>;
+  evaluate<T>(fn: string | (() => T)): Promise<T>;
+}
+
+function ensurePage(ctx: CommandContext): XBPage {
+  const page = (ctx as Record<string, unknown>).page;
+  if (!page) throw new Error('No active page. Start a session first.');
+  return page as unknown as XBPage;
 }
-function readCommandFile(filePath) {
-  const content = readFileSync15(filePath, "utf-8");
-  return content.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+
+export default createSite({
+  name: '${pluginName}',
+  domain: '${domain}',
+  description: 'Auto-generated plugin for ${domain} from recording',
+
+  login: {
+    url: '${data.startUrl}',
+    detect: async (ctx: CommandContext) => {
+      const page = ensurePage(ctx);
+      // TODO: Add login detection logic
+      return false;
+    },
+  },
+
+  setup(site) {
+${commands.join("\n\n")}
+  },
+});
+`;
 }
 
+// src/stdin.ts
+import { readStdin as readStdin2, readCommandFile, splitFileLine } from "@dyyz1993/xcli-core";
+
 // src/cli/run-routes.ts
 async function handleRun(filePath, options) {
   let commands;
@@ -9741,10 +10716,10 @@ async function handleRun(filePath, options) {
 async function handleViewer(_args, options, mode, _cdpEndpoint) {
   const name = options.name || process.env.XBROWSER_SESSION || "default";
   const selector = options.selector;
-  const status = getDaemonProcessStatus();
+  let status = getDaemonProcessStatus();
   if (!status.running) {
-    outputError("Daemon is not running. Start with: xbrowser daemon start");
-    return;
+    await startDaemonProcess();
+    status = getDaemonProcessStatus();
   }
   const port = status.port || getDaemonConfig().basePort;
   let url = `http://localhost:${port}/preview/${name}`;
@@ -10064,6 +11039,235 @@ async function handleNetCommand(args, options, mode, sessionName) {
   }
 }
 
+// src/cli/test-routes.ts
+import { execSync as execSync3 } from "child_process";
+import { readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve9 } from "path";
+function findPluginPath(plugin) {
+  const candidates = [
+    resolve9(process.cwd(), ".xcli/plugins", plugin, "index.ts"),
+    resolve9(process.cwd(), "node_modules/@xbrowser/cli/.xcli/plugins", plugin, "index.ts")
+  ];
+  for (const p of candidates) {
+    try {
+      readFileSync8(p, "utf-8");
+      return p;
+    } catch {
+    }
+  }
+  return resolve9(process.cwd(), ".xcli/plugins", plugin, "index.ts");
+}
+function extractSchema(plugin, command) {
+  const pluginPath = findPluginPath(plugin);
+  let src;
+  try {
+    src = readFileSync8(pluginPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const cmdIdx = src.indexOf(`.command('${command}'`);
+  if (cmdIdx < 0) return null;
+  const after = src.slice(cmdIdx);
+  const resultIdx = after.indexOf("result:");
+  if (resultIdx < 0) return null;
+  let block = after.slice(resultIdx + 7);
+  let depth = 0;
+  let schemaStr = "";
+  for (const ch of block) {
+    if (ch === "{" || ch === "(" || ch === "[") depth++;
+    if (ch === "}" || ch === ")" || ch === "]") {
+      depth--;
+      if (depth < 0) break;
+    }
+    if (depth === 0 && /\w/.test(ch) && schemaStr.trim().endsWith(",")) {
+      break;
+    }
+    schemaStr += ch;
+  }
+  const objStart = schemaStr.indexOf("z.object({");
+  const objEnd = objStart >= 0 ? schemaStr.indexOf("})", objStart) : -1;
+  const objStr = objStart >= 0 && objEnd > objStart ? schemaStr.slice(objStart + 10, objEnd) : schemaStr;
+  const fields = [];
+  const SKIP_NAMES = /* @__PURE__ */ new Set(["passthrough", "optional", "describe", "default"]);
+  const fieldRegex = /(\w+)\s*:\s*z\.(\w+)/g;
+  let match;
+  while ((match = fieldRegex.exec(objStr)) !== null) {
+    const name = match[1];
+    const type = match[2];
+    if (SKIP_NAMES.has(name) || type === "union" || type === "enum") continue;
+    const afterField = objStr.slice(match.index + match[0].length);
+    const isOptional = afterField.trimStart().startsWith(".optional()");
+    fields.push({
+      name,
+      type: type === "string" ? "string" : type === "number" ? "number" : type === "boolean" ? "boolean" : type === "array" ? "array" : type,
+      optional: isOptional || name === "index"
+    });
+  }
+  return fields.length > 0 ? fields : null;
+}
+async function runTest(plugin, command, cmdArgs, options) {
+  const cdp = options.cdp || options.cdpEndpoint || "http://localhost:9221";
+  const argsStr = cmdArgs.filter((a) => !a.startsWith("--cdp")).join(" ");
+  const schema = extractSchema(plugin, command);
+  const fullCmd = `npx xbrowser ${plugin} ${command} ${argsStr} --cdp ${cdp} --json --timeout 60000`;
+  let stdout = "";
+  try {
+    stdout = execSync3(fullCmd, {
+      timeout: 65e3,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, FORCE_COLOR: "0" }
+    });
+  } catch (e) {
+    const err = e;
+    stdout = err.stdout?.toString() || "";
+    const jsonLine = stdout.split("\n").find((l) => {
+      try {
+        JSON.parse(l);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    if (jsonLine) {
+      try {
+        const parsed2 = JSON.parse(jsonLine);
+        const code = parsed2?.data?.code || "";
+        if (code === "LOGIN_REQUIRED") {
+          return { status: "LOGIN_REQUIRED", message: parsed2.message || "\u9700\u8981\u767B\u5F55", viewerUrl: "http://localhost:9224/preview/default" };
+        }
+      } catch {
+      }
+    }
+    const stderr = err.stderr?.toString() || "";
+    if (stdout.includes("captcha") || stderr.includes("captcha") || stdout.includes("CAPTCHA")) {
+      return { status: "CAPTCHA", message: "\u68C0\u6D4B\u5230\u9A8C\u8BC1\u7801", viewerUrl: "http://localhost:9224/preview/default" };
+    }
+    return { status: "EXEC_ERROR", message: (err.message || "").slice(0, 200) || "\u6267\u884C\u5931\u8D25" };
+  }
+  const allLines = stdout.split("\n");
+  const jsonStart = allLines.findIndex((l) => l.trim().startsWith("{"));
+  const jsonStr = jsonStart >= 0 ? allLines.slice(jsonStart).join("\n") : "";
+  let parsed = {};
+  try {
+    parsed = JSON.parse(jsonStr);
+  } catch {
+    return { status: "EXEC_ERROR", message: "\u65E0\u6CD5\u89E3\u6790 CLI \u8F93\u51FA" };
+  }
+  const rawData = parsed.data;
+  const rawTips = parsed.tips || [];
+  if (parsed.success === false) {
+    const code = rawData?.code || "";
+    if (code === "LOGIN_REQUIRED") {
+      return { status: "LOGIN_REQUIRED", message: parsed.message || "\u9700\u8981\u767B\u5F55", viewerUrl: "http://localhost:9224/preview/default" };
+    }
+    if (rawTips.join(" ").includes("captcha") || rawTips.join(" ").includes("CAPTCHA")) {
+      return { status: "CAPTCHA", message: parsed.message || "\u9A8C\u8BC1\u7801", viewerUrl: "http://localhost:9224/preview/default" };
+    }
+  }
+  const data = rawData;
+  if (data === null || data === void 0) {
+    const msg = parsed.message || "";
+    const tips = rawTips.join(" ");
+    const viewerUrl = parsed.viewerUrl || rawData?.viewerUrl || "";
+    let status = "NO_DATA";
+    if (msg.includes("block") || msg.includes("anti-bot") || msg.includes("captcha") || tips.includes("viewer")) {
+      status = "BLOCKED";
+    } else if (msg.includes("\u767B\u5F55") || msg.includes("login")) {
+      status = "LOGIN_REQUIRED";
+    }
+    const ret = { status, message: msg || "\u6682\u65E0\u6570\u636E" };
+    if (viewerUrl) ret.viewerUrl = viewerUrl;
+    return ret;
+  }
+  if (!schema) {
+    return { status: "OK", note: "\u65E0 result schema", data: JSON.stringify(data).slice(0, 200) };
+  }
+  const errors = [];
+  const items = Array.isArray(data) ? data.slice(0, 3) : [data];
+  for (const item of items) {
+    if (typeof item !== "object" || item === null) {
+      errors.push("\u6570\u636E\u9879\u4E0D\u662F\u5BF9\u8C61");
+      continue;
+    }
+    for (const field of schema) {
+      const val = item[field.name];
+      if (val === void 0) {
+        if (!field.optional) errors.push(`\u7F3A\u5C11: ${field.name}`);
+        continue;
+      }
+      if (field.type === "array") {
+        if (!Array.isArray(val)) errors.push(`${field.name}: \u671F\u671B array`);
+      } else if (typeof val !== field.type) {
+        errors.push(`${field.name}: \u671F\u671B ${field.type}, \u5B9E\u9645 ${typeof val}`);
+      }
+    }
+  }
+  if (errors.length > 0) {
+    return { status: "SCHEMA_ERROR", errors, data: JSON.stringify(data).slice(0, 200) };
+  }
+  const count = Array.isArray(data) ? data.length : 1;
+  return { status: "OK", count, data: JSON.stringify(data).slice(0, 200) };
+}
+async function handleTest(cmdArgs, options, mode, cdpEndpoint) {
+  const plugin = cmdArgs[0];
+  const command = cmdArgs[1];
+  if (!plugin || !command) {
+    console.error("\u7528\u6CD5: xbrowser test <plugin> <command> [\u53C2\u6570...]");
+    console.error("\u793A\u4F8B: xbrowser test doubao list --cdp 9221");
+    return;
+  }
+  const loader = await getPluginLoader();
+  const internalLoader = loader.getCore().loader;
+  const site = internalLoader.getSite(plugin);
+  if (!site) {
+    console.error(`\u63D2\u4EF6 "${plugin}" \u4E0D\u5B58\u5728`);
+    return;
+  }
+  const cmdEntry = site.getCommand(command);
+  if (!cmdEntry) {
+    console.error(`\u6307\u4EE4 "${command}" \u4E0D\u5B58\u5728`);
+    return;
+  }
+  const testArgs = cmdArgs.slice(2);
+  const mergedOptions = { ...options, cdp: cdpEndpoint || options.cdp };
+  const result = await runTest(plugin, command, testArgs, mergedOptions);
+  if (mode === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const r = result;
+  const icons = {
+    OK: "\u2705",
+    LOGIN_REQUIRED: "\u{1F511}",
+    CAPTCHA: "\u{1F6A8}",
+    SCHEMA_ERROR: "\u274C",
+    BLOCKED: "\u{1F6A7}",
+    NO_DATA: "\u{1F4ED}",
+    EXEC_ERROR: "\u{1F4A5}"
+  };
+  const status = String(r.status);
+  const icon = icons[status] || "\u2753";
+  console.log(`
+${icon}  ${plugin}.${command}`);
+  console.log(`   \u72B6\u6001: ${status}`);
+  if (status === "OK") {
+    if (r.count) console.log(`   \u6570\u636E: ${r.count} \u9879`);
+    if (r.data) console.log(`   \u9884\u89C8: ${String(r.data).slice(0, 150)}`);
+  } else if (status === "LOGIN_REQUIRED" || status === "CAPTCHA") {
+    console.log(`   \u4FE1\u606F: ${String(r.message)}`);
+    console.log(`   Viewer: ${String(r.viewerUrl)}`);
+  } else if (status === "SCHEMA_ERROR") {
+    const errs = r.errors;
+    if (errs) console.log(`   \u9519\u8BEF: ${errs.join("; ")}`);
+  } else if (["NO_DATA", "BLOCKED"].includes(status)) {
+    console.log(`   \u4FE1\u606F: ${String(r.message)}`);
+    if (r.viewerUrl) console.log(`   Viewer: ${String(r.viewerUrl)}`);
+  } else {
+    console.log(`   \u4FE1\u606F: ${String(r.message)}`);
+  }
+}
+
 // src/cli/help.ts
 function showMainHelp() {
   console.log(`
@@ -10077,11 +11281,11 @@ Usage:
   xbrowser -e cmd1 -e cmd2             Execute multiple -e commands
 
 Commands:
-  session open <url> [--name <n>]   Open browser session
-  session close [--name <n>]        Close session
+  session close [--session <name>]  Close session
   session list                      List sessions
-  session kill [--name <n>]         Kill session
+  session kill [--session <name>]   Kill session
   goto <url>                        Navigate to URL
+  open <url>                        Navigate to URL (alias for goto)
   click <selector>                  Click element (-s <sel>)
   fill <selector> <value>           Fill input (-s <sel> -v <val>)
   type <selector> <text>            Type text (-s <sel> -v <text>)
@@ -10091,7 +11295,7 @@ Commands:
   dblclick <selector>               Double click (-s <sel>)
   check <selector>                  Check checkbox (-s <sel>)
   uncheck <selector>                Uncheck checkbox (-s <sel>)
-  screenshot [--full-page]          Take screenshot
+  screenshot [--full-page] [--base64]  Take screenshot (saves to ~/.xbrowser/screenshots/; use --base64 for inline data)
   eval <expression>                 Evaluate JS
   wait <selector> [--timeout <ms>]  Wait for element (-s <sel>)
   scroll <direction> [--distance N] Scroll page
@@ -10113,9 +11317,6 @@ Commands:
   plugin list                       List plugins
   plugin reload <name>              Reload plugin
   create <name> --template <type>   Create plugin
-  daemon start [--port <port>]      Start daemon
-  daemon stop                       Stop daemon
-  daemon status                     Check status
   serve [--port <port>] [--token <t>] Start HTTP server for remote access
   remote <url> [command] [--token <t>] Execute command on remote server
   record start --url <url>          Start recording
@@ -10326,14 +11527,14 @@ async function listCommands() {
   return jsonResponse(200, { commands });
 }
 async function listSessions2() {
-  const sessions = getAllSessions().map((s) => ({
+  const sessions2 = getAllSessions().map((s) => ({
     id: s.id,
     name: s.name,
     url: s.page?.url() ?? null,
     createdAt: s.createdAt,
     isCDP: s.isCDP ?? false
   }));
-  return jsonResponse(200, { sessions });
+  return jsonResponse(200, { sessions: sessions2 });
 }
 async function createSessionHandler(req) {
   const body = req.body;
@@ -10488,19 +11689,19 @@ function headersToObject(headers) {
   return result;
 }
 function readBody(req) {
-  return new Promise((resolve16, reject) => {
+  return new Promise((resolve10, reject) => {
     const chunks = [];
     req.on("data", (chunk) => chunks.push(chunk));
     req.on("end", () => {
       const raw = Buffer.concat(chunks).toString("utf-8");
       if (!raw) {
-        resolve16(null);
+        resolve10(null);
         return;
       }
       try {
-        resolve16(JSON.parse(raw));
+        resolve10(JSON.parse(raw));
       } catch {
-        resolve16(null);
+        resolve10(null);
       }
     });
     req.on("error", reject);
@@ -10545,7 +11746,7 @@ var HTTPServer = class {
         res.end(JSON.stringify({ error: "INTERNAL_ERROR", message, statusCode: 500 }));
       });
     });
-    return new Promise((resolve16, reject) => {
+    return new Promise((resolve10, reject) => {
       const server = this.server;
       server.on("error", (err) => {
         this.server = null;
@@ -10557,7 +11758,7 @@ var HTTPServer = class {
           this.port = addr.port;
         }
         console.log(`HTTP server listening on http://${this.host}:${this.port}`);
-        resolve16({ port: this.port, host: this.host });
+        resolve10({ port: this.port, host: this.host });
       });
     });
   }
@@ -10568,13 +11769,13 @@ var HTTPServer = class {
    */
   async stop() {
     if (!this.server) return;
-    return new Promise((resolve16, reject) => {
+    return new Promise((resolve10, reject) => {
       this.server.close((err) => {
         if (err) {
           reject(err);
         } else {
           this.server = null;
-          resolve16();
+          resolve10();
         }
       });
     });
@@ -10633,6 +11834,7 @@ function showCommandHelp(siteName, cmd, siteConfig, mode) {
       command: c.name,
       description: c.description,
       scope: c.scope,
+      ...c.loginRequired ? { loginRequired: c.loginRequired } : {},
       parameters: paramsList
     }, mode);
   } else {
@@ -10645,9 +11847,25 @@ function showCommandHelp(siteName, cmd, siteConfig, mode) {
       examples: c.examples
     }, { color: false, emoji: false });
     console.log(text);
+    if (c.loginRequired) {
+      console.log(`  Login: ${c.loginRequired}`);
+    }
     console.log("");
   }
 }
+function outputLoginRequired(result, mode) {
+  if (mode === "json" || mode === "yaml") {
+    console.log(outputFormatter2.format(result, { mode, color: false, emoji: false }));
+    return;
+  }
+  const message = result.message || "Login required";
+  console.error(message);
+  for (const tip of result.tips || []) {
+    const text = typeof tip === "string" ? tip : tip.message;
+    if (text !== message) console.error(`  \u{1F4A1} ${text}`);
+  }
+  process.exit(1);
+}
 function extractZodFieldInfo(value) {
   const field = value;
   const fieldDef = field._def;
@@ -10711,7 +11929,7 @@ function extractCdpFromArgv(argv) {
     if (argv[i] === "--cdp" && argv[i + 1]) return argv[i + 1];
     if (typeof argv[i] === "string" && argv[i].startsWith("--cdp=")) return argv[i].slice(6);
   }
-  return void 0;
+  return process.env.XBROWSER_CDP;
 }
 async function handleStdinMode(stdinCommands, argv) {
   const chain = stdinCommands.join(" && ");
@@ -10774,7 +11992,7 @@ async function routeCommand(argv, stdinCommands) {
   const cmdArgs = positional.slice(1);
   const mode = options.json ? "json" : options.yaml ? "yaml" : "text";
   const sessionName = options.session || process.env.XBROWSER_SESSION || "default";
-  const cdpEndpoint = options.cdp;
+  const cdpEndpoint = options.cdp || process.env.XBROWSER_CDP;
   if (options.version || options.v) {
     console.log(`xbrowser v${version}`);
     return;
@@ -10907,12 +12125,21 @@ async function routeCommand(argv, stdinCommands) {
         if (builtin) await builtin.execute(cmdArgs, options, { cwd: process.cwd() });
         break;
       }
+      case "knowledge":
+      case "know": {
+        const builtin = allBuiltins.find((b) => b.name === "knowledge");
+        if (builtin) await builtin.execute(cmdArgs, options, { cwd: process.cwd() });
+        break;
+      }
       case "viewer":
         await handleViewer(cmdArgs, options, mode, cdpEndpoint);
         break;
       case "help":
         showMainHelp();
         break;
+      case "test":
+        await handleTest(cmdArgs, options, mode, cdpEndpoint);
+        break;
       case "net":
         await handleNetCommand(cmdArgs, options, mode, sessionName);
         break;
@@ -11022,9 +12249,14 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
           }
           const needsBrowser = cmdEntry.scope === "page" || cmdEntry.scope === "browser";
           if (needsBrowser && !process.env.XBROWSER_DAEMON_WORKER) {
-            const { forwardExec } = await import("./daemon-client-XWSSQBEA.js");
+            const { forwardExec } = await import("./daemon-client-UZZEHHIV.js");
             const userTimeout = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1e3 + 3e4 : void 0;
-            const result = await forwardExec(command, params, sessionName, cdpEndpoint, userTimeout);
+            const result = await forwardExec(`${command}.${subCommand}`, params, sessionName, cdpEndpoint, userTimeout);
+            const resultData = result && typeof result === "object" ? result.data : void 0;
+            if (result && result.success === false && resultData?.code === "LOGIN_REQUIRED") {
+              outputLoginRequired(result, mode);
+              return;
+            }
             if (result && result.success !== false) {
               if (isCommandResult2(result)) {
                 if (mode === "json" || mode === "yaml") {
@@ -11057,6 +12289,7 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
             browser: needsBrowser ? session.context.browser() : null,
             browserContext: needsBrowser ? session.context : null,
             sessionId: needsBrowser ? session.id : "",
+            cdpEndpoint: cdpEndpoint || (needsBrowser ? session?.cdpEndpoint : void 0),
             storage: getPluginStorage(command),
             output: { mode, showTips: true, color: true, emoji: true },
             error: (msg) => {
@@ -11067,10 +12300,33 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
             cliName: "xbrowser",
             waitForHuman: async (_opts) => {
               return { solved: false, timedOut: true };
-            }
+            },
+            tips: new TipCollector2()
           };
           try {
             const cmdStart = Date.now();
+            const loginGuard = await checkPluginLoginRequired({
+              site,
+              command: cmdEntry,
+              commandName: subCommand,
+              ctx,
+              page: needsBrowser ? session?.page : null,
+              sessionName
+            });
+            if (!loginGuard.ok) {
+              const result2 = {
+                success: false,
+                data: loginGuard.data ?? null,
+                message: loginGuard.message,
+                tips: normalizeTips7(loginGuard.tips)
+              };
+              if (mode === "json" || mode === "yaml") {
+                outputLoginRequired(result2, mode);
+              } else {
+                outputLoginRequired(result2, mode);
+              }
+              return;
+            }
             const cmdHooks = await loadHooks();
             if (cmdHooks.length > 0 && session?.page) {
               await Promise.all(cmdHooks.map((h) => h.onBeforeCommand?.({ page: session.page, command: `${command} ${subCommand}`, params })));
@@ -11089,23 +12345,39 @@ Run "xbrowser ${command} ${subCommand} --help" to see available parameters.`
                 saveSessionDiskMeta(sessionName, { conversationUrl: convUrl, cdpEndpoint });
               }
             }
+            let injectedViewerUrl;
+            const LOGIN_FAIL_KEYWORDS = ["\u767B\u5F55", "login", "Login", "\u672A\u767B\u5F55", "not logged in", "cdp", "CDP", "\u9A8C\u8BC1\u7801", "\u9A8C\u8BC1", "captcha", "\u9700\u8981\u767B\u5F55", "requires login"];
+            const tipTexts = (result.tips || []).map((t) => typeof t === "string" ? t : t.message);
+            const isLoginFail = isCommandResult2(result) && result.success === false && [result.message, ...tipTexts].filter(Boolean).join(" ").toLowerCase().match(new RegExp(LOGIN_FAIL_KEYWORDS.join("|"), "i"));
+            if (isLoginFail) {
+              injectedViewerUrl = buildViewerUrl(sessionName);
+              if (injectedViewerUrl) {
+                result.tips = [...result.tips || [], makeTip.info(`Open viewer to complete login: ${injectedViewerUrl}`)];
+              }
+            }
             const outputData = isCommandResult2(result) ? result.data : result && typeof result === "object" ? result.data ?? result : result;
             const tips = isCommandResult2(result) ? result.tips : result && typeof result === "object" ? result.tips : void 0;
             if (mode === "json" || mode === "yaml") {
               const finalOutput = {
                 data: outputData
               };
+              if (injectedViewerUrl) {
+                finalOutput.viewerUrl = injectedViewerUrl;
+              }
+              if (tips?.length) {
+                finalOutput.tips = tips;
+              }
               if (hookOutputs.length > 0) {
                 finalOutput.hooks = hookOutputs;
               }
               console.log(outputFormatter2.format(finalOutput, { mode, color: false, emoji: false }));
               if (tips?.length) {
-                for (const tip of tips) console.error(`\u{1F4A1} ${tip}`);
+                for (const tip of tips) console.error(`\u{1F4A1} ${typeof tip === "string" ? tip : tip.message}`);
               }
             } else {
               console.log(outputFormatter2.format(outputData, { mode: "text", color: true, emoji: true }));
               if (tips?.length) {
-                for (const tip of tips) console.log(`  \u{1F4A1} ${tip}`);
+                for (const tip of tips) console.log(`  \u{1F4A1} ${typeof tip === "string" ? tip : tip.message}`);
               }
               if (hookOutputs.length > 0) {
                 for (const ho of hookOutputs) {
@@ -11283,7 +12555,7 @@ async function main() {
     const command = process.argv[2];
     const isLongRunning = command === "preview" || command === "serve";
     if (!isLongRunning) {
-      const { ensureProcessCanExit } = await import("./browser-GWBH6OJK.js");
+      const { ensureProcessCanExit } = await import("./browser-R56O3CW6.js");
       await ensureProcessCanExit().catch(() => {
       });
       process.exit(exitCode);