@agentrhq/webcmd 0.2.1 → 0.2.3

package/clis/zepto/zepto.test.js

@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest';
+import { JSDOM } from 'jsdom';
+import { ArgumentError, AuthRequiredError } from '@agentrhq/webcmd/errors';
+import { getRegistry } from '@agentrhq/webcmd/registry';
+import './auth.js';
+import './location.js';
+import './search.js';
+import './product.js';
+import './add-to-cart.js';
+import './cart.js';
+import './checkout.js';
+import './place-order.js';
+import {
+  CART_EVALUATE,
+  buildSearchUrl,
+  normalizeLocationState,
+  normalizeProductRow,
+  parseLimitArg,
+  parseQuantityArg,
+  productCardsEvaluate,
+  resolveProductInput,
+  safeGoto,
+} from './utils.js';
+
+describe('zepto helpers', () => {
+  it('builds search URLs and validates numeric args', () => {
+    expect(buildSearchUrl('amul milk')).toBe('https://www.zepto.com/search?query=amul%20milk');
+    expect(() => buildSearchUrl('   ')).toThrow(ArgumentError);
+    expect(() => parseLimitArg(0, 20, 50)).toThrow(ArgumentError);
+    expect(() => parseLimitArg(51, 20, 50)).toThrow(ArgumentError);
+    expect(() => parseQuantityArg(0, 1, 12)).toThrow(ArgumentError);
+  });
+
+  it('parses product pvids and URLs', () => {
+    expect(resolveProductInput('https://www.zepto.com/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089')).toMatchObject({
+      productId: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      url: 'https://www.zepto.com/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+    });
+    expect(() => resolveProductInput('5f54bb83-f3e0-4d8d-89b0-6339f3312089')).toThrow(ArgumentError);
+  });
+
+  it('normalizes product rows', () => {
+    expect(normalizeProductRow({
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      title: 'Rin Matic Top Load Detergent Liquid | Pouch',
+      pack_size: '1 pack (2 kg)',
+      price: '₹179',
+      mrp: '₹260',
+      url: '/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+    }, 0)).toMatchObject({
+      rank: 1,
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      price: 179,
+      mrp: 260,
+      url: 'https://www.zepto.com/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+    });
+  });
+
+  it('extracts rendered product cards', () => {
+    const dom = new JSDOM(`
+      <a href="/pn/rin/pvid/5f54bb83-f3e0-4d8d-89b0-6339f3312089">
+        <div>
+          <button>ADD</button>
+          <span>₹ 179</span><span>₹ 260</span>
+          <span>Rin Matic Top Load Detergent Liquid | Pouch</span>
+          <span>1 pack (2 kg)</span>
+        </div>
+      </a>
+    `, { runScripts: 'outside-only', url: 'https://www.zepto.com/search?query=rin' });
+
+    const result = dom.window.eval(productCardsEvaluate(5));
+
+    expect(result.rows[0]).toMatchObject({
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      title: 'Rin Matic Top Load Detergent Liquid | Pouch',
+      price: '₹ 179',
+      mrp: '₹ 260',
+    });
+  });
+
+  it('normalizes selected location without leaking exact coordinates', () => {
+    expect(normalizeLocationState({
+      addressText: 'Home: HSR Layout, Bengaluru',
+      userPosition: { latitude: 12.911, longitude: 77.629 },
+    })).toEqual({
+      selected: true,
+      label: 'Home',
+      area: '',
+      city: 'Bengaluru',
+      pincode: '',
+      hasCoordinates: true,
+      source: 'browser',
+    });
+  });
+
+  it('redacts exact house and floor details from location output', () => {
+    expect(normalizeLocationState({
+      addressText: 'home - House number - 5, Floor - 5th, HSR Layout, Bengaluru, India',
+      userPosition: { latitude: 12.911, longitude: 77.629 },
+    })).toEqual({
+      selected: true,
+      label: 'Home',
+      area: '',
+      city: 'Bengaluru',
+      pincode: '',
+      hasCoordinates: true,
+      source: 'browser',
+    });
+  });
+
+  it('does not treat the Select Location placeholder as selected', () => {
+    expect(normalizeLocationState({ addressText: 'Select Location' })).toEqual({
+      selected: false,
+      label: '',
+      area: '',
+      city: '',
+      pincode: '',
+      hasCoordinates: false,
+      source: 'browser',
+    });
+  });
+
+  it('tolerates Zepto SPA navigation aborts but keeps real navigation failures', async () => {
+    await expect(safeGoto({
+      goto: async () => { throw new Error('page.goto: net::ERR_ABORTED at https://www.zepto.com/'); },
+    }, 'https://www.zepto.com/', 'zepto cart')).resolves.toBeUndefined();
+
+    await expect(safeGoto({
+      goto: async () => { throw new Error('page.goto: net::ERR_NAME_NOT_RESOLVED'); },
+    }, 'https://www.zepto.com/', 'zepto cart')).rejects.toThrow('zepto cart navigation failed');
+  });
+
+  it('extracts cart items from Zepto cart storage without recommendations', () => {
+    const cart = {
+      state: {
+        cartContent: {
+          '5f54bb83-f3e0-4d8d-89b0-6339f3312089': {
+            quantity: 2,
+            productVariant: {
+              id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+              name: 'Rin Matic Top Load Detergent Liquid | Pouch',
+              formattedPacksize: '1 pack (2 kg)',
+              price: 17900,
+              mrp: 26000,
+            },
+          },
+        },
+      },
+    };
+    const dom = new JSDOM('', { runScripts: 'outside-only', url: 'https://www.zepto.com/' });
+    dom.window.localStorage.setItem('cart', JSON.stringify(cart));
+
+    const result = dom.window.eval(CART_EVALUATE);
+
+    expect(result.rows).toEqual([expect.objectContaining({
+      product_id: '5f54bb83-f3e0-4d8d-89b0-6339f3312089',
+      title: 'Rin Matic Top Load Detergent Liquid | Pouch',
+      quantity: 2,
+      price: 179,
+    })]);
+  });
+
+  it('extracts top-level Zepto cart item fields', () => {
+    const cart = {
+      state: {
+        cartContent: {
+          'ba77f9b3-0525-4ce8-bc4b-a2480419b780': {
+            quantity: 1,
+            title: 'Godrej Jersey Toned Fresh Milk | Pouch',
+            productVariantId: 'ba77f9b3-0525-4ce8-bc4b-a2480419b780',
+            quantityText: '1 pack (490 ml or 500 ml)',
+            superSaverSellingPrice: 2600,
+            mrp: 2700,
+          },
+        },
+      },
+    };
+    const dom = new JSDOM('', { runScripts: 'outside-only', url: 'https://www.zepto.com/' });
+    dom.window.localStorage.setItem('cart', JSON.stringify(cart));
+
+    const result = dom.window.eval(CART_EVALUATE);
+
+    expect(result.rows).toEqual([expect.objectContaining({
+      product_id: 'ba77f9b3-0525-4ce8-bc4b-a2480419b780',
+      title: 'Godrej Jersey Toned Fresh Milk | Pouch',
+      pack_size: '1 pack (490 ml or 500 ml)',
+      quantity: 1,
+      price: 26,
+      mrp: 27,
+    })]);
+  });
+});
+
+describe('zepto registry shape', () => {
+  it('registers the buying-path commands', () => {
+    for (const name of ['login', 'location', 'search', 'product', 'add-to-cart', 'cart', 'checkout', 'place-order']) {
+      expect(getRegistry().get(`zepto/${name}`)).toBeDefined();
+    }
+  });
+
+  it('marks only cart-changing commands as write', () => {
+    expect(getRegistry().get('zepto/location').access).toBe('read');
+    expect(getRegistry().get('zepto/search').access).toBe('read');
+    expect(getRegistry().get('zepto/product').access).toBe('read');
+    expect(getRegistry().get('zepto/cart').access).toBe('read');
+    expect(getRegistry().get('zepto/login').access).toBe('write');
+    expect(getRegistry().get('zepto/add-to-cart').access).toBe('write');
+    expect(getRegistry().get('zepto/checkout').access).toBe('write');
+    expect(getRegistry().get('zepto/place-order').access).toBe('write');
+  });
+
+  it('lets commands own Zepto navigation instead of framework pre-navigation', () => {
+    for (const name of ['login', 'location', 'search', 'product', 'add-to-cart', 'cart', 'checkout', 'place-order']) {
+      expect(getRegistry().get(`zepto/${name}`).navigateBefore).toBe(false);
+    }
+  });
+});
+
+describe('zepto command behavior', () => {
+  it('search reports auth-required when Zepto blocks web search', async () => {
+    const command = getRegistry().get('zepto/search');
+    const calls = [];
+    const fakePage = {
+      goto: async (...args) => { calls.push(args); },
+      wait: async () => {},
+      evaluate: async () => ({ authRequired: true, rows: [] }),
+    };
+
+    await expect(command.func(fakePage, { query: 'milk' })).rejects.toThrow(AuthRequiredError);
+    expect(calls[0]).toEqual(['https://www.zepto.com/search?query=milk', { waitUntil: 'none', settleMs: 1500 }]);
+  });
+
+  it('keeps place-order no-op unless --confirm is passed', async () => {
+    const command = getRegistry().get('zepto/place-order');
+    const fakePage = { goto: () => { throw new Error('should not navigate'); } };
+    await expect(command.func(fakePage, {})).resolves.toMatchObject([{ status: 'no-op', confirmed: false }]);
+  });
+});

package/dist/src/browser/bridge.d.ts

@@ -21,6 +21,7 @@ export declare class BrowserBridge implements IBrowserFactory {
         windowMode?: 'foreground' | 'background';
         surface?: 'browser' | 'adapter';
         siteSession?: 'ephemeral' | 'persistent';
+        freshPage?: boolean;
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;

package/dist/src/browser/bridge.js

@@ -32,7 +32,7 @@ export class BrowserBridge {
             await this._ensureDaemon(opts.timeout, routing.contextId);
             if (!opts.session?.trim())
                 throw new Error('Browser session is required');
-            this._page = new Page(opts.session.trim(), opts.idleTimeout, routing.contextId, opts.windowMode, opts.surface, opts.siteSession, routing.preferredContextId);
+            this._page = new Page(opts.session.trim(), opts.idleTimeout, routing.contextId, opts.windowMode, opts.surface, opts.siteSession, routing.preferredContextId, opts.freshPage);
             this._state = 'connected';
             return this._page;
         }

package/dist/src/browser/page.d.ts

@@ -21,7 +21,10 @@ export declare class Page extends BasePage {
     private readonly siteSession?;
     readonly preferredContextId?: string | undefined;
     private readonly _idleTimeout;
-    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined, preferredContextId?: string | undefined);
+    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined, preferredContextId?: string | undefined, freshPage?: boolean);
+    /** When set, the next daemon command asks for a fresh leased page; consumed on first send. */
+    private _freshPagePending;
+    private _freshPageOpts;
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;

package/dist/src/browser/page.js

@@ -42,7 +42,7 @@ export class Page extends BasePage {
     siteSession;
     preferredContextId;
     _idleTimeout;
-    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession, preferredContextId) {
+    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession, preferredContextId, freshPage) {
         super();
         this.session = session;
         this.contextId = contextId;
@@ -51,6 +51,15 @@ export class Page extends BasePage {
         this.siteSession = siteSession;
         this.preferredContextId = preferredContextId;
         this._idleTimeout = idleTimeout;
+        this._freshPagePending = freshPage === true;
+    }
+    /** When set, the next daemon command asks for a fresh leased page; consumed on first send. */
+    _freshPagePending;
+    _freshPageOpts() {
+        if (!this._freshPagePending)
+            return {};
+        this._freshPagePending = false;
+        return { freshPage: true };
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     _page;
@@ -66,6 +75,7 @@ export class Page extends BasePage {
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
             ...(this.siteSession && { siteSession: this.siteSession }),
+            ...this._freshPageOpts(),
         };
     }
     /** Helper: spread session + page identity into command params */
@@ -79,6 +89,7 @@ export class Page extends BasePage {
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
             ...(this.siteSession && { siteSession: this.siteSession }),
+            ...this._freshPageOpts(),
         };
     }
     async goto(url, options) {

package/dist/src/browser/protocol.d.ts

@@ -10,6 +10,8 @@ export interface BrowserRuntimeCommand {
     session?: string;
     surface?: BrowserSurface;
     siteSession?: SiteSessionMode;
+    /** Close any existing leased page and start on a new one (sent on the first action of a command run). */
+    freshPage?: boolean;
     url?: string;
     op?: string;
     index?: number;

package/dist/src/browser/runtime/local-cloak/actions.js

@@ -43,6 +43,7 @@ async function resolveLease(manager, command) {
         surface: command.surface,
         siteSession: command.siteSession,
         idleTimeout: command.idleTimeout,
+        freshPage: command.freshPage,
     });
 }
 function execTarget(page, frameIndex, pageId) {

package/dist/src/browser/runtime/local-cloak/session-manager.d.ts

@@ -9,6 +9,8 @@ export interface SessionKeyInput {
     surface?: BrowserSurface;
     siteSession?: SiteSessionMode;
     idleTimeout?: number;
+    /** Discard the existing leased page (if any) and create a new one under the same lease. */
+    freshPage?: boolean;
 }
 export interface CloakPageLease {
     profileId: string;

package/dist/src/browser/runtime/local-cloak/session-manager.js

@@ -40,15 +40,25 @@ export class CloakSessionManager {
         const surface = normalizeSurface(input.surface);
         const leaseKey = resolveLeaseKey(input);
         const runtime = await this.getProfileRuntime(profileId);
+        const freshPage = input.freshPage === true;
         const existing = runtime.pages.get(leaseKey);
-        if (existing && !pageIsClosed(existing.page)) {
+        if (existing && !pageIsClosed(existing.page) && !freshPage) {
             runtime.lastSeenAt = Date.now();
             existing.idleTimeout = input.idleTimeout;
             this.refreshIdleTimer(runtime, leaseKey, existing);
             return { profileId, leaseKey, context: runtime.context, page: existing.page, pageId: existing.pageId };
         }
+        if (existing && freshPage) {
+            runtime.pages.delete(leaseKey);
+            this.clearIdleTimer(existing);
+            if (runtime.selectedPageId === existing.pageId)
+                runtime.selectedPageId = undefined;
+            if (!pageIsClosed(existing.page))
+                await existing.page.close().catch(() => { });
+        }
         const existingPages = runtime.context.pages();
-        const page = existingPages[0] && runtime.pages.size === 0 ? existingPages[0] : await runtime.context.newPage();
+        // freshPage must never adopt a leftover tab — its whole point is a clean DOM.
+        const page = !freshPage && existingPages[0] && runtime.pages.size === 0 ? existingPages[0] : await runtime.context.newPage();
         const pageId = nextPageId();
         const entry = { page, pageId, session, surface, siteSession: input.siteSession, idleTimeout: input.idleTimeout };
         runtime.pages.set(leaseKey, entry);

package/dist/src/browser/runtime/local-cloak/session-manager.test.js

@@ -42,6 +42,64 @@ describe('CloakSessionManager', () => {
         expect(launchPersistentContext).toHaveBeenCalledTimes(1);
         expect(launchPersistentContext.mock.calls[0][0]).toMatchObject({ headless: false });
     });
+    it('freshPage closes the existing persistent lease page and creates a new one', async () => {
+        const makePage = () => ({
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue('ok'),
+            title: vi.fn().mockResolvedValue('Title'),
+            url: vi.fn().mockReturnValue('about:blank'),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        });
+        const openPages = [];
+        const context = {
+            pages: vi.fn(() => openPages),
+            newPage: vi.fn(async () => {
+                const page = makePage();
+                openPages.push(page);
+                return page;
+            }),
+            cookies: vi.fn().mockResolvedValue([]),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(context),
+        });
+        const key = { profileId: 'default', session: 'site:district', surface: 'adapter', siteSession: 'persistent' };
+        const first = await manager.getPage(key);
+        expect((await manager.getPage(key)).page).toBe(first.page);
+        const fresh = await manager.getPage({ ...key, freshPage: true });
+        expect(first.page.close).toHaveBeenCalled();
+        expect(fresh.page).not.toBe(first.page);
+        const reused = await manager.getPage(key);
+        expect(reused.page).toBe(fresh.page);
+    });
+    it('freshPage never adopts a leftover context tab', async () => {
+        const leftover = {
+            goto: vi.fn(),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const created = {
+            goto: vi.fn(),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const context = {
+            pages: vi.fn().mockReturnValue([leftover]),
+            newPage: vi.fn().mockResolvedValue(created),
+            cookies: vi.fn().mockResolvedValue([]),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(context),
+        });
+        const lease = await manager.getPage({ profileId: 'default', session: 'site:district', surface: 'adapter', siteSession: 'persistent', freshPage: true });
+        expect(lease.page).toBe(created);
+        expect(context.newPage).toHaveBeenCalled();
+    });
     it('closes ephemeral adapter sessions when released', async () => {
         const launched = fakeContext();
         const manager = new CloakSessionManager({

package/dist/src/build-manifest.js

@@ -103,6 +103,7 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         sourceFile,
         navigateBefore: cmd.navigateBefore,
         siteSession: cmd.siteSession,
+        freshPage: cmd.freshPage,
         defaultWindowMode: cmd.defaultWindowMode,
     };
 }

package/dist/src/build-manifest.test.js

@@ -81,6 +81,40 @@ describe('manifest helper rules', () => {
         expect(entries[0].sourceFile).not.toContain('\\');
         getRegistry().delete(key);
     });
+    it('serializes freshPage for persistent browser commands', async () => {
+        const site = `manifest-fresh-page-${Date.now()}`;
+        const key = `${site}/checkout`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'checkout', access: 'write' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            command: cli({
+                site,
+                name: 'checkout',
+                access: 'write',
+                description: 'checkout command',
+                strategy: Strategy.COOKIE,
+                browser: true,
+                siteSession: 'persistent',
+                freshPage: true,
+            }),
+        }));
+        expect(entries).toMatchObject([
+            {
+                site,
+                name: 'checkout',
+                access: 'write',
+                strategy: 'cookie',
+                browser: true,
+                siteSession: 'persistent',
+                freshPage: true,
+                type: 'js',
+                modulePath: `${site}/${site}.js`,
+            },
+        ]);
+        getRegistry().delete(key);
+    });
     it('falls back to registry delta for side-effect-only cli modules', async () => {
         const site = `manifest-side-effect-${Date.now()}`;
         const key = `${site}/legacy`;

package/dist/src/cli.js

@@ -7,6 +7,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import * as readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import { Command, InvalidArgumentError, Option } from 'commander';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
@@ -16,10 +17,10 @@ import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
-import { listWebcmdSkills, readWebcmdSkill } from './skills.js';
+import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
 import { registerAllCommands } from './commanderAdapter.js';
 import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
-import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError } from './errors.js';
+import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError, ArgumentError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
 import { buildFindJs, buildSemanticFindJs, isFindError } from './browser/find.js';
@@ -58,6 +59,70 @@ function parseDurationMs(raw, flagName) {
 function timestampFromRaw(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
 }
+function isInteractiveInstall(opts) {
+    return !opts.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+async function resolveSkillInstallOptions(opts) {
+    if (!isInteractiveInstall(opts))
+        return opts;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd install skills?', [
+            { key: '1', label: 'Global', value: 'user', aliases: ['global', 'user', 'g'] },
+            { key: '2', label: 'Local project', value: 'project', aliases: ['local', 'project', 'l'] },
+        ], '1');
+        const provider = opts.provider ?? (opts.path ? undefined : await choosePrompt(rl, 'Which coding agent should use them?', [
+            { key: '1', label: 'Agents', value: 'agents', aliases: ['agents', 'agent', 'a'] },
+            { key: '2', label: 'Codex', value: 'codex', aliases: ['codex', 'c'] },
+            { key: '3', label: 'Claude', value: 'claude', aliases: ['claude', 'claude-code'] },
+            { key: '4', label: 'Custom path', value: 'custom', aliases: ['custom', 'path'] },
+        ], '1'));
+        const customPath = opts.path ?? (provider === 'custom' ? await nonEmptyPrompt(rl, 'Skills directory path: ') : undefined);
+        return { ...opts, scope, provider: provider === 'custom' ? undefined : provider, path: customPath };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function choosePrompt(rl, question, choices, defaultKey) {
+    console.log(question);
+    for (const choice of choices)
+        console.log(`  ${choice.key}) ${choice.label}`);
+    while (true) {
+        const answer = (await rl.question(`Choose [${defaultKey}]: `)).trim().toLowerCase() || defaultKey;
+        const choice = choices.find((item) => item.key === answer || item.aliases.includes(answer));
+        if (choice)
+            return choice.value;
+        console.log(`Choose one of: ${choices.map((item) => item.key).join(', ')}`);
+    }
+}
+async function nonEmptyPrompt(rl, question) {
+    while (true) {
+        const answer = (await rl.question(question)).trim();
+        if (answer)
+            return answer;
+        console.log('Path is required.');
+    }
+}
+async function handleSkillLinkCommand(action, json, verb) {
+    try {
+        const result = await action();
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Webcmd skills ${verb}: ${result.skills.length}`);
+        for (const skill of result.skills) {
+            console.log(`${skill.name}: ${skill.destination ? `${skill.destination} -> ` : ''}${skill.stableLink}`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${getErrorMessage(err)}`);
+        if (err instanceof CliError && err.hint)
+            console.error(`Hint: ${err.hint}`);
+        process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
+    }
+}
 function toIsoTimestamp(timestamp) {
     if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0)
         return undefined;
@@ -711,10 +776,20 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     });
     const skillsCmd = program
         .command('skills')
-        .description('Read bundled Webcmd skills');
+        .description('List, install, and update bundled Webcmd skills')
+        .action(() => {
+        const rows = listWebcmdSkills();
+        renderOutput(rows, {
+            fmt: 'table',
+            fmtExplicit: false,
+            columns: ['name', 'description', 'version', 'path'],
+            title: 'webcmd/skills/list',
+            source: 'webcmd skills',
+        });
+    });
     skillsCmd
         .command('list')
-        .description('List bundled webcmd-* skills')
+        .description('List bundled Webcmd skills')
         .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
         .action((opts) => {
         const rows = listWebcmdSkills();
@@ -727,30 +802,38 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         });
     });
     skillsCmd
-        .command('read')
-        .description("Print a bundled webcmd-* skill's SKILL.md or reference file")
-        .argument('<skill>', 'Skill name, or skill/path like webcmd-browser/references/foo.md')
-        .argument('[path]', 'Path under the skill directory')
-        .option('--json', 'Output a JSON envelope instead of raw markdown', false)
-        .action((skill, skillPath, opts) => {
-        let result;
-        try {
-            result = readWebcmdSkill(skill, skillPath ?? '');
-        }
-        catch (err) {
-            console.error(`Error: ${getErrorMessage(err)}`);
-            if (err instanceof CliError && err.hint)
-                console.error(`Hint: ${err.hint}`);
-            process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
-            return;
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(result, null, 2));
-            return;
-        }
-        process.stdout.write(result.content);
-        if (!result.content.endsWith('\n'))
-            process.stdout.write('\n');
+        .command('install')
+        .description('Install bundled Webcmd skills into an agent skills folder')
+        .option('-p, --provider <provider>', 'Agent provider: agents, codex, claude')
+        .option('-s, --scope <scope>', 'Install scope: user/global or project/local')
+        .option('--path <path>', 'Custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action(async (opts) => {
+        await handleSkillLinkCommand(async () => {
+            const resolved = await resolveSkillInstallOptions(opts);
+            if (resolved.provider === 'custom' && !resolved.path) {
+                throw new ArgumentError('Custom skill provider requires --path.', 'Pass --path <skills-dir> or run interactively.');
+            }
+            return installWebcmdSkill({
+                provider: resolved.provider,
+                scope: resolved.scope,
+                customPath: resolved.path,
+            });
+        }, opts.json, 'installed');
+    });
+    skillsCmd
+        .command('update')
+        .description('Refresh bundled Webcmd skill symlinks after updating the package')
+        .option('-p, --provider <provider>', 'Also repair provider link: agents, codex, claude')
+        .option('-s, --scope <scope>', 'Also repair scoped link: user/global or project/local')
+        .option('--path <path>', 'Also repair a custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action(async (opts) => {
+        await handleSkillLinkCommand(() => updateWebcmdSkill({
+            provider: opts.provider,
+            scope: opts.scope,
+            customPath: opts.path,
+        }), opts.json, 'updated');
     });
     const authCmd = registerAuthCommands(program);
     program