@clue-ai/cli 0.0.17 → 0.0.19

package/src/setup-check.mjs

@@ -39,11 +39,18 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`",
     "Do not read `process.env.CLUE_PROJECT_KEY`",
     "CLUE_API_BASE_URL` is not part of backend SDK initialization",
-    "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`",
+    "Install Clue SDK dependencies through the latest channel",
+    "`@clue-ai/browser-sdk` must use `latest`",
+    "Python backend SDK dependencies must not be pinned",
     "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 +59,11 @@ 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`",
+    "Reject Clue SDK dependency entries that pin stale fixed versions",
+    "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",
@@ -138,6 +150,12 @@ const DEPENDENCY_FILE_CANDIDATES = [
   "poetry.lock",
   "Pipfile",
 ];
+const PYTHON_BACKEND_DEPENDENCY_DECLARATION_FILES = [
+  "requirements.txt",
+  "requirements-dev.txt",
+  "pyproject.toml",
+  "Pipfile",
+];
 const exists = async (path) => {
   try {
     await access(path);
@@ -385,6 +403,20 @@ const setupSourcePaths = async ({ repoRoot, request, includeFrontend }) => {
   return existing.length ? existing : requested;
 };
 
+const setupBackendRootPaths = (request) => {
+  const configuredRoots = [
+    ...(Array.isArray(request?.backend_root_paths)
+      ? request.backend_root_paths
+      : []),
+    request?.backend_root_path,
+  ]
+    .filter((root) => typeof root === "string" && root.trim())
+    .map((root) => root.trim());
+  return configuredRoots.length
+    ? [...new Set(configuredRoots)]
+    : (request?.allowed_source_paths ?? []);
+};
+
 const secretLeakPatterns = [
   /pk_(live|test)_[A-Za-z0-9_-]+/,
   /sk_(live|test)_[A-Za-z0-9_-]+/,
@@ -736,7 +768,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,
@@ -761,17 +799,71 @@ const findNextLifecycleNonPublicEnvFiles = ({
     .map((source) => source.file_path);
 };
 
-const findWildcardFrontendSdkDependencyFiles = (dependencySources) =>
+const findNonLatestFrontendSdkDependencyFiles = (dependencySources) =>
   packageJsonSourcesWithDependency(dependencySources, FRONTEND_SDK_PACKAGE)
     .filter((source) => {
       const version = packageJsonDependencyVersion(
         source.text,
         FRONTEND_SDK_PACKAGE,
       );
-      return version === "*" || version === "latest";
+      return version !== "latest";
     })
     .map((source) => source.file_path);
 
+const sourceIsPythonBackendDependencyDeclaration = (source) =>
+  PYTHON_BACKEND_DEPENDENCY_DECLARATION_FILES.some((fileName) =>
+    source.file_path.endsWith(fileName),
+  );
+
+const backendSdkDependencyLineHasPinnedVersion = (line, packageName) => {
+  const stripped = line.trim();
+  if (!stripped || stripped.startsWith("#")) return false;
+  const withoutInlineComment = stripped.replace(/\s+#.*$/, "");
+  const packagePattern = new RegExp(
+    `(^|[\\s"'=,{\\[]+)${escapeRegex(packageName)}($|[\\s"'=<>~!@,;)}\\]]+)`,
+    "i",
+  );
+  if (!packagePattern.test(withoutInlineComment)) return false;
+
+  const requirementPattern = new RegExp(
+    `${escapeRegex(packageName)}(?:\\[[^\\]]+\\])?([^\\s"',;}\\]]*)`,
+    "i",
+  );
+  const requirementMatch = requirementPattern.exec(withoutInlineComment);
+  const suffix = requirementMatch?.[1] ?? "";
+  if (suffix && suffix !== ";") {
+    return true;
+  }
+
+  const keyPattern = new RegExp(
+    `^\\s*["']?${escapeRegex(packageName)}["']?\\s*=\\s*(.+)$`,
+    "i",
+  );
+  const keyMatch = keyPattern.exec(withoutInlineComment);
+  if (!keyMatch) return false;
+  const value = keyMatch[1].trim();
+  if (/^["']\*["']$/.test(value)) return false;
+  if (/version\s*=\s*["']\*["']/.test(value)) return false;
+  return true;
+};
+
+const findPinnedBackendSdkDependencyFiles = (
+  dependencySources,
+  packageNames,
+) =>
+  dependencySources
+    .filter(sourceIsPythonBackendDependencyDeclaration)
+    .filter((source) =>
+      source.text
+        .split(/\r?\n/)
+        .some((line) =>
+          packageNames.some((packageName) =>
+            backendSdkDependencyLineHasPinnedVersion(line, packageName),
+          ),
+        ),
+    )
+    .map((source) => source.file_path);
+
 const sourceLooksLikeBrowserTokenProvider = (source) => {
   const text = stripSourceNoise(source.text);
   return (
@@ -810,14 +902,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);
 
@@ -969,6 +1130,10 @@ const checkSdkLifecycle = ({
   const backendSdkDependencyPresent =
     !backendPresent ||
     dependencyHasAnyPackage(dependencySources, backendSpec.packages);
+  const pinnedBackendSdkDependencyFiles = findPinnedBackendSdkDependencyFiles(
+    dependencySources,
+    backendSpec.packages,
+  );
   const backendSdkImportPresent =
     !backendPresent ||
     sourcesHavePythonImport(backendSources, backendSpec.imports);
@@ -995,17 +1160,28 @@ const checkSdkLifecycle = ({
     dependencySources,
     frontendSources,
   });
-  const wildcardFrontendSdkDependencyFiles =
-    findWildcardFrontendSdkDependencyFiles(dependencySources);
+  const nonLatestFrontendSdkDependencyFiles =
+    findNonLatestFrontendSdkDependencyFiles(dependencySources);
   const browserTokenProviderMissingServiceKeyFiles =
     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 =
@@ -1048,6 +1224,7 @@ const checkSdkLifecycle = ({
         ? null
         : backendSpec.blocker,
       sdk_dependency_present: backendSdkDependencyPresent,
+      pinned_sdk_dependency_files: pinnedBackendSdkDependencyFiles,
       sdk_import_present: backendSdkImportPresent,
       sdk_dependency_or_import_present: backendSdkPresent,
       sdk_init_present: backendInitPresent,
@@ -1069,13 +1246,19 @@ const checkSdkLifecycle = ({
         frontendLifecycleFilesWithoutVerifiedSdk,
       wrong_sdk_packages: wrongFrontendSdkPackages,
       next_lifecycle_non_public_env_files: nextLifecycleNonPublicEnvFiles,
-      wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
+      non_latest_sdk_dependency_files: nonLatestFrontendSdkDependencyFiles,
       browser_token_provider_missing_service_key_files:
         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:
@@ -1093,16 +1276,21 @@ const checkSdkLifecycle = ({
       missingApis.length === 0 &&
       backendSdkPresent &&
       backendSdkInstallabilityVerified &&
+      pinnedBackendSdkDependencyFiles.length === 0 &&
       backendInitPresent &&
       backendMissingApis.length === 0 &&
       frontendSdkPresent &&
       frontendLifecycleFilesWithoutVerifiedSdk.length === 0 &&
       wrongFrontendSdkPackages.length === 0 &&
       nextLifecycleNonPublicEnvFiles.length === 0 &&
-      wildcardFrontendSdkDependencyFiles.length === 0 &&
+      nonLatestFrontendSdkDependencyFiles.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 &&
@@ -1309,7 +1497,7 @@ export const runSetupCheck = async ({
 
   if (requireSdkLifecycle) {
     const sdkLifecycle = checkSdkLifecycle({
-      backendRootPaths: request?.allowed_source_paths ?? [],
+      backendRootPaths: setupBackendRootPaths(request),
       dependencySources,
       framework: request?.framework,
       sources,

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"],
@@ -53,6 +55,21 @@ export const buildAiSetupHelp = () => ({
         "whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines",
       ],
     },
+    sdk_dependency_contract: {
+      frontend: {
+        package: "@clue-ai/browser-sdk",
+        install: "package-manager add @clue-ai/browser-sdk@latest",
+        rule:
+          "Frontend package.json must declare @clue-ai/browser-sdk as latest. Fixed versions and * are rejected by setup-check because stale SDKs break setup contracts.",
+      },
+      backend: {
+        fastapi_package: "clue-fastapi-sdk",
+        django_package: "clue-django-sdk",
+        install: "pip install --upgrade <backend-sdk-package>",
+        rule:
+          "Python backend SDK dependency declarations must be unpinned so pip resolves the latest release. Fixed ==, ~=, <=, >=, <, >, local path, and exact-version declarations are rejected by setup-check.",
+      },
+    },
     environment_contract: {
       nextjs_frontend_client_env: {
         variables: [
@@ -60,8 +77,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"],
@@ -83,9 +101,21 @@ export const buildAiSetupHelp = () => ({
       owner: "ai_or_user",
       ai_agent_may_run: true,
       command: clueCliCommand("setup-doctor --local"),
-      rule: "Run setup-doctor after local frontend/backend services and required env are available. It checks API connectivity only and does not replace user-operated setup-watch.",
+      rule: "Run setup-doctor after local frontend/backend services and required env are available. setup-agent blocks when required setup-doctor inputs are missing or connectivity fails, unless setup-doctor is explicitly skipped. It checks API connectivity only and does not replace user-operated setup-watch.",
       checked_hops: Object.keys(API_CONNECTIVITY_CONTRACT.hops),
     },
+    setup_agent: {
+      owner: "clue_cli",
+      command: clueCliCommand("setup-agent --repo ."),
+      providers: ["openai", "anthropic"],
+      env:
+        "Set exactly CLUE_AI_PROVIDER, CLUE_AI_PROVIDER_API_KEY, and CLUE_AI_MODEL. setup-agent uses the same AI provider configuration as the rest of the Clue CLI. Optional CLI overrides are --ai-provider, --ai-provider-api-key, and --ai-model; do not use ambiguous --api_key flags.",
+      model_role:
+        "Return a strict structured lifecycle plan only; the CLI owns scanning, edit application, checks, doctor preflight, retry, and final status.",
+      tool_calling:
+        "OpenAI uses Responses API forced function tools with strict schema and parallel_tool_calls false. Anthropic uses Messages API tool_choice with the same input schema.",
+      setup_watch_auto_run: false,
+    },
     completion_boundary: {
       ai_may_claim: [
         "Clue setup code changes were applied",

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

@@ -316,27 +316,34 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Do not add per-call try/catch, try/except, `.catch`, or custom safe wrappers solely around official Clue SDK public lifecycle calls.",
       "Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
       "Add or report the required SDK dependency instead of fabricating lifecycle APIs.",
-      "For frontend code, add the real `@clue-ai/browser-sdk` dependency when missing. Do not invent `clue-js-sdk`, `@clue/browser-sdk`, local placeholder modules, or dynamic imports that hide a missing SDK.",
+      "For frontend code, add the real `@clue-ai/browser-sdk` dependency when missing. Use the latest channel (`@clue-ai/browser-sdk@latest`) so setup receives current SDK fixes. Do not invent `clue-js-sdk`, `@clue/browser-sdk`, local placeholder modules, or dynamic imports that hide a missing SDK.",
       `When lifecycle edits are clear, write an exact replacement plan to a temporary local JSON file and apply it with \`${clueCliCommand("lifecycle-apply --plan <plan-file> --repo .")}\`.`,
       "If npm/npx cannot fetch the Clue CLI package, report a blocker with the exact command and error instead of manually applying replacement plans.",
       "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`.",
       "If a backend-owned browser token endpoint is implemented, read `CLUE_API_BASE_URL` from the backend env block and normalize it so values with or without a trailing `/api/v1` do not produce duplicate paths.",
-      "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT` from the backend env block.",
+      "For FastAPI code, add unpinned `clue-fastapi-sdk` to the backend dependency file when missing so pip resolves the latest release, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `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.",
-      "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
+      "Python backend SDK dependencies must not be pinned.",
+      "`@clue-ai/browser-sdk` must use `latest`.",
+      "Install Clue SDK dependencies through the latest channel. Frontend package managers must use `@clue-ai/browser-sdk@latest`; Python backend dependency declarations must not pin `clue-fastapi-sdk` or `clue-django-sdk` to a fixed version.",
       "Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
       "For frontend code, pass `serviceKey` from the frontend service env name written by `.env.clue` to `ClueInit`; in Next.js browser/client code that name is `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
       "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable; if it is not published or cannot be verified, report a blocker instead of adding a guessed dependency or import.",
@@ -367,12 +374,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 Clue SDK dependency entries that pin stale fixed versions. Frontend package.json must use `@clue-ai/browser-sdk: latest`; Python backend SDK dependency declarations must be unpinned or package-manager wildcard-latest.",
+      "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.",
@@ -392,7 +404,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
       `Run \`${clueCliCommand("setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle")}\` when possible.`,
-      `Run \`${clueCliCommand("setup-doctor --local")}\` when local frontend/backend services are running and required env values are available. Report skipped_setup_doctor with the missing service URL or env name when it cannot run.`,
+      `Run \`${clueCliCommand("setup-doctor --local")}\` when local frontend/backend services are running. Missing setup-doctor inputs or failed API hops are blockers unless the user explicitly skipped setup-doctor.`,
       `Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch requires the user to operate real local frontend/backend services and login/logout/account flows.`,
       "If the user has not provided setup-watch or setup-screen evidence, report event delivery verification as `user_verification_pending` and do not state `setup completed`.",
       "Local static verification passed does not mean setup complete unless dependency install, SDK imports, app startup, and user-provided setup-watch or setup-screen event delivery were all verified.",
@@ -465,7 +477,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     `- Setup API connectivity has four distinct hops: ${Object.entries(API_CONNECTIVITY_CONTRACT.hops)
       .map(([name, hop]) => `${name}=${hop.method} ${hop.path}`)
       .join(", ")}.`,
-    `- Run \`${clueCliCommand("setup-doctor --local")}\` when local services and required env are available. This checks API connectivity only; it does not replace user-operated setup-watch.`,
+    `- Run \`${clueCliCommand("setup-doctor --local")}\` when local services are running. Missing setup-doctor inputs or failed API hops are blockers unless the user explicitly skipped setup-doctor. This checks API connectivity only; it does not replace user-operated setup-watch.`,
     "- Do not implement or refresh semantic snapshot CI during lifecycle placement; report a blocker if generated semantic artifacts are missing or stale.",
     `- Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch and the Clue setup screen are user-operated verification steps, not implementation-agent responsibility.`,
     "- The full setup must start with `clue-setup-orchestrator`.",