fullstackgtm 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -5,6 +5,52 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.10.1] — 2026-06-11
+
+Fixes from a full fresh-user journey audit (install → demo → MCP → real CRM),
+focused on the first-contact experience.
+
+### Added
+
+- **`fullstackgtm --version`** (also `-v` / `version`) — previously exited 1
+  with a usage dump.
+- **README "Connect your CRM" section**: HubSpot private-app walkthrough with
+  the exact read scopes the audit needs (`crm.objects.{owners,companies,contacts,deals}.read`)
+  and the write scopes `apply` needs; Salesforce Connected App prerequisites
+  (admin-created, device flow enabled, `api` + `refresh_token` scopes,
+  propagation delay); Stripe restricted-key guidance. Previously the word
+  "scope" appeared nowhere in the docs.
+- Roadmap: documented the known real-portal gaps to close before 1.0
+  (pipeline-aware closed-deal detection, 429/retry, fetchChanges 10k
+  truncation, MCP plan hand-off, scope-complete login validation).
+
+### Fixed
+
+- **`FSGTM_NO_BROWSER=1` suppresses OS browser opens** in all login flows
+  (broker pairing, Salesforce device flow, HubSpot OAuth) — for agent
+  sandboxes, CI, and headless use; verification URLs are always printed.
+  The broker test suite sets it, so running `npm test` no longer pops a
+  real browser tab at a mock pairing URL on every run.
+- **MCP server now works from inside existing projects.** When launched via
+  `npx -p ... fullstackgtm-mcp` from a directory whose node_modules already
+  contains the peers (but not fullstackgtm), npx skips installing them into
+  its cache and module resolution failed; the server now falls back to
+  resolving the peers from the working directory — peer-dependency semantics.
+  Previously this made the README's `claude mcp add` setup produce a dead
+  server in most agent-tooling repos.
+- **README auth examples matched the CLI again**: `login salesforce --token ...`
+  and `login hubspot --oauth ... --client-secret ...` showed argv-secret forms
+  the CLI deliberately rejects; both now use stdin.
+- The no-credentials Stripe error suggested `login stripe --token sk_...`,
+  which the CLI itself refuses — it now shows the stdin form and mentions
+  restricted keys.
+- Unreachable hosts no longer surface as a bare `fetch failed`: HubSpot and
+  Salesforce connection errors name the target URL and (for Salesforce) point
+  at SALESFORCE_INSTANCE_URL.
+- Credential errors now point at `fullstackgtm doctor` and the README scope
+  guide; the MCP audit tool description now mentions the `demo` source;
+  README rule count corrected (11 built-ins, not five).
+
 ## [0.10.0] — 2026-06-10
 
 **Versioning reset to reflect beta status.** The 1.x numbering below

package/INSTALL_FOR_AGENTS.md

@@ -45,7 +45,15 @@ Credential resolution ladder, first match wins:
 4. Broker pairing: `fullstackgtm login --via <hosted url>` (a human approves the pairing code)
 
 In an agent sandbox, prefer rung 1 or 2. Never echo tokens into argv —
-`login` reads secrets from stdin only.
+`login` reads secrets from stdin only. Set `FSGTM_NO_BROWSER=1` in headless
+environments — login flows then print verification URLs instead of opening
+the OS browser.
+
+Provider prerequisites (what the human must create, and which scopes) are in
+the README's **"Connect your CRM"** section: HubSpot needs a private app with
+four `crm.objects.*.read` scopes (plus write scopes only for `apply`);
+Salesforce needs an admin-created Connected App with device flow enabled;
+Stripe works with a restricted key (Customers + Subscriptions read).
 
 ```bash
 HUBSPOT_ACCESS_TOKEN=$TOKEN fullstackgtm audit --provider hubspot --json --out plan.json
@@ -71,9 +79,13 @@ The MCP entrypoint needs optional peers that plain `npx fullstackgtm-mcp`
 does not install:
 
 ```bash
-npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
 ```
 
+If the working directory's project already has the peers in its node_modules,
+the server resolves them from there (peer-dependency semantics) — so this
+works from inside existing projects too.
+
 Tools exposed over stdio: `fullstackgtm_audit` (read-only),
 `fullstackgtm_rules`, `fullstackgtm_apply` (requires `approvedOperationIds`).
 

package/README.md

@@ -1,5 +1,7 @@
 # fullstackgtm
 
+[![CI](https://github.com/fullstackgtm/core/actions/workflows/ci.yml/badge.svg)](https://github.com/fullstackgtm/core/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/fullstackgtm)](https://www.npmjs.com/package/fullstackgtm) [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+
 **Plan/apply for your GTM stack.** An open-source framework for managing disparate go-to-market data spread across third-party systems: a canonical CRM/GTM data model, deterministic hygiene audits, reviewable dry-run patch plans, and approval-gated write-back to providers.
 
 Think `terraform plan` for your CRM: agents and scripts may *read* everything, but every proposed change becomes a typed patch operation — object, field, before, after, reason, risk — that a human approves before any provider write happens.
@@ -93,28 +95,61 @@ fullstackgtm login hubspot
 
 # HubSpot, bring-your-own-app OAuth. The browser is used exactly once — the
 # consent grant — captured on a 127.0.0.1 loopback (RFC 8252); the CLI
-# exchanges the code itself and refreshes silently from then on.
-fullstackgtm login hubspot --oauth --client-id <id> --client-secret <secret>
+# exchanges the code itself and refreshes silently from then on. The client
+# secret is read from stdin or an interactive prompt — never as a flag.
+echo "$CLIENT_SECRET" | fullstackgtm login hubspot --oauth --client-id <id>
 #   (register http://localhost:8763/callback as a redirect URL on your app)
 
 # Salesforce: native device flow — confirm a code on any device, no localhost
 # server, no client secret, silent refresh. Needs a Connected App consumer key
-# with device flow enabled.
+# with device flow enabled (see "Connect your CRM" below).
 fullstackgtm login salesforce --device --client-id <consumer key>
-# ...or a session token directly:
-fullstackgtm login salesforce --token <t> --instance-url https://yourorg.my.salesforce.com
+# ...or a session token directly (token on stdin, never as a flag):
+echo "$SF_SESSION_TOKEN" | fullstackgtm login salesforce --instance-url https://yourorg.my.salesforce.com
 
 fullstackgtm logout hubspot   # or: salesforce | broker
 ```
 
 A direct `login hubspot` always wins over a broker pairing, so an operator can override the team default. HubSpot does not support the device-authorization grant or secretless public clients, which is why the bring-your-own-app OAuth path requires client credentials; they are stored locally for silent refresh, the same model as `gcloud` and `aws` CLI profiles.
 
+## Connect your CRM
+
+What each provider actually requires before `audit --provider <name>` works on your data.
+
+### HubSpot: create a private app (~2 minutes, needs super-admin)
+
+1. In HubSpot: **Settings → Integrations → Private Apps → Create a private app.**
+2. On the **Scopes** tab, grant the read scopes the audit needs:
+   - `crm.objects.owners.read`
+   - `crm.objects.companies.read`
+   - `crm.objects.contacts.read`
+   - `crm.objects.deals.read`
+3. If you plan to **apply** approved operations (not just audit), also grant write scopes for the objects you'll let it touch: `crm.objects.deals.write` (covers `deal.next_step` and other deal fields), plus `crm.objects.contacts.write` / `crm.objects.companies.write` for contact/company patches, and the **Tasks** write scope for `create_task` operations (search "tasks" in the scope picker; naming varies by portal).
+4. Create the app, copy the token (`pat-...`), then: `echo "$TOKEN" | fullstackgtm login hubspot`.
+
+If a scope is missing you'll see a `403` mid-run whose body names the exact missing scope (`requiredGranularScopes`) — add it to the private app and re-run. Note that `login` only validates the token itself; it can't tell whether every scope you'll need is granted.
+
+### Salesforce: a Connected App (one-time, usually needs an admin)
+
+Device-flow login requires a Connected App in your org — if you're not an admin, this is the step to ask one for:
+
+1. **Setup → App Manager → New Connected App**, enable OAuth settings.
+2. Check **Enable Device Flow**.
+3. OAuth scopes: **Manage user data via APIs (`api`)** and **Perform requests at any time (`refresh_token`)** — the CLI requests exactly these.
+4. Save (Salesforce can take ~2–10 minutes to propagate a new Connected App), copy the **Consumer Key**, then: `fullstackgtm login salesforce --device --client-id <consumer key>`.
+
+Writeback needs no extra OAuth scope — applies are gated by the logged-in user's normal object/field permissions.
+
+### Stripe: a restricted key is enough (read-only connector)
+
+The Stripe connector only reads customers and subscriptions, and `apply` is read-only by construction. Create a **restricted key** with just **Customers: Read** and **Subscriptions: Read** (Developers → API keys → Create restricted key) instead of pasting a full-access secret key: `echo "$KEY" | fullstackgtm login stripe`.
+
 ## Concepts
 
 | Concept | What it is |
 |---|---|
 | **Canonical snapshot** | Provider-independent view of users, accounts, contacts, deals, activities. Records carry `identities` — `(provider, externalId)` claims — so the same real-world entity can be tracked across several systems. |
-| **Audit rule** | A deterministic function `(context) => { findings, operations }`. Five built-ins cover orphan accounts, ownerless deals, unlinked deals, past close dates, and stale pipeline. Write your own in ~10 lines. |
+| **Audit rule** | A deterministic function `(context) => { findings, operations }`. Eleven built-ins cover orphan accounts, ownerless/unlinked/amount-less deals, past close dates, stale pipeline, duplicates, and more — `fullstackgtm rules` lists them all. Write your own in ~10 lines. |
 | **Patch plan** | The dry-run output of an audit: findings plus typed patch operations with before/after values, reasons, risk levels, and approval flags. Always a proposal, never a mutation. |
 | **Connector** | A provider adapter: `fetchSnapshot()` for reads, optional `applyOperation()` for writes. HubSpot and Salesforce reference connectors ship in the package; connectors never drop records they can't fully resolve — the audit flags them instead. |
 | **Patch plan run** | The audit record of one apply attempt: per-operation applied/failed/skipped results. |

package/dist/cli.js

@@ -132,7 +132,7 @@ async function hubspotConnection(args) {
     const stored = await resolveHubspotConnection();
     if (stored)
         return stored;
-    throw new Error("No HubSpot credentials. Run `fullstackgtm login hubspot`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set HUBSPOT_ACCESS_TOKEN.");
+    throw new Error("No HubSpot credentials. Run `fullstackgtm login hubspot`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set HUBSPOT_ACCESS_TOKEN. (`fullstackgtm doctor` shows credential status; see the README's \"Connect your CRM\" section for the private-app scopes to grant.)");
 }
 async function salesforceConnection() {
     if (process.env.SALESFORCE_ACCESS_TOKEN && process.env.SALESFORCE_INSTANCE_URL) {
@@ -144,7 +144,7 @@ async function salesforceConnection() {
     const stored = await resolveSalesforceConnection();
     if (stored)
         return stored;
-    throw new Error("No Salesforce credentials. Run `fullstackgtm login salesforce`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL.");
+    throw new Error("No Salesforce credentials. Run `fullstackgtm login salesforce`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL. (`fullstackgtm doctor` shows credential status; device-flow login needs an admin-created Connected App — see the README's \"Connect your CRM\" section.)");
 }
 async function connectorFor(provider, args) {
     if (provider === "hubspot") {
@@ -164,7 +164,7 @@ async function connectorFor(provider, args) {
     if (provider === "stripe") {
         const key = process.env.STRIPE_SECRET_KEY ?? getCredential("stripe")?.accessToken;
         if (!key) {
-            throw new Error("No Stripe credentials. Run `fullstackgtm login stripe --token sk_...` or set STRIPE_SECRET_KEY.");
+            throw new Error("No Stripe credentials. Run `echo \"$STRIPE_KEY\" | fullstackgtm login stripe` or set STRIPE_SECRET_KEY. A restricted key with read access to Customers and Subscriptions is enough. (`fullstackgtm doctor` shows credential status.)");
         }
         return createStripeConnector({ getApiKey: () => key });
     }
@@ -868,6 +868,10 @@ export async function runCli(argv) {
         console.log(usage());
         return;
     }
+    if (command === "--version" || command === "-v" || command === "version") {
+        console.log(readPackageInfo().version);
+        return;
+    }
     if (command === "login") {
         await login(args);
         return;

package/dist/connectors/hubspot.js

@@ -24,14 +24,21 @@ export function createHubspotConnector(options) {
     const mappings = options.fieldMappings;
     async function request(path, init = {}) {
         const token = await options.getAccessToken();
-        const response = await fetchImpl(`${baseUrl}${path}`, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-                ...(init.headers ?? {}),
-            },
-        });
+        let response;
+        try {
+            response = await fetchImpl(`${baseUrl}${path}`, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                    ...(init.headers ?? {}),
+                },
+            });
+        }
+        catch (error) {
+            const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+            throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
+        }
         if (!response.ok) {
             const body = await response.text();
             throw new Error(`HubSpot API error ${response.status}: ${body}`);

package/dist/connectors/hubspotAuth.js

@@ -154,6 +154,10 @@ export async function runHubspotLoopbackLogin(options) {
     });
 }
 export async function openInBrowser(url) {
+    // Headless contexts (agent sandboxes, CI, tests) suppress the OS browser;
+    // every flow that opens a URL also prints it for manual use.
+    if (process.env.FSGTM_NO_BROWSER)
+        return;
     // The URL may come from an external source (e.g. a broker deployment's
     // verification URL). Only ever hand a well-formed http(s) URL to the OS
     // opener — this prevents a leading `-` from being read as a flag by

package/dist/connectors/salesforce.js

@@ -28,14 +28,21 @@ export function createSalesforceConnector(options) {
         const url = path.startsWith("http")
             ? path
             : `${connection.instanceUrl.replace(/\/$/, "")}${path}`;
-        const response = await fetchImpl(url, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${connection.accessToken}`,
-                "Content-Type": "application/json",
-                ...(init.headers ?? {}),
-            },
-        });
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${connection.accessToken}`,
+                    "Content-Type": "application/json",
+                    ...(init.headers ?? {}),
+                },
+            });
+        }
+        catch (error) {
+            const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+            throw new Error(`Cannot reach Salesforce at ${connection.instanceUrl}${cause}. Check SALESFORCE_INSTANCE_URL (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`);
+        }
         if (!response.ok) {
             const body = await response.text();
             throw new Error(`Salesforce API error ${response.status}: ${body}`);

package/dist/mcp.js

@@ -1,8 +1,39 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod/v4";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * The MCP peers resolve normally when installed alongside this package, but
+ * `npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod` skips installing
+ * peers into the npx cache when the invoking project's node_modules already
+ * satisfies them — and the cache can't reach the project's tree. Fall back to
+ * resolving from the working directory: peer dependencies' natural home.
+ */
+async function importPeer(specifier) {
+    try {
+        return (await import(__rewriteRelativeImportExtension(specifier)));
+    }
+    catch (error) {
+        try {
+            const projectRequire = createRequire(join(process.cwd(), "package.json"));
+            return (await import(__rewriteRelativeImportExtension(pathToFileURL(projectRequire.resolve(specifier)).href)));
+        }
+        catch {
+            throw error; // the original error carries the missing-peer signal mcp-bin reports on
+        }
+    }
+}
+const { McpServer } = await importPeer("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = await importPeer("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = await importPeer("zod/v4");
 import { auditSnapshot, defaultPolicy } from "./audit.js";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "./config.js";
 import { applyPatchPlan } from "./connector.js";
@@ -84,7 +115,8 @@ export async function startMcpServer() {
     server.registerTool("fullstackgtm_audit", {
         title: "GTM Ops Audit",
         description: "Run a dry-run GTM hygiene audit and return a reviewable patch plan. " +
-            "Reads from the sample dataset, a snapshot file, or a live provider.",
+            "Sources: the realistic zero-credential demo CRM (provider: \"demo\" — richest test data), " +
+            "the minimal sample dataset, a snapshot file, or a live provider.",
         inputSchema: {
             provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
             inputPath: z.string().optional(),

package/docs/roadmap-to-1.0.md

@@ -106,11 +106,39 @@ The original thesis: GTM data disagrees across systems.
 - Docs site with the operating-model registry as browsable reference.
 - Performance pass: streaming snapshots for very large orgs.
 
-## 1.0.0 — The contract (reached)
+## Known real-portal gaps to close before 1.0
+
+Found by exercising the published package as a fresh RevOps user with a real
+CRM (2026-06):
+
+- **Pipeline-aware closed-deal detection (HubSpot).** `isClosed`/`isWon` are
+  derived by substring-matching the raw `dealstage` value against
+  `closedwon`/`closedlost`. Custom pipelines use opaque stage ids, so closed
+  deals read as open and flood stale-deal/past-close findings. Fix: resolve
+  stage metadata from `/crm/v3/pipelines` once per snapshot.
+- **Rate-limit resilience.** No 429/retry/backoff handling anywhere; a
+  mid-size portal snapshot is ~1,000+ sequential page requests and one
+  transient failure aborts the run. Fix: honor `Retry-After`, retry
+  idempotent reads with backoff.
+- **`fetchChanges` 10k truncation.** The HubSpot search API caps at 10,000
+  results; the connector stops silently at MAX_PAGES. Fix: detect the cap
+  and fall back to (or instruct) a full snapshot, loudly.
+- **MCP plan hand-off.** `fullstackgtm_audit` can only return the full plan
+  inline (200KB+ on real data) while `fullstackgtm_apply` requires a file
+  path. Fix: an `outPath` option on the audit tool plus a summary-only
+  output mode.
+- **Scope-complete login validation.** `login hubspot` validates against the
+  owners endpoint only, so an under-scoped token passes login and fails
+  mid-audit. Fix: probe each required object endpoint at login and report
+  missing scopes up front.
+
+## 1.0.0 — The contract (not yet declared)
 
 Semver stability commitment on the canonical model, rule interface, connector
-contract, plan format, CLI, and MCP tools. From here, new providers and new
-rules are minor releases; the model only breaks at 2.0.
+contract, plan format, CLI, and MCP tools. Declared only after the API
+surface has survived external usage and the real-portal gaps above are
+closed. From there, new providers and new rules are minor releases; the
+model only breaks at 2.0.
 
 ## Deliberately out of scope until after 1.0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM",

package/src/cli.ts

@@ -157,7 +157,7 @@ async function hubspotConnection(args: string[]) {
   const stored = await resolveHubspotConnection();
   if (stored) return stored;
   throw new Error(
-    "No HubSpot credentials. Run `fullstackgtm login hubspot`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set HUBSPOT_ACCESS_TOKEN.",
+    "No HubSpot credentials. Run `fullstackgtm login hubspot`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set HUBSPOT_ACCESS_TOKEN. (`fullstackgtm doctor` shows credential status; see the README's \"Connect your CRM\" section for the private-app scopes to grant.)",
   );
 }
 
@@ -171,7 +171,7 @@ async function salesforceConnection() {
   const stored = await resolveSalesforceConnection();
   if (stored) return stored;
   throw new Error(
-    "No Salesforce credentials. Run `fullstackgtm login salesforce`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL.",
+    "No Salesforce credentials. Run `fullstackgtm login salesforce`, pair with a hosted deployment via `fullstackgtm login --via <url>`, or set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL. (`fullstackgtm doctor` shows credential status; device-flow login needs an admin-created Connected App — see the README's \"Connect your CRM\" section.)",
   );
 }
 
@@ -198,7 +198,7 @@ async function connectorFor(provider: string, args: string[]): Promise<GtmConnec
       process.env.STRIPE_SECRET_KEY ?? getCredential("stripe")?.accessToken;
     if (!key) {
       throw new Error(
-        "No Stripe credentials. Run `fullstackgtm login stripe --token sk_...` or set STRIPE_SECRET_KEY.",
+        "No Stripe credentials. Run `echo \"$STRIPE_KEY\" | fullstackgtm login stripe` or set STRIPE_SECRET_KEY. A restricted key with read access to Customers and Subscriptions is enough. (`fullstackgtm doctor` shows credential status.)",
       );
     }
     return createStripeConnector({ getApiKey: () => key });
@@ -993,6 +993,10 @@ export async function runCli(argv: string[]) {
     console.log(usage());
     return;
   }
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log(readPackageInfo().version);
+    return;
+  }
 
   if (command === "login") {
     await login(args);

package/src/connectors/hubspot.ts

@@ -57,14 +57,20 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const token = await options.getAccessToken();
-    const response = await fetchImpl(`${baseUrl}${path}`, {
-      ...init,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-        ...(init.headers ?? {}),
-      },
-    });
+    let response: Response;
+    try {
+      response = await fetchImpl(`${baseUrl}${path}`, {
+        ...init,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          ...(init.headers ?? {}),
+        },
+      });
+    } catch (error) {
+      const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+      throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
+    }
     if (!response.ok) {
       const body = await response.text();
       throw new Error(`HubSpot API error ${response.status}: ${body}`);

package/src/connectors/hubspotAuth.ts

@@ -212,6 +212,9 @@ export async function runHubspotLoopbackLogin(
 }
 
 export async function openInBrowser(url: string) {
+  // Headless contexts (agent sandboxes, CI, tests) suppress the OS browser;
+  // every flow that opens a URL also prints it for manual use.
+  if (process.env.FSGTM_NO_BROWSER) return;
   // The URL may come from an external source (e.g. a broker deployment's
   // verification URL). Only ever hand a well-formed http(s) URL to the OS
   // opener — this prevents a leading `-` from being read as a flag by

package/src/connectors/salesforce.ts

@@ -69,14 +69,22 @@ export function createSalesforceConnector(
     const url = path.startsWith("http")
       ? path
       : `${connection.instanceUrl.replace(/\/$/, "")}${path}`;
-    const response = await fetchImpl(url, {
-      ...init,
-      headers: {
-        Authorization: `Bearer ${connection.accessToken}`,
-        "Content-Type": "application/json",
-        ...(init.headers ?? {}),
-      },
-    });
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        ...init,
+        headers: {
+          Authorization: `Bearer ${connection.accessToken}`,
+          "Content-Type": "application/json",
+          ...(init.headers ?? {}),
+        },
+      });
+    } catch (error) {
+      const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+      throw new Error(
+        `Cannot reach Salesforce at ${connection.instanceUrl}${cause}. Check SALESFORCE_INSTANCE_URL (your My Domain URL, e.g. https://yourco.my.salesforce.com) and network access.`,
+      );
+    }
     if (!response.ok) {
       const body = await response.text();
       throw new Error(`Salesforce API error ${response.status}: ${body}`);

package/src/mcp.ts

@@ -1,8 +1,35 @@
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod/v4";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * The MCP peers resolve normally when installed alongside this package, but
+ * `npx -p fullstackgtm -p @modelcontextprotocol/sdk -p zod` skips installing
+ * peers into the npx cache when the invoking project's node_modules already
+ * satisfies them — and the cache can't reach the project's tree. Fall back to
+ * resolving from the working directory: peer dependencies' natural home.
+ */
+async function importPeer<T>(specifier: string): Promise<T> {
+  try {
+    return (await import(specifier)) as T;
+  } catch (error) {
+    try {
+      const projectRequire = createRequire(join(process.cwd(), "package.json"));
+      return (await import(pathToFileURL(projectRequire.resolve(specifier)).href)) as T;
+    } catch {
+      throw error; // the original error carries the missing-peer signal mcp-bin reports on
+    }
+  }
+}
+
+const { McpServer } = await importPeer<typeof import("@modelcontextprotocol/sdk/server/mcp.js")>(
+  "@modelcontextprotocol/sdk/server/mcp.js",
+);
+const { StdioServerTransport } = await importPeer<typeof import("@modelcontextprotocol/sdk/server/stdio.js")>(
+  "@modelcontextprotocol/sdk/server/stdio.js",
+);
+const { z } = await importPeer<typeof import("zod/v4")>("zod/v4");
 import { auditSnapshot, defaultPolicy } from "./audit.ts";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "./config.ts";
 import { applyPatchPlan } from "./connector.ts";
@@ -113,7 +140,8 @@ export async function startMcpServer() {
       title: "GTM Ops Audit",
       description:
         "Run a dry-run GTM hygiene audit and return a reviewable patch plan. " +
-        "Reads from the sample dataset, a snapshot file, or a live provider.",
+        "Sources: the realistic zero-credential demo CRM (provider: \"demo\" — richest test data), " +
+        "the minimal sample dataset, a snapshot file, or a live provider.",
       inputSchema: {
         provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
         inputPath: z.string().optional(),