@clue-ai/cli 0.0.22 → 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.22",
+  "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

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import {
   callJsonAiProvider,
@@ -15,6 +15,7 @@ import { listAllowedSourceFiles } from "./path-policy.mjs";
 import {
   API_CONNECTIVITY_CONTRACT,
   DETERMINISTIC_CONTROL_MODEL,
+  OFFICIAL_SDK_CONTRACT,
   SETUP_DOCTRINE,
 } from "./setup-ai-contract.mjs";
 
@@ -39,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: {
@@ -57,6 +62,32 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
         additionalProperties: false,
       },
     },
+    file_creations: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file_path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["file_path", "content"],
+        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: {
@@ -85,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,
@@ -99,6 +130,8 @@ const LIFECYCLE_PLAN_TOOL_SCHEMA = {
   required: [
     "status",
     "edits",
+    "file_creations",
+    "insertions",
     "lifecycle_insertions",
     "blockers",
     "warnings",
@@ -113,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);
@@ -183,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(
@@ -190,13 +242,41 @@ 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}`,
     );
   }
 };
 
+const assertClueSetupOnlyFileCreation = (fileCreation) => {
+  if (!CLUE_SETUP_ADDITION_PATTERN.test(fileCreation.content)) {
+    throw new Error(
+      `Clue lifecycle file creations must contain only Clue setup related code in ${fileCreation.file_path}`,
+    );
+  }
+  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) => ({
   api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
   file_path: nonEmpty(input.file_path, "file_path"),
@@ -237,9 +317,26 @@ 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: 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)
     ? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
     : [];
@@ -247,7 +344,12 @@ const normalizePlan = (input) => {
     ? input.blockers.map(normalizeBlocker)
     : [];
   if (status === "blocked") {
-    if (edits.length > 0 || lifecycleInsertions.length > 0) {
+    if (
+      edits.length > 0 ||
+      fileCreations.length > 0 ||
+      insertions.length > 0 ||
+      lifecycleInsertions.length > 0
+    ) {
       throw new Error("blocked lifecycle plan must not include edits");
     }
     if (blockers.length === 0) {
@@ -260,6 +362,8 @@ const normalizePlan = (input) => {
   return {
     status,
     edits,
+    fileCreations,
+    insertions,
     lifecycleInsertions,
     blockers,
     warnings: Array.isArray(input.warnings)
@@ -532,10 +636,12 @@ const buildLifecycleEvidenceSourceMap = async ({
   sourceByPath = new Map(),
 }) => {
   for (const filePath of [
-    ...new Set([
-      ...plan.edits.map((edit) => edit.file_path),
-      ...plan.lifecycleInsertions.map((insertion) => insertion.file_path),
-    ]),
+      ...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),
+      ]),
   ]) {
     await loadSourceIntoMap({ repoRoot, sourceByPath, filePath });
   }
@@ -580,6 +686,55 @@ export const applyLifecyclePlan = async ({
   }
   const sourceByPath = new Map();
   const pendingWrites = new Map();
+  for (const fileCreation of plan.fileCreations) {
+    const { absolutePath, relativePath } = safeRelativePath(
+      repoRoot,
+      fileCreation.file_path,
+    );
+    assertAllowedWritePath({ allowedWritePaths, filePath: relativePath });
+    assertClueSetupOnlyFileCreation(fileCreation);
+    try {
+      await readFile(absolutePath, "utf8");
+      throw new Error(`file_creation target already exists: ${relativePath}`);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    sourceByPath.set(relativePath, {
+      file_path: relativePath,
+      text: fileCreation.content,
+    });
+    pendingWrites.set(relativePath, {
+      absolutePath,
+      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,
@@ -598,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,
@@ -624,9 +780,17 @@ export const applyLifecyclePlan = async ({
     });
   }
   for (const write of pendingWrites.values()) {
+    await mkdir(dirname(write.absolutePath), { recursive: true });
     await writeFile(write.absolutePath, write.text, "utf8");
   }
   return {
+    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,
   };
@@ -719,13 +883,20 @@ const buildLifecyclePrompt = ({ request, files }) =>
     task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
     setup_doctrine: SETUP_DOCTRINE,
     deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
+    official_sdk_contract: OFFICIAL_SDK_CONTRACT,
     api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
     rules: [
       "Return JSON only.",
       "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.",
-      "If SDK signatures, environment names, browser token behavior, package installability, or verification ownership are unclear, return status blocked instead of guessing.",
+      "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.",
+      "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.",
       "Official Clue SDK public lifecycle APIs are no-throw and own SDK failure isolation.",
       "Do not add per-call try/catch, try/except, .catch, or custom safe wrappers solely around official Clue SDK public lifecycle calls.",
@@ -738,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.",
@@ -748,10 +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.",
@@ -759,6 +936,7 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "For non-Next.js browser code, use the exact frontend env names written in .env.clue for that service instead of inventing a framework-specific prefix.",
       "Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
+      "If no backend-owned browser token proxy module exists, create a minimal Clue-owned route/module under the existing backend source root and add the smallest exact replacement needed to register it in the existing backend router.",
       "Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
       "Keep the four setup API hops distinct: customer frontend -> customer backend /api/v1/clue/browser-tokens, customer backend -> Clue /api/v1/ingest/browser-tokens, customer frontend -> Clue /api/v1/ingest/browser, and customer backend -> Clue /api/v1/ingest/backend.",
       "The local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as /api/v1/clue/browser-tokens; do not use a generic path such as /browser-tokens that could be confused with product behavior. It must call Clue server-side at /api/v1/ingest/browser-tokens.",
@@ -766,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,
@@ -797,6 +977,20 @@ const buildLifecyclePrompt = ({ request, files }) =>
     output_shape: {
       status: "ready",
       blockers: [],
+      file_creations: [
+        {
+          file_path: "app/clue_adapter.py",
+          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",