@clue-ai/cli 0.0.22 → 0.0.24

package/src/setup-check.mjs

@@ -39,6 +39,8 @@ 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",
+    "FastAPI `clue_init_fastapi` must pass `service_key`",
+    "Do not use `os.environ[\"CLUE_*\"]`",
     "Install Clue SDK dependencies through the latest channel",
     "`@clue-ai/browser-sdk` must use `latest`",
     "Python backend SDK dependencies must not be pinned",
@@ -49,6 +51,7 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "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`",
+    "Next.js browser SDK adapter files must start with `\"use client\"`",
     "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",
@@ -58,9 +61,13 @@ 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 backend Clue setup code that uses `os.environ[\"CLUE_*\"]` required indexing instead of non-crashing env reads",
     "Reject browser token proxy code that forwards origin, projectKey, or environment from request JSON/body under server `CLUE_API_KEY`",
+    "Reject browser token proxy code that sends `CLUE_API_KEY` as `Authorization: Bearer`",
+    "Reject browser token proxy code that imports undeclared HTTP client dependencies",
     "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 Next.js browser SDK adapter files that omit `\"use client\"`",
     "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",
@@ -71,6 +78,7 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-local-verification": [
     "`setup-check --require-sdk-lifecycle` is a static source check only",
     "`setup-doctor --local` API connectivity preflight",
+    "setup-agent quality gates must be reported honestly",
     "Verify frontend SDK installability/import",
     "Verify backend SDK installability/import",
     "Do not run `npx -y @clue-ai/cli setup-watch --local` automatically",
@@ -88,6 +96,7 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-setup-report": [
     "Never claim `setup completed` from `setup-check --require-sdk-lifecycle` alone",
     "Completion requires all applicable evidence",
+    "setup-agent quality gates must be reported honestly",
     "For every completion claim, include the evidence source",
   ],
 };
@@ -504,6 +513,9 @@ const sourceIsUnderAnyRoot = (source, roots) =>
     );
   });
 
+const hasUseClientDirective = (text) =>
+  /^\s*(?:"use client"|'use client')\s*;?/.test(text);
+
 const dependencySourceHasPackage = (source, packageName) => {
   if (source.file_path.endsWith("package.json")) {
     return packageJsonDependencyNames(source.text).includes(packageName);
@@ -920,6 +932,25 @@ const findNextBrowserTokenProviderMissingPublicEndpointFiles = ({
     .map((source) => source.file_path);
 };
 
+const findNextLifecycleMissingUseClientFiles = ({
+  dependencySources,
+  frontendSources,
+}) => {
+  const roots = nextPackageRoots(dependencySources);
+  if (roots.length === 0) return [];
+  return frontendSources
+    .filter((source) => sourceIsUnderAnyRoot(source, roots))
+    .filter(
+      (source) =>
+        sourceImportsFrontendSdk(source) ||
+        /\bClueInit\s*\(/.test(
+          stripSourceNoise(source.text, { stripStrings: true }),
+        ),
+    )
+    .filter((source) => !hasUseClientDirective(source.text))
+    .map((source) => source.file_path);
+};
+
 const browserTokenPathLiterals = (text) =>
   [
     ...stripSourceNoise(text).matchAll(
@@ -990,6 +1021,35 @@ const sourceLooksLikeBrowserTokenProxy = (source) => {
   );
 };
 
+const findBackendSdkInitMissingServiceKeyFiles = ({
+  backendSources,
+  framework,
+}) => {
+  if (framework !== "fastapi") return [];
+  return backendSources
+    .filter((source) =>
+      /\bclue_init_fastapi\s*\(/.test(
+        stripSourceNoise(source.text, { stripStrings: true }),
+      ),
+    )
+    .filter(
+      (source) =>
+        !/\bclue_init_fastapi\s*\([\s\S]{0,1600}\bservice_key\s*=/.test(
+          stripSourceNoise(source.text, { stripStrings: true }),
+        ),
+    )
+    .map((source) => source.file_path);
+};
+
+const findBackendClueEnvRequiredIndexFiles = (backendSources) =>
+  backendSources
+    .filter((source) =>
+      /os\.environ\s*\[\s*["']CLUE_[A-Z0-9_]+["']\s*\]/.test(
+        stripSourceNoise(source.text),
+      ),
+    )
+    .map((source) => source.file_path);
+
 const findBrowserTokenProxyUsingBackendServiceKeyFiles = (backendSources) =>
   backendSources
     .filter(sourceLooksLikeBrowserTokenProxy)
@@ -1004,18 +1064,18 @@ 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,
+  /\b(?:body|requestBody|request_body|data|input)\.origin\b/i,
+  /\b(?:body|requestBody|request_body|data|input)\s*\[\s*["']origin["']\s*\]/i,
+  /\b(?:body|requestBody|request_body|data|input)\.get\s*\(\s*["']origin["']/i,
+  /["']origin["']\s*:\s*(?:body|requestBody|request_body|data|input)\b/i,
+  /\borigin\s*=\s*(?: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,
+  /\b(?:projectKey|project_key)\s*:\s*(?:body|requestBody|request_body|data|input)\b/i,
+  /["'](?:projectKey|project_key)["']\s*:\s*(?:body|requestBody|request_body|data|input)\b/i,
+  /\benvironment\s*:\s*(?:body|requestBody|request_body|data|input)\b/i,
+  /["']environment["']\s*:\s*(?:body|requestBody|request_body|data|input)\b/i,
 ];
 
 const findBrowserTokenProxyTrustingBodyOriginFiles = (backendSources) =>
@@ -1040,6 +1100,37 @@ const findBrowserTokenProxyTrustingBodyProjectEnvironmentFiles = (
     })
     .map((source) => source.file_path);
 
+const findBrowserTokenProxyMissingApiKeyHeaderFiles = (backendSources) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter(
+      (source) =>
+        !/["']x-clue-api-key["']\s*:/.test(stripSourceNoise(source.text)),
+    )
+    .map((source) => source.file_path);
+
+const findBrowserTokenProxyUndeclaredHttpClientFiles = ({
+  backendSources,
+  dependencySources,
+}) => {
+  const declaredHttpClients = ["httpx", "requests"].filter((packageName) =>
+    dependencyHasAnyPackage(dependencySources, [packageName]),
+  );
+  return backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text, { stripStrings: true });
+      const importsHttpx = /(?:^|\n)\s*import\s+httpx\b/.test(text);
+      const importsRequests =
+        /(?:^|\n)\s*(?:import\s+requests\b|from\s+requests\b)/.test(text);
+      return (
+        (importsHttpx && !declaredHttpClients.includes("httpx")) ||
+        (importsRequests && !declaredHttpClients.includes("requests"))
+      );
+    })
+    .map((source) => source.file_path);
+};
+
 const backendSdkSpec = (framework) =>
   BACKEND_SDK_BY_FRAMEWORK[String(framework ?? "").toLowerCase()] ?? {
     packages: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
@@ -1143,6 +1234,13 @@ const checkSdkLifecycle = ({
     !backendPresent || backendSpec.installabilityStatus !== "unverified";
   const backendInitPresent =
     !backendPresent || backendSpec.initPattern.test(backendCombined);
+  const backendSdkInitMissingServiceKeyFiles =
+    findBackendSdkInitMissingServiceKeyFiles({
+      backendSources,
+      framework,
+    });
+  const backendClueEnvRequiredIndexFiles =
+    findBackendClueEnvRequiredIndexFiles(backendSources);
   const frontendLifecyclePresent = frontendFoundApiNames.length > 0;
   const frontendSdkDependencyPresent =
     !frontendLifecyclePresent ||
@@ -1182,12 +1280,24 @@ const checkSdkLifecycle = ({
       dependencySources,
       frontendSources,
     });
+  const nextLifecycleMissingUseClientFiles =
+    findNextLifecycleMissingUseClientFiles({
+      dependencySources,
+      frontendSources,
+    });
   const browserTokenProxyUsingBackendServiceKeyFiles =
     findBrowserTokenProxyUsingBackendServiceKeyFiles(backendSources);
   const browserTokenProxyTrustingBodyOriginFiles =
     findBrowserTokenProxyTrustingBodyOriginFiles(backendSources);
   const browserTokenProxyTrustingBodyProjectEnvironmentFiles =
     findBrowserTokenProxyTrustingBodyProjectEnvironmentFiles(backendSources);
+  const browserTokenProxyMissingApiKeyHeaderFiles =
+    findBrowserTokenProxyMissingApiKeyHeaderFiles(backendSources);
+  const browserTokenProxyUndeclaredHttpClientFiles =
+    findBrowserTokenProxyUndeclaredHttpClientFiles({
+      backendSources,
+      dependencySources,
+    });
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -1228,6 +1338,8 @@ const checkSdkLifecycle = ({
       sdk_import_present: backendSdkImportPresent,
       sdk_dependency_or_import_present: backendSdkPresent,
       sdk_init_present: backendInitPresent,
+      sdk_init_missing_service_key_files: backendSdkInitMissingServiceKeyFiles,
+      clue_env_required_index_files: backendClueEnvRequiredIndexFiles,
       required_apis: [
         ...(backendIdentityRequired ? ["ClueIdentify"] : []),
         ...(backendAccountRequired ? ["ClueSetAccount"] : []),
@@ -1259,12 +1371,18 @@ const checkSdkLifecycle = ({
         nextBrowserTokenProviderMissingPublicServiceKeyFiles,
       next_browser_token_provider_missing_public_endpoint_files:
         nextBrowserTokenProviderMissingPublicEndpointFiles,
+      next_lifecycle_missing_use_client_files:
+        nextLifecycleMissingUseClientFiles,
       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,
+      browser_token_proxy_missing_api_key_header_files:
+        browserTokenProxyMissingApiKeyHeaderFiles,
+      browser_token_proxy_undeclared_http_client_files:
+        browserTokenProxyUndeclaredHttpClientFiles,
     },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
@@ -1278,6 +1396,8 @@ const checkSdkLifecycle = ({
       backendSdkInstallabilityVerified &&
       pinnedBackendSdkDependencyFiles.length === 0 &&
       backendInitPresent &&
+      backendSdkInitMissingServiceKeyFiles.length === 0 &&
+      backendClueEnvRequiredIndexFiles.length === 0 &&
       backendMissingApis.length === 0 &&
       frontendSdkPresent &&
       frontendLifecycleFilesWithoutVerifiedSdk.length === 0 &&
@@ -1291,9 +1411,12 @@ const checkSdkLifecycle = ({
       frontendInitBeforeClueInitFiles.length === 0 &&
       nextBrowserTokenProviderMissingPublicServiceKeyFiles.length === 0 &&
       nextBrowserTokenProviderMissingPublicEndpointFiles.length === 0 &&
+      nextLifecycleMissingUseClientFiles.length === 0 &&
       browserTokenProxyUsingBackendServiceKeyFiles.length === 0 &&
       browserTokenProxyTrustingBodyOriginFiles.length === 0 &&
       browserTokenProxyTrustingBodyProjectEnvironmentFiles.length === 0 &&
+      browserTokenProxyMissingApiKeyHeaderFiles.length === 0 &&
+      browserTokenProxyUndeclaredHttpClientFiles.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
       blockingLifecycleFiles.length === 0,

package/src/setup-detect.mjs

@@ -34,6 +34,23 @@ const commonDirectory = (paths) => {
   return common.length ? common.join("/") : ".";
 };
 
+const isPathInside = (childPath, parentPath) =>
+  childPath === parentPath || childPath.startsWith(`${parentPath}/`);
+
+const findFastApiAppRoot = async ({ repoRoot, files, routeFiles }) => {
+  const appRootCandidates = [];
+  for (const absolutePath of files) {
+    const relativePath = relative(repoRoot, absolutePath);
+    const source = await readFile(absolutePath, "utf8");
+    if (!/\bFastAPI\s*\(/.test(source)) continue;
+    const candidate = dirname(relativePath);
+    if (routeFiles.every((routeFile) => isPathInside(routeFile, candidate))) {
+      appRootCandidates.push(candidate);
+    }
+  }
+  return appRootCandidates.sort((left, right) => right.length - left.length)[0] ?? null;
+};
+
 const ignoredPackageDirs = new Set([
   ".git",
   ".next",
@@ -162,7 +179,12 @@ export const runSetupDetect = async ({ repoRoot, excludedSourcePaths = [] }) =>
       fastApiRoutes.map((route) => route.ai_context.relative_path).filter(Boolean),
     ),
   ].sort();
-  const backendRootPath = commonDirectory(routeFiles);
+  const backendRootPath =
+    (await findFastApiAppRoot({
+      repoRoot: resolvedRepoRoot,
+      files,
+      routeFiles,
+    })) ?? commonDirectory(routeFiles);
   const backendServiceKey = deriveServiceKeyFromPath(backendRootPath);
   return {
     detected: true,

package/src/setup-documents.mjs

@@ -8,6 +8,7 @@ export const CORE_SETUP_DOCUMENT_IDS = [
   "clue-boundary",
   "environment-and-secrets",
   "find-integration-points",
+  "official-sdk-contract",
   "browser-token-endpoint",
   "clue-init",
   "clue-identify",
@@ -96,4 +97,3 @@ export const buildSetupDocumentationContract = ({
       "Read the relevant Clue setup documents before editing and list consulted_document_ids in the final report.",
   };
 };
-

package/src/setup-help.mjs

@@ -8,6 +8,7 @@ import {
   DETERMINISTIC_CONTROL_MODEL,
   FRONTEND_ADAPTER_CONTRACT,
   SETUP_DOCTRINE,
+  SETUP_AGENT_QUALITY_GATES,
 } from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
@@ -116,6 +117,7 @@ export const buildAiSetupHelp = () => ({
         "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,
     },
+    setup_agent_quality_gates: SETUP_AGENT_QUALITY_GATES,
     completion_boundary: {
       ai_may_claim: [
         "Clue setup code changes were applied",

package/src/setup-tool.mjs

@@ -10,6 +10,7 @@ import {
 import {
   AI_SETUP_CONTRACT_VERSION,
   API_CONNECTIVITY_CONTRACT,
+  SETUP_AGENT_QUALITY_GATES,
   setupDoctrineSkillLines,
 } from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
@@ -54,6 +55,9 @@ const skillBody = (name, { documentsUrl } = {}) => {
   )
     .map(([framework, docId]) => `${framework} -> ${docId}`)
     .join(", ");
+  const setupAgentQualityGateIds = SETUP_AGENT_QUALITY_GATES.map(
+    (gate) => gate.id,
+  ).join(", ");
   const descriptions = {
     "clue-setup-orchestrator":
       "Use first when running Clue setup so lifecycle placement remains the only implementation workstream and read-only checks stay separate.",
@@ -260,7 +264,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Open the docs page when the AI tool has browser or HTTP access. If it cannot be opened, continue only from the generated skill text and manifest doc ids, then report `documentation_access_blocked`.",
       "Read all ids in `documentation.required_doc_ids` that apply to the detected repository.",
       "For framework-specific implementation, select ids from `documentation.selected_framework_doc_ids` first. If empty, use `documentation.framework_doc_ids_by_framework` for the detected framework.",
-      "Minimum lifecycle docs before implementation: ai-setup-order, environment-and-secrets, browser-token-endpoint, clue-init, clue-identify, clue-set-account, clue-logout, setup-verification, forbidden-patterns.",
+      "Minimum lifecycle docs before implementation: ai-setup-order, environment-and-secrets, official-sdk-contract, browser-token-endpoint, clue-init, clue-identify, clue-set-account, clue-logout, setup-verification, forbidden-patterns.",
       "For Next.js, read framework-nextjs. For React, Vite, Vue, or Angular browser apps, read framework-react-spa. For FastAPI, read framework-fastapi. For Django, read framework-django.",
       "Return `consulted_document_ids` to the orchestrator and final report.",
       "If a document contradicts `.clue/setup-manifest.json` or generated skills, stop and report a blocker instead of choosing behavior silently.",
@@ -316,6 +320,8 @@ 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.",
+      "A clean customer repository is expected to have no existing Clue SDK imports, dependencies, browserTokenProvider wiring, or Clue adapter. Do not treat that absence as a blocker; add the minimal official Clue setup wiring.",
+      "When no existing Clue adapter or browser-token proxy module exists, creating a minimal Clue-owned setup file under the existing source root is allowed. Do not use new files for unrelated host app abstractions.",
       "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.",
@@ -325,6 +331,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "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.",
+      "Next.js browser SDK adapter files must start with `\"use client\"` so Clue browser SDK code is not imported through a server component module.",
       "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.",
@@ -338,8 +345,12 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "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`.",
+      "When the backend browser token proxy calls Clue, send the server `CLUE_API_KEY` as the `x-clue-api-key` header. Do not use `Authorization: Bearer`, query parameters, or JSON body fields for the Clue API key.",
+      "Do not introduce non-Clue HTTP client dependencies for browser-token proxy code unless they already exist in dependency files. For Python, prefer an existing HTTP client or standard library instead of importing undeclared `httpx` or `requests`.",
       "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 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.",
+      "Do not use `os.environ[\"CLUE_*\"]` required indexing for Clue env values; Clue setup must not crash the host service when env is missing.",
+      "FastAPI `clue_init_fastapi` must pass `service_key` from the setup manifest/`CLUE_SERVICE_KEY`; do not rely on `service_name` alone because setup-watch targets are keyed by service key.",
       "`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.",
       "Python backend SDK dependencies must not be pinned.",
       "`@clue-ai/browser-sdk` must use `latest`.",
@@ -372,11 +383,15 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "Reject wrong SDK package names. Frontend must use `@clue-ai/browser-sdk`; FastAPI must use `clue-fastapi-sdk`; Django must use `clue-django-sdk`.",
       "Reject Django SDK setup when `clue-django-sdk` installability has not been verified.",
       "Reject backend setup when backend routes exist but no backend Clue SDK dependency/import/init was added.",
+      "Reject backend Clue setup code that uses `os.environ[\"CLUE_*\"]` required indexing instead of non-crashing env reads.",
       "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 browser token proxy code that sends `CLUE_API_KEY` as `Authorization: Bearer`, query parameters, or JSON body fields instead of the `x-clue-api-key` header.",
+      "Reject browser token proxy code that imports undeclared HTTP client dependencies such as `httpx` or `requests`.",
       "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`.",
+      "Reject Next.js browser SDK adapter files that omit `\"use client\"`.",
       "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.",
@@ -483,6 +498,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "- The full setup must start with `clue-setup-orchestrator`.",
     "- The implementation agent owns only lifecycle placement; monitoring agents review one surface at a time and report P0/P1 issues.",
     "- Do not continue past a P0/P1 monitoring finding until it is fixed or explicitly reported as blocked.",
+    `- setup-agent quality gates must be reported honestly when available: ${setupAgentQualityGateIds}. A skipped setup-doctor gate is not API connectivity verification.`,
     "- If subagents are unavailable, run the same structure as separate named review passes and say so in the final report.",
     "- Do not expose project keys, API keys, secrets, tokens, or environment variable values.",
     "- Do not ask the user to paste secret values.",