@agentrhq/webcmd 0.2.1 → 0.2.2

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 {};

package/dist/src/skills.test.js

@@ -1,19 +1,20 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import yaml from 'js-yaml';
 import { describe, expect, it } from 'vitest';
 import { ArgumentError } from './errors.js';
-import { listWebcmdSkills, readWebcmdSkill } from './skills.js';
-function makePackageRoot() {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-skills-'));
-    fs.mkdirSync(path.join(root, 'skills', 'webcmd-browser', 'references'), { recursive: true });
+import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
+function makePackageRoot(label = 'current') {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), `webcmd-skills-${label}-`));
+    fs.mkdirSync(path.join(root, 'skills', 'webcmd-browser'), { recursive: true });
     fs.mkdirSync(path.join(root, 'skills', 'webcmd-autofix'), { recursive: true });
     fs.mkdirSync(path.join(root, 'skills', 'smart-search'), { recursive: true });
     fs.writeFileSync(path.join(root, 'package.json'), '{"name":"@agentrhq/webcmd"}\n');
     fs.writeFileSync(path.join(root, 'skills', 'webcmd-browser', 'SKILL.md'), [
         '---',
         'name: webcmd-browser',
-        'description: Browser control skill',
+        `description: Browser control skill ${label}`,
         'version: 1.2.3',
         '---',
         '',
@@ -22,7 +23,6 @@ function makePackageRoot() {
         'Body.',
         '',
     ].join('\n'));
-    fs.writeFileSync(path.join(root, 'skills', 'webcmd-browser', 'references', 'targets.md'), '# Targets\n');
     fs.writeFileSync(path.join(root, 'skills', 'webcmd-autofix', 'SKILL.md'), [
         '---',
         'name: webcmd-autofix',
@@ -39,33 +39,90 @@ function makePackageRoot() {
     ].join('\n'));
     return root;
 }
+function real(filePath) {
+    return fs.realpathSync(filePath);
+}
 describe('webcmd skills content', () => {
-    it('lists only webcmd-prefixed skills', () => {
+    it('keeps bundled skill frontmatter valid yaml', () => {
+        const skillsRoot = path.join(process.cwd(), 'skills');
+        const skillNames = fs.readdirSync(skillsRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        for (const name of skillNames) {
+            const content = fs.readFileSync(path.join(skillsRoot, name, 'SKILL.md'), 'utf8');
+            const end = content.indexOf('\n---', 4);
+            expect(end, name).toBeGreaterThan(0);
+            expect(() => yaml.load(content.slice(4, end)), name).not.toThrow();
+        }
+    });
+    it('lists bundled skills', () => {
         const root = makePackageRoot();
         expect(listWebcmdSkills(root).map((skill) => skill.name)).toEqual([
+            'smart-search',
             'webcmd-autofix',
             'webcmd-browser',
         ]);
         expect(listWebcmdSkills(root).find((skill) => skill.name === 'webcmd-autofix')?.description)
             .toBe('Fix adapters: keep scope narrow');
     });
-    it('reads a skill SKILL.md and reference file', () => {
-        const root = makePackageRoot();
-        expect(readWebcmdSkill('webcmd-browser', '', root)).toMatchObject({
-            skill: 'webcmd-browser',
-            path: 'SKILL.md',
-        });
-        expect(readWebcmdSkill('webcmd-browser/references/targets.md', '', root)).toMatchObject({
-            skill: 'webcmd-browser',
-            path: 'references/targets.md',
-            content: '# Targets\n',
+    it('keeps the expected installable skill set', () => {
+        const skills = fs.readdirSync(path.join(process.cwd(), 'skills'), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        expect(skills).toEqual([
+            'smart-search',
+            'webcmd-adapter-author',
+            'webcmd-autofix',
+            'webcmd-browser',
+            'webcmd-browser-sitemap',
+            'webcmd-sitemap-author',
+            'webcmd-usage',
+        ]);
+    });
+    it('installs bundled skills once and refreshes them after package updates', () => {
+        const firstRoot = makePackageRoot('first');
+        const secondRoot = makePackageRoot('second');
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-project-'));
+        const installed = installWebcmdSkill({ packageRoot: firstRoot, homeDir, cwd, provider: 'codex', scope: 'project' });
+        expect(installed).toMatchObject({
+            provider: 'codex',
+            scope: 'project',
         });
-        expect(readWebcmdSkill('webcmd-browser', 'references/targets.md', root).content).toBe('# Targets\n');
+        expect(installed.skills.map((skill) => skill.name)).toEqual(['smart-search', 'webcmd-autofix', 'webcmd-browser']);
+        for (const skill of installed.skills) {
+            expect(skill.source).toBe(path.join(firstRoot, 'skills', skill.name));
+            expect(skill.stableLink).toBe(path.join(homeDir, '.webcmd', 'skills', skill.name));
+            expect(skill.destination).toBe(path.join(cwd, '.codex', 'skills', skill.name));
+            expect(real(skill.destination)).toBe(real(skill.source));
+        }
+        const updated = updateWebcmdSkill({ packageRoot: secondRoot, homeDir });
+        expect(updated.skills.every((skill) => skill.destination === undefined)).toBe(true);
+        for (const skill of installed.skills) {
+            expect(real(skill.destination)).toBe(real(path.join(secondRoot, 'skills', skill.name)));
+        }
     });
-    it('rejects non-webcmd skills and path traversal', () => {
-        const root = makePackageRoot();
-        expect(() => readWebcmdSkill('smart-search', '', root)).toThrow(ArgumentError);
-        expect(() => readWebcmdSkill('webcmd-browser/../smart-search/SKILL.md', '', root)).toThrow(ArgumentError);
-        expect(() => readWebcmdSkill('webcmd-browser', '../../package.json', root)).toThrow(ArgumentError);
+    it('installs bundled skills into a custom skills directory', () => {
+        const packageRoot = makePackageRoot();
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const customPath = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-custom-skills-'));
+        const installed = installWebcmdSkill({ packageRoot, homeDir, customPath });
+        expect(installed.provider).toBeUndefined();
+        expect(installed.skills.map((skill) => skill.destination)).toEqual([
+            path.join(customPath, 'smart-search'),
+            path.join(customPath, 'webcmd-autofix'),
+            path.join(customPath, 'webcmd-browser'),
+        ]);
+        for (const skill of installed.skills) {
+            expect(real(skill.destination)).toBe(real(skill.source));
+        }
+    });
+    it('refuses to replace real files or directories', () => {
+        const packageRoot = makePackageRoot();
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const stablePath = path.join(homeDir, '.webcmd', 'skills', 'smart-search');
+        fs.mkdirSync(stablePath, { recursive: true });
+        expect(() => updateWebcmdSkill({ packageRoot, homeDir })).toThrow(ArgumentError);
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"
@@ -30,7 +30,7 @@
   "files": [
     "dist/src/",
     "clis/",
-    "skills/webcmd-*/**",
+    "skills/**",
     "cli-manifest.json",
     "scripts/",
     "README.md",

package/skills/smart-search/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: smart-search
+description: Intelligent search router based on webcmd commands. Use this skill when the user wants to search, query, find, or research information through Webcmd, CLI, or API sources, especially for named websites, social media, technical material, news, shopping, travel, jobs, finance, or multilingual content
+---
+
+# Smart Search Router
+
+Route a query to the best webcmd search source based on the topic and context. The goal of this skill is not to memorize command signatures. First choose the data source, then have the agent read live help through `webcmd` so stale documentation does not leak into the answer.
+
+## Mandatory Preflight
+
+Before every use, do both of these steps:
+
+- Run `webcmd list -f yaml`
+- Use the live registry to confirm that candidate sites exist, and inspect `strategy`, `browser`, and `domain`
+
+After choosing a site, do both of these steps:
+
+- Run `webcmd <site> -h` to see the site's subcommands
+- If a subcommand is already selected, run `webcmd <site> <command> -h` to inspect parameters, output columns, and strategy
+
+Do not hard-code parameters or assume command signatures from skill docs. Trust the live output of `webcmd ... -h`.
+
+## Main Routing Rule
+
+Use this single rule instead of maintaining multiple priority lists:
+
+1. If the user explicitly names a website, platform, or data source, use that site directly.
+2. If the user does not name a site, prefer exactly one AI source: choose one of `grok`, `chatgpt`, or `gemini`.
+3. If the AI answer is thin, lacks raw data, needs authoritative corroboration, or needs vertical results, add 1-2 specialized sources.
+
+## Per-Question Budget And Rate Limits
+
+Treat a "single user question" as one problem-solving chain for the same intent. Follow-ups, clarifications, and added constraints in the same thread still count as the same question when the core problem has not changed.
+
+First create a site-call ledger. After each real search command, update it immediately:
+
+- `site`
+- `query`
+- `count`
+- `status`
+
+Counting rules:
+
+- `webcmd list -f yaml`, `webcmd <site> -h`, and `webcmd <site> <command> -h` are preflight/help commands and do not count as searches.
+- One real `webcmd <site> ...` search/query execution counts as 1 call for that site.
+- A failed call caused by an error, timeout, CAPTCHA, anti-bot check, or broken login state still counts as 1 call for that site. Do not retry indefinitely.
+
+Rate limits:
+
+- Hard AI-source limit: for the same question, call each AI source at most once.
+- The default strategy is still to choose only 1 AI source. Do not chain multiple AI sources as a routine workflow.
+- Call additional AI sources only when the user explicitly asks to compare multiple AI sources. Even then, each named AI source may be called at most once.
+- Non-AI sites default to at most 2 calls.
+- The second call to a non-AI site must have a clear reason, such as narrowing by time, region, category, sorting, or keywords after an overly broad first result.
+- Do not make a third call to a non-AI site. If information is still insufficient, stop expanding and state the gap clearly.
+
+When a rate limit is reached:
+
+- Record: `Skipped: <site> reached the rate limit`
+- Prefer another site of the same type
+- If no suitable alternative source exists, answer from the collected information and explain coverage and gaps
+
+## End-Of-Query Report
+
+At the end of every query, append a short "Search Summary" with at least these three items:
+
+- Which sites were searched
+- What query terms were used for each site
+- How many times each site was searched
+
+If any site was skipped because of a rate limit, say so explicitly.
+
+Use this fixed format when possible:
+
+```md
+Search Summary
+- Site: <site1> | Query: <term1> | Calls: <n>
+- Site: <site2> | Query: <term2>; <term3> | Calls: <n>
+- Skipped: <site3> | Reason: reached the rate limit
+```
+
+## AI Source Selection
+
+- `grok`
+  Best for real-time discussion, English-language internet sentiment, Twitter/X context, and trending topics.
+- `chatgpt`
+  Best for broad Q&A, synthesis, planning, coding help, and general-purpose English-language research.
+- `gemini`
+  Best for global web coverage, English-language sources, general information retrieval, and background summaries.
+
+If the user did not name a site, first judge language and context, then choose exactly one of these three.
+
+After an AI site has run one real query for the same question, do not call that same AI site again with rewritten keywords. If the answer is insufficient, prefer specialized sources instead of repeatedly hitting the same AI site.
+
+## AI Query Guidance
+
+When using an AI source, do not send a very short keyword by itself. Prefer a query shaped as "topic + goal + constraints."
+
+- Topic
+  The object, event, product, person, company, or technical term the user really wants to investigate.
+- Goal
+  The desired result, such as summary, comparison, cause, trend, recommendation, or raw leads.
+- Constraints
+  Language, region, time range, platform scope, audience, price band, job location, or whether raw sources are required.
+
+Prefer these shapes:
+
+- `<topic> + <question to answer>`
+- `<topic> + <time range/region/language>`
+- `<topic> + <platform or source scope>`
+- `<topic> + <output requirement>`
+
+Avoid sending only:
+
+- A single noun
+- A trending question with no time range
+- A shopping, jobs, or travel question with no region
+- A social-media question with no platform scope
+
+## When To Add Specialized Sources
+
+Add specialized sources when any of these conditions apply:
+
+- The AI provides a summary, but raw posts, raw videos, raw products, or raw job results are needed
+- The AI coverage is thin or misses vertical-site information
+- Higher authority or stronger domain relevance is needed
+- The user explicitly asks to search on a specific platform
+
+Keep a typical query to 1 AI source plus 1-2 specialized sources to avoid result overload.
+
+## Handling Unavailable Sources
+
+When a site is unavailable:
+
+- Do not stop the whole search because one source failed
+- Record: `Skipped: <site> unavailable`
+- Fall back to another site of the same type, or to one AI source
+- Always trust the actual output of `webcmd list -f yaml` and `webcmd <site> -h`
+
+Do not assume any site is always available. Even for public sites, trust live help and execution results in the current environment.
+
+## Reference Files
+
+Read only the files relevant to the current query:
+
+- **`references/sources-ai.md`** - default AI sources
+- **`references/sources-tech.md`** - technology and research
+- **`references/sources-social.md`** - social media
+- **`references/sources-media.md`** - media and entertainment
+- **`references/sources-info.md`** - news and knowledge
+- **`references/sources-shopping.md`** - shopping
+- **`references/sources-travel.md`** - travel
+- **`references/sources-other.md`** - other vertical sources
+
+Do not load every reference file unless the query actually needs them.

package/skills/smart-search/references/sources-ai.md

@@ -0,0 +1,74 @@
+# Default AI Sources
+
+When the user does not explicitly name a site, choose one of `grok`, `chatgpt`, or `gemini` first. Do not start by running multiple AI sources in parallel.
+
+## Usage Rules
+
+1. Run `webcmd list -f yaml`
+2. Confirm which of `grok`, `chatgpt`, and `gemini` are available in the current registry
+3. Run `webcmd <site> -h`
+4. After selecting a subcommand, run `webcmd <site> <command> -h`
+
+## Routing Guidance
+
+### grok
+
+- Use for: real-time trends, Twitter/X context, English-language internet discussion, sentiment, and trends
+- Common follow-up sources: `twitter`, `reddit`, `reuters`, `google`
+- Query suggestions:
+  - Add a time range, such as "today" or "this week"
+  - Add a platform scope, such as "on X" or "from social posts"
+  - Add a goal, such as "latest reactions", "main viewpoints", or "key claims"
+  - Examples:
+    - `OpenAI latest reactions on X this week`
+    - `TSLA earnings main viewpoints on social media April 2026`
+    - `Nintendo Switch 2 rumors latest discussion on X`
+
+### chatgpt
+
+- Use for: broad Q&A, synthesis, planning, coding help, and general-purpose English-language research
+- Common follow-up sources: `reddit`, `youtube`, `google`, `reuters`
+- Query suggestions:
+  - Add a language, market, or audience scope, such as "English-language discussion" or "US users"
+  - Add the requested goal, such as "summarize", "compare", or "extract recommendation reasons"
+  - Add audience or use-case constraints, such as "for beginners", "under $500", or "remote jobs"
+  - Examples:
+    - `Is the 2026 MacBook Air worth buying? Main views in English-language discussions`
+    - `Remote AI product manager hiring trends over the last month`
+    - `Sunscreen recommendations for sensitive skin, common pros and cons from US users`
+
+### gemini
+
+- Use for: global web coverage, English-language sources, background summaries, and general retrieval
+- Common follow-up sources: `google`, `wikipedia`, `arxiv`, `stackoverflow`
+- Query suggestions:
+  - Add a topic type, such as "overview", "comparison", "background", or "best sources"
+  - Add scope constraints, such as region, time, language, or industry
+  - Add an output shape, such as "with sources", "compare pros and cons", or "official guidance"
+  - Examples:
+    - `MCP overview and official guidance with sources`
+    - `best budget travel destinations in Japan April 2026 compare pros and cons`
+    - `TypeScript decorators current status official sources`
+
+## Follow-Up Principles
+
+- Use one AI source first to get an initial answer
+- If the answer lacks raw data, vertical results, or authoritative sources, add 1-2 specialized sources
+- Do not treat default AI sources as ground truth for command signatures; command details always come from `webcmd ... -h`
+
+## General Query Templates
+
+You can build AI queries from these templates:
+
+- Trending topic/news:
+  `<event> + latest developments + <time range> + <region/platform>`
+- Comparison/recommendation:
+  `<item A> vs <item B> + <evaluation dimensions> + <audience/budget/use case>`
+- Regional or language community:
+  `<topic> + main viewpoints in <language/market> discussions + <time range>`
+- Global sources:
+  `<topic> + overview/background + with sources`
+- Jobs:
+  `<role> + <city/country> + market trends/hiring + <time range>`
+- Shopping:
+  `<product> + reviews/price/value + <region/budget>`

package/skills/smart-search/references/sources-info.md

@@ -0,0 +1,43 @@
+# News And Knowledge
+
+Use for news, encyclopedic background, general knowledge, and technology/business reporting.
+
+## Sites
+
+### google
+
+- Use for: general web search and cross-site fallback
+- Before use, run: `webcmd google -h`
+
+### wikipedia
+
+- Use for: definitions, background knowledge, and historical facts
+- Before use, run: `webcmd wikipedia -h`
+
+### reuters
+
+- Use for: international news and factual reporting
+- Before use, run: `webcmd reuters -h`
+
+### hackernews
+
+- Use for: technology news discussion, startup links, and developer reactions
+- Before use, run: `webcmd hackernews -h`
+
+### github
+
+- Use for: repository, issue, pull request, release, and open-source project signals
+- Before use, run: `webcmd github -h`
+
+### substack
+
+- Use for: newsletters, creator subscription content, and long-form posts
+- Before use, run: `webcmd substack -h`
+
+## Routing Hints
+
+- For background knowledge and definitions, prefer `wikipedia`
+- For general web and cross-site information, prefer `google`
+- For international news, prefer `reuters`
+- For technology-community signals, prefer `hackernews` or `github`
+- When an AI answer is too generic, use these sources to add facts and links

package/skills/smart-search/references/sources-media.md

@@ -0,0 +1,40 @@
+# Media And Entertainment
+
+Use for video, film, TV, music, podcast, and content-platform search.
+
+## Sites
+
+### youtube
+
+- Use for: videos, tutorials, reviews, interviews, creator channels, and explainers
+- Before use, run: `webcmd youtube -h`
+
+### tiktok
+
+- Use for: short video, trends, entertainment clips, and creator discovery
+- Before use, run: `webcmd tiktok -h`
+
+### imdb
+
+- Use for: movies, TV shows, actors, credits, and ratings
+- Before use, run: `webcmd imdb -h`
+
+### spotify
+
+- Use for: songs, artists, albums, playlists, and music discovery
+- Before use, run: `webcmd spotify -h`
+
+### apple-podcasts
+
+- Use for: podcast shows and podcast search
+- Before use, run: `webcmd apple-podcasts -h`
+
+### medium
+
+- Use for: long-form articles, technical blogs, design writing, and product posts
+- Before use, run: `webcmd medium -h`
+
+## Routing Hints
+
+- If the user only asks for videos, reviews, podcasts, or articles, choose the site by content type first
+- If the user did not name a site, start with `grok` or `gemini`, then add a media site for raw results

package/skills/smart-search/references/sources-other.md

@@ -0,0 +1,32 @@
+# Other Vertical Sources
+
+Use for jobs, finance, books, dictionaries, and other cases that do not fit the earlier categories.
+
+## Sites
+
+### linkedin
+
+- Use for: global jobs, English-language job listings, and multinational-company hiring
+- Before use, run: `webcmd linkedin -h`
+
+### yahoo
+
+- Use for: finance, market data, stock quotes, and company finance pages
+- Before use, run: `webcmd yahoo -h`
+
+### github
+
+- Use for: open-source project discovery, repository signals, issues, pull requests, and releases
+- Before use, run: `webcmd github -h`
+
+### dictionary
+
+- Use for: English word meanings and basic dictionary lookup
+- Before use, run: `webcmd dictionary -h`
+
+## Routing Hints
+
+- For jobs, prefer `linkedin`
+- For finance and market data, prefer `yahoo`
+- For open-source project signals, prefer `github`
+- For English word definitions, prefer `dictionary`