@agentrhq/webcmd 0.3.2 → 0.3.4

package/dist/src/skills.test.js

@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import yaml from 'js-yaml';
 import { describe, expect, it } from 'vitest';
 import { ArgumentError } from './errors.js';
-import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
+import { addWebcmdSkills, listWebcmdSkills, removeWebcmdSkills, 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 });
@@ -80,18 +80,18 @@ describe('webcmd skills content', () => {
             'webcmd-usage',
         ]);
     });
-    it('installs bundled skills once and refreshes them after package updates', () => {
+    it('adds 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({
+        const added = addWebcmdSkills({ packageRoot: firstRoot, homeDir, cwd, provider: 'codex', scope: 'project' });
+        expect(added).toMatchObject({
             provider: 'codex',
             scope: 'project',
         });
-        expect(installed.skills.map((skill) => skill.name)).toEqual(['smart-search', 'webcmd-autofix', 'webcmd-browser']);
-        for (const skill of installed.skills) {
+        expect(added.skills.map((skill) => skill.name)).toEqual(['smart-search', 'webcmd-autofix', 'webcmd-browser']);
+        for (const skill of added.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));
@@ -99,22 +99,22 @@ describe('webcmd skills content', () => {
         }
         const updated = updateWebcmdSkill({ packageRoot: secondRoot, homeDir });
         expect(updated.skills.every((skill) => skill.destination === undefined)).toBe(true);
-        for (const skill of installed.skills) {
+        for (const skill of added.skills) {
             expect(real(skill.destination)).toBe(real(path.join(secondRoot, 'skills', skill.name)));
         }
     });
-    it('installs bundled skills into a custom skills directory', () => {
+    it('adds 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([
+        const added = addWebcmdSkills({ packageRoot, homeDir, customPath });
+        expect(added.provider).toBeUndefined();
+        expect(added.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) {
+        for (const skill of added.skills) {
             expect(real(skill.destination)).toBe(real(skill.source));
         }
     });
@@ -125,4 +125,32 @@ describe('webcmd skills content', () => {
         fs.mkdirSync(stablePath, { recursive: true });
         expect(() => updateWebcmdSkill({ packageRoot, homeDir })).toThrow(ArgumentError);
     });
+    it('removes bundled skill links from every supported location', () => {
+        const packageRoot = makePackageRoot();
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-project-'));
+        const customPath = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-custom-skills-'));
+        for (const provider of ['agents', 'codex', 'claude']) {
+            addWebcmdSkills({ packageRoot, homeDir, cwd, provider, scope: 'user' });
+            addWebcmdSkills({ packageRoot, homeDir, cwd, provider, scope: 'project' });
+        }
+        addWebcmdSkills({ packageRoot, homeDir, cwd, customPath });
+        const result = removeWebcmdSkills({ packageRoot, homeDir, cwd, customPath });
+        expect(result.removed).toHaveLength(24);
+        for (const linkPath of result.removed) {
+            expect(() => fs.lstatSync(linkPath)).toThrow();
+        }
+        expect(removeWebcmdSkills({ packageRoot, homeDir, cwd, customPath })).toEqual({ removed: [] });
+    });
+    it('refuses removal before deleting any links when a destination is not a symlink', () => {
+        const packageRoot = makePackageRoot();
+        const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-home-'));
+        const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-project-'));
+        const added = addWebcmdSkills({ packageRoot, homeDir, cwd, provider: 'agents', scope: 'user' });
+        const blocker = path.join(cwd, '.codex', 'skills', 'smart-search');
+        fs.mkdirSync(blocker, { recursive: true });
+        expect(() => removeWebcmdSkills({ packageRoot, homeDir, cwd })).toThrow(ArgumentError);
+        expect(fs.lstatSync(added.skills[0].destination).isSymbolicLink()).toBe(true);
+        expect(fs.lstatSync(blocker).isDirectory()).toBe(true);
+    });
 });

package/hosted-contract.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "webcmdVersion": "0.3.2",
+  "webcmdVersion": "0.3.4",
   "outputFormats": [
     "table",
     "plain",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"
@@ -18,6 +18,7 @@
     "./utils": "./dist/src/utils.js",
     "./logger": "./dist/src/logger.js",
     "./launcher": "./dist/src/launcher.js",
+    "./browser/ax-snapshot": "./dist/src/browser/ax-snapshot.js",
     "./browser/cdp": "./dist/src/browser/cdp.js",
     "./browser/page": "./dist/src/browser/page.js",
     "./browser/utils": "./dist/src/browser/utils.js",
@@ -77,6 +78,7 @@
   ],
   "author": "AgentR",
   "license": "Apache-2.0",
+  "homepage": "https://docs.webcmd.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/agentrhq/webcmd.git"

package/scripts/check-package-bin.mjs

@@ -5,6 +5,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  formatPackageBinSpawnFailure,
+  packageBinSpawnOptions,
+} from '../dist/src/package-bin-process.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
@@ -20,14 +24,11 @@ function run(command, args, opts = {}) {
     cwd: ROOT,
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
+    ...packageBinSpawnOptions(process.platform, command),
     ...opts,
   });
-  if (result.status !== 0) {
-    fail([
-      `${command} ${args.join(' ')} exited ${result.status}`,
-      result.stdout.trim(),
-      result.stderr.trim(),
-    ].filter(Boolean).join('\n'));
+  if (result.error || result.status !== 0) {
+    fail(formatPackageBinSpawnFailure(command, args, result));
   }
   return result;
 }

package/scripts/collect-ci-diagnostics.ps1

@@ -0,0 +1,274 @@
+[CmdletBinding()]
+param(
+  [switch]$SelfTest
+)
+
+$ErrorActionPreference = 'Continue'
+
+function Protect-SensitiveDiagnosticText {
+  param(
+    [AllowEmptyString()][string]$Text
+  )
+
+  $sensitiveLinePattern = '(?i)(?:^|[^a-z0-9])(?:auth(?:[-_]?token)?|authorization|proxy[-_]?authorization|bearer|token|api[-_]?key|secret|password|credentials?|set[-_]?cookie|cookie|cdp(?:[-_\s]?(?:endpoint|url))?|devtools(?:[-_\s]?url)?|live[-_\s]?url|browser[-_\s]?url|websocket[-_\s]?url|ws[-_\s]?url|page[-_\s]?(?:content|text|html)|innerhtml|outerhtml|snapshot)(?:$|[^a-z0-9])|document\.|<html|<body|\b(?:html|body|content)\b\s*"?\s*:'
+  $schemeUrlPattern = '(?i)\b[a-z][a-z0-9+.-]*://[^\s"''<>]+'
+  $sanitized = foreach ($line in ($Text -split "`r?`n")) {
+    if ($line -match $sensitiveLinePattern) {
+      '[REDACTED sensitive diagnostic line]'
+      continue
+    }
+    $line -replace $schemeUrlPattern, '[REDACTED_URL]'
+  }
+
+  return ($sanitized -join [Environment]::NewLine)
+}
+
+function Write-SanitizedText {
+  param(
+    [Parameter(Mandatory = $true)][string]$Path,
+    [AllowEmptyString()][string]$Text
+  )
+
+  Protect-SensitiveDiagnosticText -Text $Text | Set-Content -LiteralPath $Path -Encoding utf8
+}
+
+function Write-SanitizedJson {
+  param(
+    [Parameter(Mandatory = $true)][string]$Path,
+    [Parameter(Mandatory = $true)][AllowNull()][AllowEmptyCollection()]$Value
+  )
+
+  Write-SanitizedText -Path $Path -Text (ConvertTo-Json -InputObject $Value -Depth 20)
+}
+
+function Get-DaemonLogMetadata {
+  param(
+    [Parameter(Mandatory = $true)][AllowNull()]$Response
+  )
+
+  $knownLevels = @('debug', 'info', 'warn', 'error')
+  $logs = if ($null -ne $Response -and $null -ne $Response.logs) { @($Response.logs) } else { @() }
+  $countsByKnownLevel = [ordered]@{}
+  foreach ($knownLevel in $knownLevels) {
+    $countsByKnownLevel[$knownLevel] = 0
+  }
+
+  $unrecognizedLevelCount = 0
+  $timestamps = @()
+  $maximumTimestamp = [DateTimeOffset]::UtcNow.AddDays(1).ToUnixTimeMilliseconds()
+  foreach ($entry in $logs) {
+    $level = if ($null -ne $entry.level) { ([string]$entry.level).ToLowerInvariant() } else { '' }
+    if ($knownLevels -contains $level) {
+      $countsByKnownLevel[$level] += 1
+    } else {
+      $unrecognizedLevelCount += 1
+    }
+
+    $timestamp = 0L
+    if ($null -ne $entry.ts -and [Int64]::TryParse(([string]$entry.ts), [ref]$timestamp) -and $timestamp -ge 0 -and $timestamp -le $maximumTimestamp) {
+      $timestamps += $timestamp
+    }
+  }
+
+  $earliestTimestampUtc = $null
+  $latestTimestampUtc = $null
+  if ($timestamps.Count -gt 0) {
+    $earliestTimestamp = [Int64](($timestamps | Measure-Object -Minimum).Minimum)
+    $latestTimestamp = [Int64](($timestamps | Measure-Object -Maximum).Maximum)
+    $earliestTimestampUtc = [DateTimeOffset]::FromUnixTimeMilliseconds($earliestTimestamp).UtcDateTime.ToString('o')
+    $latestTimestampUtc = [DateTimeOffset]::FromUnixTimeMilliseconds($latestTimestamp).UtcDateTime.ToString('o')
+  }
+
+  return [pscustomobject][ordered]@{
+    totalCount = $logs.Count
+    countsByKnownLevel = [pscustomobject]$countsByKnownLevel
+    unrecognizedLevelCount = $unrecognizedLevelCount
+    earliestTimestampUtc = $earliestTimestampUtc
+    latestTimestampUtc = $latestTimestampUtc
+  }
+}
+
+function Test-CloakDiagnosticLogName {
+  param(
+    [Parameter(Mandatory = $true)][string]$Name
+  )
+
+  return $Name.EndsWith('.log', [StringComparison]::OrdinalIgnoreCase) -or
+    $Name.Equals('LOG', [StringComparison]::OrdinalIgnoreCase) -or
+    $Name.Equals('LOG.old', [StringComparison]::OrdinalIgnoreCase)
+}
+
+function Get-CloakLogFileMetadata {
+  param(
+    [Parameter(Mandatory = $true)][string]$Root,
+    [Parameter(Mandatory = $true)]$File
+  )
+
+  return [pscustomobject][ordered]@{
+    relativePath = [System.IO.Path]::GetRelativePath($Root, $File.FullName)
+    bytes = $File.Length
+    lastWriteUtc = $File.LastWriteTimeUtc.ToString('o')
+  }
+}
+
+function Assert-DiagnosticsSelfTest {
+  param(
+    [Parameter(Mandatory = $true)][bool]$Condition,
+    [Parameter(Mandatory = $true)][string]$Message
+  )
+
+  if (-not $Condition) {
+    throw "Diagnostics self-test failed: $Message"
+  }
+}
+
+function Invoke-DiagnosticsSelfTest {
+  $sensitiveSamples = @(
+    'auth: sensitive-value',
+    'authToken: sensitive-value',
+    'auth_token: sensitive-value',
+    'authorization: Bearer sensitive-value',
+    'bearer sensitive-value',
+    'token: sensitive-value',
+    'api-key: sensitive-value',
+    'api_key: sensitive-value',
+    'apiKey: sensitive-value',
+    'secret: sensitive-value',
+    'password: sensitive-value',
+    'credentials: sensitive-value',
+    'cookie: sensitive-value',
+    'cdpUrl: ws://127.0.0.1/devtools/sensitive-value',
+    'cdp_url: ws://127.0.0.1/devtools/sensitive-value',
+    'CDP endpoint: ws://127.0.0.1/devtools/sensitive-value',
+    'liveUrl: https://example.test/sensitive-value',
+    'live_url: https://example.test/sensitive-value',
+    'live URL: https://example.test/sensitive-value',
+    'scheme only https://example.test/sensitive-value'
+  )
+  foreach ($sample in $sensitiveSamples) {
+    $protected = Protect-SensitiveDiagnosticText -Text $sample
+    Assert-DiagnosticsSelfTest -Condition (-not $protected.Contains('sensitive-value')) -Message "sensitive sample survived: $sample"
+  }
+
+  $unlabeledPageText = 'Customer account balance is 1234 and the recovery phrase is violet quartz'
+  $syntheticLogs = [pscustomobject]@{
+    ok = $true
+    logs = @(
+      [pscustomobject]@{ level = 'warn'; msg = $unlabeledPageText; text = 'private text'; value = 'private value'; data = @{ private = $true }; ts = 1704067200000 },
+      [pscustomobject]@{ level = 'info'; msg = 'https://example.test/private'; ts = 1704153600000 },
+      [pscustomobject]@{ level = 'custom'; msg = 'secret but unlabeled'; ts = -1 }
+    )
+  }
+  $metadata = Get-DaemonLogMetadata -Response $syntheticLogs
+  $metadataJson = ConvertTo-Json -InputObject $metadata -Depth 5
+  Assert-DiagnosticsSelfTest -Condition ($metadata.totalCount -eq 3) -Message 'daemon log total count is incorrect'
+  Assert-DiagnosticsSelfTest -Condition ($metadata.countsByKnownLevel.warn -eq 1 -and $metadata.countsByKnownLevel.info -eq 1) -Message 'known daemon log level counts are incorrect'
+  Assert-DiagnosticsSelfTest -Condition ($metadata.unrecognizedLevelCount -eq 1) -Message 'unrecognized daemon log level count is incorrect'
+  Assert-DiagnosticsSelfTest -Condition ($metadata.earliestTimestampUtc -eq '2024-01-01T00:00:00.0000000Z') -Message 'earliest bounded timestamp is incorrect'
+  Assert-DiagnosticsSelfTest -Condition ($metadata.latestTimestampUtc -eq '2024-01-02T00:00:00.0000000Z') -Message 'latest bounded timestamp is incorrect'
+  Assert-DiagnosticsSelfTest -Condition (-not $metadataJson.Contains($unlabeledPageText)) -Message 'unlabeled page text survived daemon metadata projection'
+  Assert-DiagnosticsSelfTest -Condition ($metadataJson -notmatch '(?i)"(?:msg|text|value|data)"\s*:') -Message 'free-form daemon fields survived metadata projection'
+  Assert-DiagnosticsSelfTest -Condition (($metadata.PSObject.Properties.Name -join ',') -eq 'totalCount,countsByKnownLevel,unrecognizedLevelCount,earliestTimestampUtc,latestTimestampUtc') -Message 'daemon metadata contains a non-allowlisted field'
+
+  $diagnosticLogNames = @('browser.log', 'debug.log', 'LOG', 'LOG.old')
+  foreach ($name in $diagnosticLogNames) {
+    Assert-DiagnosticsSelfTest -Condition (Test-CloakDiagnosticLogName -Name $name) -Message "known diagnostic log name was rejected: $name"
+  }
+  foreach ($name in @('Login Data', 'catalog.json', 'debug.txt', 'LOG.bak')) {
+    Assert-DiagnosticsSelfTest -Condition (-not (Test-CloakDiagnosticLogName -Name $name)) -Message "non-log profile file was accepted: $name"
+  }
+
+  $syntheticFile = [pscustomobject]@{
+    FullName = Join-Path ([System.IO.Path]::GetTempPath()) 'debug.log'
+    Length = 42
+    LastWriteTimeUtc = [DateTime]::Parse('2024-01-03T00:00:00Z').ToUniversalTime()
+    SensitiveContent = 'cookie=sensitive-value'
+  }
+  $fileMetadata = Get-CloakLogFileMetadata -Root ([System.IO.Path]::GetTempPath()) -File $syntheticFile
+  $fileMetadataJson = ConvertTo-Json -InputObject $fileMetadata -Depth 3
+  Assert-DiagnosticsSelfTest -Condition (($fileMetadata.PSObject.Properties.Name -join ',') -eq 'relativePath,bytes,lastWriteUtc') -Message 'Cloak file metadata contains a non-allowlisted field'
+  Assert-DiagnosticsSelfTest -Condition (-not $fileMetadataJson.Contains('sensitive-value')) -Message 'Cloak file contents survived metadata projection'
+
+  Write-Host 'Diagnostics self-test passed.'
+}
+
+if ($SelfTest) {
+  $ErrorActionPreference = 'Stop'
+  Invoke-DiagnosticsSelfTest
+  return
+}
+
+$artifactRoot = Join-Path $PWD 'artifacts/windows-cloak'
+New-Item -ItemType Directory -Path $artifactRoot -Force | Out-Null
+
+$runnerMetadata = [ordered]@{
+  collectedAtUtc = (Get-Date).ToUniversalTime().ToString('o')
+  nodeVersion = (& node --version 2>&1 | Out-String).Trim()
+  npmVersion = (& npm --version 2>&1 | Out-String).Trim()
+  runner = [ordered]@{
+    os = $env:RUNNER_OS
+    architecture = $env:RUNNER_ARCH
+    imageOs = $env:ImageOS
+    imageVersion = $env:ImageVersion
+    machineName = $env:COMPUTERNAME
+  }
+  github = [ordered]@{
+    runId = $env:GITHUB_RUN_ID
+    runAttempt = $env:GITHUB_RUN_ATTEMPT
+    sha = $env:GITHUB_SHA
+  }
+}
+
+try {
+  $windows = Get-CimInstance Win32_OperatingSystem -ErrorAction Stop
+  $runnerMetadata['windows'] = [ordered]@{
+    caption = $windows.Caption
+    version = $windows.Version
+    buildNumber = $windows.BuildNumber
+  }
+} catch {
+  $runnerMetadata['windows'] = @{ error = 'Windows metadata unavailable' }
+}
+Write-SanitizedJson -Path (Join-Path $artifactRoot 'runner-metadata.json') -Value $runnerMetadata
+
+$headers = @{ 'X-Webcmd' = '1' }
+try {
+  $daemonStatus = Invoke-RestMethod -Uri 'http://127.0.0.1:9777/status' -Headers $headers -TimeoutSec 5
+  Write-SanitizedJson -Path (Join-Path $artifactRoot 'daemon-status.json') -Value $daemonStatus
+} catch {
+  Write-SanitizedText -Path (Join-Path $artifactRoot 'daemon-status.txt') -Text 'Daemon status unavailable.'
+}
+
+try {
+  $daemonLogs = Invoke-RestMethod -Uri 'http://127.0.0.1:9777/logs' -Headers $headers -TimeoutSec 5
+  $daemonLogMetadata = Get-DaemonLogMetadata -Response $daemonLogs
+  Write-SanitizedJson -Path (Join-Path $artifactRoot 'daemon-log-metadata.json') -Value $daemonLogMetadata
+} catch {
+  Write-SanitizedText -Path (Join-Path $artifactRoot 'daemon-log-metadata.txt') -Text 'Daemon log metadata unavailable.'
+}
+
+$processMetadata = Get-Process -ErrorAction SilentlyContinue |
+  Where-Object { $_.ProcessName -match '(?i)^(node|chrome|chromium|cloak)' } |
+  ForEach-Object {
+    [ordered]@{
+      name = $_.ProcessName
+      id = $_.Id
+      startedAtUtc = if ($_.StartTime) { $_.StartTime.ToUniversalTime().ToString('o') } else { $null }
+      workingSetBytes = $_.WorkingSet64
+      cpuSeconds = $_.CPU
+    }
+  }
+Write-SanitizedJson -Path (Join-Path $artifactRoot 'process-metadata.json') -Value @($processMetadata)
+
+$cloakRoot = if ($env:USERPROFILE) { Join-Path $env:USERPROFILE '.webcmd/cloak' } else { $null }
+$cloakLogMetadata = @()
+if ($cloakRoot -and (Test-Path -LiteralPath $cloakRoot)) {
+  $cloakLogMetadata = Get-ChildItem -LiteralPath $cloakRoot -Recurse -File -ErrorAction SilentlyContinue |
+    Where-Object { Test-CloakDiagnosticLogName -Name $_.Name } |
+    ForEach-Object {
+      Get-CloakLogFileMetadata -Root $cloakRoot -File $_
+    }
+}
+Write-SanitizedJson -Path (Join-Path $artifactRoot 'cloak-log-metadata.json') -Value @($cloakLogMetadata)
+
+Write-Host "Sanitized diagnostics written to $artifactRoot"

package/scripts/docs-sync-review.ts

@@ -223,7 +223,7 @@ export async function generateGeminiReview(
       responseMimeType: 'application/json',
       responseJsonSchema: REVIEW_JSON_SCHEMA,
       temperature: 0.1,
-      abortSignal: AbortSignal.timeout(60_000),
+      abortSignal: AbortSignal.timeout(180_000),
     },
   });
   const text = response.text?.trim();

package/skills/smart-search/SKILL.md

@@ -11,10 +11,24 @@ Route a query to the best webcmd search source based on the topic and context. T
 
 Before every use, do both of these steps:
 
-- Run `webcmd list -f json`
-- Use the live registry to confirm that candidate sites exist, and inspect `strategy`, `browser`, and `domain`
+- Derive literal workflow terms from the requested action, entity, output fields, and any explicitly named site, then filter the live registry before it reaches bounded agent output:
 
-If the user explicitly names a site/source and it is missing from `webcmd list` or when none of the sites cover the query, check installable plugins before marking it unavailable:
+  ```bash
+  WORKFLOW_TERMS='["requested action", "output field", "named site"]'
+  webcmd list -f json | jq --argjson terms "$WORKFLOW_TERMS" '
+    [.[] | select(
+      ([.site, .name, .description, ((.columns // []) | join(" "))]
+        | map(. // "") | join(" ") | ascii_downcase) as $text
+      | any($terms[]; . as $term | $text | contains($term | ascii_downcase))
+    )]
+  '
+  ```
+
+- Use the complete, non-truncated filtered registry to confirm that candidate sites exist, and inspect `strategy`, `browser`, and `domain`
+
+Any truncation warning from registry or plugin output means the inspection is incomplete. Narrow the filter or query and inspect again; absence from truncated output never proves a site, command, or plugin is unavailable. Do not search plugins until a complete filtered registry result for the missing capability is exactly `[]`, and do not use raw browser fallback until plugin output is also complete and non-truncated.
+
+If the user explicitly names a site/source, or no installed command covers the query, refine the filter for that missing site or capability. Only when the complete filtered result is `[]`, check installable plugins before marking it unavailable:
 
 ```bash
 webcmd plugin search <site-or-source-or-capability> -f json
@@ -22,7 +36,7 @@ webcmd plugin search <site-or-source-or-capability> -f json
 
 Derive a short plugin query from the missing site or capability. Preserve the user's term when practical: `find flights` becomes `flight`.
 
-If plugin search finds a match, tell the user it is available as a plugin and offer `webcmd plugin install <source>`. If plugin search fails because catalog sources cannot be fetched, report that catalog/search error separately from no plugin match.
+If a complete, non-truncated plugin search finds a match, tell the user it is available as a plugin and offer `webcmd plugin install <source>`. If plugin search is truncated, refine it before fallback. If it fails because catalog sources cannot be fetched, report that catalog/search error separately from no plugin match.
 
 After choosing a site, do both of these steps:
 
@@ -144,12 +158,12 @@ Keep a typical query to 1 AI source plus 1-2 specialized sources to avoid result
 When a site is unavailable:
 
 - Do not stop the whole search because one source failed
-- For a missing site or capability, run `webcmd plugin search <query> -f json` before recording unavailable
+- For a missing site or capability, first require a complete filtered registry result of `[]`, then run `webcmd plugin search <query> -f json` before recording unavailable
 - 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 json`, `webcmd plugin search -f json`, 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.
+Do not assume any site is always available. Even for public sites, trust complete, non-truncated live registry and plugin output, live help, and execution results in the current environment. Raw browser fallback requires both the complete `[]` registry result and a complete, non-truncated plugin search that returned no match and no error.
 
 ## Reference Files
 

package/skills/webcmd-adapter-author/SKILL.md

@@ -175,7 +175,7 @@ Check these off step by step:
        [ ] Order: identifier columns -> business numbers -> metadata.
 
 [ ] 9. Write the adapter (`adapter-template.md`):
-       [ ] `webcmd browser init <site>/<name> --strategy <strategy>`
+       [ ] `webcmd browser init <site>/<name>`, then set `strategy: Strategy.<strategy>` in the generated file
        [ ] Find the closest same-site or same-type adapter and copy it.
        [ ] Edit name, URL, and field mapping.
 

package/skills/webcmd-adapter-author/references/adapter-template.md

@@ -7,14 +7,10 @@ Use this after recon, endpoint verification, field decoding, output design, and
 For private iteration:
 
 ```bash
-webcmd browser init <site>/<name> --strategy <strategy>
+webcmd browser init <site>/<name>
 ```
 
-Write the working file at:
-
-```text
-~/.webcmd/clis/<site>/<name>.js
-```
+This scaffolds `~/.webcmd/clis/<site>/<name>.js` with a `Strategy.PUBLIC` placeholder — `init` takes no flags, so set the real `strategy:` value (and the other `TODO` fields) by hand once the file exists.
 
 Promote a community CLI to the main repo as a plugin:
 

package/skills/webcmd-browser/SKILL.md

@@ -12,13 +12,26 @@ This skill is for **driving a live browser** to accomplish an agent task. If you
 
 ---
 
+## Adapter fallback gate
+
+Before starting a raw browser session, filter `webcmd list -f json` at the source using request-derived terms across `site`, `name`, `description`, and `columns`; follow `webcmd-usage` for the command shape. Any truncation warning means adapter discovery is incomplete: narrow the filter and inspect again. Absence from truncated output never proves that no adapter exists.
+
+Raw `webcmd browser` use is allowed only after both conditions hold:
+
+1. The complete, non-truncated filtered registry result for the missing capability is exactly `[]`.
+2. A complete, non-truncated `webcmd plugin search <capability> -f json` result returns no match and no error.
+
+If plugin search returns a match, offer installation. If its output is truncated, refine the query or output and inspect again. If it errors, report the error and stop instead of opening the browser.
+
+---
+
 ## Prerequisites
 
 ```bash
 webcmd doctor
 ```
 
-Until `doctor` is green, nothing else will work. Typical failures: Chrome not running, extension not installed, debug port blocked by 1Password / other extensions. The doctor output tells you which.
+Until `doctor` is green, browser commands will not work. Registry and plugin discovery do not require `doctor`. Typical failures: Chrome not running, extension not installed, debug port blocked by 1Password / other extensions. The doctor output tells you which.
 
 ---
 
@@ -61,7 +74,7 @@ Bound sessions use the normal Webcmd session lifecycle; `unbind` releases the Cl
 ## Critical rules
 
 1. **Always inspect before you act.** Run `state` or `find` first. Never hard-code a ref or selector from memory across sessions — indices are per-snapshot.
-2. **Prefer site adapters before raw browser driving.** If `webcmd <site> <command>` already covers the task, use that adapter command first (`webcmd facebook notifications`, `webcmd reddit read`, `webcmd chatgpt model <level>`, etc.). Use `webcmd browser ...` only for gaps, debugging, or one-off UI flows the adapter does not expose.
+2. **Prefer site adapters before raw browser driving.** Complete the adapter fallback gate above. If `webcmd <site> <command>` already covers the task, use that adapter command first (`webcmd facebook notifications`, `webcmd reddit read`, `webcmd chatgpt model <level>`, etc.). Use `webcmd browser ...` only for gaps, debugging, or one-off UI flows the adapter does not expose.
 3. **Prefer numeric ref over CSS once you have it.** Numeric refs survive mild DOM shifts because the CLI fingerprints each tagged element. A CSS selector written by hand will break the first time the site re-renders.
 4. **Read `match_level` after every write.** `exact` = all good. `stable` = the element is the same but some soft attrs drifted — your action still applied. `reidentified` = the original ref was gone and the CLI found a unique replacement; double-check you hit the right element.
 5. **Use the `compound` field for form controls.** Do not regex-guess a date format, do not `state` twice to get the full `<select>` options list. The compound envelope has the format string, full option list up to 50, `options_total` for overflow, and `accept`/`multiple` for `<input type=file>`.
@@ -433,6 +446,7 @@ normal DOM `state`, or navigate/bind directly to the iframe URL when possible.
 | `stale_ref` across every command | You are reusing refs from a prior page. Re-`state`. |
 | `click` succeeds but nothing happens | The element is probably a decorative wrapper stealing clicks from the real target. `find --css "..."` with a narrower selector and retry on the inner element. |
 | `type` appears to finish but value is wrong | Autocomplete, masked input, or React controlled re-render. Verify with `get value`. Add `keys Enter` or re-type. |
+| `webcmd list -f json` output is truncated | Adapter discovery is incomplete. Filter at the source with request-derived terms and narrow until the complete result is `[]`; do not start browser fallback yet. |
 | Giant `get html` output | Pass `--selector` + `--as json --depth 3 --children-max 20 --text-max 200`. |
 | Network cache seems stale | Bump `--ttl` down, or let it expire. The cache lives at `~/.webcmd/cache/browser-network/`. |
 

package/skills/webcmd-usage/SKILL.md

@@ -50,19 +50,33 @@ Run commands instead of reading static docs:
 
 ```bash
 webcmd
-webcmd list -f json
 webcmd <site> --help
 webcmd <site> <command> --help
 ```
 
 Run `webcmd` with no arguments to see all available functions and installed site adapters. Do not hard-code adapter lists: `webcmd list -f json` is the source of truth for installed commands and emits one entry per command with fields such as `{site, name, aliases, description, strategy, browser, args, columns}`.
 
+Large registries can exceed an agent or tool output budget. Filter the JSON stream before it is emitted, using broad literal terms derived from the whole requested workflow:
+
+```bash
+WORKFLOW_TERMS='["requested action", "output field", "named site"]'
+webcmd list -f json | jq --argjson terms "$WORKFLOW_TERMS" '
+  [.[] | select(
+    ([.site, .name, .description, ((.columns // []) | join(" "))]
+      | map(. // "") | join(" ") | ascii_downcase) as $text
+    | any($terms[]; . as $term | $text | contains($term | ascii_downcase))
+  )]
+'
+```
+
+Replace `WORKFLOW_TERMS` with terms from the current request: the requested action, entity, output fields, and any explicitly named site. Literal matching avoids regex errors from terms such as `C++` or `[foo]`. Do not maintain a site or category allowlist. Match across `site`, `name`, `description`, and `columns`. If any layer reports truncated output, the inspection is incomplete. Narrow the filter and inspect again. Never treat absence from truncated output as proof that an adapter or plugin is missing, and do not proceed to the next fallback stage from that evidence.
+
 Use this fallback order:
 
-1. Run `webcmd list -f json` once.
-2. Check that result against the whole requested workflow, not only a named site. If one installed command covers it, use that command and stop discovery.
-3. If none covers it, derive a short plugin query from the missing site or capability and run `webcmd plugin search <query> -f json`. Preserve the user's term when practical: `find flights` becomes `flight`.
-4. If plugin search returns a match, offer `webcmd plugin install <installSource>`. If it returns no match and no error, raw `webcmd browser` is allowed. If it errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve.
+1. Run `webcmd list -f json` through a workflow-derived filter before returning its output to the agent.
+2. Check the complete, non-truncated filtered result against the whole requested workflow. If one installed command covers it, use that command and stop discovery. If candidates do not cover the missing capability, refine the capability filter until its complete result is exactly `[]`.
+3. Only after that complete filtered result is `[]`, derive a short plugin query from the missing site or capability and run `webcmd plugin search <query> -f json`. Preserve the user's term when practical: `find flights` becomes `flight`.
+4. If the complete, non-truncated plugin search returns a match, offer `webcmd plugin install <installSource>`. Only if that complete result returns no match and no error is raw `webcmd browser` allowed. Both plugin search and raw browser fallback require the prior complete filtered registry result to be `[]`. A truncated plugin result is incomplete evidence: refine the query or output before fallback. If plugin search errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve.
 
 ## Universal Flags
 
@@ -194,6 +208,7 @@ Do not invoke these removed commands:
 
 ## Do Not
 
-- Do not paste static command lists into plans; call `webcmd list -f json`.
+- Do not paste static command lists into plans; query `webcmd list -f json` through a workflow-derived filter.
+- Do not emit a large unfiltered registry into a bounded output or infer absence from a truncation warning; filter at the source and narrow until the result is complete.
 - Do not assume every adapter needs a browser; check `strategy`.
 - Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first.