@clue-ai/cli 0.0.23 → 0.0.24

package/bin/clue-cli.mjs

@@ -928,9 +928,24 @@ const renderSetupResult = ({ preparation }) => {
 
 const renderSetupAgentResult = (report) => {
   if (report?.status === "user_verification_pending") {
+    const setupDoctorPassed = report.setup_doctor?.status === "passed";
+    const setupDoctorMissingInputs = Array.isArray(
+      report.setup_doctor?.missing_inputs,
+    )
+      ? report.setup_doctor.missing_inputs
+      : [];
+    const setupDoctorLine =
+      setupDoctorPassed
+        ? "setup-doctor のAPI疎通確認は通過しました。"
+        : setupDoctorMissingInputs.length > 0
+          ? `setup-doctor のAPI疎通確認は未実行です。不足: ${setupDoctorMissingInputs.join(", ")}`
+          : "setup-doctor のAPI疎通確認は未実行です。local services 起動後に確認してください。";
     return [
-      "Clue setup-agent の実行が完了しました。",
+      setupDoctorPassed
+        ? "Clue setup-agent の実行が完了しました。"
+        : "Clue setup-agent の静的実装が完了しました。",
       "",
+      setupDoctorLine,
       "コード差分を確認してください。",
       `次の動作確認: ${clueCliCommand("setup-watch --local")}`,
     ].join("\n");

package/package.json

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

package/src/ai-provider.mjs

@@ -79,6 +79,58 @@ const parseOpenAiStrictToolJson = async ({ response, toolName, emptyMessage }) =
   throw new Error(emptyMessage);
 };
 
+const providerErrorDetailFromBody = (body) => {
+  if (!body) return "";
+  try {
+    const parsed = JSON.parse(body);
+    const message =
+      parsed?.error?.message ??
+      parsed?.message ??
+      parsed?.error ??
+      parsed?.detail ??
+      null;
+    if (typeof message === "string" && message.trim()) {
+      return message.trim();
+    }
+  } catch {
+    // The provider may return plain text, HTML, or an empty body.
+  }
+  return body.trim();
+};
+
+const redactedProviderErrorDetail = ({ detail, apiKey }) => {
+  const redacted = String(detail)
+    .replaceAll(apiKey, "[redacted]")
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[redacted]")
+    .replace(/\bsk-ant-[A-Za-z0-9_-]{8,}\b/g, "[redacted]");
+  return redacted.length > 600 ? `${redacted.slice(0, 600)}...` : redacted;
+};
+
+const providerHttpError = async ({ response, failureMessage, apiKey }) => {
+  let detail = "";
+  try {
+    const body =
+      typeof response.text === "function"
+        ? await response.text()
+        : typeof response.json === "function"
+          ? JSON.stringify(await response.json())
+          : "";
+    detail = redactedProviderErrorDetail({
+      detail: providerErrorDetailFromBody(body),
+      apiKey,
+    });
+  } catch {
+    detail = "";
+  }
+  const statusText =
+    typeof response.statusText === "string" && response.statusText.trim()
+      ? ` ${response.statusText.trim()}`
+      : "";
+  return new Error(
+    `${failureMessage}: ${response.status}${statusText}${detail ? ` - ${detail}` : ""}`,
+  );
+};
+
 const parseAnthropicJson = async ({ response, toolName, emptyMessage }) => {
   const body = await response.json();
   const toolUse = Array.isArray(body?.content)
@@ -162,12 +214,15 @@ export const callStrictToolAiProvider = async ({
             ],
             tool_choice: { type: "function", name: toolName },
             parallel_tool_calls: false,
-            temperature: 0,
           }),
         });
 
   if (!response.ok) {
-    throw new Error(`${failureMessage}: ${response.status}`);
+    throw await providerHttpError({
+      response,
+      failureMessage,
+      apiKey: config.apiKey,
+    });
   }
   return config.provider === "anthropic"
     ? parseAnthropicJson({ response, toolName, emptyMessage })
@@ -219,7 +274,6 @@ export const callJsonAiProvider = async ({
           },
           body: JSON.stringify({
             model: config.model,
-            temperature: 0,
             messages: [
               { role: "system", content: system },
               { role: "user", content: user },
@@ -229,7 +283,11 @@ export const callJsonAiProvider = async ({
         });
 
   if (!response.ok) {
-    throw new Error(`${failureMessage}: ${response.status}`);
+    throw await providerHttpError({
+      response,
+      failureMessage,
+      apiKey: config.apiKey,
+    });
   }
   return config.provider === "anthropic"
     ? parseAnthropicJson({ response, toolName, emptyMessage })

package/src/lifecycle-init.mjs

@@ -40,7 +40,11 @@ const MAX_TOTAL_CHARS = 360_000;
 const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
 const WRONG_FRONTEND_SDK_PACKAGES = ["clue-js-sdk", "@clue/browser-sdk"];
 const CLUE_SETUP_ADDITION_PATTERN =
-  /\b(?:ClueInit|ClueIdentify|ClueSetAccount|ClueLogout|clue_init_fastapi|clue_init_django|clue-fastapi-sdk|clue-django-sdk|CLUE_[A-Z0-9_]+|browserTokenProvider|clue[-_])|@clue-ai\/browser-sdk/i;
+  /\b(?:Clue[A-Za-z0-9_]*|clue_init_fastapi|clue_init_django|clue-fastapi-sdk|clue-django-sdk|CLUE_[A-Z0-9_]+|browserTokenProvider|clue[-_])|@clue-ai\/browser-sdk/i;
+const CLUE_SETUP_SUPPORT_IMPORT_PATTERN =
+  /^\s*(?:import\s+os|from\s+os\s+import\s+(?:getenv|environ)|import\s+json|from\s+urllib(?:\.error)?\s+import\s+[A-Za-z_,\s]+|from\s+fastapi\s+import\s+.*\b(?:HTTPException|Request)\b.*|from\s+pydantic\s+import\s+BaseModel)\s*$/m;
+const CLUE_SETUP_SUPPORT_ADDITION_PATTERN =
+  /\b(?:os|getenv|environ|json|urllib_request|HTTPError|URLError|HTTPException|Request|BaseModel)\b/;
 const LIFECYCLE_PLAN_TOOL_SCHEMA = {
   type: "object",
   properties: {
@@ -70,6 +74,20 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
         additionalProperties: false,
       },
     },
+    insertions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file_path: { type: "string" },
+          anchor: { type: "string" },
+          position: { type: "string", enum: ["before", "after"] },
+          content: { type: "string" },
+        },
+        required: ["file_path", "anchor", "position", "content"],
+        additionalProperties: false,
+      },
+    },
     lifecycle_insertions: {
       type: "array",
       items: {
@@ -98,7 +116,7 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
         type: "object",
         properties: {
           reason: { type: "string" },
-          evidence: { type: ["string", "null"] },
+          evidence: { type: "string" },
         },
         required: ["reason", "evidence"],
         additionalProperties: false,
@@ -113,6 +131,7 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
     "status",
     "edits",
     "file_creations",
+    "insertions",
     "lifecycle_insertions",
     "blockers",
     "warnings",
@@ -127,6 +146,13 @@ const nonEmpty = (value, field) => {
   return value.trim();
 };
 
+const nonEmptyRaw = (value, field) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} is required`);
+  }
+  return value;
+};
+
 const safeRelativePath = (repoRoot, filePath) => {
   const root = resolve(repoRoot);
   const absolutePath = resolve(root, filePath);
@@ -197,6 +223,18 @@ const assertLifecycleCallsAreNonBlocking = (replacement) => {
   }
 };
 
+const assertNoRepeatedFrontendClueInit = (content) => {
+  if (
+    /useEffect\s*\([\s\S]{0,1200}ClueInit/.test(
+      stripSourceNoise(content, { stripStrings: true }),
+    )
+  ) {
+    throw new Error(
+      "ClueInit must not run inside React component lifecycle hooks; use a module-level client singleton or SDK adapter and import it from the app bootstrap",
+    );
+  }
+};
+
 const assertClueSetupOnlyEdit = (edit) => {
   if (!edit.replace.includes(edit.find)) {
     throw new Error(
@@ -204,7 +242,10 @@ const assertClueSetupOnlyEdit = (edit) => {
     );
   }
   const addedText = edit.replace.split(edit.find).join("");
-  if (!CLUE_SETUP_ADDITION_PATTERN.test(addedText)) {
+  if (
+    !CLUE_SETUP_ADDITION_PATTERN.test(addedText) &&
+    !CLUE_SETUP_SUPPORT_ADDITION_PATTERN.test(addedText)
+  ) {
     throw new Error(
       `Clue lifecycle edits must add only Clue setup related code in ${edit.file_path}`,
     );
@@ -219,6 +260,21 @@ const assertClueSetupOnlyFileCreation = (fileCreation) => {
   }
   assertNoForbiddenInstrumentation(fileCreation.content);
   assertLifecycleCallsAreNonBlocking(fileCreation.content);
+  assertNoRepeatedFrontendClueInit(fileCreation.content);
+};
+
+const assertClueSetupOnlyInsertion = (insertion) => {
+  if (
+    !CLUE_SETUP_ADDITION_PATTERN.test(insertion.content) &&
+    !CLUE_SETUP_SUPPORT_IMPORT_PATTERN.test(insertion.content)
+  ) {
+    throw new Error(
+      `Clue lifecycle insertions must contain only Clue setup related code in ${insertion.file_path}`,
+    );
+  }
+  assertNoForbiddenInstrumentation(insertion.content);
+  assertLifecycleCallsAreNonBlocking(insertion.content);
+  assertNoRepeatedFrontendClueInit(insertion.content);
 };
 
 const normalizeLifecycleInsertion = (input) => ({
@@ -261,13 +317,24 @@ const normalizePlan = (input) => {
   }
   const edits = input.edits.map((edit) => ({
     file_path: nonEmpty(edit.file_path, "edit.file_path"),
-    find: nonEmpty(edit.find, "edit.find"),
-    replace: nonEmpty(edit.replace, "edit.replace"),
+    find: nonEmptyRaw(edit.find, "edit.find"),
+    replace: nonEmptyRaw(edit.replace, "edit.replace"),
   }));
   const fileCreations = Array.isArray(input.file_creations)
     ? input.file_creations.map((fileCreation) => ({
         file_path: nonEmpty(fileCreation.file_path, "file_creation.file_path"),
-        content: nonEmpty(fileCreation.content, "file_creation.content"),
+        content: nonEmptyRaw(fileCreation.content, "file_creation.content"),
+      }))
+    : [];
+  const insertions = Array.isArray(input.insertions)
+    ? input.insertions.map((insertion) => ({
+        file_path: nonEmpty(insertion.file_path, "insertion.file_path"),
+        anchor: nonEmptyRaw(insertion.anchor, "insertion.anchor"),
+        position:
+          insertion.position === "before" || insertion.position === "after"
+            ? insertion.position
+            : "after",
+        content: nonEmptyRaw(insertion.content, "insertion.content"),
       }))
     : [];
   const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
@@ -280,6 +347,7 @@ const normalizePlan = (input) => {
     if (
       edits.length > 0 ||
       fileCreations.length > 0 ||
+      insertions.length > 0 ||
       lifecycleInsertions.length > 0
     ) {
       throw new Error("blocked lifecycle plan must not include edits");
@@ -295,6 +363,7 @@ const normalizePlan = (input) => {
     status,
     edits,
     fileCreations,
+    insertions,
     lifecycleInsertions,
     blockers,
     warnings: Array.isArray(input.warnings)
@@ -570,6 +639,7 @@ const buildLifecycleEvidenceSourceMap = async ({
       ...new Set([
         ...plan.edits.map((edit) => edit.file_path),
         ...plan.fileCreations.map((fileCreation) => fileCreation.file_path),
+        ...plan.insertions.map((insertion) => insertion.file_path),
         ...plan.lifecycleInsertions.map((insertion) => insertion.file_path),
       ]),
   ]) {
@@ -638,6 +708,33 @@ export const applyLifecyclePlan = async ({
       text: fileCreation.content,
     });
   }
+  for (const insertion of plan.insertions) {
+    const { absolutePath, relativePath } = safeRelativePath(
+      repoRoot,
+      insertion.file_path,
+    );
+    assertAllowedWritePath({ allowedWritePaths, filePath: relativePath });
+    assertClueSetupOnlyInsertion(insertion);
+    const current =
+      sourceByPath.get(relativePath)?.text ??
+      (await readFile(absolutePath, "utf8"));
+    const occurrences = current.split(insertion.anchor).length - 1;
+    if (occurrences !== 1) {
+      throw new Error(
+        `insertion.anchor must match exactly once in ${insertion.file_path}; matched ${occurrences}`,
+      );
+    }
+    const replacement =
+      insertion.position === "before"
+        ? `${insertion.content}${insertion.anchor}`
+        : `${insertion.anchor}${insertion.content}`;
+    const next = current.replace(insertion.anchor, replacement);
+    sourceByPath.set(relativePath, {
+      file_path: relativePath,
+      text: next,
+    });
+    pendingWrites.set(relativePath, { absolutePath, text: next });
+  }
   for (const edit of plan.edits) {
     const { absolutePath, relativePath } = safeRelativePath(
       repoRoot,
@@ -656,6 +753,7 @@ export const applyLifecyclePlan = async ({
     }
     assertClueSetupOnlyEdit(edit);
     assertLifecycleCallsAreNonBlocking(edit.replace);
+    assertNoRepeatedFrontendClueInit(edit.replace);
     const next = current.replace(edit.find, edit.replace);
     sourceByPath.set(relativePath, {
       file_path: relativePath,
@@ -689,6 +787,10 @@ export const applyLifecyclePlan = async ({
     fileCreations: plan.fileCreations.map((fileCreation) => ({
       file_path: fileCreation.file_path,
     })),
+    insertions: plan.insertions.map((insertion) => ({
+      file_path: insertion.file_path,
+      position: insertion.position,
+    })),
     lifecycleInsertions: plan.lifecycleInsertions,
     warnings: plan.warnings,
   };
@@ -788,8 +890,11 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Understand the setup doctrine before choosing edits. This is an external Clue integration, not a host app refactor or redesign task.",
       "Use AI judgment only for lifecycle boundary placement. Let the CLI, generated skills, documentation contract, lifecycle plan schema, and setup-check static guards control deterministic mechanics.",
       "Treat official_sdk_contract as verified Clue setup input from the CLI. Do not block merely because the customer repo does not already contain Clue SDK imports, dependencies, browserTokenProvider wiring, or a Clue adapter.",
-      "If SDK signatures, environment names, browser token behavior, package installability, or verification ownership remain unclear after applying official_sdk_contract, return status blocked instead of guessing.",
+      "For supported FastAPI and Next.js setup paths, do not block merely because the customer repo starts without Clue code or because one non-critical lifecycle point is unclear. Complete safe minimal Clue wiring, skip unclear lifecycle points with warnings, and let setup-check drive retries.",
+      "Return status blocked only when the official SDK contract does not cover the detected framework, required AI/provider setup is missing, no safe bootstrap or route insertion can be found, or applying the setup would require guessing outside Clue setup scope.",
       "Use only exact replacements. Each find string must be copied exactly from source.",
+      "Prefer insertions for adding imports, SDK initialization, lifecycle calls, route registration, and frontend provider mounts. For insertions, choose an anchor that appears exactly once and let the CLI preserve the existing source.",
+      "Use edits only when a true exact replacement is necessary. Every edit.replace must contain edit.find as an exact substring; otherwise the CLI rejects it as a host-app rewrite.",
       "Use file_creations only for minimal Clue-owned setup wiring files when no existing Clue adapter or browser-token proxy module exists.",
       "Do not use file_creations for host application refactors, business logic, unrelated helpers, formatting, or non-Clue abstractions.",
       "Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
@@ -804,6 +909,7 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
       "For frontend code, add or use the real @clue-ai/browser-sdk dependency through the latest channel (@clue-ai/browser-sdk@latest). Do not invent clue-js-sdk, @clue/browser-sdk, local SDK modules, global window.Clue APIs, or dynamic imports that hide a missing SDK.",
       "For FastAPI backends, add the unpinned clue-fastapi-sdk dependency when missing so pip resolves the latest release, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
+      "FastAPI clue_init_fastapi must pass service_key using the setup manifest service key or CLUE_SERVICE_KEY. Do not rely on service_name alone because setup-watch and event attribution use the service key.",
       "For Django backends, use clue-django-sdk only after dependency or registry verification confirms it is installable. If it cannot be verified, report a blocker instead of adding guessed imports or dependencies.",
       "For other backend frameworks, treat SDK existence as unverified unless present in dependency files or verified through package-manager/official documentation. If no backend SDK exists or verification is impossible, report a blocker instead of silently frontend-only setup.",
       "Do not add broad ClueTrack instrumentation.",
@@ -814,11 +920,15 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
       "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.",
+      "Do not use os.environ[\"CLUE_*\"] required indexing for Clue env values. Use non-crashing reads such as os.environ.get/os.getenv and skip initialization if required Clue env is missing.",
       "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, 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.",
       "If no safe frontend/browser SDK adapter boundary exists, create a minimal Clue-owned adapter file under the existing frontend source root and add the smallest exact replacement needed to import or mount it from an existing stable bootstrap point.",
+      "For Next.js, prefer a module-level client singleton such as src/lib/clue.ts that calls ClueInit once after checking required NEXT_PUBLIC_CLUE_* values, then import that module from app/layout.tsx or the existing app bootstrap.",
+      "Next.js browser SDK adapter files must begin with the exact directive \"use client\" so browser SDK code is not imported as a server module.",
+      "Do not create a React component whose useEffect calls ClueInit. React component lifecycle hooks, page components, sidebars, and auth callbacks are repeated UI paths and are rejected by setup-check.",
       "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.",
@@ -834,13 +944,15 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "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.",
+      "When the backend browser token proxy calls Clue, send the server CLUE_API_KEY in the x-clue-api-key header. Do not use Authorization bearer, query parameters, or JSON body fields for the Clue API 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.",
+      "Do not introduce non-Clue HTTP client dependencies for the browser-token proxy unless they already exist in dependency files. For Python, prefer an existing HTTP client or the standard library instead of importing undeclared httpx or requests.",
       "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.",
       "Prefer minimal edits that engineers can review in one PR.",
       "Do not run broad formatters, import sorters, cleanup tools, or style-only edits. Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring.",
       "If a lifecycle point is unclear, skip that edit and include a warning.",
-      "Return status ready only when edits are safe to apply. Return status blocked when required SDKs or lifecycle points cannot be verified.",
-      "If status is blocked, return no edits and no lifecycle_insertions, and list blockers. Do not encode blockers as warnings.",
+      "Return status ready when the safe Clue setup edits can be applied, even if individual unclear lifecycle points are skipped and listed as warnings.",
+      "If status is blocked, return no edits and no lifecycle_insertions, and list blockers. Use an empty string for blocker evidence when there is no specific evidence. Do not encode blockers as warnings.",
     ],
     repository_context: {
       target_tool: request.target_tool,
@@ -871,6 +983,14 @@ const buildLifecyclePrompt = ({ request, files }) =>
           content: "new Clue-only setup file content",
         },
       ],
+      insertions: [
+        {
+          file_path: "app/main.py",
+          anchor: "app = FastAPI()\n",
+          position: "after",
+          content: "clue_init_fastapi(app=app)\n",
+        },
+      ],
       edits: [
         {
           file_path: "app/main.py",

package/src/setup-agent.mjs

@@ -1,4 +1,4 @@
-import { access, readFile } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import {
   applyLifecyclePlan,
@@ -28,6 +28,8 @@ const DEPENDENCY_WRITE_FILE_CANDIDATES = [
   "Pipfile.lock",
   "poetry.lock",
 ];
+const FRONTEND_SDK_PACKAGE = "@clue-ai/browser-sdk";
+const BACKEND_FASTAPI_SDK_PACKAGE = "clue-fastapi-sdk";
 
 const optionalString = (value) =>
   typeof value === "string" && value.trim() ? value.trim() : null;
@@ -100,6 +102,13 @@ const blockedMissingAiProviderConfig = ({ manifestPath, missingInputs }) => ({
     missing_inputs: missingInputs,
     report: null,
   },
+  quality_gates: buildQualityGates({
+    aiConfigPresent: false,
+    setupDoctorResult: {
+      status: "skipped",
+      reason: "AI provider configuration is missing",
+    },
+  }),
   blockers: [
     {
       reason:
@@ -187,6 +196,143 @@ const discoveredDependencyWritePaths = async ({ repoRoot, sourcePaths }) => {
   return discovered;
 };
 
+const writeJson = async ({ path, value }) => {
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+};
+
+const ensureFrontendSdkDependency = async ({ repoRoot, rootPath }) => {
+  const packageJsonPath = resolve(repoRoot, rootPath, "package.json");
+  if (!(await exists(packageJsonPath))) return null;
+  const packageJson = await readJson(packageJsonPath);
+  const dependencies =
+    packageJson.dependencies && typeof packageJson.dependencies === "object"
+      ? packageJson.dependencies
+      : {};
+  if (dependencies[FRONTEND_SDK_PACKAGE] === "latest") return null;
+  packageJson.dependencies = {
+    ...dependencies,
+    [FRONTEND_SDK_PACKAGE]: "latest",
+  };
+  await writeJson({ path: packageJsonPath, value: packageJson });
+  return {
+    file_path: join(rootPath, "package.json"),
+    dependency: FRONTEND_SDK_PACKAGE,
+    version: "latest",
+  };
+};
+
+const ensureRequirementsDependency = async ({ repoRoot, path }) => {
+  const absolutePath = resolve(repoRoot, path);
+  if (!(await exists(absolutePath))) return null;
+  const text = await readFile(absolutePath, "utf8");
+  const rawLines = text.split(/\r?\n/);
+  while (rawLines.at(-1) === "") rawLines.pop();
+  const lines = rawLines.filter(
+    (line) => !new RegExp(`^\\s*${BACKEND_FASTAPI_SDK_PACKAGE}\\b`).test(line),
+  );
+  if (!lines.some((line) => line.trim() === BACKEND_FASTAPI_SDK_PACKAGE)) {
+    lines.push(BACKEND_FASTAPI_SDK_PACKAGE);
+  }
+  const next = `${lines.join("\n")}\n`;
+  if (next === text) return null;
+  await writeFile(absolutePath, next, "utf8");
+  return {
+    file_path: path,
+    dependency: BACKEND_FASTAPI_SDK_PACKAGE,
+    version: "latest",
+  };
+};
+
+const ensureSdkDependencies = async ({ repoRoot, manifest, request }) => {
+  const writes = [];
+  const watchTargets = Array.isArray(
+    manifest.lifecycle_verification?.watch_targets,
+  )
+    ? manifest.lifecycle_verification.watch_targets
+    : [];
+  for (const target of watchTargets) {
+    if (target?.kind !== "frontend" || !optionalString(target.root_path)) {
+      continue;
+    }
+    const write = await ensureFrontendSdkDependency({
+      repoRoot,
+      rootPath: target.root_path,
+    });
+    if (write) writes.push(write);
+  }
+  if (request.framework === "fastapi") {
+    const dependencyPaths = await discoveredDependencyWritePaths({
+      repoRoot,
+      sourcePaths: [request.backend_root_path],
+    });
+    const requirementsPath = dependencyPaths.find((path) =>
+      path.endsWith("requirements.txt"),
+    );
+    if (requirementsPath) {
+      const write = await ensureRequirementsDependency({
+        repoRoot,
+        path: requirementsPath,
+      });
+      if (write) writes.push(write);
+    }
+  }
+  return writes;
+};
+
+const planTouchedPaths = (plan) => [
+  ...new Set(
+    [
+      ...(Array.isArray(plan?.edits)
+        ? plan.edits.map((edit) => edit?.file_path)
+        : []),
+      ...(Array.isArray(plan?.file_creations)
+        ? plan.file_creations.map((fileCreation) => fileCreation?.file_path)
+        : []),
+      ...(Array.isArray(plan?.insertions)
+        ? plan.insertions.map((insertion) => insertion?.file_path)
+        : []),
+      ...(Array.isArray(plan?.lifecycle_insertions)
+        ? plan.lifecycle_insertions.map((insertion) => insertion?.file_path)
+        : []),
+    ]
+      .map(optionalString)
+      .filter(Boolean),
+  ),
+];
+
+const snapshotPlanTouchedFiles = async ({ repoRoot, plan }) => {
+  const snapshot = new Map();
+  for (const filePath of planTouchedPaths(plan)) {
+    const absolutePath = resolve(repoRoot, filePath);
+    try {
+      snapshot.set(filePath, {
+        absolutePath,
+        existed: true,
+        text: await readFile(absolutePath, "utf8"),
+      });
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      snapshot.set(filePath, {
+        absolutePath,
+        existed: false,
+        text: null,
+      });
+    }
+  }
+  return snapshot;
+};
+
+const restorePlanTouchedFiles = async (snapshot) => {
+  for (const entry of snapshot.values()) {
+    if (entry.existed) {
+      await mkdir(dirname(entry.absolutePath), { recursive: true });
+      await writeFile(entry.absolutePath, entry.text, "utf8");
+    } else {
+      await rm(entry.absolutePath, { force: true });
+    }
+  }
+};
+
 const allowedWritePathsFromRequest = async ({ repoRoot, request }) => [
   ...new Set([
     ...request.allowed_source_paths,
@@ -274,6 +420,55 @@ const missingInputsFromDoctor = (report) => [
   ),
 ];
 
+const buildQualityGates = ({
+  aiConfigPresent,
+  dependencyWrites = [],
+  lifecyclePlanApplied = false,
+  setupCheck = null,
+  setupDoctorResult = null,
+}) => [
+  {
+    id: "ai_provider_config_present",
+    passed: Boolean(aiConfigPresent),
+    evidence: REQUIRED_SETUP_AGENT_AI_ENV_NAMES,
+  },
+  {
+    id: "sdk_dependencies_cli_owned",
+    passed: true,
+    evidence: {
+      dependency_writes: dependencyWrites,
+      note:
+        "setup-agent owns Clue SDK dependency declarations before AI planning",
+    },
+  },
+  {
+    id: "lifecycle_plan_cli_applied",
+    passed: Boolean(lifecyclePlanApplied),
+    evidence:
+      "AI returns a structured plan only; setup-agent validates and applies edits",
+  },
+  {
+    id: "static_setup_check_passed",
+    passed: Boolean(setupCheck?.passed),
+    evidence: "setup-check --require-sdk-lifecycle",
+  },
+  {
+    id: "setup_doctor_preflight",
+    passed: setupDoctorResult?.status === "passed",
+    skipped: setupDoctorResult?.status === "skipped",
+    evidence:
+      setupDoctorResult?.status === "passed"
+        ? "setup-doctor --local passed"
+        : setupDoctorResult?.reason ?? "setup-doctor --local did not pass",
+  },
+  {
+    id: "setup_watch_user_owned",
+    passed: true,
+    evidence:
+      "setup-watch remains user-operated lifecycle and event-delivery verification",
+  },
+];
+
 const runOptionalSetupDoctor = async ({ env, flags, repoRoot, setupDoctor }) => {
   if (flags.has("skip-setup-doctor")) {
     return {
@@ -296,7 +491,7 @@ const runOptionalSetupDoctor = async ({ env, flags, repoRoot, setupDoctor }) =>
       );
     if (allFailuresAreMissingInputs) {
       return {
-        status: "blocked_missing_inputs",
+        status: "skipped",
         reason: "setup-doctor required inputs are missing",
         missing_inputs: missingInputs,
         report,
@@ -430,10 +625,16 @@ export const runSetupAgent = async ({
     });
   }
   const attempts = [];
+  const dependencyWrites = await ensureSdkDependencies({
+    repoRoot: resolvedRepoRoot,
+    manifest,
+    request,
+  });
   let failureContext = null;
   let lastSetupCheck = null;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let planSnapshot = null;
     try {
       const plan = await lifecyclePlanner({
         repoRoot: resolvedRepoRoot,
@@ -441,6 +642,10 @@ export const runSetupAgent = async ({
         env: aiEnv,
         failureContext,
       });
+      planSnapshot = await snapshotPlanTouchedFiles({
+        repoRoot: resolvedRepoRoot,
+        plan,
+      });
       const lifecycleResult = await lifecycleApplier({
         repoRoot: resolvedRepoRoot,
         plan,
@@ -456,7 +661,9 @@ export const runSetupAgent = async ({
       lastSetupCheck = setupCheck;
       attempts.push({
         attempt,
+        dependency_writes: dependencyWrites,
         file_creations: lifecycleResult.fileCreations ?? [],
+        insertions: lifecycleResult.insertions ?? [],
         lifecycle_insertions: lifecycleResult.lifecycleInsertions,
         warnings: lifecycleResult.warnings,
         setup_check_passed: setupCheck.passed,
@@ -471,14 +678,20 @@ export const runSetupAgent = async ({
         });
         return {
           status:
-            setupDoctorResult.status === "passed" ||
-            setupDoctorResult.status === "skipped"
+            setupDoctorResult.status !== "failed"
               ? "user_verification_pending"
               : "blocked",
           manifest_path: manifestPath,
           attempts,
           setup_check: setupCheck,
           setup_doctor: setupDoctorResult,
+          quality_gates: buildQualityGates({
+            aiConfigPresent: true,
+            dependencyWrites,
+            lifecyclePlanApplied: true,
+            setupCheck,
+            setupDoctorResult,
+          }),
           user_verification: {
             setup_watch_owner: "user",
             setup_watch_auto_run: false,
@@ -487,12 +700,16 @@ export const runSetupAgent = async ({
           },
         };
       }
+      await restorePlanTouchedFiles(planSnapshot);
       failureContext = attemptFailureContext({
         attempt,
         setupCheck,
         stage: "setup_check",
       });
     } catch (error) {
+      if (planSnapshot) {
+        await restorePlanTouchedFiles(planSnapshot);
+      }
       failureContext = attemptFailureContext({
         attempt,
         error,
@@ -500,6 +717,7 @@ export const runSetupAgent = async ({
       });
       attempts.push({
         attempt,
+        dependency_writes: dependencyWrites,
         setup_check_passed: false,
         error: failureContext.error,
         failed_checks: [],
@@ -518,6 +736,18 @@ export const runSetupAgent = async ({
       missing_inputs: [],
       report: null,
     },
+    quality_gates: buildQualityGates({
+      aiConfigPresent: true,
+      dependencyWrites,
+      lifecyclePlanApplied: attempts.some(
+        (attempt) => Array.isArray(attempt.lifecycle_insertions),
+      ),
+      setupCheck: lastSetupCheck,
+      setupDoctorResult: {
+        status: "skipped",
+        reason: "setup-check did not pass",
+      },
+    }),
     blockers: [
       {
         reason: summarizeAttemptFailure(failureContext),

package/src/setup-ai-contract.mjs

@@ -1,5 +1,5 @@
 export const AI_SETUP_CONTRACT_VERSION =
-  "2026-05-10.latest-sdk-contract.v10";
+  "2026-05-10.latest-sdk-contract.v17";
 
 export const SETUP_DOCTRINE = {
   purpose:
@@ -13,7 +13,7 @@ export const SETUP_DOCTRINE = {
   documentation_reason:
     "SDK signatures, environment variable names, browser token behavior, and verification ownership are contracts. The AI must read the setup documents instead of relying on memory.",
   failure_posture:
-    "When a lifecycle point, SDK package, signature, env name, or verification step is unclear, the correct output is a blocker or user_verification_pending, not a guessed implementation or a completion claim.",
+    "For supported setup paths, prefer completing safe minimal Clue wiring and reporting unclear lifecycle points as warnings. Reserve blockers for truly unsupported frameworks, unavailable SDK contracts, missing AI configuration, or edits that cannot be applied without guessing outside Clue setup scope.",
 };
 
 export const DETERMINISTIC_CONTROL_MODEL = {
@@ -22,7 +22,7 @@ export const DETERMINISTIC_CONTROL_MODEL = {
     "which existing login/session success point owns ClueIdentify",
     "which existing account/workspace/organization resolution point owns ClueSetAccount",
     "which existing logout/session reset point owns ClueLogout",
-    "whether a lifecycle point is unclear and should be reported as blocked",
+    "whether a lifecycle point is unclear and should be skipped with a warning instead of guessed",
   ],
   cli_should_control: [
     "official SDK package names",
@@ -37,6 +37,39 @@ export const DETERMINISTIC_CONTROL_MODEL = {
   ],
 };
 
+export const SETUP_AGENT_QUALITY_GATES = [
+  {
+    id: "ai_provider_config_present",
+    purpose:
+      "Prevent silent setup-agent startup failure when AI provider env is missing.",
+  },
+  {
+    id: "sdk_dependencies_cli_owned",
+    purpose:
+      "Ensure official SDK package names and latest-channel declarations are controlled by CLI logic, not model guesses.",
+  },
+  {
+    id: "lifecycle_plan_cli_applied",
+    purpose:
+      "Ensure the AI only returns a structured plan and cannot directly write files or run shell commands.",
+  },
+  {
+    id: "static_setup_check_passed",
+    purpose:
+      "Reject known bad local-prompt failure modes such as wrong SDKs, stale env names, unsafe browser token wiring, awaited lifecycle calls, and partial lifecycle setup.",
+  },
+  {
+    id: "setup_doctor_preflight",
+    purpose:
+      "Separate API connectivity verification from static source verification and make skipped preflight visible.",
+  },
+  {
+    id: "setup_watch_user_owned",
+    purpose:
+      "Keep real login/logout/account event delivery verification under the user's control.",
+  },
+];
+
 export const API_CONNECTIVITY_CONTRACT = {
   purpose:
     "Clue setup has four distinct HTTP hops. The AI must not collapse customer-owned proxy routes and Clue-owned ingest routes into one vague browser-token endpoint.",
@@ -55,7 +88,7 @@ export const API_CONNECTIVITY_CONTRACT = {
       path: "/api/v1/ingest/browser-tokens",
       caller: "customer_backend_browser_token_proxy",
       purpose:
-        "Clue backend validates CLUE_API_KEY, project, environment, service key, and origin, then returns a browser token.",
+        "Clue backend validates x-clue-api-key, project, environment, service key, and origin, then returns a browser token.",
     },
     browser_ingest: {
       owner: "clue_backend",
@@ -93,12 +126,17 @@ export const FRONTEND_ADAPTER_CONTRACT = {
   ],
   browser_token_proxy_path: "/api/v1/clue/browser-tokens",
   rules: [
+    "For Next.js, prefer a module-level client singleton such as src/lib/clue.ts that calls ClueInit once after required NEXT_PUBLIC_CLUE_* values are present, then import that module from app/layout.tsx or the existing app bootstrap.",
+    "Next.js browser SDK adapter files must start with \"use client\".",
+    "Do not create a React component whose useEffect calls ClueInit. Component lifecycle hooks, page components, sidebars, login/register success callbacks, and other repeated UI paths are rejected setup locations.",
     "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.",
+    "Backend browser-token proxy calls to Clue must send CLUE_API_KEY as the x-clue-api-key header, never as Authorization bearer, query, or JSON body.",
+    "Do not introduce non-Clue HTTP client dependencies for browser-token proxy code unless they already exist in dependency files.",
   ],
 };
 
@@ -136,7 +174,7 @@ export const OFFICIAL_SDK_CONTRACT = {
       ClueLogout: "ClueLogout(reason: str | None = None) -> bool",
     },
     safety_contract:
-      "Public lifecycle APIs catch SDK errors internally and return bool where applicable. Do not wrap each call solely for Clue failure isolation.",
+      "Public lifecycle APIs catch SDK errors internally and return bool where applicable. Do not wrap each call solely for Clue failure isolation. FastAPI initialization must pass service_key so event attribution matches setup-watch service targets. Clue env reads must be non-crashing; do not use os.environ[\"CLUE_*\"] required indexing.",
   },
   minimal_file_creation_contract: {
     allowed_when:

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-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.",
@@ -327,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.",
@@ -340,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`.",
@@ -374,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.",
@@ -485,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.",