@clue-ai/cli 0.0.17 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clue-ai/cli",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
   "bin": {
     "clue-ai": "bin/clue-cli.mjs"

package/src/lifecycle-init.mjs

@@ -580,15 +580,20 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Use environment variable names for Clue configuration values.",
       "For Python/FastAPI code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_API_KEY, and CLUE_INGEST_ENDPOINT from the backend env block.",
       "CLUE_API_BASE_URL is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
-      "For Next.js browser/client code, read NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, NEXT_PUBLIC_CLUE_SERVICE_KEY, and NEXT_PUBLIC_CLUE_INGEST_ENDPOINT from the frontend .env.local block.",
+      "For Next.js browser/client code, read NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, NEXT_PUBLIC_CLUE_SERVICE_KEY, NEXT_PUBLIC_CLUE_INGEST_ENDPOINT, and NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT from the frontend .env.local block.",
       "Do not read process.env.CLUE_PROJECT_KEY, process.env.CLUE_ENVIRONMENT, process.env.CLUE_SERVICE_KEY, or process.env.CLUE_INGEST_ENDPOINT in Next.js browser/client code, and do not add non-public CLUE_* fallbacks there.",
+      "Frontend SDK adapter code is contract-owned Clue setup wiring. The AI may choose the existing import/mount point, but must not invent token URL, env, or initialization semantics.",
+      "For Next.js frontend adapters, read the full customer-backend browser-token proxy URL from NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT. Do not derive it from NEXT_PUBLIC_API_URL, generic app API env names, detected backend ports, or relative frontend-origin paths.",
+      "Do not mix stale browser-token paths such as /api/clue/browser-token, /clue/browser-tokens, or /browser-tokens with the canonical /api/v1/clue/browser-tokens path.",
+      "Do not call ClueInit with empty-string fallbacks for required NEXT_PUBLIC_CLUE_* values. If required Clue env is absent, skip initialization and report the missing env names.",
+      "If a singleton guard is used, do not set initialized = true before ClueInit has actually been called with required config present.",
       "For non-Next.js browser code, use the exact frontend env names written in .env.clue for that service instead of inventing a framework-specific prefix.",
       "Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
       "Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
       "Keep the four setup API hops distinct: customer frontend -> customer backend /api/v1/clue/browser-tokens, customer backend -> Clue /api/v1/ingest/browser-tokens, customer frontend -> Clue /api/v1/ingest/browser, and customer backend -> Clue /api/v1/ingest/backend.",
       "The local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as /api/v1/clue/browser-tokens; do not use a generic path such as /browser-tokens that could be confused with product behavior. It must call Clue server-side at /api/v1/ingest/browser-tokens.",
-      "The frontend browserTokenProvider must send the same service key used by ClueInit to the customer backend token endpoint. For Next.js this value comes from NEXT_PUBLIC_CLUE_SERVICE_KEY.",
+      "The frontend browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT and send the same service key used by ClueInit to the customer backend token endpoint. For Next.js this value comes from NEXT_PUBLIC_CLUE_SERVICE_KEY.",
       "The browser token request must include the frontend service key used by ClueInit. Project key and environment may be included only as public consistency hints; the backend must use server configuration or validate them against server configuration before calling Clue.",
       "The backend browser token proxy must derive request origin from trusted request headers or server request metadata. Do not trust origin, projectKey, or environment from JSON/body payload fields when calling Clue with server CLUE_API_KEY.",
       "For browser token proxy code, the service key sent to Clue must be the frontend ClueInit serviceKey from the browser request, not the backend service's CLUE_SERVICE_KEY.",
@@ -614,6 +619,8 @@ const buildLifecyclePrompt = ({ request, files }) =>
       browser_ingest_endpoint_env: "framework_specific",
       nextjs_browser_ingest_endpoint_env: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
       client_backend_browser_token_proxy_path: "/api/v1/clue/browser-tokens",
+      nextjs_browser_token_endpoint_env:
+        "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
       clue_backend_browser_token_issue_path: "/api/v1/ingest/browser-tokens",
       nextjs_browser_service_key_env: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
       service_key: request.service_key,

package/src/semantic-ci.mjs

@@ -97,6 +97,9 @@ const PURPOSE_CHANGE_STATES = new Set([
   "new_route",
 ]);
 
+const shouldPurposeRecheckAllRoutes = (env) =>
+  env.CLUE_SEMANTIC_PURPOSE_RECHECK_ALL === "1";
+
 const semanticSnapshotHashScope = (request) =>
   [
     "clue_tools_semantic_snapshot",
@@ -2067,27 +2070,27 @@ const buildSnapshot = ({
       currentRoute: route,
       plan,
       route: {
-      ...baseRoute,
-      operation_effects: assignmentCollections.operationEffects,
-      unresolved_operation_effects:
-        assignmentCollections.unresolvedOperationEffects,
-      source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
-      route_input_hash: plan.route_input_hash,
-      previous_route_input_hash: plan.previous_route_input_hash,
-      previous_route_semantic_hash: plan.previous_route_semantic_hash,
-      semantic_origin:
-        plan.origin === "changed_route_needs_review" && aiRoute?.semantics
-          ? "changed_route_needs_review"
-          : plan.origin,
-      semantic_change_reason: plan.semantic_change_reason,
-      previous_semantic_snapshot_version:
-        plan.previous_route?.semantic_snapshot_version,
-      route_semantic_hash: routeSemanticHash({
         ...baseRoute,
         operation_effects: assignmentCollections.operationEffects,
         unresolved_operation_effects:
           assignmentCollections.unresolvedOperationEffects,
-      }),
+        source_evidence_refs: routeEvidenceRefs.map((entry) => entry.id),
+        route_input_hash: plan.route_input_hash,
+        previous_route_input_hash: plan.previous_route_input_hash,
+        previous_route_semantic_hash: plan.previous_route_semantic_hash,
+        semantic_origin:
+          plan.origin === "changed_route_needs_review" && aiRoute?.semantics
+            ? "changed_route_needs_review"
+            : plan.origin,
+        semantic_change_reason: plan.semantic_change_reason,
+        previous_semantic_snapshot_version:
+          plan.previous_route?.semantic_snapshot_version,
+        route_semantic_hash: routeSemanticHash({
+          ...baseRoute,
+          operation_effects: assignmentCollections.operationEffects,
+          unresolved_operation_effects:
+            assignmentCollections.unresolvedOperationEffects,
+        }),
       },
     });
   });
@@ -2537,6 +2540,7 @@ const classifyRoutesForSnapshot = async ({
   hashScope,
   generationContract,
   agentSkills,
+  purposeRecheckAllRoutes = false,
 }) => {
   const previousRoutes = previousRouteMap(previousSnapshot);
   const plans = new Map();
@@ -2562,6 +2566,80 @@ const classifyRoutesForSnapshot = async ({
       previousRoute.route_input_hash === currentHash &&
       hasReusablePreviousRouteSemantics(previousRoute)
     ) {
+      if (purposeRecheckAllRoutes) {
+        const decision = await callAiReuseDecisionProvider({
+          request,
+          env,
+          apiKey: aiProviderApiKey,
+          route: buildRouteEvidencePromptEntry({ route, hashScope }),
+          previousRoute,
+          currentHash,
+          generationContract,
+          agentSkills,
+        });
+        if (
+          decision.purpose_change_state === "same_purpose" &&
+          decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+        ) {
+          plans.set(route.operation_source_key, {
+            origin: "unchanged_route_reused",
+            purpose_change_state: "same_purpose",
+            active_semantic_source: "previous_reused",
+            stability_confidence: decision.confidence,
+            stability_missing_context: decision.missing_context,
+            route_input_hash: currentHash,
+            previous_route: previousRoute,
+            previous_route_input_hash: previousRoute.route_input_hash,
+            previous_route_semantic_hash:
+              previousRoute.route_semantic_hash ??
+              routeSemanticHash(previousRoute),
+            semantic_change_reason: sanitizeText(
+              `Periodic full purpose check confirmed previous semantics still apply: ${decision.reason}`,
+              route,
+            ),
+          });
+          continue;
+        }
+        if (
+          decision.decision === "regenerate" &&
+          decision.confidence >= PURPOSE_STABILITY_CONFIDENCE_THRESHOLD
+        ) {
+          plans.set(route.operation_source_key, {
+            origin: "changed_route_semantic_regenerated",
+            purpose_change_state: decision.purpose_change_state,
+            active_semantic_source: "new_confirmed",
+            stability_confidence: decision.confidence,
+            stability_missing_context: decision.missing_context,
+            route_input_hash: currentHash,
+            previous_route: previousRoute,
+            previous_route_input_hash: previousRoute.route_input_hash,
+            previous_route_semantic_hash:
+              previousRoute.route_semantic_hash ??
+              routeSemanticHash(previousRoute),
+            semantic_change_reason: sanitizeText(decision.reason, route),
+          });
+          routesRequiringGeneration.push(route);
+          continue;
+        }
+        plans.set(route.operation_source_key, {
+          origin: "changed_route_needs_review",
+          purpose_change_state: "insufficient_evidence",
+          active_semantic_source: "previous_kept_pending_review",
+          stability_confidence: decision.confidence,
+          stability_missing_context: decision.missing_context,
+          route_input_hash: currentHash,
+          previous_route: previousRoute,
+          previous_route_input_hash: previousRoute.route_input_hash,
+          previous_route_semantic_hash:
+            previousRoute.route_semantic_hash ??
+            routeSemanticHash(previousRoute),
+          semantic_change_reason: sanitizeText(
+            `Periodic full purpose check could not prove a purpose-level change: ${decision.reason}`,
+            route,
+          ),
+        });
+        continue;
+      }
       plans.set(route.operation_source_key, {
         origin: "unchanged_route_reused",
         purpose_change_state: "same_purpose",
@@ -3186,6 +3264,10 @@ const assertSemanticSnapshotAudit = ({
   const routeByKey = new Map(
     routes.map((route) => [route.operation_source_key, route]),
   );
+  const previousActiveSources = new Set([
+    "previous_reused",
+    "previous_kept_pending_review",
+  ]);
   const allowedOrigins = new Set([
     "new_route_ai_generated",
     "unchanged_route_reused",
@@ -3216,6 +3298,56 @@ const assertSemanticSnapshotAudit = ({
         `semantic snapshot audit found stale route_semantic_hash: ${route.operation_source_key}`,
       );
     }
+    if (auditedSnapshot.schema_version >= 3) {
+      if (route.semantic_stability.purpose_change_state !== route.purpose_change_state) {
+        throw new Error(
+          `semantic snapshot audit found mismatched purpose stability metadata: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        previousActiveSources.has(route.active_semantic_source) &&
+        (!route.previous_route_input_hash ||
+          !route.previous_route_semantic_hash ||
+          !route.previous_semantic_snapshot_version)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found incomplete previous active semantic metadata: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        previousActiveSources.has(route.active_semantic_source) &&
+        route.route_semantic_hash !== route.previous_route_semantic_hash
+      ) {
+        throw new Error(
+          `semantic snapshot audit found changed active semantics for previous-backed route: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "previous_kept_pending_review" &&
+        (route.purpose_change_state !== "insufficient_evidence" ||
+          route.semantic_origin !== "changed_route_needs_review")
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent pending-review semantics: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.active_semantic_source === "previous_reused" &&
+        route.purpose_change_state !== "same_purpose"
+      ) {
+        throw new Error(
+          `semantic snapshot audit found inconsistent reused semantics: ${route.operation_source_key}`,
+        );
+      }
+      if (
+        route.purpose_change_state === "purpose_added" &&
+        (!route.previous_route_input_hash || !route.previous_route_semantic_hash)
+      ) {
+        throw new Error(
+          `semantic snapshot audit found missing previous metadata for added purpose: ${route.operation_source_key}`,
+        );
+      }
+    }
     if (
       (route.semantic_origin === "unchanged_route_reused" ||
         route.semantic_origin === "changed_route_semantic_reused") &&
@@ -3272,12 +3404,14 @@ export const runSemanticCi = async ({
       ? await fetchLatestSnapshot({ request, env })
       : validatePreviousSnapshotForReuse(providedPreviousSnapshot);
   const previousRoutes = previousRouteMap(previousSnapshot);
+  const purposeRecheckAllRoutes = shouldPurposeRecheckAllRoutes(env);
   const routeNeedsAi = routes.some((route) => {
     const previousRoute = previousRoutes.get(route.operation_source_key);
     return (
       !previousRoute ||
       previousRoute.route_input_hash !== routeInputHash(route) ||
-      !hasReusablePreviousRouteSemantics(previousRoute)
+      !hasReusablePreviousRouteSemantics(previousRoute) ||
+      purposeRecheckAllRoutes
     );
   });
   if (routeNeedsAi && !env.CLUE_AI_PROVIDER_API_KEY) {
@@ -3310,6 +3444,7 @@ export const runSemanticCi = async ({
     hashScope,
     generationContract,
     agentSkills,
+    purposeRecheckAllRoutes,
   });
   const promptRoutes = routesRequiringGeneration.map((route) =>
     buildRouteEvidencePromptEntry({ route, hashScope }),

package/src/setup-ai-contract.mjs

@@ -1,5 +1,5 @@
 export const AI_SETUP_CONTRACT_VERSION =
-  "2026-05-10.api-connectivity-contract.v6";
+  "2026-05-10.frontend-adapter-contract.v8";
 
 export const SETUP_DOCTRINE = {
   purpose:
@@ -32,6 +32,7 @@ export const DETERMINISTIC_CONTROL_MODEL = {
     "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",
+    "canonical frontend SDK adapter env names, token proxy path, and initialization safety checks",
   ],
 };
 
@@ -79,6 +80,27 @@ export const API_CONNECTIVITY_CONTRACT = {
     "setup-doctor checks local API connectivity before user flows. setup-watch remains user-operated lifecycle and event-delivery verification.",
 };
 
+export const FRONTEND_ADAPTER_CONTRACT = {
+  purpose:
+    "Frontend SDK adapter code is part of the Clue setup contract. The AI may choose where the adapter is imported, but must not invent new token URL, env, or initialization semantics.",
+  nextjs_public_env: [
+    "NEXT_PUBLIC_CLUE_PROJECT_KEY",
+    "NEXT_PUBLIC_CLUE_ENVIRONMENT",
+    "NEXT_PUBLIC_CLUE_SERVICE_KEY",
+    "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+    "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
+  ],
+  browser_token_proxy_path: "/api/v1/clue/browser-tokens",
+  rules: [
+    "Do not derive the Clue browser-token proxy from generic app API env names such as NEXT_PUBLIC_API_URL.",
+    "Do not mix stale browser token paths with the canonical /api/v1/clue/browser-tokens path in the same adapter.",
+    "Next.js browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT, whose value is the customer backend browser-token proxy URL.",
+    "Do not call ClueInit with empty-string fallbacks for required NEXT_PUBLIC_CLUE_* values.",
+    "If a singleton guard is used, do not mark initialized=true before ClueInit has been called with required config present.",
+    "The browser token provider must send the same frontend serviceKey used by ClueInit.",
+  ],
+};
+
 export const setupDoctrineSkillLines = () => [
   `- Purpose: ${SETUP_DOCTRINE.purpose}`,
   `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
@@ -87,5 +109,6 @@ export const setupDoctrineSkillLines = () => [
   `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
   `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
   `- API connectivity: ${API_CONNECTIVITY_CONTRACT.purpose}`,
+  `- Frontend adapter: ${FRONTEND_ADAPTER_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

@@ -42,8 +42,13 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`",
     "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`",
+    "send the same service key used by `ClueInit`",
+    "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
     "Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`",
+    "Frontend SDK adapter code is contract-owned Clue setup wiring",
+    "Do not derive it from `NEXT_PUBLIC_API_URL`",
+    "Do not call `ClueInit` with empty-string fallbacks",
+    "do not set `initialized = true` before `ClueInit`",
     "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
   ],
   "clue-setup-audit": [
@@ -52,6 +57,10 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "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 frontend browser token providers that derive the Clue proxy URL from `NEXT_PUBLIC_API_URL`",
+    "Reject frontend adapters that mix stale browser-token paths",
+    "Reject frontend adapters that set `initialized = true` before calling `ClueInit`",
+    "Audit the setup diff against the Clue setup contract even when the code was written by another agent",
     "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",
@@ -736,7 +745,13 @@ const NEXT_PUBLIC_CLUE_NAMES = [
   "CLUE_ENVIRONMENT",
   "CLUE_SERVICE_KEY",
   "CLUE_INGEST_ENDPOINT",
+  "CLUE_BROWSER_TOKEN_ENDPOINT",
 ];
+const CANONICAL_BROWSER_TOKEN_PROXY_PATH = "/api/v1/clue/browser-tokens";
+const BROWSER_TOKEN_PATH_PATTERN =
+  /\/[^"'`\s]*(?:browser[-_]?tokens?|browser[-_]?token)\b/i;
+const GENERIC_PUBLIC_API_ENV_PATTERN =
+  /\bprocess\.env\.(?:(?:NEXT_PUBLIC|VITE|REACT_APP)_(?!CLUE_)[A-Z0-9_]*(?:API|BACKEND|BASE|URL)[A-Z0-9_]*)\b/;
 
 const findNextLifecycleNonPublicEnvFiles = ({
   dependencySources,
@@ -810,14 +825,83 @@ const findNextBrowserTokenProviderMissingPublicServiceKeyFiles = ({
     .map((source) => source.file_path);
 };
 
+const findNextBrowserTokenProviderMissingPublicEndpointFiles = ({
+  dependencySources,
+  frontendSources,
+}) => {
+  const roots = nextPackageRoots(dependencySources);
+  if (roots.length === 0) return [];
+  return frontendSources
+    .filter((source) => sourceIsUnderAnyRoot(source, roots))
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter(
+      (source) =>
+        !/\bprocess\.env\.NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT\b/.test(
+          source.text,
+        ),
+    )
+    .map((source) => source.file_path);
+};
+
+const browserTokenPathLiterals = (text) =>
+  [
+    ...stripSourceNoise(text).matchAll(
+      /(["'`])([^"'`]*(?:browser[-_]?tokens?|browser[-_]?token)[^"'`]*)\1/gi,
+    ),
+  ].map((match) => match[2]);
+
 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);
+      const tokenPathLiterals = browserTokenPathLiterals(text).filter(
+        (literal) => BROWSER_TOKEN_PATH_PATTERN.test(literal),
+      );
+      if (tokenPathLiterals.length === 0) {
+        return false;
+      }
+      return tokenPathLiterals.some(
+        (literal) => !literal.includes(CANONICAL_BROWSER_TOKEN_PROXY_PATH),
+      );
+    })
+    .map((source) => source.file_path);
+
+const findBrowserTokenProviderNonClueEndpointEnvFiles = (frontendSources) =>
+  frontendSources
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter((source) =>
+      GENERIC_PUBLIC_API_ENV_PATTERN.test(stripSourceNoise(source.text)),
+    )
+    .map((source) => source.file_path);
+
+const findClueInitEmptyEnvFallbackFiles = (frontendSources) =>
+  frontendSources
+    .filter(
+      (source) =>
+        sourceImportsFrontendSdk(source) ||
+        sourceLooksLikeBrowserTokenProvider(source),
+    )
+    .filter((source) =>
+      /process\.env\.NEXT_PUBLIC_CLUE_[A-Z0-9_]+\s*(?:\?\?|\|\|)\s*(["'])\1/.test(
+        stripSourceNoise(source.text),
+      ),
+    )
+    .map((source) => source.file_path);
+
+const findFrontendInitBeforeClueInitFiles = (frontendSources) =>
+  frontendSources
+    .filter((source) => sourceImportsFrontendSdk(source))
+    .filter((source) => {
+      const text = stripSourceNoise(source.text, { stripStrings: true });
+      const initializedIndex = text.search(/\binitialized\s*=\s*true\b/);
+      const clueInitIndex = text.search(/\bClueInit\s*\(/);
+      return (
+        initializedIndex >= 0 &&
+        clueInitIndex >= 0 &&
+        initializedIndex < clueInitIndex
+      );
     })
     .map((source) => source.file_path);
 
@@ -1001,11 +1085,22 @@ const checkSdkLifecycle = ({
     findBrowserTokenProviderMissingServiceKeyFiles(frontendSources);
   const browserTokenProviderWrongProxyPathFiles =
     findBrowserTokenProviderWrongProxyPathFiles(frontendSources);
+  const browserTokenProviderNonClueEndpointEnvFiles =
+    findBrowserTokenProviderNonClueEndpointEnvFiles(frontendSources);
+  const clueInitEmptyEnvFallbackFiles =
+    findClueInitEmptyEnvFallbackFiles(frontendSources);
+  const frontendInitBeforeClueInitFiles =
+    findFrontendInitBeforeClueInitFiles(frontendSources);
   const nextBrowserTokenProviderMissingPublicServiceKeyFiles =
     findNextBrowserTokenProviderMissingPublicServiceKeyFiles({
       dependencySources,
       frontendSources,
     });
+  const nextBrowserTokenProviderMissingPublicEndpointFiles =
+    findNextBrowserTokenProviderMissingPublicEndpointFiles({
+      dependencySources,
+      frontendSources,
+    });
   const browserTokenProxyUsingBackendServiceKeyFiles =
     findBrowserTokenProxyUsingBackendServiceKeyFiles(backendSources);
   const browserTokenProxyTrustingBodyOriginFiles =
@@ -1074,8 +1169,14 @@ const checkSdkLifecycle = ({
         browserTokenProviderMissingServiceKeyFiles,
       browser_token_provider_wrong_proxy_path_files:
         browserTokenProviderWrongProxyPathFiles,
+      browser_token_provider_non_clue_endpoint_env_files:
+        browserTokenProviderNonClueEndpointEnvFiles,
+      clue_init_empty_env_fallback_files: clueInitEmptyEnvFallbackFiles,
+      frontend_init_before_clue_init_files: frontendInitBeforeClueInitFiles,
       next_browser_token_provider_missing_public_service_key_files:
         nextBrowserTokenProviderMissingPublicServiceKeyFiles,
+      next_browser_token_provider_missing_public_endpoint_files:
+        nextBrowserTokenProviderMissingPublicEndpointFiles,
       browser_token_proxy_uses_backend_service_key_files:
         browserTokenProxyUsingBackendServiceKeyFiles,
       browser_token_proxy_trusts_body_origin_files:
@@ -1102,7 +1203,11 @@ const checkSdkLifecycle = ({
       wildcardFrontendSdkDependencyFiles.length === 0 &&
       browserTokenProviderMissingServiceKeyFiles.length === 0 &&
       browserTokenProviderWrongProxyPathFiles.length === 0 &&
+      browserTokenProviderNonClueEndpointEnvFiles.length === 0 &&
+      clueInitEmptyEnvFallbackFiles.length === 0 &&
+      frontendInitBeforeClueInitFiles.length === 0 &&
       nextBrowserTokenProviderMissingPublicServiceKeyFiles.length === 0 &&
+      nextBrowserTokenProviderMissingPublicEndpointFiles.length === 0 &&
       browserTokenProxyUsingBackendServiceKeyFiles.length === 0 &&
       browserTokenProxyTrustingBodyOriginFiles.length === 0 &&
       browserTokenProxyTrustingBodyProjectEnvironmentFiles.length === 0 &&

package/src/setup-doctor.mjs

@@ -247,9 +247,11 @@ export const runSetupDoctor = async ({
     optionalString(flags.get("origin")) ??
     clientFrontendUrl ??
     "http://localhost";
-  const browserTokenProxyUrl = clientBackendUrl
-    ? joinUrl(clientBackendUrl, BROWSER_TOKEN_PROXY_PATH)
-    : null;
+  const browserTokenProxyUrl =
+    optionalString(flags.get("browser-token-proxy-url")) ??
+    optionalString(env.NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT) ??
+    optionalString(env.CLUE_BROWSER_TOKEN_ENDPOINT) ??
+    (clientBackendUrl ? joinUrl(clientBackendUrl, BROWSER_TOKEN_PROXY_PATH) : null);
   const clueBrowserTokenUrl = clueApiBaseUrl
     ? joinUrl(clueApiBaseUrl, CLUE_BROWSER_TOKEN_PATH)
     : null;
@@ -272,7 +274,11 @@ export const runSetupDoctor = async ({
       requiredInputCheck({
         id: "client_backend_browser_token_proxy",
         missing: [
-          ...(!browserTokenProxyUrl ? ["client-backend-url"] : []),
+          ...(!browserTokenProxyUrl
+            ? [
+                "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT or CLUE_BROWSER_TOKEN_ENDPOINT or client-backend-url",
+              ]
+            : []),
           ...(!serviceKey ? ["service-key"] : []),
         ],
         url: browserTokenProxyUrl,
@@ -424,6 +430,7 @@ export const runSetupDoctor = async ({
       manifest_loaded: Boolean(manifest),
       client_backend_url_configured: Boolean(clientBackendUrl),
       client_frontend_url_configured: Boolean(clientFrontendUrl),
+      browser_token_proxy_url_configured: Boolean(browserTokenProxyUrl),
       clue_api_base_url_configured: Boolean(clueApiBaseUrl),
       project_key_configured: Boolean(projectKey),
       environment_configured: Boolean(environment),

package/src/setup-help.mjs

@@ -6,6 +6,7 @@ import {
   AI_SETUP_CONTRACT_VERSION,
   API_CONNECTIVITY_CONTRACT,
   DETERMINISTIC_CONTROL_MODEL,
+  FRONTEND_ADAPTER_CONTRACT,
   SETUP_DOCTRINE,
 } from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
@@ -22,6 +23,7 @@ export const buildAiSetupHelp = () => ({
     setup_doctrine: SETUP_DOCTRINE,
     deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
     api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
+    frontend_adapter_contract: FRONTEND_ADAPTER_CONTRACT,
     agent_primary_task:
       "Decide where to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing repository lifecycle boundaries, then apply only those minimal Clue SDK wiring changes.",
     implementation_workstreams: ["sdk_lifecycle_placement"],
@@ -60,8 +62,9 @@ export const buildAiSetupHelp = () => ({
           "NEXT_PUBLIC_CLUE_ENVIRONMENT",
           "NEXT_PUBLIC_CLUE_SERVICE_KEY",
           "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+          "NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT",
         ],
-        rule: "When the frontend framework is Next.js, browser/client code must read only these NEXT_PUBLIC_* Clue variables. Do not add process.env.CLUE_* fallbacks in client-bundled code.",
+        rule: "When the frontend framework is Next.js, browser/client code must read only these NEXT_PUBLIC_* Clue variables. Do not add process.env.CLUE_* fallbacks in client-bundled code. browserTokenProvider must call NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT, not a relative frontend-origin path or generic NEXT_PUBLIC_API_URL.",
       },
       backend_browser_token_proxy_env: {
         variables: ["CLUE_API_KEY", "CLUE_API_BASE_URL"],

package/src/setup-prepare.mjs

@@ -16,11 +16,14 @@ const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
 const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
 const BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
 const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
+const BROWSER_TOKEN_PROXY_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.client_backend_browser_token_proxy.path;
 const FRONTEND_PUBLIC_ENV_NAMES = [
   "CLUE_INGEST_ENDPOINT",
   "CLUE_PROJECT_KEY",
   "CLUE_ENVIRONMENT",
   "CLUE_SERVICE_KEY",
+  "CLUE_BROWSER_TOKEN_ENDPOINT",
 ];
 const BACKEND_RUNTIME_ENV_NAMES = [
   "CLUE_SERVICE_KEY",
@@ -187,6 +190,7 @@ const frontendEnvName = ({ target, name }) =>
     : name;
 
 const buildServiceEnvBlock = ({
+  browserTokenEndpoint,
   target,
   setupContext,
   includeBrowserTokenProxyConfig = false,
@@ -211,6 +215,12 @@ const buildServiceEnvBlock = ({
       value: target.service_key,
     },
   ];
+  if (target.kind === "frontend") {
+    variables.push({
+      name: frontendEnvName({ target, name: "CLUE_BROWSER_TOKEN_ENDPOINT" }),
+      value: browserTokenEndpoint,
+    });
+  }
   if (target.kind === "backend") {
     variables.push({ name: "CLUE_API_KEY", value: setupContext.clue_api_key });
     if (includeBrowserTokenProxyConfig) {
@@ -266,6 +276,14 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
   const includeBrowserTokenProxyConfig = watchTargets.some(
     (target) => target.kind === "frontend",
   );
+  const backendTarget = watchTargets.find((target) => target.kind === "backend");
+  const backendUrlCandidate =
+    optionalString(backendTarget?.local_url_candidates?.[0]) ??
+    "http://<client-backend-url>";
+  const browserTokenEndpoint = buildEndpoint(
+    backendUrlCandidate,
+    BROWSER_TOKEN_PROXY_PATH,
+  );
   return {
     status: "ready",
     env_file_path: DEFAULT_ENV_GUIDE_PATH,
@@ -277,6 +295,7 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
       service_key: target.service_key,
       env_file_candidates: envFileCandidates(target),
       env_block: buildServiceEnvBlock({
+        browserTokenEndpoint,
         target,
         setupContext,
         includeBrowserTokenProxyConfig,

package/src/setup-tool.mjs

@@ -322,14 +322,19 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
       "Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
       `For local env files, use the service-specific env blocks written to \`.env.clue\` by \`${clueCliCommand("setup")}\`; do not ask the user to guess \`CLUE_SERVICE_KEY\`.`,
-      "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`, `NEXT_PUBLIC_CLUE_ENVIRONMENT`, `NEXT_PUBLIC_CLUE_SERVICE_KEY`, and `NEXT_PUBLIC_CLUE_INGEST_ENDPOINT` from the frontend `.env.local` block.",
+      "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`, `NEXT_PUBLIC_CLUE_ENVIRONMENT`, `NEXT_PUBLIC_CLUE_SERVICE_KEY`, `NEXT_PUBLIC_CLUE_INGEST_ENDPOINT`, and `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT` from the frontend `.env.local` block.",
       "Do not read `process.env.CLUE_PROJECT_KEY`, `process.env.CLUE_ENVIRONMENT`, `process.env.CLUE_SERVICE_KEY`, or `process.env.CLUE_INGEST_ENDPOINT` in Next.js browser/client code, and do not add non-public `CLUE_*` fallbacks there.",
+      "Frontend SDK adapter code is contract-owned Clue setup wiring. The AI may choose the existing import/mount point, but must not invent token URL, env, or initialization semantics.",
+      "For Next.js frontend adapters, read the full customer-backend browser-token proxy URL from `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT`. Do not derive it from `NEXT_PUBLIC_API_URL`, generic app API env names, detected backend ports, or relative frontend-origin paths.",
+      "Do not mix stale browser-token paths such as `/api/clue/browser-token`, `/clue/browser-tokens`, or `/browser-tokens` with the canonical `/api/v1/clue/browser-tokens` path.",
+      "Do not call `ClueInit` with empty-string fallbacks for required `NEXT_PUBLIC_CLUE_*` values. If required Clue env is absent, skip initialization and report the missing env names.",
+      "If a singleton guard is used, do not set `initialized = true` before `ClueInit` has actually been called with required config present.",
       "For non-Next.js browser code, use the exact frontend env names written in `.env.clue` for that service instead of inventing a framework-specific prefix.",
       "Never put `CLUE_API_KEY` in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side `CLUE_API_KEY` and requests `POST /api/v1/ingest/browser-tokens` from Clue.",
       "Configure frontend `ClueInit` with `browserTokenProvider` that calls the local backend token endpoint and returns the token string.",
       "The local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as `/api/v1/clue/browser-tokens`; do not use a generic path such as `/browser-tokens` that could be confused with product behavior. It must call Clue server-side at `/api/v1/ingest/browser-tokens`.",
-      "The frontend `browserTokenProvider` must send the same service key used by `ClueInit` to the customer backend token endpoint. For Next.js this value comes from `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
+      "The frontend `browserTokenProvider` must call `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT` and send the same service key used by `ClueInit` to the customer backend token endpoint. For Next.js this value comes from `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
       "The browser token request must include the frontend service key used by `ClueInit`. Project key and environment may be included only as public consistency hints; the backend must use server configuration or validate them against server configuration before calling Clue.",
       "The backend browser token proxy must derive origin from trusted request headers or server request metadata. Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`.",
       "For browser token proxy code, the service key sent to Clue must be the frontend `ClueInit` serviceKey from the browser request, not the backend service's `CLUE_SERVICE_KEY`.",
@@ -367,12 +372,17 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Reject backend setup when backend routes exist but no backend Clue SDK dependency/import/init was added.",
       "Reject awaited lifecycle calls that can block host service behavior.",
       "Reject browser token proxy code that forwards origin, projectKey, or environment from request JSON/body under server `CLUE_API_KEY`.",
+      "Reject frontend browser token providers that derive the Clue proxy URL from `NEXT_PUBLIC_API_URL`, generic app API env names, detected backend ports, or non-Clue routing assumptions.",
+      "Reject frontend adapters that mix stale browser-token paths such as `/api/clue/browser-token`, `/clue/browser-tokens`, or `/browser-tokens` with the canonical `/api/v1/clue/browser-tokens` path.",
+      "Reject frontend adapters that set `initialized = true` before calling `ClueInit`, or pass empty-string fallbacks for required `NEXT_PUBLIC_CLUE_*` values into `ClueInit`.",
+      "Audit the setup diff against the Clue setup contract even when the code was written by another agent or an earlier pass. Ownership of authorship is irrelevant to approval.",
       "Reject setup that covers only one login path when multiple login success paths are clearly present.",
       "Reject ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or any repeated user interaction path.",
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
       "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 Clue SDK dependency entries that use `*` or `latest` instead of a concrete published version or package-manager-resolved semver range.",
+      "Reject Next.js browser token providers that do not read `NEXT_PUBLIC_CLUE_BROWSER_TOKEN_ENDPOINT`.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
       "Reject whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines.",