@dotsetlabs/bellwether 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.2] - 2026-02-16
+
+### Added
+
+- **Remote MCP header auth support** across config, transport, and CLI:
+  - `server.headers` and `discovery.headers` configuration
+  - `-H/--header` overrides on `check`, `explore`, and `discover`
+  - `ServerAuthError` classification with auth-aware retry behavior
+- **Header parsing utilities and tests** for validated, case-insensitive CLI/config header merging.
+
+### Changed
+
+- **Remote diagnostics and guidance**: improved auth/connection error hints in `check`, `explore`, `discover`, and `watch`.
+- **Capability handling**: `check`/`explore` now continue when prompts/resources exist even if no tools are exposed.
+- **Documentation refresh** across README + website guides/CLI references to align with current auth, config, and command behavior.
+- **Release consistency tooling**: simplified consistency validation by removing checks tied to deleted policy files.
+
+### Fixed
+
+- **Remote preflight stream cleanup**: preflight now cancels response bodies to avoid leaving open remote streams before transport initialization.
+- **Broken documentation links and stale examples**: removed/updated outdated references and invalid CLI examples.
+
+### Removed
+
+- **Man page generation and distribution** (`man/`, `scripts/generate-manpage.sh`, `man:generate` script).
+- **Husky/lint-staged workflow** and related hook files.
+- **Repository files no longer maintained** (`ROADMAP.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`).
+
+## [2.1.1] - 2026-02-14
+
+### Changed
+
+- **Product focus tightening**: Clarified the core workflow (`init`, `check`, `baseline`) and repositioned advanced commands as opt-in in CLI/docs.
+- **Release quality hardening**: Added stronger consistency checks and documentation alignment to reduce drift between code behavior and published guidance.
+
 ## [2.1.0] - 2026-02-11
 
 ### Changed

package/README.md

@@ -31,6 +31,15 @@ bellwether check
 
 That's it. No API keys. No LLM costs. Runs in seconds.
 
+## Product Focus
+
+Bellwether is intentionally opinionated:
+
+- **Core workflow (default)**: `init` -> `check` -> `baseline`
+- **Advanced workflow (opt-in)**: `explore`, `watch`, `discover`, `golden`, `contract`, `registry`
+
+If you only need CI-safe drift detection, you can stay entirely in the core workflow.
+
 ## Two Modes
 
 | Mode | Purpose | Cost | When to Use |
@@ -85,45 +94,29 @@ jobs:
 
 Comparisons are **protocol-version-aware** — version-specific fields (annotations, titles, output schemas, etc.) are only compared when both baselines support the relevant MCP protocol version.
 
-## Commands
-
-### Essential Commands
-
-```bash
-bellwether init <server-command>   # Create config
-bellwether check                   # Detect drift (free, deterministic)
-bellwether baseline save           # Save baseline to compare against
-bellwether baseline compare        # Compare current vs saved baseline
-```
-
-### Explore Command (Optional)
+## Command Tiers
 
-```bash
-bellwether init --preset local npx @mcp/server  # Uses Ollama (free)
-bellwether explore                              # LLM-powered testing
-```
+### Core Commands (Recommended)
 
-Requires LLM (Ollama for free local, or OpenAI/Anthropic). Generates `AGENTS.md` with behavioral documentation.
+| Command | Purpose |
+|:--------|:--------|
+| `init` | Create `bellwether.yaml` |
+| `check` | Deterministic schema drift detection |
+| `baseline save` | Save snapshot for future comparisons |
+| `baseline compare` | Compare latest check output to saved baseline |
 
-### All Commands
+### Advanced Commands (Optional)
 
 | Command | Purpose |
 |:--------|:--------|
-| `init` | Create `bellwether.yaml` config |
-| `check` | Schema drift detection (free) |
-| `explore` | LLM behavioral testing |
-| `baseline save` | Save test results as baseline |
-| `baseline compare` | Compare against baseline |
-| `baseline show` | Display baseline contents |
-| `baseline accept` | Accept drift as intentional |
-| `baseline diff` | Compare two baselines |
-| `discover` | Show server capabilities |
+| `explore` | LLM behavioral testing and `AGENTS.md` generation |
 | `watch` | Continuous checking on file changes |
+| `discover` | Capability inspection without tests |
 | `registry` | Search MCP Registry |
 | `golden` | Golden output regression testing |
-| `contract` | Contract validation (generate/validate/show) |
+| `contract` | Contract validation and generation |
 | `auth` | Manage LLM provider API keys |
-| `validate-config` | Validate bellwether.yaml without running tests |
+| `validate-config` | Validate `bellwether.yaml` without running tests |
 
 ## CI/CD Exit Codes
 
@@ -139,9 +132,9 @@ Requires LLM (Ollama for free local, or OpenAI/Anthropic). Generates `AGENTS.md`
 ## GitHub Action
 
 ```yaml
-- uses: dotsetlabs/bellwether@v2.0.0
+- uses: dotsetlabs/bellwether@v2.1.2
   with:
-    version: '2.0.0'
+    version: '2.1.2'
     server-command: 'npx @mcp/your-server'
     baseline-path: './bellwether-baseline.json'
     fail-on-severity: 'warning'
@@ -157,6 +150,22 @@ bellwether init --preset ci npx @mcp/server    # Optimized for CI/CD
 bellwether init --preset local npx @mcp/server # Local Ollama (free)
 ```
 
+For remote MCP servers that require auth headers, configure:
+
+```yaml
+server:
+  transport: sse
+  url: "https://api.example.com/mcp"
+  headers:
+    Authorization: "Bearer ${MCP_SERVER_TOKEN}"
+```
+
+Or use one-off CLI overrides:
+
+```bash
+bellwether check -H "Authorization: Bearer $MCP_SERVER_TOKEN"
+```
+
 ## Environment Variables
 
 | Variable | Description |
@@ -170,8 +179,16 @@ bellwether init --preset local npx @mcp/server # Local Ollama (free)
 **[docs.bellwether.sh](https://docs.bellwether.sh)** — Full reference for configuration and commands.
 
 - [Quick Start](https://docs.bellwether.sh/quickstart)
+- [Core vs Advanced](https://docs.bellwether.sh/concepts/core-vs-advanced)
 - [CLI Reference](https://docs.bellwether.sh/cli/init)
 - [CI/CD Integration](https://docs.bellwether.sh/guides/ci-cd)
+- [Golden Paths](https://docs.bellwether.sh/guides/golden-paths)
+- [Compatibility Policy](https://docs.bellwether.sh/concepts/compatibility-policy)
+
+## Project Governance
+
+- [Changelog](./CHANGELOG.md)
+- [Releases](https://github.com/dotsetlabs/bellwether/releases)
 
 ## Community
 

package/dist/cli/commands/check.js

@@ -29,6 +29,8 @@ import { configureLogger } from '../../logging/logger.js';
 import { buildInterviewInsights } from '../../interview/insights.js';
 import { EXIT_CODES, SEVERITY_TO_EXIT_CODE, PATHS, SECURITY_TESTING, CHECK_SAMPLING, WORKFLOW, REPORT_SCHEMAS, PERCENTAGE_CONVERSION, MCP, } from '../../constants.js';
 import { getFeatureFlags, getExcludedFeatureNames } from '../../protocol/index.js';
+import { ServerAuthError } from '../../errors/types.js';
+import { mergeHeaders, parseCliHeaders } from '../utils/headers.js';
 export const checkCommand = new Command('check')
     .description('Check MCP server schema and detect drift (free, fast, deterministic)')
     .allowUnknownOption() // Allow server flags like -y for npx to pass through
@@ -41,6 +43,7 @@ export const checkCommand = new Command('check')
     .option('--format <format>', 'Diff output format: text, json, compact, github, markdown, junit, sarif')
     .option('--min-severity <level>', 'Minimum severity to report (overrides config): none, info, warning, breaking')
     .option('--fail-on-severity <level>', 'Fail threshold (overrides config): none, info, warning, breaking')
+    .option('-H, --header <header...>', 'Custom headers for remote MCP requests (e.g., "Authorization: Bearer token")')
     .action(async (serverCommandArg, serverArgs, options) => {
     // Load configuration
     let config;
@@ -67,6 +70,16 @@ export const checkCommand = new Command('check')
     const transport = config.server.transport ?? 'stdio';
     const remoteUrl = config.server.url?.trim();
     const remoteSessionId = config.server.sessionId?.trim();
+    const configRemoteHeaders = config.server.headers;
+    let cliHeaders;
+    try {
+        cliHeaders = parseCliHeaders(options.header);
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const remoteHeaders = mergeHeaders(configRemoteHeaders, cliHeaders);
     // Validate config for check
     try {
         validateConfigForCheck(config, serverCommand);
@@ -193,6 +206,7 @@ export const checkCommand = new Command('check')
             await mcpClient.connectRemote(remoteUrl, {
                 transport,
                 sessionId: remoteSessionId || undefined,
+                headers: remoteHeaders,
             });
         }
         // Discovery phase
@@ -255,12 +269,18 @@ export const checkCommand = new Command('check')
             toolsDiscovered: discovery.tools.length,
             personasUsed: 0, // No personas in check mode
         });
-        if (discovery.tools.length === 0) {
-            output.info('No tools found. Nothing to check.');
+        const hasInterviewTargets = discovery.tools.length > 0 ||
+            discovery.prompts.length > 0 ||
+            (discovery.resources?.length ?? 0) > 0;
+        if (!hasInterviewTargets) {
+            output.info('No tools, prompts, or resources found. Nothing to check.');
             metricsCollector.endInterview();
             await mcpClient.disconnect();
             return;
         }
+        if (discovery.tools.length === 0) {
+            output.info('No tools found; continuing with prompt/resource checks.');
+        }
         // Incremental checking - load baseline and determine which tools to test
         let incrementalBaseline = null;
         let incrementalResult = null;
@@ -948,17 +968,40 @@ export const checkCommand = new Command('check')
         const errorMessage = error instanceof Error ? error.message : String(error);
         output.error('\n--- Check Failed ---');
         output.error(`Error: ${errorMessage}`);
-        if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
+        const isRemoteTransport = transport !== 'stdio';
+        if (error instanceof ServerAuthError ||
+            errorMessage.includes('401') ||
+            errorMessage.includes('403') ||
+            errorMessage.includes('407') ||
+            /unauthorized|forbidden|authentication|authorization/i.test(errorMessage)) {
+            output.error('\nAuthentication failed:');
+            output.error('  - Add server.headers.Authorization in bellwether.yaml');
+            output.error('  - Or pass --header "Authorization: Bearer $TOKEN"');
+            output.error('  - Verify credentials are valid and not expired');
+        }
+        else if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
+            output.error('\nPossible causes:');
+            if (isRemoteTransport) {
+                output.error('  - The remote MCP server is not reachable');
+                output.error('  - The server URL/port is incorrect');
+            }
+            else {
+                output.error('  - The MCP server is not running');
+                output.error('  - The server address/port is incorrect');
+            }
+        }
+        else if (isRemoteTransport && errorMessage.includes('HTTP 404')) {
             output.error('\nPossible causes:');
-            output.error('  - The MCP server is not running');
-            output.error('  - The server address/port is incorrect');
+            output.error('  - The remote MCP URL is incorrect');
+            output.error('  - For SSE transport, verify the server exposes /sse');
         }
         else if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
             output.error('\nPossible causes:');
             output.error('  - The MCP server is taking too long to respond');
             output.error('  - Increase server.timeout in bellwether.yaml');
         }
-        else if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
+        else if (!isRemoteTransport &&
+            (errorMessage.includes('ENOENT') || errorMessage.includes('not found'))) {
             output.error('\nPossible causes:');
             output.error('  - The server command was not found');
             output.error('  - Check that the command is installed and in PATH');

package/dist/cli/commands/dashboard.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare const dashboardCommand: Command;
+//# sourceMappingURL=dashboard.d.ts.map

package/dist/cli/commands/dashboard.js

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+import { EXIT_CODES } from '../../constants.js';
+import { startDashboard } from '../../dashboard/index.js';
+import * as output from '../output.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 7331;
+function parsePort(rawPort) {
+    const parsed = Number.parseInt(rawPort, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        throw new Error(`Invalid port "${rawPort}". Use a value between 1 and 65535.`);
+    }
+    return parsed;
+}
+export const dashboardCommand = new Command('dashboard')
+    .description('Start local web dashboard for Bellwether')
+    .option('--host <host>', 'Host interface to bind', DEFAULT_HOST)
+    .option('-p, --port <port>', 'Port to listen on', String(DEFAULT_PORT))
+    .action(async (options) => {
+    const host = String(options.host ?? DEFAULT_HOST).trim();
+    let port;
+    try {
+        port = parsePort(String(options.port ?? DEFAULT_PORT));
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
+        return;
+    }
+    try {
+        const dashboard = await startDashboard({
+            host,
+            port,
+            cwd: process.cwd(),
+            cliEntrypoint: process.argv[1],
+        });
+        output.info('Bellwether Dashboard');
+        output.info(`URL: ${dashboard.url}`);
+        output.info('Available profiles: check, explore, validate-config, discover, watch, baseline.save, baseline.compare, baseline.show, baseline.diff, baseline.accept, registry.search, contract.validate, contract.generate, contract.show, golden.save, golden.compare, golden.list, golden.delete');
+        output.info('Press Ctrl+C to stop.');
+        let shuttingDown = false;
+        const shutdown = async (signal) => {
+            if (shuttingDown) {
+                return;
+            }
+            shuttingDown = true;
+            output.info(`\nReceived ${signal}. Stopping dashboard...`);
+            try {
+                await dashboard.stop();
+            }
+            catch (error) {
+                output.error(error instanceof Error ? error.message : String(error));
+                process.exit(EXIT_CODES.ERROR);
+                return;
+            }
+            process.exit(EXIT_CODES.CLEAN);
+        };
+        process.on('SIGINT', () => {
+            void shutdown('SIGINT');
+        });
+        process.on('SIGTERM', () => {
+            void shutdown('SIGTERM');
+        });
+    }
+    catch (error) {
+        output.error(`Failed to start dashboard: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+//# sourceMappingURL=dashboard.js.map

package/dist/cli/commands/discover.js

@@ -4,6 +4,8 @@ import { discover, summarizeDiscovery } from '../../discovery/discovery.js';
 import { EXIT_CODES } from '../../constants.js';
 import { loadConfig, ConfigNotFoundError } from '../../config/loader.js';
 import * as output from '../output.js';
+import { ServerAuthError } from '../../errors/types.js';
+import { mergeHeaders, parseCliHeaders } from '../utils/headers.js';
 /**
  * Action handler for the discover command.
  */
@@ -28,6 +30,16 @@ async function discoverAction(command, args, options) {
     const outputJson = options.json ?? config?.discovery?.json ?? false;
     const remoteUrl = options.url ?? config?.discovery?.url;
     const sessionId = options.sessionId ?? config?.discovery?.sessionId;
+    const configuredHeaders = mergeHeaders(config?.server?.headers, config?.discovery?.headers);
+    let cliHeaders;
+    try {
+        cliHeaders = parseCliHeaders(options.header);
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const headers = mergeHeaders(configuredHeaders, cliHeaders);
     // Validate transport options
     if (isRemoteTransport && !remoteUrl) {
         output.error(`Error: --url is required when using --transport ${transportType}`);
@@ -49,10 +61,11 @@ async function discoverAction(command, args, options) {
             await client.connectRemote(remoteUrl, {
                 transport: transportType,
                 sessionId,
+                headers,
             });
         }
         else {
-            await client.connect(command, args);
+            await client.connect(command, args, config?.server?.env);
         }
         output.info('Discovering capabilities...\n');
         const result = await discover(client, isRemoteTransport ? remoteUrl : command, isRemoteTransport ? [] : args);
@@ -83,7 +96,15 @@ async function discoverAction(command, args, options) {
         }
     }
     catch (error) {
-        output.error(`Discovery failed: ${error instanceof Error ? error.message : String(error)}`);
+        const message = error instanceof Error ? error.message : String(error);
+        output.error(`Discovery failed: ${message}`);
+        if (error instanceof ServerAuthError ||
+            message.includes('401') ||
+            message.includes('403') ||
+            message.includes('407') ||
+            /unauthorized|forbidden|authentication|authorization/i.test(message)) {
+            output.error('Hint: configure discovery.headers/server.headers or pass --header.');
+        }
         process.exit(EXIT_CODES.ERROR);
     }
     finally {
@@ -101,5 +122,6 @@ export const discoverCommand = new Command('discover')
     .option('--transport <type>', 'Transport type: stdio, sse, streamable-http')
     .option('--url <url>', 'URL for remote MCP server (requires --transport sse or streamable-http)')
     .option('--session-id <id>', 'Session ID for remote server authentication')
+    .option('-H, --header <header...>', 'Custom headers for remote MCP requests (e.g., "Authorization: Bearer token")')
     .action(discoverAction);
 //# sourceMappingURL=discover.js.map

package/dist/cli/commands/explore.js

@@ -31,6 +31,8 @@ import { suppressLogs, restoreLogLevel, configureLogger, } from '../../logging/l
 import { extractServerContextFromArgs } from '../utils/server-context.js';
 import { isCI } from '../utils/env.js';
 import { buildInterviewInsights } from '../../interview/insights.js';
+import { ServerAuthError } from '../../errors/types.js';
+import { mergeHeaders, parseCliHeaders } from '../utils/headers.js';
 /**
  * Wrapper to parse personas with warning output.
  */
@@ -45,6 +47,7 @@ export const exploreCommand = new Command('explore')
     .argument('[server-command]', 'Server command (overrides config)')
     .argument('[args...]', 'Server arguments')
     .option('-c, --config <path>', 'Path to config file', PATHS.DEFAULT_CONFIG_FILENAME)
+    .option('-H, --header <header...>', 'Custom headers for remote MCP requests (e.g., "Authorization: Bearer token")')
     .action(async (serverCommandArg, serverArgs, options) => {
     // Load configuration
     let config;
@@ -71,6 +74,16 @@ export const exploreCommand = new Command('explore')
     const transport = config.server.transport ?? 'stdio';
     const remoteUrl = config.server.url?.trim();
     const remoteSessionId = config.server.sessionId?.trim();
+    const configRemoteHeaders = config.server.headers;
+    let cliHeaders;
+    try {
+        cliHeaders = parseCliHeaders(options.header);
+    }
+    catch (error) {
+        output.error(error instanceof Error ? error.message : String(error));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    const remoteHeaders = mergeHeaders(configRemoteHeaders, cliHeaders);
     // Validate config for explore
     try {
         validateConfigForExplore(config, serverCommand);
@@ -184,6 +197,7 @@ export const exploreCommand = new Command('explore')
             await mcpClient.connectRemote(remoteUrl, {
                 transport,
                 sessionId: remoteSessionId || undefined,
+                headers: remoteHeaders,
             });
         }
         // Discovery phase
@@ -211,12 +225,18 @@ export const exploreCommand = new Command('explore')
             toolsDiscovered: discovery.tools.length,
             personasUsed: selectedPersonas.length,
         });
-        if (discovery.tools.length === 0) {
-            output.info('No tools found. Nothing to explore.');
+        const hasInterviewTargets = discovery.tools.length > 0 ||
+            discovery.prompts.length > 0 ||
+            (discovery.resources?.length ?? 0) > 0;
+        if (!hasInterviewTargets) {
+            output.info('No tools, prompts, or resources found. Nothing to explore.');
             metricsCollector.endInterview();
             await mcpClient.disconnect();
             return;
         }
+        if (discovery.tools.length === 0) {
+            output.info('No tools found; continuing with prompt/resource exploration.');
+        }
         // Show cost/time estimate (unless in CI)
         if (!isCI()) {
             const costEstimate = estimateInterviewCost(model || 'default', discovery.tools.length, maxQuestions, selectedPersonas.length);
@@ -480,17 +500,40 @@ export const exploreCommand = new Command('explore')
         const errorMessage = error instanceof Error ? error.message : String(error);
         output.error('\n--- Exploration Failed ---');
         output.error(`Error: ${errorMessage}`);
-        if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
+        const isRemoteTransport = transport !== 'stdio';
+        if (error instanceof ServerAuthError ||
+            errorMessage.includes('401') ||
+            errorMessage.includes('403') ||
+            errorMessage.includes('407') ||
+            /unauthorized|forbidden|authentication|authorization/i.test(errorMessage)) {
+            output.error('\nPossible causes:');
+            output.error('  - Missing or invalid remote MCP authentication headers');
+            output.error('  - Add server.headers.Authorization or pass --header "Authorization: Bearer $TOKEN"');
+            output.error('  - Verify token scopes/permissions');
+        }
+        else if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('Connection refused')) {
+            output.error('\nPossible causes:');
+            if (isRemoteTransport) {
+                output.error('  - The remote MCP server is not reachable');
+                output.error('  - The server URL/port is incorrect');
+            }
+            else {
+                output.error('  - The MCP server is not running');
+                output.error('  - The server address/port is incorrect');
+            }
+        }
+        else if (isRemoteTransport && errorMessage.includes('HTTP 404')) {
             output.error('\nPossible causes:');
-            output.error('  - The MCP server is not running');
-            output.error('  - The server address/port is incorrect');
+            output.error('  - The remote MCP URL is incorrect');
+            output.error('  - For SSE transport, verify the server exposes /sse');
         }
         else if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
             output.error('\nPossible causes:');
             output.error('  - The MCP server is taking too long to respond');
             output.error('  - Increase server.timeout in bellwether.yaml');
         }
-        else if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
+        else if (!isRemoteTransport &&
+            (errorMessage.includes('ENOENT') || errorMessage.includes('not found'))) {
             output.error('\nPossible causes:');
             output.error('  - The server command was not found');
             output.error('  - Check that the command is installed and in PATH');

package/dist/cli/commands/watch.js

@@ -18,6 +18,7 @@ import { validateConfigForCheck } from '../../config/validator.js';
 import { createBaseline, saveBaseline, loadBaseline, compareBaselines, formatDiffText, } from '../../baseline/index.js';
 import { EXIT_CODES } from '../../constants.js';
 import * as output from '../output.js';
+import { ServerAuthError } from '../../errors/types.js';
 export const watchCommand = new Command('watch')
     .description('Watch for file changes and auto-check (uses bellwether.yaml)')
     .argument('[server-command]', 'Server command (overrides config)')
@@ -42,6 +43,7 @@ export const watchCommand = new Command('watch')
     const transport = config.server.transport ?? 'stdio';
     const remoteUrl = config.server.url?.trim();
     const remoteSessionId = config.server.sessionId?.trim();
+    const remoteHeaders = config.server.headers;
     // Validate config for check mode (watch only does check, not explore)
     try {
         validateConfigForCheck(config, serverCommand);
@@ -97,6 +99,7 @@ export const watchCommand = new Command('watch')
                 await mcpClient.connectRemote(remoteUrl, {
                     transport,
                     sessionId: remoteSessionId || undefined,
+                    headers: remoteHeaders,
                 });
             }
             const discovery = await discover(mcpClient, transport === 'stdio' ? serverCommand : (remoteUrl ?? serverCommand), transport === 'stdio' ? args : []);
@@ -168,7 +171,15 @@ export const watchCommand = new Command('watch')
             output.info(`Baseline updated: ${newBaseline.hash.slice(0, 8)}`);
         }
         catch (error) {
-            output.error(`Test failed: ${error instanceof Error ? error.message : String(error)}`);
+            const message = error instanceof Error ? error.message : String(error);
+            output.error(`Test failed: ${message}`);
+            if (error instanceof ServerAuthError ||
+                message.includes('401') ||
+                message.includes('403') ||
+                message.includes('407') ||
+                /unauthorized|forbidden|authentication|authorization/i.test(message)) {
+                output.error('Hint: configure server.headers.Authorization in bellwether.yaml');
+            }
         }
         finally {
             await mcpClient.disconnect();

package/dist/cli/index.js

@@ -86,42 +86,37 @@ Bellwether - MCP Server Validation & Documentation
 const examples = `
 Examples:
 
-  Initialize configuration:
-    $ bellwether init                       # Create bellwether.yaml
-    $ bellwether init --preset ci           # Optimized for CI/CD
-    $ bellwether init --preset local        # Local LLM with Ollama
+  Core workflow (recommended):
+    $ bellwether init npx @mcp/my-server    # Create bellwether.yaml
+    $ bellwether check                      # Free, deterministic drift detection
+    $ bellwether baseline save              # Save baseline snapshot
+    $ bellwether check --fail-on-drift      # CI/CD gating
 
-  Check for drift (free, fast, deterministic):
-    $ bellwether check npx @mcp/my-server   # Validate schemas
-    $ bellwether baseline save              # Save baseline
-    $ bellwether baseline compare ./bellwether-baseline.json  # Detect drift
-
-  Explore behavior (LLM-powered):
-    $ bellwether explore npx @mcp/my-server # Generate AGENTS.md documentation
-
-  Discover server capabilities:
-    $ bellwether discover npx @mcp/server-postgres
-
-  Search MCP Registry:
-    $ bellwether registry filesystem
+  Advanced workflow (opt-in):
+    $ bellwether explore                    # LLM behavioral exploration
+    $ bellwether discover                   # Quick capability inspection
+    $ bellwether watch                      # Continuous checking
 
 Documentation: https://docs.bellwether.sh
 `;
 program
     .name('bellwether')
     .description(`${banner}
-Check MCP servers for drift. Explore behavior. Generate documentation.
+Deterministic MCP drift detection with an optional advanced analysis layer.
 
-Commands:
-  check    - Schema validation and drift detection (free, fast, deterministic)
-  explore  - LLM-powered behavioral exploration and documentation
-  discover - Quick capability discovery (no tests)
-  registry - Search the MCP Registry
-  baseline - Manage baselines (save/compare/accept/diff/show)
-  golden   - Golden output regression testing
-  contract - Contract validation (generate/validate/show)
-  watch    - Continuous checking on file changes
-  auth     - Manage LLM provider API keys
+Core commands (default path):
+  init     - Create bellwether.yaml configuration
+  check    - Schema validation and drift detection (free, deterministic)
+  baseline - Save and compare baseline snapshots
+
+Advanced commands (opt-in):
+  explore         - LLM-powered behavioral exploration and documentation
+  discover        - Quick capability discovery (no tests)
+  watch           - Continuous checking on file changes
+  registry        - Search the MCP Registry
+  golden          - Golden output regression testing
+  contract        - Contract validation (generate/validate/show)
+  auth            - Manage LLM provider API keys
   validate-config - Validate bellwether.yaml without running tests
 
 For more information on a specific command, use:
@@ -155,19 +150,17 @@ For more information on a specific command, use:
     }
 })
     .addHelpText('after', examples);
-// Add command groups for better organization
-program.addHelpText('beforeAll', '\nCore Commands:');
-// Core commands - check and explore
+program.addCommand(initCommand.description('Create a new bellwether.yaml configuration file'));
 program.addCommand(checkCommand.description('Check MCP server schema and detect drift (free, fast, deterministic)'));
+program.addCommand(baselineCommand.description('Manage baselines for drift detection (save, compare, show, diff)'));
+// Advanced commands
 program.addCommand(exploreCommand.description('Explore MCP server behavior with LLM-powered testing'));
 program.addCommand(watchCommand.description('Watch for MCP server changes and auto-check'));
 program.addCommand(discoverCommand.description('Discover MCP server capabilities (tools, prompts, resources)'));
-program.addCommand(initCommand.description('Create a new bellwether.yaml configuration file'));
-program.addCommand(authCommand.description('Manage LLM provider API keys (keychain storage)'));
-program.addCommand(baselineCommand.description('Manage baselines for drift detection (save, compare, show, diff)'));
 program.addCommand(goldenCommand.description('Manage golden outputs for tool validation (save, compare, list, delete)'));
 program.addCommand(registryCommand.description('Search the MCP Registry for servers'));
 program.addCommand(contractCommand.description('Validate MCP servers against contract definitions (validate, generate, show)'));
+program.addCommand(authCommand.description('Manage LLM provider API keys (keychain storage)'));
 program.addCommand(validateConfigCommand.description('Validate bellwether.yaml configuration (no tests)'));
 // Custom help formatting
 program.configureHelp({