@clue-ai/cli 0.0.13 → 0.0.15

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.v4";
 const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-sdk-instrumentation": [
     "Do not create no-op wrappers",
@@ -35,14 +35,20 @@ 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",
+    "The local backend token endpoint is part of the customer app, not the Clue API",
+    "The frontend `browserTokenProvider` must send the same service key used by `ClueInit`",
     "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
   ],
   "clue-setup-audit": [
     "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 +231,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,
@@ -294,7 +337,9 @@ const readAllowedSourceText = async ({
 
 const readDependencyText = async ({ repoRoot, roots }) => {
   const expandedRoots = roots.flatMap((root) =>
-    root.endsWith("/src") ? [root, dirname(root)] : [root],
+    root.endsWith("/src") || root.endsWith("/app")
+      ? [root, dirname(root)]
+      : [root],
   );
   const candidatePaths = [
     ...DEPENDENCY_FILE_CANDIDATES,
@@ -372,6 +417,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 +727,106 @@ 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 sourceLooksLikeBrowserTokenProvider = (source) => {
+  const text = stripSourceNoise(source.text);
+  return (
+    sourceImportsFrontendSdk(source) &&
+    /browserTokenProvider|browser[-_]?tokens/i.test(text)
+  );
+};
+
+const findBrowserTokenProviderMissingServiceKeyFiles = (frontendSources) =>
+  frontendSources
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      if (/body\s*:\s*JSON\.stringify\s*\(\s*{\s*}\s*\)/.test(text)) {
+        return true;
+      }
+      return !/body\s*:\s*JSON\.stringify\s*\(\s*{[^}]*\b(?:service_key|serviceKey)\b/.test(
+        text,
+      );
+    })
+    .map((source) => source.file_path);
+
+const findNextBrowserTokenProviderMissingPublicServiceKeyFiles = ({
+  dependencySources,
+  frontendSources,
+}) => {
+  const roots = nextPackageRoots(dependencySources);
+  if (roots.length === 0) return [];
+  return frontendSources
+    .filter((source) => sourceIsUnderAnyRoot(source, roots))
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter(
+      (source) =>
+        !/\bprocess\.env\.NEXT_PUBLIC_CLUE_SERVICE_KEY\b/.test(source.text),
+    )
+    .map((source) => source.file_path);
+};
+
+const sourceLooksLikeBrowserTokenProxy = (source) => {
+  const text = stripSourceNoise(source.text);
+  return (
+    /browser[-_]?tokens|ingest\/browser-tokens/i.test(text) &&
+    /CLUE_API_KEY|x-clue-api-key/i.test(text)
+  );
+};
+
+const findBrowserTokenProxyUsingBackendServiceKeyFiles = (backendSources) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      return [
+        /["']service_key["']\s*:\s*[^,\n}]*CLUE_SERVICE_KEY\b/i,
+        /\bserviceKey\s*:\s*[^,\n}]*CLUE_SERVICE_KEY\b/i,
+        /\b(?:browser_)?service_key\s*=\s*[^,\n]*CLUE_SERVICE_KEY\b/i,
+      ].some((pattern) => pattern.test(text));
+    })
+    .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 +939,21 @@ const checkSdkLifecycle = ({
     sources: frontendSources,
     dependencySources,
   });
+  const nextLifecycleNonPublicEnvFiles = findNextLifecycleNonPublicEnvFiles({
+    dependencySources,
+    frontendSources,
+  });
+  const wildcardFrontendSdkDependencyFiles =
+    findWildcardFrontendSdkDependencyFiles(dependencySources);
+  const browserTokenProviderMissingServiceKeyFiles =
+    findBrowserTokenProviderMissingServiceKeyFiles(frontendSources);
+  const nextBrowserTokenProviderMissingPublicServiceKeyFiles =
+    findNextBrowserTokenProviderMissingPublicServiceKeyFiles({
+      dependencySources,
+      frontendSources,
+    });
+  const browserTokenProxyUsingBackendServiceKeyFiles =
+    findBrowserTokenProxyUsingBackendServiceKeyFiles(backendSources);
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -799,6 +1010,14 @@ const checkSdkLifecycle = ({
       lifecycle_files_without_verified_sdk:
         frontendLifecycleFilesWithoutVerifiedSdk,
       wrong_sdk_packages: wrongFrontendSdkPackages,
+      next_lifecycle_non_public_env_files: nextLifecycleNonPublicEnvFiles,
+      wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
+      browser_token_provider_missing_service_key_files:
+        browserTokenProviderMissingServiceKeyFiles,
+      next_browser_token_provider_missing_public_service_key_files:
+        nextBrowserTokenProviderMissingPublicServiceKeyFiles,
+      browser_token_proxy_uses_backend_service_key_files:
+        browserTokenProxyUsingBackendServiceKeyFiles,
     },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
@@ -815,6 +1034,11 @@ const checkSdkLifecycle = ({
       frontendSdkPresent &&
       frontendLifecycleFilesWithoutVerifiedSdk.length === 0 &&
       wrongFrontendSdkPackages.length === 0 &&
+      nextLifecycleNonPublicEnvFiles.length === 0 &&
+      wildcardFrontendSdkDependencyFiles.length === 0 &&
+      browserTokenProviderMissingServiceKeyFiles.length === 0 &&
+      nextBrowserTokenProviderMissingPublicServiceKeyFiles.length === 0 &&
+      browserTokenProxyUsingBackendServiceKeyFiles.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
       blockingLifecycleFiles.length === 0,

package/src/setup-documents.mjs

@@ -0,0 +1,99 @@
+export const SETUP_DOCUMENTATION_CONTRACT_VERSION =
+  "2026-05-10.setup-documents.v1";
+
+export const DEFAULT_SETUP_DOCUMENTS_URL = "/documents";
+
+export const CORE_SETUP_DOCUMENT_IDS = [
+  "ai-setup-order",
+  "clue-boundary",
+  "environment-and-secrets",
+  "find-integration-points",
+  "browser-token-endpoint",
+  "clue-init",
+  "clue-identify",
+  "clue-set-account",
+  "clue-logout",
+  "setup-verification",
+  "forbidden-patterns",
+];
+
+export const FRAMEWORK_SETUP_DOCUMENT_IDS = {
+  angular: "framework-react-spa",
+  django: "framework-django",
+  fastapi: "framework-fastapi",
+  nextjs: "framework-nextjs",
+  react: "framework-react-spa",
+  vite: "framework-react-spa",
+  vue: "framework-react-spa",
+};
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const normalizeDocumentsUrl = (documentsUrl) =>
+  optionalString(documentsUrl)?.replace(/\/+$/, "") ??
+  DEFAULT_SETUP_DOCUMENTS_URL;
+
+const normalizeFrameworks = (frameworks = []) => [
+  ...new Set(
+    frameworks
+      .map((framework) =>
+        typeof framework === "string" && framework.trim()
+          ? framework.trim().toLowerCase()
+          : null,
+      )
+      .filter(Boolean),
+  ),
+];
+
+const docUrlFor = ({ documentsUrl, docId }) => `${documentsUrl}#${docId}`;
+
+export const frameworkDocIdsFor = (frameworks = []) =>
+  [
+    ...new Set(
+      normalizeFrameworks(frameworks)
+        .map((framework) => FRAMEWORK_SETUP_DOCUMENT_IDS[framework])
+        .filter(Boolean),
+    ),
+  ];
+
+export const buildSetupDocumentationContract = ({
+  documentsUrl,
+  framework,
+  frameworks = [],
+} = {}) => {
+  const normalizedDocumentsUrl = normalizeDocumentsUrl(documentsUrl);
+  const selectedFrameworks = normalizeFrameworks([
+    ...(framework ? [framework] : []),
+    ...frameworks,
+  ]);
+  const selectedFrameworkDocIds = frameworkDocIdsFor(selectedFrameworks);
+  const requiredDocIds = [
+    ...new Set([...CORE_SETUP_DOCUMENT_IDS, ...selectedFrameworkDocIds]),
+  ];
+
+  return {
+    version: SETUP_DOCUMENTATION_CONTRACT_VERSION,
+    documents_url: normalizedDocumentsUrl,
+    required_doc_ids: requiredDocIds,
+    framework_doc_ids_by_framework: FRAMEWORK_SETUP_DOCUMENT_IDS,
+    selected_frameworks: selectedFrameworks,
+    selected_framework_doc_ids: selectedFrameworkDocIds,
+    doc_urls: Object.fromEntries(
+      requiredDocIds.map((docId) => [
+        docId,
+        docUrlFor({ documentsUrl: normalizedDocumentsUrl, docId }),
+      ]),
+    ),
+    pre_editing_gate: [
+      "Open documents_url before editing when tool access allows it.",
+      "Read every required_doc_ids entry that applies to the detected framework.",
+      "If documents_url cannot be opened, continue only from the generated skills and manifest doc ids, and report documentation_access_blocked.",
+      "Do not implement by prompt memory alone when the manifest contains a documentation contract.",
+    ],
+    report_required_fields: ["consulted_document_ids"],
+    agent_rule:
+      "Read the relevant Clue setup documents before editing and list consulted_document_ids in the final report.",
+  };
+};
+

package/src/setup-help.mjs

@@ -2,8 +2,9 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { buildSetupDocumentationContract } from "./setup-documents.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.v4";
 
 export const buildAiSetupHelp = () => ({
   name: "@clue-ai/cli AI setup help",
@@ -43,6 +44,22 @@ 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. The proxy endpoint belongs to the customer backend, but it calls the Clue API server-side at /api/v1/ingest/browser-tokens. The frontend browserTokenProvider must send the frontend ClueInit serviceKey to that customer backend proxy, and the proxy must issue browser tokens for that frontend serviceKey, not the backend service key.",
+      },
+    },
+    documentation_contract: buildSetupDocumentationContract(),
     setup_watch: {
       owner: "user",
       ai_agent_must_run: false,

package/src/setup-prepare.mjs

@@ -8,12 +8,26 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
 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",
@@ -154,6 +168,7 @@ const aiProviderGuideForTarget = (target) =>
 const setupContextFromInput = (input = {}) => ({
   clue_api_key: optionalString(input.clueApiKey),
   clue_api_base_url: optionalString(input.clueApiBaseUrl),
+  documents_url: optionalString(input.documentsUrl),
   project_key: optionalString(input.projectKey),
   environment: optionalString(input.environment),
 });
@@ -165,24 +180,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 +262,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 +275,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: [
@@ -323,10 +388,22 @@ export const runSetupPrepare = async ({
   const detection = await runSetupDetect({ repoRoot: resolvedRepoRoot });
   const { candidate, blockers } = firstCandidateOrBlocker(detection);
   if (!candidate) {
+    const detectedFrameworks = [
+      ...(Array.isArray(detection.services?.frontend)
+        ? detection.services.frontend.map((service) => service.framework)
+        : []),
+      ...(Array.isArray(detection.services?.backend)
+        ? detection.services.backend.map((service) => service.framework)
+        : []),
+    ];
     const manifest = {
       status: "blocked",
       target,
       skill_root: skillRoot,
+      documentation: buildSetupDocumentationContract({
+        documentsUrl: setupContext.documents_url,
+        frameworks: detectedFrameworks,
+      }),
       blockers,
       detection,
       ai_next_scope: "blocked_until_backend_routes_are_detected",
@@ -371,6 +448,16 @@ export const runSetupPrepare = async ({
     repoRoot: resolvedRepoRoot,
     request,
   });
+  const watchTargets = buildWatchTargets(detection, candidate);
+  const detectedFrameworks = [
+    candidate.framework,
+    ...watchTargets.map((target) => target.framework),
+  ];
+  const frontendRuntimeEnvNames = requiredFrontendEnvNames(watchTargets);
+  const backendRuntimeEnvNames = requiredBackendEnvNames(watchTargets);
+  const serviceRuntimeEnvNames = [
+    ...new Set([...frontendRuntimeEnvNames, ...backendRuntimeEnvNames]),
+  ];
 
   const manifest = {
     status: "ready_for_ai",
@@ -381,10 +468,19 @@ export const runSetupPrepare = async ({
       backend_root_path: candidate.backend_root_path,
       service_key: candidate.service_key,
     },
+    documentation: buildSetupDocumentationContract({
+      documentsUrl: setupContext.documents_url,
+      framework: candidate.framework,
+      frameworks: detectedFrameworks,
+    }),
     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 +507,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 +565,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",