@agentrhq/webcmd 0.2.1 → 0.2.3

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.3",
   "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/scripts/generate-release-notes.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { GoogleGenAI } from '@google/genai';
 import {
@@ -6,6 +7,7 @@ import {
   extractPullRequestNumber,
   filterReleasePullRequests,
   normalizeReleaseNotes,
+  replaceChangelogReleaseNotes,
   type PullRequestDetails,
   type ReleaseContext,
 } from '../src/release-notes.js';
@@ -195,12 +197,41 @@ function contributorHandles(pullRequests: PullRequestDetails[]): string[] {
   return pullRequests.flatMap((pr) => (pr.author?.login ? [pr.author.login] : []));
 }
 
+function updateChangelog(tag: string | undefined, notesPath: string | undefined, changelogPath: string | undefined, io: Io): number {
+  if (!tag || !notesPath) {
+    io.writeStderr('Usage: generate-release-notes --update-changelog <tag> <notes-file> [changelog-file]\n');
+    return 1;
+  }
+
+  const targetChangelogPath = changelogPath ?? 'CHANGELOG.md';
+
+  try {
+    const notes = readFileSync(notesPath, 'utf8');
+    const changelog = readFileSync(targetChangelogPath, 'utf8');
+    const updated = replaceChangelogReleaseNotes(changelog, tag, notes);
+    if (updated !== changelog) {
+      writeFileSync(targetChangelogPath, updated);
+    }
+
+    io.writeStdout(`Updated ${targetChangelogPath} for ${tag}\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    io.writeStderr(`CHANGELOG.md update failed: ${message}\n`);
+    return 1;
+  }
+}
+
 export async function runGenerateReleaseNotes(
   argv: string[] = process.argv,
   env: NodeJS.ProcessEnv = process.env,
   deps: RunDependencies = {},
   io: Io = DEFAULT_IO,
 ): Promise<number> {
+  if (argv[2] === '--update-changelog') {
+    return updateChangelog(argv[3], argv[4], argv[5], io);
+  }
+
   const tag = argv[2];
   if (!tag) {
     io.writeStderr('Usage: generate-release-notes <tag>\n');

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`

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

@@ -0,0 +1,21 @@
+# Shopping
+
+Use for product search, prices, deals, reputation, and regional e-commerce results.
+
+## Sites
+
+### amazon
+
+- Use for: global product search, price references, and English-language e-commerce
+- Before use, run: `webcmd amazon -h`
+
+### coupang
+
+- Use for: Korean e-commerce product search
+- Before use, run: `webcmd coupang -h`
+
+## Routing Hints
+
+- If the user names a platform, use that platform directly
+- If no platform is named, prefer `amazon` for global products and `coupang` for Korean e-commerce
+- If product research starts with an AI source, add an e-commerce site afterward for actual product results

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

@@ -0,0 +1,36 @@
+# Social Media
+
+Use when raw posts, raw user results, or community discussions are needed.
+
+## Sites
+
+### twitter
+
+- Use for: Twitter/X posts, authors, real-time discussion, and public reactions
+- Before use, run: `webcmd twitter -h`
+
+### reddit
+
+- Use for: community Q&A, experience posts, recommendations, comparisons, and subreddit discussions
+- Before use, run: `webcmd reddit -h`
+
+### instagram
+
+- Use for: account search, image-first social signals, creators, and profile clues
+- Before use, run: `webcmd instagram -h`
+
+### facebook
+
+- Use for: pages, people, post clues, and public social presence
+- Before use, run: `webcmd facebook -h`
+
+### bluesky
+
+- Use for: Bluesky users and account search
+- Before use, run: `webcmd bluesky -h`
+
+## Routing Hints
+
+- If the user explicitly names a platform, use that platform directly
+- If the user only asks what people are saying on social media, start with `grok`
+- If an AI answer only summarizes and does not provide raw posts, switch to the relevant social site

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

@@ -0,0 +1,38 @@
+# Technology And Research
+
+Use for technical questions, research papers, developer discussion, and open-source community information.
+
+## Sites
+
+### arxiv
+
+- Use for: papers, research, models, algorithms, and academic background
+- Before use, run: `webcmd arxiv -h`
+
+### stackoverflow
+
+- Use for: specific errors, API usage, code patterns, and implementation details
+- Before use, run: `webcmd stackoverflow -h`
+
+### hackernews
+
+- Use for: technical community discussion, developer opinions, startup topics, and product discussion
+- Before use, run: `webcmd hackernews -h`
+
+### reddit
+
+- Use for: community Q&A, experience posts, recommendations, and comparison discussions
+- Before use, run: `webcmd reddit -h`
+
+### github
+
+- Use for: repositories, issues, pull requests, releases, code search, and open-source project signals
+- Before use, run: `webcmd github -h`
+
+## Routing Hints
+
+- If the user explicitly asks for papers or research, prefer `arxiv`
+- If the user asks about an error or API usage, prefer `stackoverflow`
+- If the user wants community discussion or developer viewpoints, prefer `hackernews` or `reddit`
+- If the user wants open-source project evidence, prefer `github`
+- If the user did not name a site, start with `gemini` or `grok`, then add these specialized sources when needed