@clue-ai/cli 0.0.7 → 0.0.9

package/src/lifecycle-init.mjs

@@ -5,10 +5,10 @@ import { findLifecycleGuardViolations } from "./lifecycle-guard.mjs";
 import { listAllowedSourceFiles } from "./path-policy.mjs";
 
 const API_NAMES = new Set([
-  "ClueInit",
-  "ClueIdentify",
-  "ClueSetAccount",
-  "ClueLogout",
+	"ClueInit",
+	"ClueIdentify",
+	"ClueSetAccount",
+	"ClueLogout",
 ]);
 
 const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
@@ -17,208 +17,213 @@ const MAX_FILE_CHARS = 12_000;
 const MAX_TOTAL_CHARS = 360_000;
 
 const nonEmpty = (value, field) => {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`${field} is required`);
-  }
-  return value.trim();
+	if (typeof value !== "string" || value.trim() === "") {
+		throw new Error(`${field} is required`);
+	}
+	return value.trim();
 };
 
 const safeRelativePath = (repoRoot, filePath) => {
-  const root = resolve(repoRoot);
-  const absolutePath = resolve(root, filePath);
-  const relativePath = relative(root, absolutePath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-    throw new Error(`edit path escapes repo root: ${filePath}`);
-  }
-  return { absolutePath, relativePath };
+	const root = resolve(repoRoot);
+	const absolutePath = resolve(root, filePath);
+	const relativePath = relative(root, absolutePath);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+		throw new Error(`edit path escapes repo root: ${filePath}`);
+	}
+	return { absolutePath, relativePath };
 };
 
 const assertApiName = (apiName) => {
-  if (!API_NAMES.has(apiName)) {
-    throw new Error(`unsupported lifecycle API: ${apiName}`);
-  }
-  return apiName;
+	if (!API_NAMES.has(apiName)) {
+		throw new Error(`unsupported lifecycle API: ${apiName}`);
+	}
+	return apiName;
 };
 
 const assertNoForbiddenInstrumentation = (replacement) => {
-  if (replacement.includes("ClueTrack")) {
-    throw new Error("init tool must not add broad ClueTrack instrumentation");
-  }
-  if (/data-clue-(id|key)/i.test(replacement)) {
-    throw new Error("init tool must not add data-clue-id or data-clue-key");
-  }
+	if (replacement.includes("ClueTrack")) {
+		throw new Error("init tool must not add broad ClueTrack instrumentation");
+	}
+	if (/data-clue-(id|key)/i.test(replacement)) {
+		throw new Error("init tool must not add data-clue-id or data-clue-key");
+	}
 };
 
 const assertLifecycleCallsAreGuarded = (replacement) => {
-  const violations = findLifecycleGuardViolations(replacement);
-  if (violations.length > 0) {
-    throw new Error(
-      `Clue lifecycle calls must be failure-isolated with try/catch, try/except, or an explicit safe Clue helper: ${JSON.stringify(violations)}`,
-    );
-  }
+	const violations = findLifecycleGuardViolations(replacement);
+	if (violations.length > 0) {
+		throw new Error(
+			`Clue lifecycle calls must be failure-isolated with try/catch, try/except, or an explicit safe Clue helper: ${JSON.stringify(violations)}`,
+		);
+	}
 };
 
 const normalizeLifecycleInsertion = (input) => ({
-  api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
-  file_path: nonEmpty(input.file_path, "file_path"),
-  confidence: Math.max(0, Math.min(1, Number(input.confidence ?? 0))),
-  reason: nonEmpty(input.reason, "reason"),
+	api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
+	file_path: nonEmpty(input.file_path, "file_path"),
+	confidence: Math.max(0, Math.min(1, Number(input.confidence ?? 0))),
+	reason: nonEmpty(input.reason, "reason"),
 });
 
 const normalizePlan = (input) => {
-  if (!input || typeof input !== "object") {
-    throw new Error("AI lifecycle plan must be an object");
-  }
-  if (!Array.isArray(input.edits)) {
-    throw new Error("AI lifecycle plan must include edits");
-  }
-  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"),
-  }));
-  const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
-    ? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
-    : [];
-  return {
-    edits,
-    lifecycleInsertions,
-    warnings: Array.isArray(input.warnings)
-      ? input.warnings
-          .filter((warning) => typeof warning === "string" && warning.trim())
-          .map((warning) => warning.trim())
-      : [],
-  };
+	if (!input || typeof input !== "object") {
+		throw new Error("AI lifecycle plan must be an object");
+	}
+	if (!Array.isArray(input.edits)) {
+		throw new Error("AI lifecycle plan must include edits");
+	}
+	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"),
+	}));
+	const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
+		? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
+		: [];
+	return {
+		edits,
+		lifecycleInsertions,
+		warnings: Array.isArray(input.warnings)
+			? input.warnings
+					.filter((warning) => typeof warning === "string" && warning.trim())
+					.map((warning) => warning.trim())
+			: [],
+	};
 };
 
 export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
-  const plan = normalizePlan(rawPlan);
-  for (const edit of plan.edits) {
-    const { absolutePath } = safeRelativePath(repoRoot, edit.file_path);
-    assertNoForbiddenInstrumentation(edit.replace);
-    const current = await readFile(absolutePath, "utf8");
-    const occurrences = current.split(edit.find).length - 1;
-    if (occurrences !== 1) {
-      throw new Error(
-        `edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
-      );
-    }
-    assertLifecycleCallsAreGuarded(edit.replace);
-    await writeFile(
-      absolutePath,
-      current.replace(edit.find, edit.replace),
-      "utf8",
-    );
-  }
-  return {
-    lifecycleInsertions: plan.lifecycleInsertions,
-    warnings: plan.warnings,
-  };
+	const plan = normalizePlan(rawPlan);
+	for (const edit of plan.edits) {
+		const { absolutePath } = safeRelativePath(repoRoot, edit.file_path);
+		assertNoForbiddenInstrumentation(edit.replace);
+		const current = await readFile(absolutePath, "utf8");
+		const occurrences = current.split(edit.find).length - 1;
+		if (occurrences !== 1) {
+			throw new Error(
+				`edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
+			);
+		}
+		assertLifecycleCallsAreGuarded(edit.replace);
+		await writeFile(
+			absolutePath,
+			current.replace(edit.find, edit.replace),
+			"utf8",
+		);
+	}
+	return {
+		lifecycleInsertions: plan.lifecycleInsertions,
+		warnings: plan.warnings,
+	};
 };
 
 const readContextFiles = async ({ repoRoot, request }) => {
-  const files = await listAllowedSourceFiles({
-    repoRoot,
-    allowedSourcePaths: request.allowed_source_paths,
-    excludedSourcePaths: request.excluded_source_paths,
-    extensions: SOURCE_EXTENSIONS,
-  });
-  const context = [];
-  let totalChars = 0;
-  for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
-    const text = await readFile(absolutePath, "utf8");
-    const snippet = text.slice(0, MAX_FILE_CHARS);
-    totalChars += snippet.length;
-    if (totalChars > MAX_TOTAL_CHARS) {
-      break;
-    }
-    context.push({
-      file_path: relative(resolve(repoRoot), absolutePath),
-      source: snippet,
-      truncated: text.length > snippet.length,
-    });
-  }
-  return context;
+	const files = await listAllowedSourceFiles({
+		repoRoot,
+		allowedSourcePaths: request.allowed_source_paths,
+		excludedSourcePaths: request.excluded_source_paths,
+		extensions: SOURCE_EXTENSIONS,
+	});
+	const context = [];
+	let totalChars = 0;
+	for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
+		const text = await readFile(absolutePath, "utf8");
+		const snippet = text.slice(0, MAX_FILE_CHARS);
+		totalChars += snippet.length;
+		if (totalChars > MAX_TOTAL_CHARS) {
+			break;
+		}
+		context.push({
+			file_path: relative(resolve(repoRoot), absolutePath),
+			source: snippet,
+			truncated: text.length > snippet.length,
+		});
+	}
+	return context;
 };
 
 const buildLifecyclePrompt = ({ request, files }) =>
-  JSON.stringify({
-    task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
-    rules: [
-      "Return JSON only.",
-      "Use only exact replacements. Each find string must be copied exactly from source.",
-      "Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
-      "Every Clue lifecycle call must be failure-isolated. If Clue fails, the host service must continue without throwing, rejecting, or blocking login/API behavior.",
-      "Use a small safe Clue helper, local try/catch/try/except wrapper, or direct .catch handler around Clue 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.",
-      "Find all clear login success paths and add ClueIdentify to every one of them. Do not stop after the first login flow.",
-      "Find all clear account, workspace, organization, or tenant resolution paths and add ClueSetAccount to every one of them.",
-      "Find all clear logout or session reset paths and add ClueLogout to every one of them.",
-      "Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
-      "For FastAPI backends, add the clue-fastapi-sdk dependency when missing, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
-      "For Django backends, add the clue-django-sdk dependency when missing, import the Django SDK lifecycle helpers where needed, and initialize the SDK in the Django integration point.",
-      "For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
-      "Do not add broad ClueTrack instrumentation.",
-      "Do not add data-clue-id, data-clue-key, or similar DOM tags.",
-      "Do not create route semantics files or layer files.",
-      "Do not copy project keys, API keys, service secrets, or environment-specific values into code.",
-      "Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
-      "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 environment variables.",
-      "For browser code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, and CLUE_INGEST_ENDPOINT from environment variables through the target framework's safe client config mechanism. Do not hard-code a Next.js-only prefix.",
-      "Prefer minimal edits that engineers can review in one PR.",
-      "If a lifecycle point is unclear, skip that edit and include a warning.",
-    ],
-    repository_context: {
-      target_tool: request.target_tool,
-      framework: request.framework,
-      project_key_env: "CLUE_PROJECT_KEY",
-      browser_project_key_env: "CLUE_PROJECT_KEY",
-      environment_env: "CLUE_ENVIRONMENT",
-      browser_environment_env: "CLUE_ENVIRONMENT",
-      clue_api_base_url_env: "CLUE_API_BASE_URL",
-      clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
-      browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
-      service_key: request.service_key,
-    },
-    output_shape: {
-      edits: [
-        {
-          file_path: "app/main.py",
-          find: "exact original text",
-          replace: "exact replacement text",
-        },
-      ],
-      lifecycle_insertions: [
-        {
-          api_name: "ClueInit",
-          file_path: "app/main.py",
-          confidence: 0.8,
-          reason: "SDK initialized where FastAPI app is created.",
-        },
-      ],
-      warnings: ["short engineer review note"],
-    },
-    files,
-  });
+	JSON.stringify({
+		task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
+		rules: [
+			"Return JSON only.",
+			"Use only exact replacements. Each find string must be copied exactly from source.",
+			"Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
+			"Every Clue lifecycle call must be failure-isolated. If Clue fails, the host service must continue without throwing, rejecting, or blocking login/API behavior.",
+			"Use a small safe Clue helper, local try/catch/try/except wrapper, or direct .catch handler around Clue 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.",
+			"Find all clear login success paths and add ClueIdentify to every one of them. Do not stop after the first login flow.",
+			"Find all clear account, workspace, organization, or tenant resolution paths and add ClueSetAccount to every one of them.",
+			"Find all clear logout or session reset paths and add ClueLogout to every one of them.",
+			"Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
+			"For FastAPI backends, add the clue-fastapi-sdk dependency when missing, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
+			"For Django backends, add the clue-django-sdk dependency when missing, import the Django SDK lifecycle helpers where needed, and initialize the SDK in the Django integration point.",
+			"For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
+			"Do not add broad ClueTrack instrumentation.",
+			"Do not add data-clue-id, data-clue-key, or similar DOM tags.",
+			"Do not create route semantics files or layer files.",
+			"Do not copy project keys, API keys, service secrets, or environment-specific values into code.",
+			"Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
+			"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 environment variables.",
+			"For browser code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_SERVICE_KEY, and CLUE_INGEST_ENDPOINT from environment variables through the target framework's safe client config mechanism. Do not hard-code a Next.js-only prefix.",
+			"Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
+			"When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
+			"Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
+			"The browser token request must include project key, environment, service key, and the current browser origin; the backend must attach x-clue-api-key server-side when calling Clue.",
+			"Prefer minimal edits that engineers can review in one PR.",
+			"If a lifecycle point is unclear, skip that edit and include a warning.",
+		],
+		repository_context: {
+			target_tool: request.target_tool,
+			framework: request.framework,
+			project_key_env: "CLUE_PROJECT_KEY",
+			browser_project_key_env: "CLUE_PROJECT_KEY",
+			environment_env: "CLUE_ENVIRONMENT",
+			browser_environment_env: "CLUE_ENVIRONMENT",
+			clue_api_base_url_env: "CLUE_API_BASE_URL",
+			clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+			browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+			browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
+			service_key: request.service_key,
+		},
+		output_shape: {
+			edits: [
+				{
+					file_path: "app/main.py",
+					find: "exact original text",
+					replace: "exact replacement text",
+				},
+			],
+			lifecycle_insertions: [
+				{
+					api_name: "ClueInit",
+					file_path: "app/main.py",
+					confidence: 0.8,
+					reason: "SDK initialized where FastAPI app is created.",
+				},
+			],
+			warnings: ["short engineer review note"],
+		},
+		files,
+	});
 
 export const planLifecycleInsertions = async ({ repoRoot, request, env }) => {
-  const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
-  if (!apiKey) {
-    throw new Error(
-      "CLUE_AI_PROVIDER_API_KEY is required for lifecycle API insertion",
-    );
-  }
-  const files = await readContextFiles({ repoRoot, request });
-  return callJsonAiProvider({
-    config: resolveAiProviderConfig({ env, apiKey }),
-    system:
-      "You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
-    user: buildLifecyclePrompt({ request, files }),
-    toolName: "return_lifecycle_plan",
-    toolDescription: "Return the Clue SDK lifecycle insertion plan.",
-    failureMessage: "AI provider failed during lifecycle planning",
-    emptyMessage: "AI provider returned empty lifecycle plan",
-  });
+	const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"CLUE_AI_PROVIDER_API_KEY is required for lifecycle API insertion",
+		);
+	}
+	const files = await readContextFiles({ repoRoot, request });
+	return callJsonAiProvider({
+		config: resolveAiProviderConfig({ env, apiKey }),
+		system:
+			"You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
+		user: buildLifecyclePrompt({ request, files }),
+		toolName: "return_lifecycle_plan",
+		toolDescription: "Return the Clue SDK lifecycle insertion plan.",
+		failureMessage: "AI provider failed during lifecycle planning",
+		emptyMessage: "AI provider returned empty lifecycle plan",
+	});
 };

package/src/public-schema.cjs

@@ -76,6 +76,10 @@ const clueInitToolReportSchema = zod_1.z.object({
     semantic_generation_timing: zod_1.z.literal("after_merge_ci"),
     semantic_preview_generated: zod_1.z.literal(false),
     client_repo_generated_files_committed: zod_1.z.literal(false),
+    frontend_api_key_exposed: zod_1.z.literal(false),
+    browser_token_endpoint_required: zod_1.z.literal(true),
+    browser_token_provider_required: zod_1.z.literal(true),
+    browser_token_endpoint_path: nonEmptyStringSchema,
     clue_track_inserted: zod_1.z.literal(false),
     clue_dom_tag_inserted: zod_1.z.literal(false),
     allowed_source_paths: zod_1.z.array(nonEmptyStringSchema),

package/src/setup-check.mjs

@@ -440,10 +440,12 @@ export const runSetupCheck = async ({
       checks,
       "sdk_lifecycle",
       sdkLifecycle.passed,
-      "SDK lifecycle calls resolve to real source code instead of no-op globals",
+      "static SDK lifecycle references are present and guarded; dependency install, import, app startup, and event delivery are not verified by this check",
       {
         found_apis: sdkLifecycle.foundApis,
         missing_apis: sdkLifecycle.missingApis,
+        verification_scope:
+          "static_source_only_not_dependency_install_or_runtime_event_delivery",
         backend_lifecycle: sdkLifecycle.backend_lifecycle,
         has_noop_wrapper: sdkLifecycle.has_noop_wrapper,
         component_lifecycle_init_files:

package/src/setup-prepare.mjs

@@ -10,6 +10,62 @@ const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
 const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
 const BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
 const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
+const AI_PROVIDER_GUIDES = {
+  codex: {
+    provider: "openai",
+    apiKeyValue: "<openai-api-key>",
+    model: "gpt-5.4-mini",
+    secretComments: [
+      "Codexを選んだ場合はOpenAIのAPI keyを使います。",
+      "https://platform.openai.com/api-keys で作成して、GitHub Secretに保存してください。",
+      "ここにはClue API keyではなく、OpenAI API keyを入れてください。",
+    ],
+    providerComments: [
+      "setup targetがcodexのため、providerはopenaiで自動設定しています。",
+    ],
+    modelComments: [
+      "まず迷ったら gpt-5.4-mini を使ってください。",
+      "精度を優先する場合の例: gpt-5.5",
+      "コストを優先する場合の例: gpt-5.4-nano",
+    ],
+  },
+  claude_code: {
+    provider: "anthropic",
+    apiKeyValue: "<anthropic-api-key>",
+    model: "claude-sonnet-4-6",
+    secretComments: [
+      "Claude Codeを選んだ場合はAnthropicのAPI keyを使います。",
+      "https://console.anthropic.com/settings/keys で作成して、GitHub Secretに保存してください。",
+      "ここにはClue API keyではなく、Anthropic API keyを入れてください。",
+    ],
+    providerComments: [
+      "setup targetがclaude_codeのため、providerはanthropicで自動設定しています。",
+    ],
+    modelComments: [
+      "まず迷ったら claude-sonnet-4-6 を使ってください。",
+      "精度を優先する場合の例: claude-opus-4-7",
+      "コストを優先する場合の例: claude-haiku-4-5-20251001",
+    ],
+  },
+};
+const GENERIC_AI_PROVIDER_GUIDE = {
+  provider: "<openai-or-anthropic>",
+  apiKeyValue: "<provider-api-key>",
+  model: "<provider-model>",
+  secretComments: [
+    "OpenAIまたはAnthropicのAPI keyを作成し、GitHub Secretに保存してください。",
+    "OpenAI: https://platform.openai.com/api-keys",
+    "Anthropic: https://console.anthropic.com/settings/keys",
+    "ここにはClue API keyではなく、選択したAI providerのAPI keyを入れてください。",
+  ],
+  providerComments: [
+    "codexを使う場合はopenai、claude_codeを使う場合はanthropicを指定してください。",
+  ],
+  modelComments: [
+    "OpenAIの例: gpt-5.4-mini / gpt-5.5 / gpt-5.4-nano",
+    "Anthropicの例: claude-sonnet-4-6 / claude-opus-4-7 / claude-haiku-4-5-20251001",
+  ],
+};
 
 const writeJson = async ({ repoRoot, path, value }) => {
   const absolutePath = join(resolve(repoRoot), path);
@@ -88,6 +144,9 @@ const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
 
 const buildEndpoint = (baseUrl, path) => `${trimTrailingSlash(baseUrl)}${path}`;
 
+const aiProviderGuideForTarget = (target) =>
+  AI_PROVIDER_GUIDES[target] ?? GENERIC_AI_PROVIDER_GUIDE;
+
 const setupContextFromInput = (input = {}) => ({
   clue_api_key: optionalString(input.clueApiKey),
   clue_api_base_url: optionalString(input.clueApiBaseUrl),
@@ -140,6 +199,7 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
   }
 
   const watchTargets = manifest.lifecycle_verification.watch_targets;
+  const aiProviderGuide = aiProviderGuideForTarget(manifest.target);
   return {
     status: "ready",
     env_file_path: DEFAULT_ENV_GUIDE_PATH,
@@ -157,17 +217,33 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
         { name: "CLUE_API_KEY", value: setupContext.clue_api_key },
         {
           name: "CLUE_AI_PROVIDER_API_KEY",
-          value: "<openai-or-anthropic-api-key>",
+          value: aiProviderGuide.apiKeyValue,
+          comments: aiProviderGuide.secretComments,
         },
       ],
       variables: [
-        { name: "CLUE_AI_PROVIDER", value: "<openai-or-anthropic>" },
-        { name: "CLUE_AI_MODEL", value: "<selected-provider-model>" },
+        {
+          name: "CLUE_AI_PROVIDER",
+          value: aiProviderGuide.provider,
+          comments: aiProviderGuide.providerComments,
+        },
+        {
+          name: "CLUE_AI_MODEL",
+          value: aiProviderGuide.model,
+          comments: aiProviderGuide.modelComments,
+        },
       ],
     },
   };
 };
 
+const renderEnvironmentEntry = (entry) => [
+  ...(Array.isArray(entry.comments)
+    ? entry.comments.map((comment) => `# ${comment}`)
+    : []),
+  `${entry.name}=${entry.value}`,
+];
+
 const buildEnvironmentGuideText = (instructions) => {
   if (!instructions || instructions.status !== "ready") return null;
   const lines = [
@@ -186,17 +262,13 @@ const buildEnvironmentGuideText = (instructions) => {
   }
   lines.push(
     "GitHub Secrets",
-    ...instructions.ci_github.secrets.map(
-      (entry) => `${entry.name}=${entry.value}`,
-    ),
+    ...instructions.ci_github.secrets.flatMap(renderEnvironmentEntry),
     "",
   );
   if (instructions.ci_github.variables.length > 0) {
     lines.push(
       "GitHub Variables",
-      ...instructions.ci_github.variables.map(
-        (entry) => `${entry.name}=${entry.value}`,
-      ),
+      ...instructions.ci_github.variables.flatMap(renderEnvironmentEntry),
       "",
     );
   }