@clue-ai/cli 0.0.13 → 0.0.14

package/README.md

@@ -69,6 +69,9 @@ service key and the lifecycle checks expected for that service, for example
 `frontend:web[init,identify,set-account,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>`.
 Do not assume localhost ports; use the actual URLs printed by the repository's
 dev scripts or configured in its local env.
+In `--local` mode, the watcher stays open until the expected lifecycle checks
+pass or you stop it with Ctrl+C. It prints a per-service Clue lifecycle
+checklist and only prints a new snapshot when the observed state changes.
 
 `npx -y @clue-ai/cli setup` reads Clue values from the setup screen flags, detects local
 services, writes `.clue/setup-manifest.json`, and prints service-specific env

package/bin/clue-cli.mjs

@@ -135,6 +135,15 @@ const DEFAULT_WATCH_LIFECYCLE = [
   "event-sent",
 ];
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const DEFAULT_REMOTE_SETUP_WATCH_TIMEOUT_MS = 120_000;
+
+const WATCH_LIFECYCLE_LABELS = new Map([
+  ["init", "ClueInit"],
+  ["identify", "ClueIdentify"],
+  ["set-account", "ClueSetAccount"],
+  ["logout", "ClueLogout"],
+  ["event-sent", "Event delivery"],
+]);
 
 const parseExpectedLifecycle = (value) => {
   if (typeof value !== "string" || !value.trim()) {
@@ -333,6 +342,20 @@ const buildWatchProducerIds = ({ explicitProducerIds, watchTargets }) =>
     ...watchTargets.map((target) => target.producerId),
   ]);
 
+const parseSetupWatchTimeoutMs = ({ flags, localMode }) => {
+  if (!flags.has("timeout-ms")) {
+    return localMode ? null : DEFAULT_REMOTE_SETUP_WATCH_TIMEOUT_MS;
+  }
+  const timeoutMs = Number(flags.get("timeout-ms"));
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new Error("--timeout-ms must be a non-negative number");
+  }
+  return timeoutMs;
+};
+
+const isSetupWatchTimedOut = ({ started, timeoutMs }) =>
+  timeoutMs !== null && Date.now() - started > timeoutMs;
+
 const checkTargetUrl = async (url) => {
   if (!url) return { checked: true, reachable: false, status: null };
   try {
@@ -543,25 +566,60 @@ const startLocalSetupReceiver = async ({ host, port }) => {
   };
 };
 
+const lifecycleLabel = (name) => WATCH_LIFECYCLE_LABELS.get(name) ?? name;
+
+const statusMark = (passed) => (passed ? "x" : " ");
+
+const lifecycleStatusText = (passed) => (passed ? "done!" : "pending...");
+
+const targetUrlStatusText = (target) => {
+  if (!target.urlChecked) return null;
+  return String(
+    target.urlReachable
+      ? target.urlStatus
+      : (target.urlStatus ?? "unreachable"),
+  );
+};
+
 const renderWatchTargets = (targetChecks) =>
   targetChecks
     .map((target) => {
-      const urlStatus = target.urlChecked
-        ? ` url:${target.urlReachable ? target.urlStatus : (target.urlStatus ?? "unreachable")}`
-        : "";
-      const lifecycle = target.expectedLifecycle
-        .map(
-          (name) =>
-            `${name}:${target.lifecycleStatus[name] ? "ok" : "waiting"}`,
-        )
-        .join(" ");
-      const unexpected = target.unexpectedLifecycle.length
-        ? ` unexpected:${target.unexpectedLifecycle.join(",")}`
-        : "";
-      return `${target.passed ? "[x]" : "[ ]"} ${target.kind}:${target.serviceKey} ${lifecycle} events:${target.eventCount}${urlStatus}${unexpected}`;
+      const lifecycleLines = target.expectedLifecycle.map((name) => {
+        const passed = Boolean(target.lifecycleStatus[name]);
+        return `  [${statusMark(passed)}] ${lifecycleLabel(name)} ${lifecycleStatusText(passed)}`;
+      });
+      const urlStatus = targetUrlStatusText(target);
+      const detailLines = [`  events: ${target.eventCount}`];
+      if (urlStatus !== null) {
+        detailLines.push(`  url: ${urlStatus}`);
+      }
+      if (target.unexpectedLifecycle.length) {
+        detailLines.push(
+          `  unexpected: ${target.unexpectedLifecycle.map(lifecycleLabel).join(", ")}`,
+        );
+      }
+      return [
+        `[${statusMark(target.passed)}] ${target.kind}:${target.serviceKey}`,
+        ...lifecycleLines,
+        ...detailLines,
+      ].join("\n");
     })
+    .join("\n\n");
+
+const renderSetupCheckEntries = (entries) =>
+  entries
+    .map(([id, status]) => `${status === "passed" ? "[x]" : "[ ]"} ${id}`)
     .join("\n");
 
+const joinRenderedSections = (...sections) =>
+  sections.filter((section) => section.trim()).join("\n\n");
+
+const writeChangedSetupWatchSnapshot = ({ rendered, state }) => {
+  if (!rendered || rendered === state.lastRendered) return;
+  process.stdout.write(`${rendered}\n\n`);
+  state.lastRendered = rendered;
+};
+
 const setupCheckUrl = ({
   clueApiBaseUrl,
   environment,
@@ -621,7 +679,7 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
   const startedAt = String(
     flags.get("started-at") || new Date().toISOString(),
   ).trim();
-  const timeoutMs = Number(flags.get("timeout-ms") || 120_000);
+  const timeoutMs = parseSetupWatchTimeoutMs({ flags, localMode });
   const pollIntervalMs = Number(flags.get("poll-interval-ms") || 3000);
   const limit = Number(flags.get("limit") || 200);
   const projectId = flags.get("project-id");
@@ -639,6 +697,11 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
       "setup-watch requires --watch-targets or .clue/setup-manifest.json lifecycle_verification.watch_targets before setup can be treated as verified",
     );
   }
+  if (localMode && watchTargets.length === 0) {
+    throw new Error(
+      "setup-watch --local requires .clue/setup-manifest.json lifecycle_verification.watch_targets",
+    );
+  }
   const producerIds = buildWatchProducerIds({
     explicitProducerIds: flags.get("producer-ids"),
     watchTargets,
@@ -664,7 +727,13 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
           `Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
         );
       }
-      while (Date.now() - started <= timeoutMs) {
+      process.stdout.write(
+        timeoutMs === null
+          ? "No automatic timeout in local mode. Operate your local app, then press Ctrl+C to stop if needed.\n"
+          : `Timeout: ${timeoutMs}ms\n`,
+      );
+      const renderState = { lastRendered: "" };
+      while (!isSetupWatchTimedOut({ started, timeoutMs })) {
         latest = localSetupCheckSnapshot({
           receivedBatches: receiver.receivedBatches,
         });
@@ -676,14 +745,19 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
           targetChecks.length > 0 &&
           targetChecks.every((target) => target.passed);
         const renderedTargets = renderWatchTargets(targetChecks);
-        process.stdout.write(`${renderedTargets}\n\n`);
+        writeChangedSetupWatchSnapshot({
+          rendered: renderedTargets,
+          state: renderState,
+        });
         if (targetChecksPassed) {
           process.stdout.write("Clue local setup checks passed.\n");
           return { ...latest, local: true, watchTargets: targetChecks };
         }
         await sleep(pollIntervalMs);
       }
-      process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+      if (flags.has("json")) {
+        process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+      }
       throw new Error(
         "setup-watch --local timed out before all Clue setup checks passed",
       );
@@ -701,7 +775,8 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
     );
   }
 
-  while (Date.now() - started <= timeoutMs) {
+  const renderState = { lastRendered: "" };
+  while (!isSetupWatchTimedOut({ started, timeoutMs })) {
     const response = await fetch(
       setupCheckUrl({
         clueApiBaseUrl,
@@ -724,13 +799,12 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
     const targetChecks = await evaluateWatchTargets({ latest, watchTargets });
     const targetChecksPassed = targetChecks.every((target) => target.passed);
     const passed = setupChecksPassed && targetChecksPassed;
-    const rendered = entries
-      .map(([id, status]) => `${status === "passed" ? "[x]" : "[ ]"} ${id}`)
-      .join("\n");
+    const rendered = renderSetupCheckEntries(entries);
     const renderedTargets = renderWatchTargets(targetChecks);
-    process.stdout.write(
-      `${rendered}${renderedTargets ? `\n${renderedTargets}` : ""}\n\n`,
-    );
+    writeChangedSetupWatchSnapshot({
+      rendered: joinRenderedSections(rendered, renderedTargets),
+      state: renderState,
+    });
     if (passed) {
       process.stdout.write("Clue setup checks passed.\n");
       return { ...latest, watchTargets: targetChecks };
@@ -738,7 +812,9 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
     await sleep(pollIntervalMs);
   }
 
-  process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+  if (flags.has("json")) {
+    process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+  }
   throw new Error("setup-watch timed out before all Clue setup checks passed");
 };
 

package/package.json

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

package/src/lifecycle-init.mjs

@@ -568,12 +568,16 @@ 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.",
-      "CLUE_API_BASE_URL is for Clue CLI and semantic snapshot CI configuration, not backend SDK runtime configuration. Do not add it to application config unless existing non-Clue code already requires it.",
-      "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.",
+      "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, and NEXT_PUBLIC_CLUE_INGEST_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.",
+      "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.",
       "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.",
+      "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 add @clue-ai/browser-sdk or backend SDK dependencies with * or latest; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
       "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.",
@@ -584,13 +588,17 @@ const buildLifecyclePrompt = ({ request, files }) =>
       target_tool: request.target_tool,
       framework: request.framework,
       project_key_env: "CLUE_PROJECT_KEY",
-      browser_project_key_env: "CLUE_PROJECT_KEY",
+      browser_project_key_env: "framework_specific",
+      nextjs_browser_project_key_env: "NEXT_PUBLIC_CLUE_PROJECT_KEY",
       environment_env: "CLUE_ENVIRONMENT",
-      browser_environment_env: "CLUE_ENVIRONMENT",
+      browser_environment_env: "framework_specific",
+      nextjs_browser_environment_env: "NEXT_PUBLIC_CLUE_ENVIRONMENT",
       clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
       tooling_api_base_url_env: "CLUE_API_BASE_URL",
-      browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+      browser_ingest_endpoint_env: "framework_specific",
+      nextjs_browser_ingest_endpoint_env: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
       browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
+      nextjs_browser_service_key_env: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
       service_key: request.service_key,
     },
     output_shape: {

package/src/setup-check.mjs

@@ -27,7 +27,7 @@ const SETUP_SKILLS = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v2";
+const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v3";
 const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-sdk-instrumentation": [
     "Do not create no-op wrappers",
@@ -35,7 +35,10 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "add the real `@clue-ai/browser-sdk` dependency",
     "Do not invent `clue-js-sdk`",
     "The implementation scope is only ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout placement",
-    "CLUE_API_BASE_URL` is for Clue CLI and semantic snapshot CI configuration",
+    "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`",
+    "Do not read `process.env.CLUE_PROJECT_KEY`",
+    "CLUE_API_BASE_URL` is not part of backend SDK initialization",
+    "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`",
     "Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring",
     "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
   ],
@@ -43,6 +46,7 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "Reject wrong SDK package names",
     "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 whitespace-only edits, import sorting, formatter churn",
     "Reject unrelated refactors, renames, file moves",
     "Execution agents must not approve, certify, or mark their own work complete",
@@ -225,6 +229,43 @@ const validateSetupManifestContract = (manifest) => {
       "required_final_verification.local_event_delivery must report user_verification_pending without user evidence",
     );
   }
+  const watchTargets = Array.isArray(
+    manifest.lifecycle_verification?.watch_targets,
+  )
+    ? manifest.lifecycle_verification.watch_targets
+    : [];
+  const hasNextFrontend = watchTargets.some(
+    (target) => target?.kind === "frontend" && target?.framework === "nextjs",
+  );
+  const hasFrontend = watchTargets.some((target) => target?.kind === "frontend");
+  const frontendRuntime = Array.isArray(
+    manifest.required_env_scopes?.frontend_runtime,
+  )
+    ? manifest.required_env_scopes.frontend_runtime
+    : [];
+  const backendRuntime = Array.isArray(
+    manifest.required_env_scopes?.backend_runtime,
+  )
+    ? manifest.required_env_scopes.backend_runtime
+    : [];
+  if (
+    hasNextFrontend &&
+    ![
+      "NEXT_PUBLIC_CLUE_PROJECT_KEY",
+      "NEXT_PUBLIC_CLUE_ENVIRONMENT",
+      "NEXT_PUBLIC_CLUE_SERVICE_KEY",
+      "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+    ].every((name) => frontendRuntime.includes(name))
+  ) {
+    findings.push(
+      "Next.js frontend runtime env must use NEXT_PUBLIC_CLUE_* names",
+    );
+  }
+  if (hasFrontend && !backendRuntime.includes("CLUE_API_BASE_URL")) {
+    findings.push(
+      "backend_runtime must include CLUE_API_BASE_URL when a frontend browser token proxy can be required",
+    );
+  }
   return {
     checked: true,
     findings,
@@ -372,6 +413,57 @@ const packageJsonDependencyNames = (text) => {
   }
 };
 
+const packageJsonDependencies = (text) => {
+  try {
+    const parsed = JSON.parse(text);
+    return [
+      "dependencies",
+      "devDependencies",
+      "optionalDependencies",
+      "peerDependencies",
+    ].reduce((result, field) => {
+      if (parsed && typeof parsed[field] === "object" && parsed[field] !== null) {
+        for (const [name, version] of Object.entries(parsed[field])) {
+          if (typeof version === "string") {
+            result.set(name, version);
+          }
+        }
+      }
+      return result;
+    }, new Map());
+  } catch {
+    return new Map();
+  }
+};
+
+const packageJsonHasDependency = (text, packageName) =>
+  packageJsonDependencies(text).has(packageName);
+
+const packageJsonDependencyVersion = (text, packageName) =>
+  packageJsonDependencies(text).get(packageName) ?? null;
+
+const packageJsonSourcesWithDependency = (dependencySources, packageName) =>
+  dependencySources.filter(
+    (source) =>
+      source.file_path.endsWith("package.json") &&
+      packageJsonHasDependency(source.text, packageName),
+  );
+
+const nextPackageRoots = (dependencySources) =>
+  packageJsonSourcesWithDependency(dependencySources, "next").map((source) =>
+    dirname(source.file_path),
+  );
+
+const sourceIsUnderAnyRoot = (source, roots) =>
+  roots.some((root) => {
+    const normalizedRoot = root.replace(/\/+$/, "");
+    return (
+      normalizedRoot === "." ||
+      normalizedRoot === "" ||
+      startsWithRoot(source.file_path, normalizedRoot)
+    );
+  });
+
 const dependencySourceHasPackage = (source, packageName) => {
   if (source.file_path.endsWith("package.json")) {
     return packageJsonDependencyNames(source.text).includes(packageName);
@@ -631,6 +723,47 @@ const findWrongFrontendSdkPackages = ({ sources, dependencySources }) => {
   );
 };
 
+const NEXT_PUBLIC_CLUE_NAMES = [
+  "CLUE_PROJECT_KEY",
+  "CLUE_ENVIRONMENT",
+  "CLUE_SERVICE_KEY",
+  "CLUE_INGEST_ENDPOINT",
+];
+
+const findNextLifecycleNonPublicEnvFiles = ({
+  dependencySources,
+  frontendSources,
+}) => {
+  const roots = nextPackageRoots(dependencySources);
+  if (roots.length === 0) return [];
+  return frontendSources
+    .filter((source) => sourceIsUnderAnyRoot(source, roots))
+    .filter(
+      (source) =>
+        sourceImportsFrontendSdk(source) ||
+        findLifecycleCallApiNames(
+          stripSourceNoise(source.text, { stripStrings: true }),
+        ).length > 0,
+    )
+    .filter((source) =>
+      NEXT_PUBLIC_CLUE_NAMES.some((name) =>
+        new RegExp(`process\\.env\\.${name}\\b`).test(source.text),
+      ),
+    )
+    .map((source) => source.file_path);
+};
+
+const findWildcardFrontendSdkDependencyFiles = (dependencySources) =>
+  packageJsonSourcesWithDependency(dependencySources, FRONTEND_SDK_PACKAGE)
+    .filter((source) => {
+      const version = packageJsonDependencyVersion(
+        source.text,
+        FRONTEND_SDK_PACKAGE,
+      );
+      return version === "*" || version === "latest";
+    })
+    .map((source) => source.file_path);
+
 const backendSdkSpec = (framework) =>
   BACKEND_SDK_BY_FRAMEWORK[String(framework ?? "").toLowerCase()] ?? {
     packages: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
@@ -743,6 +876,12 @@ const checkSdkLifecycle = ({
     sources: frontendSources,
     dependencySources,
   });
+  const nextLifecycleNonPublicEnvFiles = findNextLifecycleNonPublicEnvFiles({
+    dependencySources,
+    frontendSources,
+  });
+  const wildcardFrontendSdkDependencyFiles =
+    findWildcardFrontendSdkDependencyFiles(dependencySources);
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -799,6 +938,8 @@ const checkSdkLifecycle = ({
       lifecycle_files_without_verified_sdk:
         frontendLifecycleFilesWithoutVerifiedSdk,
       wrong_sdk_packages: wrongFrontendSdkPackages,
+      next_lifecycle_non_public_env_files: nextLifecycleNonPublicEnvFiles,
+      wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
     },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
@@ -815,6 +956,8 @@ const checkSdkLifecycle = ({
       frontendSdkPresent &&
       frontendLifecycleFilesWithoutVerifiedSdk.length === 0 &&
       wrongFrontendSdkPackages.length === 0 &&
+      nextLifecycleNonPublicEnvFiles.length === 0 &&
+      wildcardFrontendSdkDependencyFiles.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
       blockingLifecycleFiles.length === 0,

package/src/setup-help.mjs

@@ -3,7 +3,7 @@ import {
   clueCliCommand,
 } from "./cli-invocation.mjs";
 
-export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v2";
+export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v3";
 
 export const buildAiSetupHelp = () => ({
   name: "@clue-ai/cli AI setup help",
@@ -43,6 +43,21 @@ export const buildAiSetupHelp = () => ({
         "whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines",
       ],
     },
+    environment_contract: {
+      nextjs_frontend_client_env: {
+        variables: [
+          "NEXT_PUBLIC_CLUE_PROJECT_KEY",
+          "NEXT_PUBLIC_CLUE_ENVIRONMENT",
+          "NEXT_PUBLIC_CLUE_SERVICE_KEY",
+          "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
+        ],
+        rule: "When the frontend framework is Next.js, browser/client code must read only these NEXT_PUBLIC_* Clue variables. Do not add process.env.CLUE_* fallbacks in client-bundled code.",
+      },
+      backend_browser_token_proxy_env: {
+        variables: ["CLUE_API_KEY", "CLUE_API_BASE_URL"],
+        rule: "CLUE_API_KEY stays server-side. CLUE_API_BASE_URL is used only by backend-owned browser token proxy code and is not part of backend SDK initialization.",
+      },
+    },
     setup_watch: {
       owner: "user",
       ai_agent_must_run: false,

package/src/setup-prepare.mjs

@@ -14,6 +14,19 @@ 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 FRONTEND_PUBLIC_ENV_NAMES = [
+  "CLUE_INGEST_ENDPOINT",
+  "CLUE_PROJECT_KEY",
+  "CLUE_ENVIRONMENT",
+  "CLUE_SERVICE_KEY",
+];
+const BACKEND_RUNTIME_ENV_NAMES = [
+  "CLUE_SERVICE_KEY",
+  "CLUE_PROJECT_KEY",
+  "CLUE_ENVIRONMENT",
+  "CLUE_INGEST_ENDPOINT",
+  "CLUE_API_KEY",
+];
 const AI_PROVIDER_GUIDES = {
   codex: {
     provider: "openai",
@@ -165,24 +178,67 @@ const envFileCandidates = (target) => {
   return [".env"];
 };
 
-const buildServiceEnvBlock = ({ target, setupContext }) => {
+const frontendEnvName = ({ target, name }) =>
+  target.kind === "frontend" && target.framework === "nextjs"
+    ? `NEXT_PUBLIC_${name}`
+    : name;
+
+const buildServiceEnvBlock = ({
+  target,
+  setupContext,
+  includeBrowserTokenProxyConfig = false,
+}) => {
   const ingestPath =
     target.kind === "frontend" ? BROWSER_INGEST_PATH : BACKEND_INGEST_PATH;
   const variables = [
     {
-      name: "CLUE_INGEST_ENDPOINT",
+      name: frontendEnvName({ target, name: "CLUE_INGEST_ENDPOINT" }),
       value: buildEndpoint(setupContext.clue_api_base_url, ingestPath),
     },
-    { name: "CLUE_PROJECT_KEY", value: setupContext.project_key },
-    { name: "CLUE_ENVIRONMENT", value: setupContext.environment },
-    { name: "CLUE_SERVICE_KEY", value: target.service_key },
+    {
+      name: frontendEnvName({ target, name: "CLUE_PROJECT_KEY" }),
+      value: setupContext.project_key,
+    },
+    {
+      name: frontendEnvName({ target, name: "CLUE_ENVIRONMENT" }),
+      value: setupContext.environment,
+    },
+    {
+      name: frontendEnvName({ target, name: "CLUE_SERVICE_KEY" }),
+      value: target.service_key,
+    },
   ];
   if (target.kind === "backend") {
     variables.push({ name: "CLUE_API_KEY", value: setupContext.clue_api_key });
+    if (includeBrowserTokenProxyConfig) {
+      variables.push({
+        name: "CLUE_API_BASE_URL",
+        value: setupContext.clue_api_base_url,
+      });
+    }
   }
   return variables.map(({ name, value }) => `${name}=${value}`).join("\n");
 };
 
+const requiredFrontendEnvNames = (watchTargets) => [
+  ...new Set(
+    watchTargets
+      .filter((target) => target.kind === "frontend")
+      .flatMap((target) =>
+        FRONTEND_PUBLIC_ENV_NAMES.map((name) =>
+          frontendEnvName({ target, name }),
+        ),
+      ),
+  ),
+];
+
+const requiredBackendEnvNames = (watchTargets) => [
+  ...BACKEND_RUNTIME_ENV_NAMES,
+  ...(watchTargets.some((target) => target.kind === "frontend")
+    ? ["CLUE_API_BASE_URL"]
+    : []),
+];
+
 const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
   const missingFlags = [
     ["clue_api_key", "--clue-api-key"],
@@ -204,6 +260,9 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
 
   const watchTargets = manifest.lifecycle_verification.watch_targets;
   const aiProviderGuide = aiProviderGuideForTarget(manifest.target);
+  const includeBrowserTokenProxyConfig = watchTargets.some(
+    (target) => target.kind === "frontend",
+  );
   return {
     status: "ready",
     env_file_path: DEFAULT_ENV_GUIDE_PATH,
@@ -214,7 +273,11 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
       root_path: target.root_path,
       service_key: target.service_key,
       env_file_candidates: envFileCandidates(target),
-      env_block: buildServiceEnvBlock({ target, setupContext }),
+      env_block: buildServiceEnvBlock({
+        target,
+        setupContext,
+        includeBrowserTokenProxyConfig,
+      }),
     })),
     ci_github: {
       secrets: [
@@ -371,6 +434,12 @@ export const runSetupPrepare = async ({
     repoRoot: resolvedRepoRoot,
     request,
   });
+  const watchTargets = buildWatchTargets(detection, candidate);
+  const frontendRuntimeEnvNames = requiredFrontendEnvNames(watchTargets);
+  const backendRuntimeEnvNames = requiredBackendEnvNames(watchTargets);
+  const serviceRuntimeEnvNames = [
+    ...new Set([...frontendRuntimeEnvNames, ...backendRuntimeEnvNames]),
+  ];
 
   const manifest = {
     status: "ready_for_ai",
@@ -384,7 +453,11 @@ export const runSetupPrepare = async ({
     service_identity: {
       canonical_field: "service_key",
       backend_env_name: "CLUE_SERVICE_KEY",
-      frontend_env_name: "CLUE_SERVICE_KEY",
+      frontend_env_name: "framework_specific",
+      frontend_env_names_by_framework: {
+        nextjs: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
+        default: "CLUE_SERVICE_KEY",
+      },
       producer_id_derivation: "producer_id defaults to service_key",
     },
     cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
@@ -411,7 +484,7 @@ export const runSetupPrepare = async ({
       watch_target_format:
         "frontend:<service-key>[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>",
       rule: "setup-watch --local uses the structured watch_targets below, but it is user-operated verification. AI implementation agents must not run setup-watch automatically.",
-      watch_targets: buildWatchTargets(detection, candidate),
+      watch_targets: watchTargets,
     },
     artifacts: {
       ci_workflow_path: workflow.ci_workflow_path,
@@ -469,24 +542,21 @@ export const runSetupPrepare = async ({
       },
     ],
     required_env_names: [
-      "CLUE_SERVICE_KEY",
-      "CLUE_API_KEY",
-      "CLUE_AI_PROVIDER",
-      "CLUE_AI_PROVIDER_API_KEY",
-      "CLUE_AI_MODEL",
-      "CLUE_PROJECT_KEY",
-      "CLUE_ENVIRONMENT",
-      "CLUE_INGEST_ENDPOINT",
-      "CLUE_API_BASE_URL",
-    ],
-    required_env_scopes: {
-      service_runtime: [
-        "CLUE_SERVICE_KEY",
+      ...new Set([
+        ...serviceRuntimeEnvNames,
+        "CLUE_API_KEY",
+        "CLUE_AI_PROVIDER",
+        "CLUE_AI_PROVIDER_API_KEY",
+        "CLUE_AI_MODEL",
         "CLUE_PROJECT_KEY",
         "CLUE_ENVIRONMENT",
-        "CLUE_INGEST_ENDPOINT",
-        "CLUE_API_KEY",
-      ],
+        "CLUE_API_BASE_URL",
+      ]),
+    ],
+    required_env_scopes: {
+      service_runtime: serviceRuntimeEnvNames,
+      frontend_runtime: frontendRuntimeEnvNames,
+      backend_runtime: backendRuntimeEnvNames,
       github_secrets: ["CLUE_API_KEY", "CLUE_AI_PROVIDER_API_KEY"],
       github_variables: [
         "CLUE_PROJECT_KEY",

package/src/setup-tool.mjs

@@ -17,7 +17,7 @@ const SKILL_NAMES = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v2";
+const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v3";
 
 const TARGETS = new Set(["codex", "claude_code"]);
 
@@ -266,15 +266,19 @@ const skillBody = (name) => {
       "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
       "Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
       `For local env files, use the service-specific env blocks written to \`.env.clue\` by \`${clueCliCommand("setup")}\`; do not ask the user to guess \`CLUE_SERVICE_KEY\`.`,
-      "For browser code, use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_SERVICE_KEY`, and `CLUE_INGEST_ENDPOINT`. Let the target framework expose or inject those values safely without hard-coding a Next.js-only prefix.",
+      "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`, `NEXT_PUBLIC_CLUE_ENVIRONMENT`, `NEXT_PUBLIC_CLUE_SERVICE_KEY`, and `NEXT_PUBLIC_CLUE_INGEST_ENDPOINT` from the frontend `.env.local` block.",
+      "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.",
+      "For non-Next.js browser code, use the exact frontend env names written in `.env.clue` for that service instead of inventing a framework-specific prefix.",
       "Never put `CLUE_API_KEY` in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side `CLUE_API_KEY` and requests `POST /api/v1/ingest/browser-tokens` from Clue.",
       "Configure frontend `ClueInit` with `browserTokenProvider` that calls the local backend token endpoint and returns the token string.",
       "The 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.",
+      "If a backend-owned browser token endpoint is implemented, read `CLUE_API_BASE_URL` from the backend env block and normalize it so values with or without a trailing `/api/v1` do not produce duplicate paths.",
       "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT` from the backend env block.",
-      "`CLUE_API_BASE_URL` is for Clue CLI and semantic snapshot CI configuration, not backend SDK runtime configuration. Do not add it to application config unless existing non-Clue code already requires it.",
+      "`CLUE_API_BASE_URL` is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
+      "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
       "Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
-      "For frontend code, pass `serviceKey` from `CLUE_SERVICE_KEY` to `ClueInit`. Do not require a separate producer id unless the repository already has one for compatibility.",
+      "For frontend code, pass `serviceKey` from the frontend service env name written by `.env.clue` to `ClueInit`; in Next.js browser/client code that name is `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
       "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable; if it is not published or cannot be verified, report a blocker instead of adding a guessed dependency or import.",
       "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 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.",
@@ -305,6 +309,8 @@ const skillBody = (name) => {
       "Reject ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or any repeated user interaction path.",
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
       "Reject ClueTrack instrumentation unless the user explicitly requested product event tracking.",
+      "Reject Next.js browser/client code that reads non-public `process.env.CLUE_*` variables.",
+      "Reject Clue SDK dependency entries that use `*` or `latest` instead of a concrete published version or package-manager-resolved semver range.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
       "Reject whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines.",
@@ -343,7 +349,7 @@ const skillBody = (name) => {
       "List skills used for each workstream.",
       "List execution agent and monitoring agents, or named review passes if subagents were unavailable.",
       "List blockers with exact file or environment names when available.",
-      "List required env names without values and group them by scope: service runtime env blocks versus GitHub Secrets/Variables. Do not report `CLUE_API_BASE_URL` as a backend SDK runtime env; it belongs to Clue CLI and semantic snapshot CI configuration.",
+      "List required env names without values and group them by scope: frontend runtime, backend runtime, GitHub Secrets, and GitHub Variables. Do not report `CLUE_API_BASE_URL` as a backend SDK init env; it belongs to Clue CLI/semantic CI and to backend browser-token proxy config only when a frontend service exists.",
       "List P0/P1 monitoring findings and fixes.",
       "State that commit and push were not performed.",
     ],