@agentrhq/webcmd 0.2.1 → 0.2.3

package/dist/src/discovery.js

@@ -211,6 +211,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
                 navigateBefore: entry.navigateBefore,
                 siteSession: entry.siteSession,
+                freshPage: entry.freshPage,
                 defaultWindowMode: entry.defaultWindowMode,
                 _lazy: true,
                 _modulePath: modulePath,

package/dist/src/engine.test.js

@@ -3,6 +3,7 @@ import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdap
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
 import { clearAllHooks, onAfterExecute } from './hooks.js';
+import * as runtime from './runtime.js';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -71,6 +72,67 @@ cli({
             await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
         }
     });
+    it('preserves freshPage from manifest before lazy command import', async () => {
+        const site = `manifest-fresh-${Date.now()}`;
+        const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-manifest-fresh-'));
+        const distDir = path.join(tempBuildRoot, 'dist');
+        const siteDir = path.join(distDir, site);
+        const commandPath = path.join(siteDir, 'checkout.js');
+        const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
+        const sessionOpts = [];
+        const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(manifestPath, `${JSON.stringify([
+                {
+                    site,
+                    name: 'checkout',
+                    description: 'fresh checkout',
+                    access: 'write',
+                    strategy: 'public',
+                    browser: true,
+                    args: [],
+                    type: 'js',
+                    modulePath: `${site}/checkout.js`,
+                    sourceFile: `${site}/checkout.js`,
+                    siteSession: 'persistent',
+                    freshPage: true,
+                },
+            ], null, 2)}\n`);
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: '${site}',
+  name: 'checkout', access: 'write',
+  description: 'fresh checkout',
+  browser: true,
+  strategy: Strategy.PUBLIC,
+  siteSession: 'persistent',
+  freshPage: true,
+  func: async () => [{ ok: true }],
+});
+`);
+            await discoverClis(distDir);
+            const cmd = getRegistry().get(`${site}/checkout`);
+            expect(cmd?.freshPage).toBe(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+                sessionOpts.push(opts ?? {});
+                return fn(mockPage);
+            });
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true }]);
+            expect(sessionOpts).toHaveLength(1);
+            expect(sessionOpts[0]).toMatchObject({
+                session: `site:${site}`,
+                siteSession: 'persistent',
+                freshPage: true,
+            });
+        }
+        finally {
+            vi.restoreAllMocks();
+            getRegistry().delete(`${site}/checkout`);
+            await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+        }
+    });
     it('loads user CLI modules via package exports symlink', async () => {
         const tempWebcmdRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-user-clis-'));
         const userClisDir = path.join(tempWebcmdRoot, 'clis');

package/dist/src/execution.js

@@ -334,7 +334,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession });
+            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession, freshPage: cmd.freshPage === true && siteSession === 'persistent' });
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes

package/dist/src/generate-release-notes-cli.test.js

@@ -1,4 +1,6 @@
-import { readFileSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it, vi } from 'vitest';
 import { loadReleaseContext, runGenerateReleaseNotes } from '../scripts/generate-release-notes.js';
@@ -72,6 +74,9 @@ describe('runGenerateReleaseNotes', () => {
                 '## Fixes',
                 'None.',
                 '',
+                '## Adapters',
+                'None.',
+                '',
                 '## Contributors',
                 '- @alice',
                 '',
@@ -94,6 +99,52 @@ describe('runGenerateReleaseNotes', () => {
             stderr: 'Gemini release notes failed: gh timed out\n',
         });
     });
+    it('updates the matching changelog entry from an existing notes file', async () => {
+        const { io, read } = createIo();
+        const tempDir = mkdtempSync(join(tmpdir(), 'webcmd-release-notes-'));
+        const notesPath = join(tempDir, 'release-notes.md');
+        const changelogPath = join(tempDir, 'CHANGELOG.md');
+        try {
+            writeFileSync(notesPath, [
+                '## Highlights',
+                '- Better generated notes.',
+                '',
+                '## Adapters',
+                '- Added checkout adapter polish.',
+                '',
+            ].join('\n'));
+            writeFileSync(changelogPath, [
+                '# Changelog',
+                '',
+                '## [0.2.3](https://github.com/agentrhq/webcmd/compare/webcmd-v0.2.2...webcmd-v0.2.3) (2026-07-09)',
+                '',
+                '### Features',
+                '',
+                '* release-please generated note',
+                '',
+                '## [0.2.2](https://github.com/agentrhq/webcmd/compare/webcmd-v0.2.1...webcmd-v0.2.2) (2026-07-08)',
+                '',
+                '### Bug Fixes',
+                '',
+                '* older note',
+                '',
+            ].join('\n'));
+            const exitCode = await runGenerateReleaseNotes(['node', 'script', '--update-changelog', 'webcmd-v0.2.3', notesPath, changelogPath], {}, {}, io);
+            expect(exitCode).toBe(0);
+            expect(read()).toEqual({
+                stdout: `Updated ${changelogPath} for webcmd-v0.2.3\n`,
+                stderr: '',
+            });
+            const changelog = readFileSync(changelogPath, 'utf8');
+            expect(changelog).toContain('### Highlights\n- Better generated notes.');
+            expect(changelog).toContain('### Adapters\n- Added checkout adapter polish.');
+            expect(changelog).not.toContain('release-please generated note');
+            expect(changelog).toContain('* older note');
+        }
+        finally {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
     it('loads bounded PR diffs into release context', async () => {
         const gh = vi.fn((args) => {
             const key = args.join(' ');
@@ -134,6 +185,9 @@ describe('runGenerateReleaseNotes', () => {
     it('keeps npm publish unblocked when enhanced release-note editing fails', () => {
         const workflowPath = fileURLToPath(new URL('../.github/workflows/release.yml', import.meta.url));
         const workflow = readFileSync(workflowPath, 'utf8');
+        expect(workflow.indexOf('- name: Publish to npm')).toBeLessThan(workflow.indexOf('- name: Update changelog with enhanced release notes'));
+        expect(workflow).toContain('npm --silent run generate-release-notes -- --update-changelog');
+        expect(workflow).toContain('git push origin "HEAD:${{ github.ref_name }}"');
         expect(workflow).toMatch(/if gh release edit "\$\{\{ steps\.release\.outputs\.tag_name \}\}" --notes-file "\$RUNNER_TEMP\/release-notes\.md"; then/);
         expect(workflow).toMatch(/Enhanced release notes could not be applied; keeping release-please notes\./);
     });

package/dist/src/manifest-types.d.ts

@@ -38,6 +38,8 @@ export interface ManifestEntry {
     navigateBefore?: boolean | string;
     /** Site session lifecycle defaults — see CliCommand.siteSession */
     siteSession?: 'ephemeral' | 'persistent';
+    /** Fresh page behavior for persistent site sessions — see CliCommand.freshPage */
+    freshPage?: boolean;
     /** Default browser window visibility — see CliCommand.defaultWindowMode */
     defaultWindowMode?: 'foreground' | 'background';
 }

package/dist/src/registry.d.ts

@@ -63,6 +63,16 @@ interface BaseCliCommand {
     navigateBefore?: boolean | string;
     /** Site session lifecycle for adapter commands. */
     siteSession?: SiteSessionMode;
+    /**
+     * Start this command on a freshly created page even when the persistent
+     * site session already has a leased tab. The old tab is closed and a new
+     * one opened under the same lease, so profile state (cookies, localStorage,
+     * login, location) survives while stale DOM (leftover modals, drawers,
+     * half-finished flows from earlier commands) is discarded. Requires
+     * `siteSession: 'persistent'` — ephemeral sessions always start fresh, so
+     * combining them is a contradiction and fails at registration.
+     */
+    freshPage?: boolean;
     /** Default browser window mode for commands whose UX requires visibility. */
     defaultWindowMode?: 'foreground' | 'background';
     /** Override the default CLI output format when the user does not pass -f/--format. */

package/dist/src/registry.js

@@ -29,6 +29,7 @@ export function cli(opts) {
         validateArgs: opts.validateArgs,
         navigateBefore: opts.navigateBefore,
         siteSession: opts.siteSession,
+        freshPage: opts.freshPage,
         defaultWindowMode: opts.defaultWindowMode,
         defaultFormat: opts.defaultFormat,
         authStatus: opts.authStatus,
@@ -86,12 +87,13 @@ function assertCommandAccess(cmd) {
     throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
 }
 function assertSiteSession(cmd) {
-    if (cmd.siteSession === undefined)
-        return;
     const key = `${cmd.site}/${cmd.name}`;
-    if (cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
+    if (cmd.siteSession !== undefined && cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
         throw new Error(`Command ${key} siteSession must be one of: ephemeral, persistent`);
     }
+    if (cmd.freshPage === true && cmd.siteSession !== 'persistent') {
+        throw new Error(`Command ${key} freshPage requires siteSession: 'persistent' — ephemeral sessions already start on a fresh page`);
+    }
 }
 export function registerCommand(cmd) {
     const normalized = normalizeCommand(cmd);

package/dist/src/registry.test.js

@@ -19,6 +19,31 @@ describe('cli() registration', () => {
         expect(cmd.browser).toBe(false);
         expect(cmd.args).toEqual([]);
     });
+    it('accepts freshPage with a persistent site session', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'fresh-ok', access: 'write',
+            description: 'test',
+            siteSession: 'persistent',
+            freshPage: true,
+        });
+        expect(cmd.freshPage).toBe(true);
+    });
+    it('rejects freshPage without a persistent site session', () => {
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'fresh-bad', access: 'write',
+            description: 'test',
+            freshPage: true,
+        })).toThrow(/freshPage requires siteSession: 'persistent'/);
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'fresh-bad-ephemeral', access: 'write',
+            description: 'test',
+            siteSession: 'ephemeral',
+            freshPage: true,
+        })).toThrow(/freshPage requires siteSession: 'persistent'/);
+    });
     it('puts registered command in the registry', () => {
         cli({
             site: 'test-registry',

package/dist/src/release-notes.d.ts

@@ -1,4 +1,4 @@
-export declare const RELEASE_NOTE_SECTIONS: readonly ["Highlights", "Improvements", "Fixes", "Contributors", "Reverts"];
+export declare const RELEASE_NOTE_SECTIONS: readonly ["Highlights", "Improvements", "Fixes", "Adapters", "Contributors", "Reverts"];
 export type ReleaseNoteSection = typeof RELEASE_NOTE_SECTIONS[number];
 export interface PullRequestLabel {
     name: string;
@@ -32,6 +32,8 @@ export interface CompareCommit {
     author?: string | null;
 }
 export type GitRunner = (args: readonly string[]) => Promise<string>;
+export declare function releaseVersionFromTag(tag: string): string;
+export declare function replaceChangelogReleaseNotes(changelog: string, tag: string, notes: string): string;
 export declare function extractPullRequestNumber(message: string): number | null;
 export declare function filterReleasePullRequests(prs: PullRequestDetails[]): PullRequestDetails[];
 export declare function normalizeReleaseNotes(raw: string, contributors: string[]): string;

package/dist/src/release-notes.js

@@ -1,4 +1,11 @@
-export const RELEASE_NOTE_SECTIONS = ['Highlights', 'Improvements', 'Fixes', 'Contributors', 'Reverts'];
+export const RELEASE_NOTE_SECTIONS = [
+    'Highlights',
+    'Improvements',
+    'Fixes',
+    'Adapters',
+    'Contributors',
+    'Reverts',
+];
 const SQUASH_MERGE_PR_NUMBER_PATTERN = /\(#(?<number>\d+)\)\s*$/;
 const MERGE_COMMIT_PR_NUMBER_PATTERN = /^Merge pull request #(?<number>\d+) /;
 const RELEASE_PLEASE_TITLE_PATTERN = /^chore(?:\([^)]+\))?: release(?:\s|$)/;
@@ -13,6 +20,39 @@ function formatSectionContent(content) {
     const trimmed = content?.trim();
     return trimmed && trimmed.length > 0 ? trimmed : 'None.';
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function formatReleaseNotesForChangelog(notes) {
+    const trimmed = notes.trim();
+    if (!trimmed)
+        return '### Highlights\nNone.';
+    return trimmed.replace(/^##\s+/gm, '### ');
+}
+export function releaseVersionFromTag(tag) {
+    const value = tag.trim();
+    if (value.startsWith('webcmd-v'))
+        return value.slice('webcmd-v'.length);
+    if (value.startsWith('v'))
+        return value.slice(1);
+    return value;
+}
+export function replaceChangelogReleaseNotes(changelog, tag, notes) {
+    const version = releaseVersionFromTag(tag);
+    const headingPattern = new RegExp(`^## \\[${escapeRegExp(version)}\\]\\([^\\n]+\\) \\([^\\n]+\\)\\s*$`, 'm');
+    const headingMatch = headingPattern.exec(changelog);
+    if (!headingMatch) {
+        throw new Error(`Could not find CHANGELOG.md entry for ${version}`);
+    }
+    const headingEnd = headingMatch.index + headingMatch[0].length;
+    const remaining = changelog.slice(headingEnd);
+    const nextReleaseMatch = /\n## \[/.exec(remaining);
+    const releaseEnd = nextReleaseMatch ? headingEnd + nextReleaseMatch.index : changelog.length;
+    const before = changelog.slice(0, headingEnd).trimEnd();
+    const after = changelog.slice(releaseEnd);
+    const suffix = after ? after.replace(/^\n+/, '\n\n') : '\n';
+    return `${before}\n\n${formatReleaseNotesForChangelog(notes)}${suffix}`;
+}
 export function extractPullRequestNumber(message) {
     const firstLine = message.split(/\r?\n/, 1)[0] ?? message;
     const squashMatch = firstLine.match(SQUASH_MERGE_PR_NUMBER_PATTERN);
@@ -92,6 +132,9 @@ export function buildReleaseNotesPrompt(context) {
         'Use only the supplied pull requests below. Do not invent changes or pull in information from elsewhere.',
         `Required sections: ${RELEASE_NOTE_SECTIONS.map((section) => `## ${section}`).join(', ')}.`,
         'Each section must be present in the final notes.',
+        'In this project, CLI commands and adapters are the same thing. Treat any PR that adds, removes, or changes files under clis/** as an adapter change, even if the PR title says "CLI" instead of "adapter".',
+        'Put new site adapters/CLIs, adapter promotions, adapter hardening, adapter output changes, selector/API updates, and site-specific workflow improvements in ## Adapters.',
+        'Use ## Improvements for non-adapter product, runtime, CLI, docs, or workflow improvements.',
         '',
         `Pull requests included for this release:`,
         prSummaries,

package/dist/src/release-notes.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, normalizeReleaseNotes, } from './release-notes.js';
+import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, normalizeReleaseNotes, replaceChangelogReleaseNotes, } from './release-notes.js';
 describe('release notes helpers', () => {
     it('extracts PR numbers from squash and merge commit messages', () => {
         expect(extractPullRequestNumber('feat: add release notes (#123)')).toBe(123);
@@ -29,10 +29,44 @@ describe('release notes helpers', () => {
         for (const section of RELEASE_NOTE_SECTIONS) {
             expect(normalized).toContain(`## ${section}`);
         }
+        expect(normalized).toContain('## Adapters\nNone.');
         expect(normalized).toContain('## Improvements\nNone.');
         expect(normalized).toContain('## Contributors\n- @alice\n- @bob');
         expect(normalized).toContain('## Reverts\nNone.');
     });
+    it('replaces a matching changelog release entry with generated notes', () => {
+        const changelog = [
+            '# Changelog',
+            '',
+            '## [0.2.3](https://github.com/agentrhq/webcmd/compare/webcmd-v0.2.2...webcmd-v0.2.3) (2026-07-09)',
+            '',
+            '',
+            '### Features',
+            '',
+            '* release-please generated note',
+            '',
+            '## [0.2.2](https://github.com/agentrhq/webcmd/compare/webcmd-v0.2.1...webcmd-v0.2.2) (2026-07-08)',
+            '',
+            '### Bug Fixes',
+            '',
+            '* older note',
+            '',
+        ].join('\n');
+        const notes = [
+            '## Highlights',
+            '- Better release notes.',
+            '',
+            '## Adapters',
+            '- Improved district checkout.',
+        ].join('\n');
+        const updated = replaceChangelogReleaseNotes(changelog, 'webcmd-v0.2.3', notes);
+        expect(updated).toContain('## [0.2.3]');
+        expect(updated).toContain('### Highlights\n- Better release notes.');
+        expect(updated).toContain('### Adapters\n- Improved district checkout.');
+        expect(updated).not.toContain('release-please generated note');
+        expect(updated).toContain('## [0.2.2]');
+        expect(updated).toContain('* older note');
+    });
     it('builds a prompt grounded in the exact release range and PR list', () => {
         const context = {
             tag: 'v0.2.0',
@@ -56,6 +90,10 @@ describe('release notes helpers', () => {
         expect(prompt).toContain('PR #42: feat: add docs scaffold');
         expect(prompt).toContain('docs/docs.json');
         expect(prompt).toContain('## Highlights');
+        expect(prompt).toContain('## Adapters');
+        expect(prompt).toContain('CLI commands and adapters are the same thing');
+        expect(prompt).toContain('files under clis/** as an adapter change');
+        expect(prompt).toContain('Put new site adapters/CLIs, adapter promotions, adapter hardening');
         expect(prompt).toContain('## Reverts');
     });
 });

package/dist/src/runtime.d.ts

@@ -34,6 +34,7 @@ export interface IBrowserFactory {
         windowMode?: BrowserWindowMode;
         surface?: BrowserSurface;
         siteSession?: 'ephemeral' | 'persistent';
+        freshPage?: boolean;
     }): Promise<IPage>;
     close(): Promise<void>;
 }
@@ -46,4 +47,5 @@ export declare function browserSession<T>(BrowserFactory: new () => IBrowserFact
     windowMode?: BrowserWindowMode;
     surface?: BrowserSurface;
     siteSession?: 'ephemeral' | 'persistent';
+    freshPage?: boolean;
 }): Promise<T>;

package/dist/src/runtime.js

@@ -46,6 +46,7 @@ export async function browserSession(BrowserFactory, fn, opts = {}) {
             windowMode: opts.windowMode,
             surface: opts.surface,
             siteSession: opts.siteSession,
+            freshPage: opts.freshPage,
         });
         return await fn(page);
     }

package/dist/src/skills.d.ts

@@ -4,11 +4,29 @@ export interface WebcmdSkillInfo {
     version: string;
     path: string;
 }
-export interface WebcmdSkillReadResult {
-    skill: string;
-    path: string;
-    content: string;
+export interface WebcmdSkillInstallOptions {
+    provider?: string;
+    scope?: string;
+    customPath?: string;
+    packageRoot?: string;
+    homeDir?: string;
+    cwd?: string;
+}
+export interface WebcmdSkillLink {
+    name: string;
+    source: string;
+    stableLink: string;
+    destination?: string;
+}
+export interface WebcmdSkillInstallResult {
+    provider?: SkillProvider;
+    scope?: SkillScope;
+    skills: WebcmdSkillLink[];
 }
+type SkillProvider = 'agents' | 'codex' | 'claude';
+type SkillScope = 'user' | 'project';
 export declare function getSkillsRoot(packageRoot?: string): string;
 export declare function listWebcmdSkills(packageRoot?: string): WebcmdSkillInfo[];
-export declare function readWebcmdSkill(target: string, relpath?: string, packageRoot?: string): WebcmdSkillReadResult;
+export declare function installWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export declare function updateWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export {};

package/dist/src/skills.js

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
@@ -13,35 +14,100 @@ export function listWebcmdSkills(packageRoot) {
     if (!fs.existsSync(skillsRoot))
         return [];
     return fs.readdirSync(skillsRoot, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory() && entry.name.startsWith('webcmd-'))
+        .filter((entry) => entry.isDirectory())
         .map((entry) => readSkillInfo(skillsRoot, entry.name))
         .filter((entry) => entry !== null)
         .sort((a, b) => a.name.localeCompare(b.name));
 }
-export function readWebcmdSkill(target, relpath = '', packageRoot) {
-    const { name, pathInSkill } = parseSkillTarget(target, relpath);
-    if (!name.startsWith('webcmd-')) {
-        throw new ArgumentError(`Unknown Webcmd skill: ${name}`, 'Run "webcmd skills list" to see available Webcmd skills.');
+export function installWebcmdSkill(options = {}) {
+    const provider = options.customPath === undefined ? normalizeProvider(options.provider) : undefined;
+    const scope = normalizeScope(options.scope);
+    const skills = updateStableSkillLinks(options)
+        .map((skill) => {
+        const destination = destinationFor(skill.name, provider, scope, options);
+        replaceDirectorySymlink(skill.stableLink, destination);
+        return { ...skill, destination };
+    });
+    return { provider, scope, skills };
+}
+export function updateWebcmdSkill(options = {}) {
+    const skills = updateStableSkillLinks(options);
+    if (options.provider === undefined && options.scope === undefined && options.customPath === undefined)
+        return { skills };
+    const provider = options.customPath === undefined ? normalizeProvider(options.provider) : undefined;
+    const scope = normalizeScope(options.scope);
+    return {
+        provider,
+        scope,
+        skills: skills.map((skill) => {
+            const destination = destinationFor(skill.name, provider, scope, options);
+            replaceDirectorySymlink(skill.stableLink, destination);
+            return { ...skill, destination };
+        }),
+    };
+}
+function updateStableSkillLinks(options) {
+    const skillsRoot = getSkillsRoot(options.packageRoot);
+    const skills = listWebcmdSkills(options.packageRoot);
+    if (skills.length === 0) {
+        throw new ArgumentError(`No Webcmd skills found: ${skillsRoot}`, 'Install a package that includes skills/*/SKILL.md.');
     }
-    const skillsRoot = getSkillsRoot(packageRoot);
-    const skillRoot = path.join(skillsRoot, name);
-    if (!isDirectory(skillRoot) || !fs.existsSync(path.join(skillRoot, 'SKILL.md'))) {
-        throw new ArgumentError(`Unknown Webcmd skill: ${name}`, 'Run "webcmd skills list" to see available Webcmd skills.');
+    return skills.map((skill) => {
+        const source = path.join(skillsRoot, skill.name);
+        const stableLink = path.join(options.homeDir ?? os.homedir(), '.webcmd', 'skills', skill.name);
+        replaceDirectorySymlink(source, stableLink);
+        return { name: skill.name, source, stableLink };
+    });
+}
+function destinationFor(name, provider, scope, options) {
+    if (options.customPath !== undefined)
+        return path.join(expandHomePath(options.customPath), name);
+    const base = scope === 'project' ? options.cwd ?? process.cwd() : options.homeDir ?? os.homedir();
+    const agentDir = provider === 'claude' ? '.claude' : provider === 'codex' ? '.codex' : '.agents';
+    return path.join(base, agentDir, 'skills', name);
+}
+function expandHomePath(raw) {
+    const value = raw.trim();
+    if (!value)
+        throw new ArgumentError('Custom skills path must be non-empty.');
+    return path.resolve(value === '~' ? os.homedir() : value.startsWith('~/') ? path.join(os.homedir(), value.slice(2)) : value);
+}
+function normalizeProvider(raw = 'agents') {
+    const value = raw.trim().toLowerCase();
+    if (value === 'agents' || value === 'codex')
+        return value;
+    if (value === 'claude' || value === 'claude-code' || value === 'claude_code')
+        return 'claude';
+    throw new ArgumentError(`Unsupported skill provider: ${raw}`, 'Use one of: agents, codex, claude.');
+}
+function normalizeScope(raw = 'user') {
+    const value = raw.trim().toLowerCase();
+    if (value === 'user' || value === 'global')
+        return 'user';
+    if (value === 'project' || value === 'local')
+        return 'project';
+    throw new ArgumentError(`Unsupported skill scope: ${raw}`, 'Use one of: user, global, project, local.');
+}
+function replaceDirectorySymlink(target, linkPath) {
+    const current = safeLstat(linkPath);
+    if (current) {
+        if (!current.isSymbolicLink()) {
+            throw new ArgumentError(`Refusing to replace non-symlink path: ${linkPath}`, 'Remove it manually or choose a different scope/provider.');
+        }
+        fs.unlinkSync(linkPath);
     }
-    const relativePath = normalizeSkillPath(pathInSkill || 'SKILL.md');
-    const absolutePath = path.resolve(skillRoot, relativePath);
-    const relativeToRoot = path.relative(skillRoot, absolutePath);
-    if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
-        throw new ArgumentError(`Invalid skill path: ${relativePath}`, 'Skill paths must stay inside the selected Webcmd skill.');
+    fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+    fs.symlinkSync(target, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
+}
+function safeLstat(filePath) {
+    try {
+        return fs.lstatSync(filePath);
     }
-    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
-        throw new ArgumentError(`Skill file not found: ${name}/${relativePath}`, 'Run "webcmd skills list <skill>" is not supported yet; read SKILL.md or a known references/... file.');
+    catch (err) {
+        if (err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT')
+            return null;
+        throw err;
     }
-    return {
-        skill: name,
-        path: relativePath,
-        content: fs.readFileSync(absolutePath, 'utf8'),
-    };
 }
 function readSkillInfo(skillsRoot, name) {
     const skillMdPath = path.join(skillsRoot, name, 'SKILL.md');
@@ -56,30 +122,6 @@ function readSkillInfo(skillsRoot, name) {
         path: `${name}/SKILL.md`,
     };
 }
-function parseSkillTarget(target, relpath) {
-    const normalizedTarget = normalizeSkillPath(target);
-    if (relpath) {
-        return { name: normalizedTarget, pathInSkill: relpath };
-    }
-    const slash = normalizedTarget.indexOf('/');
-    if (slash === -1) {
-        return { name: normalizedTarget, pathInSkill: '' };
-    }
-    return {
-        name: normalizedTarget.slice(0, slash),
-        pathInSkill: normalizedTarget.slice(slash + 1),
-    };
-}
-function normalizeSkillPath(raw) {
-    const normalized = raw.trim().replace(/\\/g, '/');
-    if (!normalized || normalized.includes('\0')) {
-        throw new ArgumentError('Skill path must be non-empty.');
-    }
-    if (normalized.startsWith('/') || normalized.split('/').some((part) => part === '..')) {
-        throw new ArgumentError(`Invalid skill path: ${raw}`, 'Use a path relative to a Webcmd skill directory.');
-    }
-    return path.posix.normalize(normalized);
-}
 function parseFrontmatter(content) {
     if (!content.startsWith('---\n'))
         return {};