@clue-ai/cli 0.0.15 → 0.0.17

package/src/setup-ai-contract.mjs

@@ -0,0 +1,91 @@
+export const AI_SETUP_CONTRACT_VERSION =
+  "2026-05-10.api-connectivity-contract.v6";
+
+export const SETUP_DOCTRINE = {
+  purpose:
+    "Clue setup installs an external SDK integration so observed product facts can reach Clue's Customer Value Understanding Engine. It is not an opportunity to improve, refactor, redesign, or reinterpret the host application.",
+  minimal_diff_reason:
+    "The customer must be able to review and merge the setup diff with confidence. Extra formatting, refactors, auth rewrites, UI changes, or unrelated cleanup make the integration harder to trust.",
+  ai_decision_boundary:
+    "The AI should use repository understanding only to choose existing lifecycle boundaries for ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout.",
+  deterministic_control_boundary:
+    "Everything that can be controlled mechanically should be controlled by the CLI, generated skills, documentation contract, lifecycle plan schema, and setup-check static guards.",
+  documentation_reason:
+    "SDK signatures, environment variable names, browser token behavior, and verification ownership are contracts. The AI must read the setup documents instead of relying on memory.",
+  failure_posture:
+    "When a lifecycle point, SDK package, signature, env name, or verification step is unclear, the correct output is a blocker or user_verification_pending, not a guessed implementation or a completion claim.",
+};
+
+export const DETERMINISTIC_CONTROL_MODEL = {
+  ai_should_decide: [
+    "which existing bootstrap point owns ClueInit",
+    "which existing login/session success point owns ClueIdentify",
+    "which existing account/workspace/organization resolution point owns ClueSetAccount",
+    "which existing logout/session reset point owns ClueLogout",
+    "whether a lifecycle point is unclear and should be reported as blocked",
+  ],
+  cli_should_control: [
+    "official SDK package names",
+    "official public SDK function names and supported lifecycle API set",
+    "environment variable names produced by setup and consumed by setup code",
+    "machine-owned semantic workflow generation and verification",
+    "setup-watch ownership as user-operated verification",
+    "static rejection of known unsafe wiring such as leaked secrets, wrong SDKs, blocking lifecycle calls, broad ClueTrack setup, and unsafe browser token proxy patterns",
+    "local API connectivity preflight for the four required setup hops before user-operated setup-watch",
+  ],
+};
+
+export const API_CONNECTIVITY_CONTRACT = {
+  purpose:
+    "Clue setup has four distinct HTTP hops. The AI must not collapse customer-owned proxy routes and Clue-owned ingest routes into one vague browser-token endpoint.",
+  hops: {
+    client_backend_browser_token_proxy: {
+      owner: "customer_backend",
+      method: "POST",
+      path: "/api/v1/clue/browser-tokens",
+      caller: "customer_frontend_browserTokenProvider",
+      purpose:
+        "Issue a short-lived browser token without exposing CLUE_API_KEY to browser code.",
+    },
+    clue_backend_browser_token_issue: {
+      owner: "clue_backend",
+      method: "POST",
+      path: "/api/v1/ingest/browser-tokens",
+      caller: "customer_backend_browser_token_proxy",
+      purpose:
+        "Clue backend validates CLUE_API_KEY, project, environment, service key, and origin, then returns a browser token.",
+    },
+    browser_ingest: {
+      owner: "clue_backend",
+      method: "POST",
+      path: "/api/v1/ingest/browser",
+      caller: "customer_frontend_browser_sdk",
+      env_name: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT for Next.js browser code",
+      purpose:
+        "Browser SDK sends observation source events with x-clue-browser-token.",
+    },
+    backend_ingest: {
+      owner: "clue_backend",
+      method: "POST",
+      path: "/api/v1/ingest/backend",
+      caller: "customer_backend_sdk",
+      env_name: "CLUE_INGEST_ENDPOINT",
+      purpose:
+        "Backend SDK sends observation source events with server-side CLUE_API_KEY.",
+    },
+  },
+  preflight_command: "setup-doctor --local",
+  setup_watch_boundary:
+    "setup-doctor checks local API connectivity before user flows. setup-watch remains user-operated lifecycle and event-delivery verification.",
+};
+
+export const setupDoctrineSkillLines = () => [
+  `- Purpose: ${SETUP_DOCTRINE.purpose}`,
+  `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
+  `- AI decision boundary: ${SETUP_DOCTRINE.ai_decision_boundary}`,
+  `- Static control boundary: ${SETUP_DOCTRINE.deterministic_control_boundary}`,
+  `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
+  `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
+  `- API connectivity: ${API_CONNECTIVITY_CONTRACT.purpose}`,
+  `- API preflight: run ${API_CONNECTIVITY_CONTRACT.preflight_command} when local services and required env are available; do not substitute it for user-operated setup-watch.`,
+];

package/src/setup-check.mjs

@@ -12,6 +12,7 @@ import {
   stripSourceNoise,
 } from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
+import { AI_SETUP_CONTRACT_VERSION } from "./setup-ai-contract.mjs";
 import { runSemanticInventory } from "./semantic-ci.mjs";
 
 const DEFAULT_WORKFLOW_PATH = ".github/workflows/clue-semantic-snapshot.yml";
@@ -27,7 +28,7 @@ const SETUP_SKILLS = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v4";
+const SETUP_SKILL_CONTENT_VERSION = AI_SETUP_CONTRACT_VERSION;
 const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-sdk-instrumentation": [
     "Do not create no-op wrappers",
@@ -42,6 +43,7 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring",
     "The local backend token endpoint is part of the customer app, not the Clue API",
     "The frontend `browserTokenProvider` must send the same service key used by `ClueInit`",
+    "Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`",
     "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
   ],
   "clue-setup-audit": [
@@ -49,12 +51,14 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Reject Django SDK setup when `clue-django-sdk` installability has not been verified",
     "Reject ClueTrack instrumentation unless the user explicitly requested product event tracking",
     "Reject Next.js browser/client code that reads non-public `process.env.CLUE_*` variables",
+    "Reject browser token proxy code that forwards origin, projectKey, or environment from request JSON/body under server `CLUE_API_KEY`",
     "Reject whitespace-only edits, import sorting, formatter churn",
     "Reject unrelated refactors, renames, file moves",
     "Execution agents must not approve, certify, or mark their own work complete",
   ],
   "clue-local-verification": [
     "`setup-check --require-sdk-lifecycle` is a static source check only",
+    "`setup-doctor --local` API connectivity preflight",
     "Verify frontend SDK installability/import",
     "Verify backend SDK installability/import",
     "Do not run `npx -y @clue-ai/cli setup-watch --local` automatically",
@@ -806,6 +810,17 @@ const findNextBrowserTokenProviderMissingPublicServiceKeyFiles = ({
     .map((source) => source.file_path);
 };
 
+const findBrowserTokenProviderWrongProxyPathFiles = (frontendSources) =>
+  frontendSources
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      if (!/\bfetch\s*\(/.test(text)) return false;
+      if (/\/api\/v1\/clue\/browser-tokens\b/.test(text)) return false;
+      return /browser[-_]?tokens?|browser[-_]?token/i.test(text);
+    })
+    .map((source) => source.file_path);
+
 const sourceLooksLikeBrowserTokenProxy = (source) => {
   const text = stripSourceNoise(source.text);
   return (
@@ -827,6 +842,43 @@ const findBrowserTokenProxyUsingBackendServiceKeyFiles = (backendSources) =>
     })
     .map((source) => source.file_path);
 
+const bodyOriginPatterns = [
+  /\b(?:payload|body|requestBody|request_body|data|input)\.origin\b/i,
+  /\b(?:payload|body|requestBody|request_body|data|input)\s*\[\s*["']origin["']\s*\]/i,
+  /\b(?:payload|body|requestBody|request_body|data|input)\.get\s*\(\s*["']origin["']/i,
+  /["']origin["']\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /\borigin\s*=\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+];
+
+const bodyProjectEnvironmentPatterns = [
+  /\b(?:projectKey|project_key)\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /["'](?:projectKey|project_key)["']\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /\benvironment\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+  /["']environment["']\s*:\s*(?:payload|body|requestBody|request_body|data|input)\b/i,
+];
+
+const findBrowserTokenProxyTrustingBodyOriginFiles = (backendSources) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      return bodyOriginPatterns.some((pattern) => pattern.test(text));
+    })
+    .map((source) => source.file_path);
+
+const findBrowserTokenProxyTrustingBodyProjectEnvironmentFiles = (
+  backendSources,
+) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      return bodyProjectEnvironmentPatterns.some((pattern) =>
+        pattern.test(text),
+      );
+    })
+    .map((source) => source.file_path);
+
 const backendSdkSpec = (framework) =>
   BACKEND_SDK_BY_FRAMEWORK[String(framework ?? "").toLowerCase()] ?? {
     packages: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
@@ -947,6 +999,8 @@ const checkSdkLifecycle = ({
     findWildcardFrontendSdkDependencyFiles(dependencySources);
   const browserTokenProviderMissingServiceKeyFiles =
     findBrowserTokenProviderMissingServiceKeyFiles(frontendSources);
+  const browserTokenProviderWrongProxyPathFiles =
+    findBrowserTokenProviderWrongProxyPathFiles(frontendSources);
   const nextBrowserTokenProviderMissingPublicServiceKeyFiles =
     findNextBrowserTokenProviderMissingPublicServiceKeyFiles({
       dependencySources,
@@ -954,6 +1008,10 @@ const checkSdkLifecycle = ({
     });
   const browserTokenProxyUsingBackendServiceKeyFiles =
     findBrowserTokenProxyUsingBackendServiceKeyFiles(backendSources);
+  const browserTokenProxyTrustingBodyOriginFiles =
+    findBrowserTokenProxyTrustingBodyOriginFiles(backendSources);
+  const browserTokenProxyTrustingBodyProjectEnvironmentFiles =
+    findBrowserTokenProxyTrustingBodyProjectEnvironmentFiles(backendSources);
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -1014,10 +1072,16 @@ const checkSdkLifecycle = ({
       wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
       browser_token_provider_missing_service_key_files:
         browserTokenProviderMissingServiceKeyFiles,
+      browser_token_provider_wrong_proxy_path_files:
+        browserTokenProviderWrongProxyPathFiles,
       next_browser_token_provider_missing_public_service_key_files:
         nextBrowserTokenProviderMissingPublicServiceKeyFiles,
       browser_token_proxy_uses_backend_service_key_files:
         browserTokenProxyUsingBackendServiceKeyFiles,
+      browser_token_proxy_trusts_body_origin_files:
+        browserTokenProxyTrustingBodyOriginFiles,
+      browser_token_proxy_trusts_body_project_environment_files:
+        browserTokenProxyTrustingBodyProjectEnvironmentFiles,
     },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
@@ -1037,8 +1101,11 @@ const checkSdkLifecycle = ({
       nextLifecycleNonPublicEnvFiles.length === 0 &&
       wildcardFrontendSdkDependencyFiles.length === 0 &&
       browserTokenProviderMissingServiceKeyFiles.length === 0 &&
+      browserTokenProviderWrongProxyPathFiles.length === 0 &&
       nextBrowserTokenProviderMissingPublicServiceKeyFiles.length === 0 &&
       browserTokenProxyUsingBackendServiceKeyFiles.length === 0 &&
+      browserTokenProxyTrustingBodyOriginFiles.length === 0 &&
+      browserTokenProxyTrustingBodyProjectEnvironmentFiles.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
       blockingLifecycleFiles.length === 0,

package/src/setup-doctor.mjs

@@ -0,0 +1,435 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const BROWSER_TOKEN_PROXY_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.client_backend_browser_token_proxy.path;
+const CLUE_BROWSER_TOKEN_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.clue_backend_browser_token_issue.path;
+const BROWSER_INGEST_PATH = API_CONNECTIVITY_CONTRACT.hops.browser_ingest.path;
+const BACKEND_INGEST_PATH = API_CONNECTIVITY_CONTRACT.hops.backend_ingest.path;
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+const joinUrl = (baseUrl, path) => `${trimTrailingSlash(baseUrl)}${path}`;
+
+const readJsonIfPresent = async (path) => {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const manifestWatchTargets = (manifest, kind) => {
+  const targets = manifest?.lifecycle_verification?.watch_targets;
+  if (!Array.isArray(targets)) return [];
+  return targets.filter((target) => target?.kind === kind);
+};
+
+const firstTargetUrl = ({ env, manifest, kind }) => {
+  for (const target of manifestWatchTargets(manifest, kind)) {
+    const explicitUrl = optionalString(target.url);
+    if (explicitUrl) return explicitUrl;
+    const envName = optionalString(target.url_env_name);
+    if (envName && optionalString(env[envName])) return optionalString(env[envName]);
+    const candidates = Array.isArray(target.local_url_candidates)
+      ? target.local_url_candidates
+      : [];
+    for (const candidate of candidates) {
+      const value = optionalString(candidate);
+      if (value) return value;
+    }
+  }
+  return null;
+};
+
+const firstTargetServiceKey = (manifest, kind) => {
+  for (const target of manifestWatchTargets(manifest, kind)) {
+    const serviceKey = optionalString(target.service_key ?? target.serviceKey);
+    if (serviceKey) return serviceKey;
+  }
+  return null;
+};
+
+const readTextResponse = async (response) => {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+};
+
+const parseJsonText = (text) => {
+  try {
+    return text.trim() ? JSON.parse(text) : null;
+  } catch {
+    return null;
+  }
+};
+
+const postJson = async ({ body, fetchImpl, headers = {}, url }) => {
+  try {
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(body),
+    });
+    const text = await readTextResponse(response);
+    return {
+      transportOk: true,
+      response,
+      text,
+      json: parseJsonText(text),
+    };
+  } catch (error) {
+    return {
+      transportOk: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
+const compactFailure = (result) => {
+  if (!result.transportOk) return result.error ?? "request failed";
+  const jsonMessage =
+    typeof result.json?.message === "string"
+      ? result.json.message
+      : typeof result.json?.error === "string"
+        ? result.json.error
+        : null;
+  return jsonMessage ?? result.text?.slice(0, 240) ?? "request failed";
+};
+
+const tokenFromResult = (result) =>
+  result.transportOk &&
+  result.response.ok &&
+  typeof result.json?.token === "string" &&
+  result.json.token.trim()
+    ? result.json.token.trim()
+    : null;
+
+const buildCheck = ({
+  error = null,
+  id,
+  method = "POST",
+  passed,
+  result = null,
+  url,
+}) => ({
+  id,
+  method,
+  url,
+  passed: Boolean(passed),
+  status: result?.transportOk ? result.response.status : null,
+  error: passed ? null : (error ?? compactFailure(result)),
+});
+
+const buildBrowserEventPayload = ({ environment, projectKey, serviceKey }) => {
+  const timestamp = new Date().toISOString();
+  const id = `setup_doctor_${Date.now()}`;
+  return {
+    batch_id: `batch_${id}`,
+    idempotency_key: `idem_${id}`,
+    sent_at: timestamp,
+    source_type: "browser_sdk",
+    source_schema_version: "1",
+    producer_metadata: {
+      producer_id: serviceKey,
+      sdk_type: "browser",
+      sdk_version: "setup-doctor",
+    },
+    events: [
+      {
+        event_id: `event_${id}`,
+        event_category: "custom",
+        event_name: "setup_doctor_browser_connectivity",
+        occurred_at: timestamp,
+        source_event_id: `event_${id}`,
+        source_schema_version: "1",
+        source_event_type: "setup_doctor_browser_connectivity",
+        source_event_kind: "custom",
+        producer_id: serviceKey,
+        project_key: projectKey,
+        environment,
+        properties: {},
+        metrics: { count: 1 },
+      },
+    ],
+  };
+};
+
+const buildBackendEventPayload = ({
+  apiKey,
+  backendServiceKey,
+  environment,
+  projectKey,
+}) => {
+  const timestamp = new Date().toISOString();
+  return {
+    projectKey,
+    apiKey,
+    environment,
+    sdkType: "backend",
+    sdkVersion: "setup-doctor",
+    schemaVersion: 1,
+    events: [
+      {
+        event_name: "setup_doctor_backend_connectivity",
+        occurred_at: timestamp,
+        service_key: backendServiceKey,
+        properties: {},
+        metrics: { count: 1 },
+      },
+    ],
+  };
+};
+
+const requiredInputCheck = ({ id, missing, url = null }) => ({
+  id,
+  method: "POST",
+  url,
+  passed: false,
+  status: null,
+  error: `missing required input: ${missing.join(", ")}`,
+});
+
+export const runSetupDoctor = async ({
+  env = process.env,
+  fetchImpl = fetch,
+  flags,
+  repoRoot = ".",
+}) => {
+  const manifestPath = String(
+    flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+  );
+  const manifest = await readJsonIfPresent(resolve(repoRoot, manifestPath));
+  const clueApiBaseUrl =
+    optionalString(flags.get("clue-api-base-url")) ??
+    optionalString(env.CLUE_API_BASE_URL) ??
+    optionalString(manifest?.clue_context?.clue_api_base_url);
+  const projectKey =
+    optionalString(flags.get("project-key")) ??
+    optionalString(env.CLUE_PROJECT_KEY) ??
+    optionalString(manifest?.clue_context?.project_key);
+  const environment =
+    optionalString(flags.get("environment")) ??
+    optionalString(env.CLUE_ENVIRONMENT) ??
+    optionalString(manifest?.clue_context?.environment) ??
+    "dev";
+  const apiKey =
+    optionalString(flags.get("clue-api-key")) ??
+    optionalString(env.CLUE_API_KEY);
+  const serviceKey =
+    optionalString(flags.get("service-key")) ??
+    optionalString(env.NEXT_PUBLIC_CLUE_SERVICE_KEY) ??
+    firstTargetServiceKey(manifest, "frontend");
+  const backendServiceKey =
+    optionalString(flags.get("backend-service-key")) ??
+    optionalString(env.CLUE_SERVICE_KEY) ??
+    firstTargetServiceKey(manifest, "backend") ??
+    serviceKey;
+  const clientBackendUrl =
+    optionalString(flags.get("client-backend-url")) ??
+    firstTargetUrl({ env, manifest, kind: "backend" });
+  const clientFrontendUrl =
+    optionalString(flags.get("client-frontend-url")) ??
+    firstTargetUrl({ env, manifest, kind: "frontend" });
+  const origin =
+    optionalString(flags.get("origin")) ??
+    clientFrontendUrl ??
+    "http://localhost";
+  const browserTokenProxyUrl = clientBackendUrl
+    ? joinUrl(clientBackendUrl, BROWSER_TOKEN_PROXY_PATH)
+    : null;
+  const clueBrowserTokenUrl = clueApiBaseUrl
+    ? joinUrl(clueApiBaseUrl, CLUE_BROWSER_TOKEN_PATH)
+    : null;
+  const browserIngestUrl =
+    optionalString(flags.get("browser-ingest-url")) ??
+    optionalString(env.NEXT_PUBLIC_CLUE_INGEST_ENDPOINT) ??
+    optionalString(manifest?.clue_context?.ingest_endpoints?.browser) ??
+    (clueApiBaseUrl ? joinUrl(clueApiBaseUrl, BROWSER_INGEST_PATH) : null);
+  const backendIngestUrl =
+    optionalString(flags.get("backend-ingest-url")) ??
+    optionalString(env.CLUE_INGEST_ENDPOINT) ??
+    optionalString(manifest?.clue_context?.ingest_endpoints?.backend) ??
+    (clueApiBaseUrl ? joinUrl(clueApiBaseUrl, BACKEND_INGEST_PATH) : null);
+
+  const checks = [];
+
+  let proxyToken = null;
+  if (!browserTokenProxyUrl || !serviceKey) {
+    checks.push(
+      requiredInputCheck({
+        id: "client_backend_browser_token_proxy",
+        missing: [
+          ...(!browserTokenProxyUrl ? ["client-backend-url"] : []),
+          ...(!serviceKey ? ["service-key"] : []),
+        ],
+        url: browserTokenProxyUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: browserTokenProxyUrl,
+      headers: { origin },
+      body: { serviceKey },
+    });
+    proxyToken = tokenFromResult(result);
+    checks.push(
+      buildCheck({
+        id: "client_backend_browser_token_proxy",
+        passed: Boolean(proxyToken),
+        result,
+        url: browserTokenProxyUrl,
+      }),
+    );
+  }
+
+  let directToken = null;
+  if (!clueBrowserTokenUrl || !apiKey || !projectKey || !environment || !serviceKey) {
+    checks.push(
+      requiredInputCheck({
+        id: "clue_backend_browser_token_issue",
+        missing: [
+          ...(!clueBrowserTokenUrl ? ["clue-api-base-url"] : []),
+          ...(!apiKey ? ["CLUE_API_KEY"] : []),
+          ...(!projectKey ? ["CLUE_PROJECT_KEY"] : []),
+          ...(!environment ? ["CLUE_ENVIRONMENT"] : []),
+          ...(!serviceKey ? ["service-key"] : []),
+        ],
+        url: clueBrowserTokenUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: clueBrowserTokenUrl,
+      headers: { "x-clue-api-key": apiKey },
+      body: {
+        projectKey,
+        environment,
+        serviceKey,
+        origin,
+      },
+    });
+    directToken = tokenFromResult(result);
+    checks.push(
+      buildCheck({
+        id: "clue_backend_browser_token_issue",
+        passed: Boolean(directToken),
+        result,
+        url: clueBrowserTokenUrl,
+      }),
+    );
+  }
+
+  const browserToken = proxyToken ?? directToken;
+  if (!browserIngestUrl || !projectKey || !environment || !serviceKey || !browserToken) {
+    checks.push(
+      requiredInputCheck({
+        id: "browser_ingest",
+        missing: [
+          ...(!browserIngestUrl ? ["browser-ingest-url"] : []),
+          ...(!projectKey ? ["CLUE_PROJECT_KEY"] : []),
+          ...(!environment ? ["CLUE_ENVIRONMENT"] : []),
+          ...(!serviceKey ? ["service-key"] : []),
+          ...(!browserToken ? ["browser token"] : []),
+        ],
+        url: browserIngestUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: browserIngestUrl,
+      headers: {
+        origin,
+        "x-clue-project-key": projectKey,
+        "x-clue-service-key": serviceKey,
+        "x-clue-browser-token": browserToken,
+        "x-clue-sdk-request": "browser",
+        "x-clue-environment": environment,
+        "x-clue-sdk-version": "setup-doctor",
+        "x-clue-source-schema-version": "1",
+      },
+      body: buildBrowserEventPayload({ environment, projectKey, serviceKey }),
+    });
+    checks.push(
+      buildCheck({
+        id: "browser_ingest",
+        passed: Boolean(result.transportOk && result.response.ok),
+        result,
+        url: browserIngestUrl,
+      }),
+    );
+  }
+
+  if (!backendIngestUrl || !apiKey || !projectKey || !environment || !backendServiceKey) {
+    checks.push(
+      requiredInputCheck({
+        id: "backend_ingest",
+        missing: [
+          ...(!backendIngestUrl ? ["backend-ingest-url"] : []),
+          ...(!apiKey ? ["CLUE_API_KEY"] : []),
+          ...(!projectKey ? ["CLUE_PROJECT_KEY"] : []),
+          ...(!environment ? ["CLUE_ENVIRONMENT"] : []),
+          ...(!backendServiceKey ? ["backend-service-key"] : []),
+        ],
+        url: backendIngestUrl,
+      }),
+    );
+  } else {
+    const result = await postJson({
+      fetchImpl,
+      url: backendIngestUrl,
+      headers: {
+        "x-clue-project-key": projectKey,
+        "x-clue-api-key": apiKey,
+      },
+      body: buildBackendEventPayload({
+        apiKey,
+        backendServiceKey,
+        environment,
+        projectKey,
+      }),
+    });
+    checks.push(
+      buildCheck({
+        id: "backend_ingest",
+        passed: Boolean(result.transportOk && result.response.ok),
+        result,
+        url: backendIngestUrl,
+      }),
+    );
+  }
+
+  const passed = checks.every((check) => check.passed);
+  return {
+    status: passed ? "passed" : "failed",
+    passed,
+    contract: API_CONNECTIVITY_CONTRACT,
+    checks,
+    inputs: {
+      manifest_loaded: Boolean(manifest),
+      client_backend_url_configured: Boolean(clientBackendUrl),
+      client_frontend_url_configured: Boolean(clientFrontendUrl),
+      clue_api_base_url_configured: Boolean(clueApiBaseUrl),
+      project_key_configured: Boolean(projectKey),
+      environment_configured: Boolean(environment),
+      service_key_configured: Boolean(serviceKey),
+      backend_service_key_configured: Boolean(backendServiceKey),
+      clue_api_key_configured: Boolean(apiKey),
+    },
+  };
+};