@genn-inc/cluebase-cli 0.0.1 → 0.0.3

package/README.md

@@ -27,8 +27,9 @@ preparation:
   Node: Express/NestJS/Fastify/Koa) from dependency manifests and framework
   import signals — language, framework, and service root only
 - writes `.cluebase/setup-manifest.json`
-- defers service-specific runtime env guidance to the Cluebase setup screen Step 2;
-  the CLI does not write `.env.cluebase`
+- writes the single root `.env.cluebase` file with `[app]`, `[frontend]`, and
+  `[frontend_user]` sections when all three Cluebase values are supplied;
+  existing `.env*` files are never modified
 
 A frontend-only project (single-page app plus serverless/static hosting, with no
 detectable backend) is a supported setup path and continues as a frontend SDK
@@ -85,8 +86,8 @@ local customer frontend/backend.
 
 `npx -y @genn-inc/cluebase-cli setup` reads the Cluebase API base URL, project key, and API
 key from setup screen flags, detects local services, writes
-`.cluebase/setup-manifest.json`, and points runtime env setup to the Cluebase setup
-screen Step 2.
+`.cluebase/setup-manifest.json`, and writes the same values to the root
+`.env.cluebase`. The file is a setup artifact and is automatically added to `.gitignore`.
 
 ## Required Environment
 
@@ -94,6 +95,11 @@ screen Step 2.
 - `CLUEBASE_PROJECT_KEY`: Cluebase setup screen issues this value.
 - `CLUEBASE_API_BASE_URL`: Cluebase API base URL shown by the setup screen.
 
+`.env.cluebase` stores `CLUEBASE_INGEST_ENDPOINT`, `CLUEBASE_PROJECT_KEY`, and
+`CLUEBASE_API_KEY` under `[app]`; framework-prefixed public values under `[frontend]`;
+and generic public values under `[frontend_user]`. The API key must never be copied into
+either frontend section.
+
 ## Boundaries
 
 - The tool may read allowed source paths in the client repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genn-inc/cluebase-cli",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "bin": {
     "cluebase-ai": "bin/cluebase-cli.mjs"

package/src/cli-command.mjs

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
@@ -85,6 +85,7 @@ const CLUEBASE_ARTIFACT_GITIGNORE_ENTRIES = [
 	".cluebase/setup-diff.patch",
 	".cluebase/setup-review-findings.md",
 	".cluebase/secrets.json",
+	".env.cluebase",
 ];
 
 const protectCluebaseArtifacts = async ({ repoRoot }) => {
@@ -102,26 +103,6 @@ const protectCluebaseArtifacts = async ({ repoRoot }) => {
 	return results;
 };
 
-const SECRETS_FILE_PATH = ".cluebase/secrets.json";
-
-const writeSecretsFile = async ({ repoRoot, apiKey }) => {
-	if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
-		return { status: "skipped", reason: "no_api_key_provided" };
-	}
-	const absolutePath = resolve(repoRoot, SECRETS_FILE_PATH);
-	const body = {
-		cluebase_api_key: apiKey.trim(),
-		_warning:
-			"DO NOT COMMIT. This file contains the Cluebase API key. The Cluebase setup CLI auto-adds `.cluebase/secrets.json` to .gitignore — keep it that way.",
-	};
-	await mkdir(dirname(absolutePath), { recursive: true });
-	await writeFile(absolutePath, `${JSON.stringify(body, null, 2)}\n`, {
-		encoding: "utf8",
-		mode: 0o600,
-	});
-	return { status: "written", path: SECRETS_FILE_PATH };
-};
-
 const usage = () =>
 	[
 		"Cluebase CLI:",
@@ -141,7 +122,7 @@ const usage = () =>
 	].join("\n");
 
 const renderEnvironmentInstructions = (instructions) => {
-	if (!instructions || instructions.status !== "deferred_to_setup_wizard") {
+	if (!instructions || instructions.status !== "written_to_cluebase_env") {
 		return "";
 	}
 	const services = Array.isArray(instructions.detected_services)
@@ -154,8 +135,9 @@ const renderEnvironmentInstructions = (instructions) => {
 	});
 	const lines = [
 		"",
-		"環境変数の設定は setup 画面の Step2 を見て行ってください。",
-		"(CLI 側では .env.cluebase ファイルは生成しません。setup 画面に必要な値が表示されます)",
+		`環境変数を ${instructions.path} に保存しました。`,
+		"[app] はサーバー用、[frontend] はframework用、[frontend_user] は公開値の確認用です。",
+		"API key は [app] のみに保存しています。既存の .env / .env.local は変更していません。",
 		"",
 		"検出したサービス:",
 		...(serviceLines.length > 0 ? serviceLines : ["  (なし)"]),
@@ -167,20 +149,35 @@ const renderEnvironmentInstructions = (instructions) => {
 const renderSetupResult = ({ preparation }) => {
 	if (preparation?.status === "ready_for_ai") {
 		const manifestPath =
-			preparation.artifacts?.setup_manifest_path ??
-			".cluebase/setup-manifest.json";
-		return [
-			"Cluebase セットアップの準備が完了しました。",
-			"",
-			"作成したファイル:",
-			`- ${manifestPath}`,
-			"",
-			"次にやること:",
-			"1. Claude Code を使う場合: `claude` を起動し、`/cluebase-discover` -> `/cluebase-discover-review` -> `/cluebase-discover-context` -> `/cluebase-discover-check` -> `/cluebase-implement` -> `/cluebase-implement-check` -> `/cluebase-implement-review` -> `/cluebase-doctor` の順に実行してください。",
-			"2. Codex を使う場合: `codex` を起動し、`$cluebase-discover` -> `$cluebase-discover-review` -> `$cluebase-discover-context` -> `$cluebase-discover-check` -> `$cluebase-implement` -> `$cluebase-implement-check` -> `$cluebase-implement-review` -> `$cluebase-doctor` の順に実行してください。",
-			"",
-			"環境変数は Step 2 のコマンド (/cluebase-implement) が env ファイルへ自動で書き込みます。手動設定は通常不要です（自動書込が動かなかった場合のみ、setup 画面の env セクションに表示された値をコピーしてください）。",
-		].join("\n");
+				preparation.artifacts?.setup_manifest_path ??
+				".cluebase/setup-manifest.json";
+			const environmentFilePath =
+				preparation.environment_instructions?.status ===
+				"written_to_cluebase_env"
+					? preparation.environment_instructions.path ??
+						preparation.artifacts?.environment_file_path ??
+						".env.cluebase"
+					: null;
+			const missingEnvironmentFlags = Array.isArray(
+				preparation.environment_instructions?.required_flags,
+			)
+				? preparation.environment_instructions.required_flags.join(", ")
+				: "--cluebase-api-key, --cluebase-api-base-url, --project-key";
+			return [
+				"Cluebase セットアップの準備が完了しました。",
+				"",
+				"作成したファイル:",
+				`- ${manifestPath}`,
+				...(environmentFilePath ? [`- ${environmentFilePath}`] : []),
+				"",
+				"次にやること:",
+				"1. Claude Code を使う場合: `claude` を起動し、`/cluebase-discover` -> `/cluebase-discover-review` -> `/cluebase-discover-context` -> `/cluebase-discover-check` -> `/cluebase-implement` -> `/cluebase-implement-check` -> `/cluebase-implement-review` -> `/cluebase-doctor` の順に実行してください。",
+				"2. Codex を使う場合: `codex` を起動し、`$cluebase-discover` -> `$cluebase-discover-review` -> `$cluebase-discover-context` -> `$cluebase-discover-check` -> `$cluebase-implement` -> `$cluebase-implement-check` -> `$cluebase-implement-review` -> `$cluebase-doctor` の順に実行してください。",
+				"",
+				environmentFilePath
+					? `環境変数はルートの ${environmentFilePath} に保存済みです。既存の .env / .env.local は変更していません。`
+					: `環境変数は未作成です。${missingEnvironmentFlags} を指定して再実行してください。`,
+			].join("\n");
 	}
 
 	const blockers = Array.isArray(preparation?.blockers)
@@ -312,6 +309,9 @@ export const runCli = async (argv, io = defaultIo) => {
 			repoRoot,
 			documentsUrl: flags.get("documents-url"),
 		});
+		const cluebaseArtifactProtection = await protectCluebaseArtifacts({
+			repoRoot,
+		});
 		const preparation = flags.has("skills-only")
 			? {
 					status: "skipped",
@@ -326,15 +326,7 @@ export const runCli = async (argv, io = defaultIo) => {
 						projectKey: flags.get("project-key"),
 					},
 				});
-		const cluebaseArtifactProtection = await protectCluebaseArtifacts({
-			repoRoot,
-		});
 		preparation.cluebase_artifact_protection = cluebaseArtifactProtection;
-		const secretsProtection = await writeSecretsFile({
-			repoRoot,
-			apiKey: flags.get("cluebase-api-key"),
-		});
-		preparation.secrets_protection = secretsProtection;
 		const environmentInstructions = renderEnvironmentInstructions(
 			preparation.environment_instructions,
 		);

package/src/cluebase-env-file.mjs

@@ -0,0 +1,177 @@
+import { chmod, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export const CLUEBASE_ENV_FILE_PATH = ".env.cluebase";
+export const CLUEBASE_ENV_SECTIONS = Object.freeze([
+  "app",
+  "frontend",
+  "frontend_user",
+]);
+
+export const FRONTEND_PUBLIC_ENV_NAMES = Object.freeze([
+  "CLUEBASE_API_BASE_URL",
+  "CLUEBASE_PROJECT_KEY",
+]);
+
+export const FRONTEND_PUBLIC_ENV_PREFIX_BY_FRAMEWORK = new Map([
+  ["nextjs", "NEXT_PUBLIC_"],
+  ["vite", "VITE_"],
+  ["vue", "VITE_"],
+  ["react", "REACT_APP_"],
+  ["sveltekit", "PUBLIC_"],
+  ["nuxt", "NUXT_PUBLIC_"],
+]);
+
+const ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SECTION_PATTERN = /^\[([a-z_]+)\]$/;
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+const formatEnvValue = (value) => {
+  const normalized = optionalString(value);
+  if (normalized === null) return null;
+  if (/[\r\n]/.test(normalized)) {
+    throw new Error(".env.cluebase values must not contain newlines");
+  }
+  return JSON.stringify(normalized);
+};
+
+const envLine = (name, value) => {
+  if (!ENV_NAME_PATTERN.test(name)) {
+    throw new Error(`invalid .env.cluebase key: ${name}`);
+  }
+  const formatted = formatEnvValue(value);
+  return formatted === null ? null : `${name}=${formatted}`;
+};
+
+const section = (name, entries) => {
+  const lines = [`[${name}]`];
+  for (const [key, value] of entries) {
+    const line = envLine(key, value);
+    if (line) lines.push(line);
+  }
+  if (lines.length === 1) lines.push("# no values");
+  return lines.join("\n");
+};
+
+const frontendEnvName = ({ framework, name }) => {
+  const prefix = FRONTEND_PUBLIC_ENV_PREFIX_BY_FRAMEWORK.get(
+    String(framework ?? "").toLowerCase(),
+  );
+  return prefix === undefined ? null : `${prefix}${name}`;
+};
+
+export const buildCluebaseEnvFile = ({
+  cluebaseApiBaseUrl,
+  cluebaseApiKey,
+  detectedServices = [],
+  projectKey,
+}) => {
+  const apiBaseUrlValue = optionalString(cluebaseApiBaseUrl);
+  const apiBaseUrl = apiBaseUrlValue
+    ? trimTrailingSlash(apiBaseUrlValue)
+    : null;
+  const normalizedProjectKey = optionalString(projectKey);
+  const ingestEndpoint = apiBaseUrl
+    ? `${trimTrailingSlash(apiBaseUrl)}/api/v1/ingest/backend`
+    : null;
+  const frontendServices = Array.isArray(detectedServices)
+    ? detectedServices.filter((service) => service?.kind === "frontend")
+    : [];
+  const frontendEntries = [];
+  for (const service of frontendServices) {
+    for (const name of FRONTEND_PUBLIC_ENV_NAMES) {
+      const prefixedName = frontendEnvName({
+        framework: service.framework,
+        name,
+      });
+      if (prefixedName) {
+        frontendEntries.push([
+          prefixedName,
+          name === "CLUEBASE_API_BASE_URL" ? apiBaseUrl : normalizedProjectKey,
+        ]);
+      }
+    }
+  }
+  const uniqueFrontendEntries = [
+    ...new Map(frontendEntries.map(([key, value]) => [key, value])).entries(),
+  ];
+
+  return [
+    section("app", [
+      ["CLUEBASE_INGEST_ENDPOINT", ingestEndpoint],
+      ["CLUEBASE_PROJECT_KEY", normalizedProjectKey],
+      ["CLUEBASE_API_KEY", cluebaseApiKey],
+    ]),
+    section("frontend", uniqueFrontendEntries),
+    section("frontend_user", [
+      ["CLUEBASE_API_BASE_URL", apiBaseUrl],
+      ["CLUEBASE_PROJECT_KEY", normalizedProjectKey],
+    ]),
+  ].join("\n\n") + "\n";
+};
+
+const unquoteValue = (value) => {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const quote = trimmed[0];
+  if ((quote !== "'" && quote !== '"') || trimmed.at(-1) !== quote) {
+    return trimmed;
+  }
+  const inner = trimmed.slice(1, -1);
+  if (quote === "'") return inner;
+  return inner
+    .replace(/\\n/g, "\n")
+    .replace(/\\r/g, "\r")
+    .replace(/\\t/g, "\t")
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, "\\");
+};
+
+export const parseCluebaseEnvFile = (content) => {
+  const sections = Object.fromEntries(
+    CLUEBASE_ENV_SECTIONS.map((name) => [name, {}]),
+  );
+  let currentSection = null;
+  for (const rawLine of String(content).split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const sectionMatch = SECTION_PATTERN.exec(line);
+    if (sectionMatch) {
+      currentSection = CLUEBASE_ENV_SECTIONS.includes(sectionMatch[1])
+        ? sectionMatch[1]
+        : null;
+      continue;
+    }
+    if (!currentSection) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (match) sections[currentSection][match[1]] = unquoteValue(match[2]);
+  }
+  return sections;
+};
+
+export const writeCluebaseEnvFile = async ({
+  repoRoot,
+  cluebaseApiBaseUrl,
+  cluebaseApiKey,
+  detectedServices,
+  projectKey,
+}) => {
+  const absolutePath = resolve(repoRoot, CLUEBASE_ENV_FILE_PATH);
+  const content = buildCluebaseEnvFile({
+    cluebaseApiBaseUrl,
+    cluebaseApiKey,
+    detectedServices,
+    projectKey,
+  });
+  await writeFile(absolutePath, content, { encoding: "utf8", mode: 0o600 });
+  await chmod(absolutePath, 0o600);
+  return {
+    status: "written",
+    path: CLUEBASE_ENV_FILE_PATH,
+    sections: [...CLUEBASE_ENV_SECTIONS],
+  };
+};

package/src/code-evidence-analyzer.mjs

@@ -16,6 +16,7 @@ import {
 	SOURCE_EXTENSIONS,
 	sourceMatchesBackendInit,
 } from "./setup-check-constants.mjs";
+import { RECOMMENDED_BACKEND_SDK_VERSION } from "./generated-sdk-version-contract.mjs";
 
 const HTTP_METHODS = new Set(CODE_EVIDENCE_ROUTE_METHODS);
 const [DATA_READ, DATA_CREATE, DATA_UPDATE, DATA_DELETE, DATA_UNKNOWN] =
@@ -946,7 +947,7 @@ const packageRepairFile = ({
 			? { ...packageManifest[targetField] }
 			: {};
 	dependencies[sdkPackageName] = sdkPackageName.startsWith("@")
-		? "latest"
+		? RECOMMENDED_BACKEND_SDK_VERSION
 		: sdkPackageName;
 	return {
 		path: packageManifestPath,

package/src/path-policy.mjs

@@ -47,7 +47,7 @@ export const listAllowedSourceFiles = async ({
     }
 		const currentStat = await lstat(absolutePath);
 		if (currentStat.isSymbolicLink()) {
-			throw new Error(`symbolic links are not allowed in source paths: ${relativePath}`);
+			return;
 		}
     if (currentStat.isDirectory()) {
       const entries = await readdir(absolutePath);

package/src/setup-ai-contract.mjs

@@ -6,6 +6,10 @@ export const SETUP_DOCTRINE = {
     "Cluebase setup installs an external SDK integration so observed product facts can reach Cluebase's Customer Value Understanding Engine. It is not an opportunity to improve, refactor, redesign, or reinterpret the host application.",
   minimal_diff_reason:
     "The customer must be able to review and merge the setup diff with confidence. Extra formatting, refactors, auth rewrites, UI changes, or unrelated cleanup make the integration harder to trust.",
+  allowed_change_scope:
+    "Only files and lines required for Cluebase SDK dependency wiring, lifecycle calls, Cluebase environment loading, and setup verification may change.",
+  forbidden_change_scope:
+    "Do not fix pre-existing defects, move unrelated code, reformat files, rewrite host authentication or API behavior, or add files that are not required for the Cluebase setup path.",
   ai_decision_boundary:
     "The AI should use repository understanding only to choose existing lifecycle boundaries for cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset.",
   deterministic_control_boundary:
@@ -207,6 +211,8 @@ export const OFFICIAL_SDK_CONTRACT = {
 export const setupDoctrineSkillLines = () => [
   `- Purpose: ${SETUP_DOCTRINE.purpose}`,
   `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
+  `- Allowed change scope: ${SETUP_DOCTRINE.allowed_change_scope}`,
+  `- Forbidden change scope: ${SETUP_DOCTRINE.forbidden_change_scope}`,
   `- AI decision boundary: ${SETUP_DOCTRINE.ai_decision_boundary}`,
   `- Static control boundary: ${SETUP_DOCTRINE.deterministic_control_boundary}`,
   `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,

package/src/setup-discover-check.mjs

@@ -553,7 +553,7 @@ const validateSecretsGitignore = async ({ repoRoot }) => {
   return errors;
 };
 
-const buildWarnings = (discoveries, { repoRoot } = {}) => {
+const buildWarnings = (discoveries) => {
   if (!isPlainObject(discoveries)) return [];
   const warnings = [];
   if (
@@ -619,19 +619,7 @@ const buildWarnings = (discoveries, { repoRoot } = {}) => {
       message: `STEP 3 context outputs are missing: ${missingFields.join(", ")}. /cluebase-implement will hard stop without them — re-run /cluebase-discover so it can resume from step3_context.`,
     });
   }
-  // SECRETS_FILE_MISSING: STEP 5 が CLUEBASE_API_KEY を env file に auto-write
-  // するための値の source (= `.cluebase/secrets.json`) が無い場合。
-  if (repoRoot) {
-    const secretsPath = resolve(repoRoot, ".cluebase/secrets.json");
-    if (!existsSync(secretsPath)) {
-      warnings.push({
-        code: "SECRETS_FILE_MISSING",
-        message:
-          ".cluebase/secrets.json was not generated. STEP 5 will not auto-write CLUEBASE_API_KEY into the backend env file. Re-run `npx -y @genn-inc/cluebase-cli setup ... --cluebase-api-key <key>` with the value from the setup screen, or set CLUEBASE_API_KEY manually in the backend env file.",
-      });
-    }
-  }
-  return warnings;
+ return warnings;
 };
 
 const pickExitCode = (errors) => {
@@ -667,7 +655,7 @@ export const validateDiscoveries = async ({
     errors.push(...validateNoDuplicates(discoveries));
     errors.push(...(await validateSecretsGitignore({ repoRoot })));
   }
-  const warnings = buildWarnings(discoveries, { repoRoot });
+  const warnings = buildWarnings(discoveries);
   const passed = errors.length === 0;
   return {
     passed,

package/src/setup-doctor-env.mjs

@@ -1,12 +1,16 @@
 // setup-doctor env / URL / dotenv helpers.
-// Extracted from setup-doctor for file-size limits; content is unchanged.
+// setup-doctor の正規化された .env.cluebase 読み込みをここで一元管理する。
 
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
 import {
   readSetupDoctorFile,
   readSetupDoctorJson,
 } from "./setup-doctor-file-boundary.mjs";
+import {
+  CLUEBASE_ENV_FILE_PATH,
+  parseCluebaseEnvFile,
+} from "./cluebase-env-file.mjs";
 
 export const DEFAULT_SETUP_MANIFEST_PATH = ".cluebase/setup-manifest.json";
 export const CLUEBASE_BROWSER_TOKEN_PATH =
@@ -18,12 +22,7 @@ export const CLUEBASE_TEST_SETUP_SDK_VERSION = "cluebase_test_setup";
 export const FRONTEND_SOURCE_IDENTIFIER = "frontend";
 export const DEFAULT_BATCH_VISIBILITY_TIMEOUT_MS = 60_000;
 export const BATCH_VISIBILITY_POLL_INTERVAL_MS = 500;
-export const DOCTOR_ENV_FILE_NAMES = [
-  ".env",
-  ".env.development",
-  ".env.local",
-  ".env.development.local",
-];
+export const DOCTOR_ENV_FILE_NAMES = [CLUEBASE_ENV_FILE_PATH];
 
 // Frontend SDK calls Cluebase backend directly. Customer backends must not expose
 // Cluebase-specific route handlers.
@@ -96,14 +95,16 @@ export const publicCluebaseApiBaseUrl = (env) =>
   optionalString(env.VITE_CLUEBASE_API_BASE_URL) ??
   optionalString(env.REACT_APP_CLUEBASE_API_BASE_URL) ??
   optionalString(env.PUBLIC_CLUEBASE_API_BASE_URL) ??
-  optionalString(env.NUXT_PUBLIC_CLUEBASE_API_BASE_URL);
+  optionalString(env.NUXT_PUBLIC_CLUEBASE_API_BASE_URL) ??
+  optionalString(env.CLUEBASE_API_BASE_URL);
 
 export const publicProjectKeyFromEnv = (env) =>
   optionalString(env.NEXT_PUBLIC_CLUEBASE_PROJECT_KEY) ??
   optionalString(env.VITE_CLUEBASE_PROJECT_KEY) ??
   optionalString(env.REACT_APP_CLUEBASE_PROJECT_KEY) ??
   optionalString(env.PUBLIC_CLUEBASE_PROJECT_KEY) ??
-  optionalString(env.NUXT_PUBLIC_CLUEBASE_PROJECT_KEY);
+  optionalString(env.NUXT_PUBLIC_CLUEBASE_PROJECT_KEY) ??
+  optionalString(env.CLUEBASE_PROJECT_KEY);
 
 export const cluebaseApiBaseUrlFromIngestEndpoint = (endpoint) => {
   const raw = optionalString(endpoint);
@@ -252,22 +253,7 @@ export const envRootsFromManifest = (manifest, kind) => {
 };
 
 export const envFileCandidates = ({ discoveries, kind, manifest, repoRoot }) => {
-  const candidates = new Set();
-  if (isPlainObject(discoveries?.env_files)) {
-    const entry = discoveries.env_files[kind];
-    if (isPlainObject(entry)) {
-      addEnvCandidate({ candidates, path: entry.path, repoRoot });
-    }
-  }
-  for (const name of DOCTOR_ENV_FILE_NAMES) {
-    addEnvCandidate({ candidates, path: name, repoRoot });
-  }
-  for (const root of envRootsFromManifest(manifest, kind)) {
-    for (const name of DOCTOR_ENV_FILE_NAMES) {
-      addEnvCandidate({ candidates, path: join(root, name), repoRoot });
-    }
-  }
-  return [...candidates];
+  return [CLUEBASE_ENV_FILE_PATH];
 };
 
 export const loadDoctorEnvFiles = async ({
@@ -292,7 +278,13 @@ export const loadDoctorEnvFiles = async ({
       optional: true,
     });
     if (content === null) continue;
-    Object.assign(fileEnv, parseDotenv(content));
+    const sections = parseCluebaseEnvFile(content);
+    Object.assign(
+      fileEnv,
+      kind === "backend"
+        ? sections.app
+        : { ...sections.frontend_user, ...sections.frontend },
+    );
     loadedFiles.push(relPath);
   }
   return { env: fileEnv, loadedFiles };

package/src/setup-doctor-probe.mjs

@@ -596,6 +596,10 @@ export const buildBackendEventPayload = ({
   };
   const resource = {
     "service.name": backendServiceKey,
+    "cluebase.project_key": projectKey,
+    "cluebase.runtime_language": "nodejs",
+    "cluebase.service_type": "backend",
+    "cluebase.producer_id": backendServiceKey,
     "telemetry.sdk.language": "nodejs",
     "service.version": CLUEBASE_TEST_SETUP_SDK_VERSION,
   };

package/src/setup-doctor-quality.mjs

@@ -40,7 +40,7 @@ import {
   checkC7,
   checkC8,
 } from "./setup-doctor-quality-checks-b.mjs";
-import { isPlainObject, isString } from "./setup-doctor-quality-shared.mjs";
+import { CLUEBASE_ENV_FILE_PATH } from "./cluebase-env-file.mjs";
 import {
   readSetupDoctorFile,
   readSetupDoctorJson,
@@ -163,7 +163,7 @@ export const loadQualityInputs = async ({ repoRoot = ".", signal } = {}) => {
     "package.json",
     signal,
   );
-  const envFiles = await readEnvFiles({ repoRoot, discoveries, signal });
+  const envFiles = await readEnvFiles({ repoRoot, signal });
   return { discoveries, packageJson, envFiles };
 };
 
@@ -171,39 +171,16 @@ const readJsonIfExists = async (repoRoot, path, signal) => {
   return readSetupDoctorJson({ repoRoot, path, signal, optional: true });
 };
 
-const COMMON_ENV_FILE_NAMES = [
-  ".env",
-  ".env.local",
-  ".env.development",
-  ".env.production",
-];
-
-const readEnvFiles = async ({ repoRoot, discoveries, signal }) => {
+const readEnvFiles = async ({ repoRoot, signal }) => {
   const result = {};
-  const candidates = new Set();
-  // discoveries.env_files から
-  if (isPlainObject(discoveries) && isPlainObject(discoveries.env_files)) {
-    for (const kind of ["frontend", "backend"]) {
-      const entry = discoveries.env_files[kind];
-      if (isPlainObject(entry) && isString(entry.path)) {
-        candidates.add(entry.path);
-      }
-    }
-  }
-  // よくある場所
-  for (const name of COMMON_ENV_FILE_NAMES) {
-    candidates.add(name);
-  }
-  for (const candidate of candidates) {
-    const content = await readSetupDoctorFile({
-      repoRoot,
-      path: candidate,
-      signal,
-      optional: true,
-    });
-    if (content !== null) {
-      result[candidate] = content;
-    }
+  const content = await readSetupDoctorFile({
+    repoRoot,
+    path: CLUEBASE_ENV_FILE_PATH,
+    signal,
+    optional: true,
+  });
+  if (content !== null) {
+    result[CLUEBASE_ENV_FILE_PATH] = content;
   }
   return result;
 };

package/src/setup-prepare.mjs

@@ -11,26 +11,17 @@ import {
 } from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 import { discoverSetupRepository } from "./setup-repository-discovery.mjs";
+import {
+  CLUEBASE_ENV_FILE_PATH,
+  FRONTEND_PUBLIC_ENV_NAMES,
+  FRONTEND_PUBLIC_ENV_PREFIX_BY_FRAMEWORK,
+  writeCluebaseEnvFile,
+} from "./cluebase-env-file.mjs";
 
 const DEFAULT_SETUP_MANIFEST_PATH = ".cluebase/setup-manifest.json";
 const BROWSER_INGEST_PATH =
   API_CONNECTIVITY_CONTRACT.hops.browser_ingest.path;
 const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
-// setup runtime で各 service が読む env 名一覧。
-// 実際の値の提示は setup 画面 (web app の setup wizard) が担当する。
-// CLI はサービス検出と manifest 出力のみを担う。
-const FRONTEND_PUBLIC_ENV_NAMES = [
-  "CLUEBASE_API_BASE_URL",
-  "CLUEBASE_PROJECT_KEY",
-];
-const FRONTEND_PUBLIC_ENV_PREFIX_BY_FRAMEWORK = new Map([
-  ["nextjs", "NEXT_PUBLIC_"],
-  ["vite", "VITE_"],
-  ["vue", "VITE_"],
-  ["react", "REACT_APP_"],
-  ["sveltekit", "PUBLIC_"],
-  ["nuxt", "NUXT_PUBLIC_"],
-]);
 const BACKEND_RUNTIME_ENV_NAMES = [
   "CLUEBASE_PROJECT_KEY",
   "CLUEBASE_INGEST_ENDPOINT",
@@ -108,11 +99,11 @@ const requiredFrontendEnvNames = (detectedServices) => [
 
 const requiredBackendEnvNames = () => [...BACKEND_RUNTIME_ENV_NAMES];
 
-// 環境変数は CLI 側で .env.cluebase ファイルを生成せず、setup 画面 (web app の setup wizard)
-// に表示・誘導を任せる方針。 CLI はサービス検出結果と manifest 出力だけを担う。
-// この関数は CLI が detect した service 一覧と「Step 2 は setup 画面で行ってください」
-// という deferred 状態を返すのみ。
-const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
+const buildEnvironmentInstructions = ({
+  environmentFile,
+  manifest,
+  setupContext,
+}) => {
   const missingFlags = [
     ["cluebase_api_key", "--cluebase-api-key"],
     ["cluebase_api_base_url", "--cluebase-api-base-url"],
@@ -134,9 +125,11 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
     ? manifest.detected_services
     : [];
   return {
-    status: "deferred_to_setup_wizard",
+    status: "written_to_cluebase_env",
     message:
-      "環境変数は setup 画面の Step 2 を見て、各サービスの env ファイルに反映してください。",
+      `Cluebase の環境変数をルートの ${CLUEBASE_ENV_FILE_PATH} に保存しました。既存の .env / .env.local は変更していません。`,
+    path: environmentFile?.path ?? CLUEBASE_ENV_FILE_PATH,
+    sections: environmentFile?.sections ?? ["app", "frontend", "frontend_user"],
     detected_services: detectedServices.map((target) => ({
       kind: target.kind,
       framework: target.framework,
@@ -146,14 +139,7 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
 };
 
 const summarizeEnvironmentInstructions = (instructions) => {
-  if (!instructions || instructions.status !== "deferred_to_setup_wizard") {
-    return instructions;
-  }
-  return {
-    status: "deferred_to_setup_wizard",
-    message: instructions.message,
-    detected_services: instructions.detected_services,
-  };
+  return instructions;
 };
 
 export const runSetupPrepare = async ({
@@ -272,9 +258,10 @@ export const runSetupPrepare = async ({
     },
     artifacts: {
       setup_manifest_path: setupManifestPath,
+      environment_file_path: CLUEBASE_ENV_FILE_PATH,
     },
-    machine_owned_artifacts: [setupManifestPath],
-    ai_must_not_edit: [],
+    machine_owned_artifacts: [setupManifestPath, CLUEBASE_ENV_FILE_PATH],
+    ai_must_not_edit: [CLUEBASE_ENV_FILE_PATH],
     ai_owned_workstreams: ["sdk_lifecycle_placement"],
     ai_implementation_scope: {
       rule: "AI implementation is limited to placing cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset in existing lifecycle boundaries plus the minimal SDK wiring required for those calls.",
@@ -342,7 +329,20 @@ export const runSetupPrepare = async ({
       backend_runtime: backendRuntimeEnvNames,
     },
   };
+  const environmentFile =
+    setupContext.cluebase_api_key &&
+    setupContext.cluebase_api_base_url &&
+    setupContext.project_key
+      ? await writeCluebaseEnvFile({
+          repoRoot: resolvedRepoRoot,
+          cluebaseApiBaseUrl: setupContext.cluebase_api_base_url,
+          cluebaseApiKey: setupContext.cluebase_api_key,
+          detectedServices,
+          projectKey: setupContext.project_key,
+        })
+      : null;
   const environmentInstructions = buildEnvironmentInstructions({
+    environmentFile,
     manifest,
     setupContext,
   });

package/src/setup-step-builders-discover.mjs

@@ -105,27 +105,15 @@ Steps:
    - Discriminator skip: \`status !== "success"\`, \`result.kind === "error"\`, \`type !== "real"\`.
    The lifecycle call must NEVER fire with the filtered value. Pick the line of the next concrete side-effect after the guard (typical examples: \`router.push\`, \`router.refresh\`, \`navigate(\`, \`await api.(post|put|delete|patch)\`, \`db.commit\`, \`return response\`, \`dispatch(success)\`, \`emit("success", ...)\`).
 
-4.5. ENV FILE PATH DISCOVER. STEP 5 (= /cluebase-implement) needs to auto-write CLUEBASE_* env vars into the customer's frontend and backend env files. Discover those file paths NOW so STEP 5 has the addresses to write into.
+4.5. ENV CONFIGURATION BOUNDARY. The CLI has already written the single Cluebase
+   environment source at the repository root: \`.env.cluebase\`. Do not search for,
+   create, edit, or record any customer \`.env\`, \`.env.local\`, or other service-local
+   environment file. Do not copy values into another file. The sections are fixed:
+   \`[app]\` for server-only values, \`[frontend]\` for framework-prefixed public values,
+   and \`[frontend_user]\` for the generic public values a user can inspect.
 
-   For each \`detected_services\` entry in \`.cluebase/setup-manifest.json\` (recall: each entry has \`kind\` = "frontend" or "backend", plus \`root_path\` = that service's directory relative to the repo root):
-
-   (a) Frontend env file: probe these candidates in order via Read / Glob and pick the FIRST one that exists:
-       1. \`<root_path>/.env.local\`     (= Next.js / Vite convention for local dev env)
-       2. \`<root_path>/.env.development\`
-       3. \`<root_path>/.env\`
-       If none exists, default to \`<root_path>/.env.local\` and treat it as a new file that STEP 5 will create. Record this as \`env_files.frontend = { "path": "<rel path>", "format": "dotenv" }\`. If \`detected_services\` has no \`kind="frontend"\` entry (= no frontend service), set \`env_files.frontend = null\`.
-
-   (b) Backend env file: probe candidates in order:
-       1. \`<root_path>/.env\`
-       2. \`<root_path>/.env.development\`
-       If neither exists, default to \`<root_path>/.env\` as a new file. Record \`env_files.backend = { "path": "<rel path>", "format": "dotenv" }\`. If no backend service is detected, set \`env_files.backend = null\`.
-
-   (c) Validate paths:
-       * Path MUST be relative to the repo root (no absolute paths).
-       * Path MUST live inside the repo (no \`..\` escape).
-       * If a probed path is outside the repo or unreachable, add an entry to \`unclear_points\` describing the issue and set \`env_files.<kind> = null\`.
-
-   Output the result on the new top-level \`env_files\` field (see "Output JSON schema" below).
+   If \`.env.cluebase\` is absent, record one \`unclear_points\` entry asking the user
+   to re-run \`npx -y @genn-inc/cluebase-cli setup\` with the three Cluebase values.
 
 5. COMPLETENESS SELF-CHECK (mandatory — answer each item internally; any "no" / "未確認" means you MUST loop back to Phase A or B before writing the artifact):
 
@@ -274,10 +262,6 @@ Output JSON schema (output exactly this shape; arrays may be empty []):
   "mastra_sites":      [ { "file": "<rel path>", "line": <int>, "mastra_variable_name": "<identifier>", "evidence": "<1-line snippet>" }, ... ],
   "existing_cluebase_calls": [ { "api": "cluebase.init|cluebase.identify|cluebase.group|cluebase.reset", "file": "<rel path>", "line": <int> }, ... ],
   "unclear_points":    [ { "concern": "<short>", "files_or_areas": ["<path or pattern>"] }, ... ],
-  "env_files": {
-    "frontend": { "path": "<rel path to frontend env file, e.g. 'frontend/.env.local'>", "format": "dotenv" } | null,
-    "backend":  { "path": "<rel path to backend env file, e.g. 'backend/.env'>", "format": "dotenv" } | null
-  },
   "db_schema": {
     "detection_notes": "<1-3 sentence summary of which schema sources were inspected (e.g. 'Prisma schema.prisma at root + raw SQL migrations in db/migrations; user/account/workspace entities identified.')>",
     "entities": [
@@ -530,44 +514,7 @@ Steps:
 
    f. Be CONSERVATIVE. When a candidate path is uncertain (e.g. the variable might be undefined at the insertion line, or comes from a guard branch that may not be entered), record it as \`null\` with a note explaining the uncertainty — do NOT invent a fake path. STEP 5 will pass null / \`None\` and degrade gracefully.
 
-3.5. ENV LINES CALCULATION. STEP 5 (= /cluebase-implement) writes env files. STEP 3 pre-computes EXACTLY what NAME=value lines belong in each env file so STEP 5 is a pure write operation with no judgment.
-
-   (a) Read \`.cluebase/setup-manifest.json\` and extract:
-	       * \`cluebase_context.project_key\` (e.g. \`pk_dev_...\`)
-	       * \`cluebase_context.cluebase_api_base_url\`
-	       * \`cluebase_context.ingest_endpoints.browser\`
-	       * \`cluebase_context.ingest_endpoints.backend\`
-		       * \`detected_services[]\` root paths. The frontend SDK calls the Cluebase backend directly.
-
-   (b) Read \`.cluebase/secrets.json\` and extract \`cluebase_api_key\`. If the file does not exist, skip CLUEBASE_API_KEY in env_lines.backend and add an \`unclear_points\` entry "CLUEBASE_API_KEY is unavailable (.cluebase/secrets.json missing) — STEP 5 will not auto-write it. Re-run setup with --cluebase-api-key.".
-
-   (c) Determine frontend env-var prefix from \`discoveries.framework_frontend\`:
-       * \`nextjs\` → \`NEXT_PUBLIC_\`
-       * \`vite\` / Vite-based React → \`VITE_\`
-       * \`react\` → \`REACT_APP_\`
-       * \`sveltekit\` → \`PUBLIC_\`
-       * \`nuxt\` → \`NUXT_PUBLIC_\`
-       * \`angular\` → leave \`env_lines.frontend\` empty and add an \`unclear_points\` entry instructing the user to copy the setup screen's Angular runtime config values.
-       * \`solid\` / \`qwik\` / \`astro\` / unknown → leave \`env_lines.frontend\` empty and add an \`unclear_points\` entry naming the framework; STEP 5 will then ask the user once for the correct public config shape.
-
-   (d) Build the line set:
-	       \`env_lines.frontend\` (2 entries when prefix is known; the frontend SDK calls Cluebase directly):
-         \`<PREFIX>CLUEBASE_API_BASE_URL=<cluebase_api_base_url>\`
-         \`<PREFIX>CLUEBASE_PROJECT_KEY=<project_key>\`
-
-       \`env_lines.backend\` (3 entries; omit CLUEBASE_API_KEY when secrets.json is absent):
-         \`CLUEBASE_INGEST_ENDPOINT=<ingest_endpoints.backend>\`
-         \`CLUEBASE_PROJECT_KEY=<project_key>\`
-         \`CLUEBASE_API_KEY=<cluebase_api_key from .cluebase/secrets.json>\`
-
-   (e) Hard rules:
-       * NEVER include CLUEBASE_API_KEY (or any other server-only secret) in env_lines.frontend. env_lines.frontend is only for browser-public SDK configuration.
-       * Every line MUST match the pattern \`^[A-Z_][A-Z0-9_]*=...$\`. No comments, no trailing whitespace, no quotes around values.
-       * env_lines.frontend / env_lines.backend may be empty arrays when the corresponding side has no env file or when the prefix is unknown (see (c)).
-
-   Record the result on the new top-level \`env_lines\` field (alongside \`env_files\` recorded by STEP 1).
-
-4. Use the Write tool to overwrite \`.cluebase/discoveries.json\` with the enriched JSON. Preserve all existing top-level keys (\`framework_frontend\`, \`framework_backend\`, \`service_key\`, \`cluebase_init_frontend\`, \`cluebase_init_backend\`, \`identify_sites\`, \`group_sites\`, \`reset_sites\`, \`existing_cluebase_calls\`, \`unclear_points\`, \`env_files\`) and add the new top-level \`organization_context\` + \`env_lines\`, the new per-site \`available_fields\` + \`field_acquisition_notes\` keys, and \`group_owner_kind\` on every \`group_sites\` entry. Output only the \`{\` ... \`}\` object content; nothing else.
+4. Use the Write tool to overwrite \`.cluebase/discoveries.json\` with the enriched JSON. Preserve all existing discovery keys and add the new per-site \`available_fields\` + \`field_acquisition_notes\` keys, \`organization_context\`, and \`group_owner_kind\` on every \`group_sites\` entry. Do not add environment file paths or copied environment values to discoveries.json. Output only the \`{\` ... \`}\` object content; nothing else.
 
 5. Respond with exactly ONE Japanese line and stop. Substitute N (identify_sites length), M (group_sites length), and the chosen organization label:
    \`.cluebase/discoveries.json の context 解析を完了しました（識別 N 件、organization M 件、organization_label = <primary_organization_label>）。次は Claude Code で /cluebase-discover-check と打って STEP 4 を実行してください。\`
@@ -675,11 +622,6 @@ Respond with exactly this Japanese line:
        SUBSTEP_TO_RESTART = step3_context
        REASON = cluebase.identify / cluebase.group に渡す引数情報 (available_fields / organization_context) がまだ記録できていません
 
-   (e) Else if ANY error.message mentions one of: "env_files", "env_lines":
-       NEXT_ACTION = RESUME_FROM_SUBSTEP
-       SUBSTEP_TO_RESTART = step1_discover
-       REASON = env file の path / line 情報が discoveries.json に正しく記録できていません
-
    (f) Otherwise (site shape / file path / duplicate / unclear points など STEP 2 で直すべき問題):
        NEXT_ACTION = RESUME_FROM_SUBSTEP
        SUBSTEP_TO_RESTART = step2_review

package/src/setup-step-builders-implement.mjs

@@ -58,52 +58,20 @@ Steps:
    - Express / NestJS / Fastify / Hono (Node backend): add \`${RECOMMENDED_BACKEND_SDK_PACKAGE_SPEC}\` to package.json. The same package serves all Node backend integrations (Express middleware / LangChain / Mastra / AI observer / MCP observer); do NOT install a separate package per framework.
 4. Run the matching install command via the Bash tool: \`bun.lock\` -> \`bun install\`, \`pnpm-lock.yaml\` -> \`pnpm install\`, \`yarn.lock\` -> \`yarn install\`, \`package-lock.json\` -> \`npm install\`. For Python: \`pip install -r requirements.txt\` (or the uv equivalent if uv is present). A package manifest / lockfile mismatch causes STEP 6's setup-check to fail. If install fails or no manager is detected, STOP and report a blocker.
 
-4.5. ENV FILE AUTO-WRITE (STEP 5 owns env file setup so STEP 9 can pass without manual user copy/paste from the setup screen).
-
-   Goal: write the required CLUEBASE_* env vars into the customer's frontend and backend env files based on values in \`.cluebase/setup-manifest.json\` + \`.cluebase/secrets.json\`.
-
-   4.5.a Read inputs (skip this whole step and continue to step 5 if any required input is missing — tell the user which one):
-      - Use Read tool on \`.cluebase/setup-manifest.json\`. Extract \`cluebase_context.project_key\`, \`cluebase_context.cluebase_api_base_url\`, \`cluebase_context.ingest_endpoints.browser\`, \`cluebase_context.ingest_endpoints.backend\`, plus \`detected_services[]\` root paths.
-      - Use Read tool on \`.cluebase/secrets.json\`. Extract \`cluebase_api_key\`. If the file does not exist, skip the CLUEBASE_API_KEY auto-write and tell the user: "CLUEBASE_API_KEY は .cluebase/secrets.json 不在のため自動書込できません。 setup CLI を --cluebase-api-key 付きで再実行するか、 backend env file に手動で追加してください。"
-
-   4.5.b Determine env file paths:
-      - frontend service root: probe in order \`<root_path>/.env.local\`, \`<root_path>/.env.development\`, \`<root_path>/.env\`. Pick the first that exists. If none exists, default to \`<root_path>/.env.local\` and create it (treat as new file).
-      - backend service root: probe \`<root_path>/.env\`, \`<root_path>/.env.development\`. Default to \`<root_path>/.env\` for new files.
-      - All paths must resolve inside the repo root (no absolute paths leading outside).
-
-   4.5.c Determine the frontend env-var prefix from \`discoveries.framework_frontend\`:
-      - \`nextjs\` → \`NEXT_PUBLIC_\`
-      - \`vite\` or React/Vite stack → \`VITE_\`
-      - \`react\` → \`REACT_APP_\`
-      - \`sveltekit\` → \`PUBLIC_\`
-      - \`nuxt\` → \`NUXT_PUBLIC_\` (verify against \`nuxt.config\` if uncertain)
-      - \`angular\` → skip frontend env auto-write and instruct the user to copy the setup screen's Angular runtime config values.
-      - \`solid\` / \`qwik\` / \`astro\` / unknown → ask the user once in a single Japanese line which public config shape the framework uses, or skip auto-write and instruct manual setup.
-
-   4.5.d Build the env line set:
-	      Frontend (2 lines, every line uses the prefix from 4.5.c — collectively \`<PREFIX>\`; the frontend SDK calls Cluebase directly):
-        \`<PREFIX>CLUEBASE_API_BASE_URL=<cluebase_api_base_url>\`
-        \`<PREFIX>CLUEBASE_PROJECT_KEY=<project_key>\`
-
-      Backend (3 lines, NO prefix; these are server-only env names):
-        \`CLUEBASE_INGEST_ENDPOINT=<ingest_endpoints.backend>\`
-        \`CLUEBASE_PROJECT_KEY=<project_key>\`
-        \`CLUEBASE_API_KEY=<from .cluebase/secrets.json>\`   ← skip this line if secrets.json was absent
-
-      Hard rule: CLUEBASE_API_KEY must NEVER be wired into browser-public frontend SDK configuration. Both are server-side values.
-
-   4.5.e Upsert the lines (use Edit tool with surgical \`old_string\` / \`new_string\` on existing files; use Write tool only when creating a new env file):
-      For each NAME in the line set, scan the existing file for a line matching \`^<NAME>\\s*=\`:
-        * found AND value differs → replace the matched line with the new \`NAME=value\`.
-        * found AND value matches → leave it; do not duplicate.
-        * not found → append \`NAME=value\` to the end (add a leading newline if the file does not already end with one).
-      When creating a new env file: write only the joined env lines + trailing newline. Do not add narrative comments.
-
-   4.5.f Verify post-write state via Read on each env file:
-      - Every required NAME appears exactly once with the expected value.
-      - The browser-public frontend SDK env lines MUST NOT contain \`CLUEBASE_API_KEY=\` or any unprefixed \`CLUEBASE_\` line. If such a line would be used by browser code, remove it from the frontend SDK wiring and re-verify.
-
-   4.5.g Record a short internal summary of what was written (counts only — do NOT echo the secret values themselves) so STEP 7 can review the env state in the next pass.
+4.5. ENV CONFIGURATION CHECK. The CLI owns one root file: \`.env.cluebase\`.
+
+   - Read \`.env.cluebase\` and use its fixed sections: \`[app]\` for server-only
+     values, \`[frontend]\` for framework-prefixed public values, and
+     \`[frontend_user]\` for generic public values.
+   - Do not create, edit, or copy Cluebase values into any \`.env\`,
+     \`.env.local\`, \`.env.development\`, or other service-local environment file.
+   - Do not edit \`.env.cluebase\` in this AI step. The CLI created it with mode
+     0600, and it is a machine-owned setup artifact.
+   - Verify that \`[app]\` contains \`CLUEBASE_INGEST_ENDPOINT\`,
+     \`CLUEBASE_PROJECT_KEY\`, and \`CLUEBASE_API_KEY\`. Verify that
+     \`[frontend]\` contains only the framework-prefixed public base URL and
+     project key. Verify that \`CLUEBASE_API_KEY\` is absent from both frontend
+     sections.
 
 5. SELF-REVIEW PASS (mandatory; up to 3 iterations). Inspect your own changes via \`git diff HEAD\` (Bash tool) and apply the rubric below to your diff. If any P0/P1 issue is found, fix it surgically (Edit tool, or \`git checkout HEAD -- <file>\` + re-apply for reformat noise), then re-inspect. Stop when clean or after 3 iterations. Track the cumulative number of self-corrections.
 
@@ -433,10 +401,10 @@ STEP 5（実装 + 自己レビュー）完了
 cluebase.init / cluebase.identify / cluebase.group / cluebase.reset 挿入数: <counts>
 依存追加: <dependency files>
 install 実行: <command>
-env file 書込: frontend=<frontend-env-path> (lines=<N>), backend=<backend-env-path> (lines=<N>)
+環境設定: ルートの .env.cluebase を確認済み（既存の .env / .env.local は変更していません）
 自己修正: <N> 件
 
-重要: frontend / backend の dev server を一度停止して再起動してください。 env file を書き換えただけでは dev server は新しい env を読み込みません。 再起動後に次の STEP に進んでください。
+重要: 顧客アプリが参照する既存の環境変数ローダーで .env.cluebase の該当sectionを読み込めることを確認してください。新しい環境変数ファイルを追加してはいけません。
 
 次は Claude Code で /cluebase-implement-check と打って STEP 6（静的検証）を実行してください。
 ==========================================
@@ -519,9 +487,8 @@ Process (loop up to 3 iterations; track iteration index N starting at 1 and cumu
 
 P0 rubric (must block release):
 - CLUEBASE_API_KEY wired into browser-public frontend SDK config. If detected, REMOVE that line from the frontend SDK wiring and verify the same key/value remains available to the server runtime.
-- Backend env file is missing any of: \`CLUEBASE_API_KEY\`, \`CLUEBASE_PROJECT_KEY\`, \`CLUEBASE_INGEST_ENDPOINT\`. Auto-fix by reading values from \`.cluebase/setup-manifest.json\` (\`cluebase_context.project_key\` / \`cluebase_context.ingest_endpoints.backend\`) + \`.cluebase/secrets.json\` (\`cluebase_api_key\`) and appending / upserting via Edit. Skip CLUEBASE_API_KEY only if \`.cluebase/secrets.json\` is absent, in which case escalate to residual findings asking the user to re-run setup with --cluebase-api-key.
-- Frontend env file is missing any of the prefixed equivalents of \`CLUEBASE_API_BASE_URL\`, \`CLUEBASE_PROJECT_KEY\` (prefix determined by framework_frontend: \`NEXT_PUBLIC_\` for Next.js, \`VITE_\` for Vite, \`PUBLIC_\` for SvelteKit, etc.). Auto-fix the same way as backend, using \`cluebase_context.cluebase_api_base_url\` for API_BASE_URL. The frontend SDK calls the Cluebase backend directly.
-- \`.cluebase/secrets.json\` exists but is NOT registered in the repo's \`.gitignore\`. Auto-fix by appending \`.cluebase/secrets.json\` to \`.gitignore\` via Edit.
+- Root \`.env.cluebase\` is missing any required value or section. Do not create a second env file and do not edit an existing \`.env*\`; ask the user to re-run the CLI setup so the machine-owned file is regenerated.
+- \`.env.cluebase\` contains \`CLUEBASE_API_KEY\` in \`[frontend]\` or \`[frontend_user]\`. Remove the leaked value from those public sections and re-run the CLI setup; the key may exist only in \`[app]\`.
 - CLUEBASE_API_KEY referenced from any browser/client-bundled file.
 - await on cluebase.init / cluebase.identify / cluebase.group / cluebase.reset in a blocking path.
 - try/catch / try/except / .catch wrapping lifecycle calls solely for Cluebase.
@@ -613,7 +580,7 @@ export function buildStep9SetupDoctor() {
 
 Before running the command, briefly explain to the user (1-2 lines) what this step does:
 
-   STEP 9 は Cluebase の疎通確認です。 Cluebase token 発行 / browser ingest / backend ingest を customer env files から作った SDK-equivalent payload で実際に POST し、downstream batch publish evidence まで検証します。 加えて顧客 backend の \`/api/v1/cluebase/*\` route を blocking error として確認します。実際の顧客 frontend/backend lifecycle 発火は、顧客のローカル画面操作後に Cluebase setup logs または published batch evidence で確認します。
+   STEP 9 は Cluebase の疎通確認です。ルートの \`.env.cluebase\` の \`[frontend]\` / \`[app]\` を読み、Cluebase token 発行 / browser ingest / backend ingest を SDK-equivalent payload で実際に POST し、downstream batch publish evidence まで検証します。加えて顧客 backend の \`/api/v1/cluebase/*\` route を blocking error として確認します。実際の顧客 frontend/backend lifecycle 発火は、顧客のローカル画面操作後に Cluebase setup logs または published batch evidence で確認します。
 
 Then run the following command via the Bash tool:
 
@@ -638,17 +605,17 @@ Respond with exactly:
      • If the local frontend Origin is not available automatically, re-run \`${CLUEBASE_CLI_INVOCATION} setup-doctor --local --client-frontend-url http://localhost:<frontend-port>\`.
 
    Bucket FRONTEND_ENV_MISSING — when check.error mentions "CLUEBASE_API_BASE_URL" or "CLUEBASE_PROJECT_KEY" on the \`browser_ingest\` check.
-     • Required env (set in frontend env file, e.g. \`.env.local\` for Next.js / \`.env\` for Vite, prefix the variable with the framework's public-env prefix):
+     • Required env (set in the \`[frontend]\` section of root \`.env.cluebase\`, using the framework's public-env prefix):
          <frontend public prefix>CLUEBASE_API_BASE_URL=<from setup screen Step 2>
          <frontend public prefix>CLUEBASE_PROJECT_KEY=<from setup screen Step 2>
-     • After writing, RESTART the frontend dev server.
+     • After the existing runtime loader reads \`.env.cluebase\`, RESTART the frontend dev server.
 
    Bucket BACKEND_ENV_MISSING — when check.error mentions "CLUEBASE_API_KEY", "CLUEBASE_INGEST_ENDPOINT", or "CLUEBASE_PROJECT_KEY" on the \`backend_ingest\` check.
-     • Required env (set in backend env file, e.g. \`.env\` for FastAPI / Django / Express):
+     • Required env (set in the \`[app]\` section of root \`.env.cluebase\`):
          CLUEBASE_API_KEY=<from setup screen Step 2>
          CLUEBASE_PROJECT_KEY=<from setup screen Step 2>
          CLUEBASE_INGEST_ENDPOINT=<from setup screen Step 2>
-     • After writing, RESTART the backend dev server.
+     • After the existing runtime loader reads \`.env.cluebase\`, RESTART the backend dev server.
 
    Bucket UPSTREAM_FAILURE — when check.error mentions "browser token" on the \`browser_ingest\` check (= caused by FRONTEND_ENV_MISSING; do not bucket separately).
 
@@ -662,23 +629,21 @@ Respond with exactly:
 
 3. AUTO-FIX (offer once before falling back to manual instructions):
 
-   For each missing env name in FRONTEND_ENV_MISSING / BACKEND_ENV_MISSING buckets, resolve the value:
-     • project key / API base URL / ingest endpoint → use the setup screen Step 2 value already written to the target env file, or the setup artifact value produced from the same screen when the env file is missing the line.
-     • CLUEBASE_API_KEY → use the setup screen Step 2 value already written to the backend env file, or \`.cluebase/secrets.json\` when the backend env file is missing the line. If neither source exists, instruct the user to copy CLUEBASE_API_KEY from the Cluebase setup screen into the backend env file; do NOT proceed to auto-fix CLUEBASE_API_KEY without a source.
+   For each missing env name in FRONTEND_ENV_MISSING / BACKEND_ENV_MISSING buckets, resolve the value from the matching section of root \`.env.cluebase\` or from the original setup arguments. If the value is absent, ask the user to re-run the CLI setup; do not create another env file and do not print the API key.
 
    For each candidate env value that resolves to a concrete string, propose the auto-fix as ONE message to the user in the form:
 
       STEP 9 で env 不足を検出しました。 以下を自動で書き込みますか?
-        frontend env file (<path>): <list of NAME=value lines>
-        backend env file (<path>): <list of NAME=value lines>
-      書き込み後、 frontend / backend dev server を再起動して /cluebase-doctor を再実行してください。
+        .env.cluebase [frontend]: <list of NAME=value keys>
+        .env.cluebase [app]: <list of NAME=value keys>
+      設定後、 frontend / backend dev server を再起動して /cluebase-doctor を再実行してください。
       OK の場合: 「OK」 と返信してください。 NG の場合: 「NG」 と返信してください。
 
    When the user replies "OK":
-     - Use Edit tool to append the lines to the frontend / backend env file (upsert semantics: if a NAME already exists with a different value, replace its value; if NAME does not exist, append a new line).
-     - Use Edit / Bash tool to do nothing else. Do NOT restart the dev server (the user controls dev servers).
+     - Do not use Edit to write any \`.env*\` file. Ask the user to re-run the CLI setup so it owns the update of \`.env.cluebase\`.
+     - Do not edit \`.env.cluebase\` from the AI step and do not restart the dev server.
      - Respond with:
-         env file への書き込みが完了しました。 frontend / backend dev server を再起動してから、 もう一度 /cluebase-doctor を実行してください。 dev server を再起動しないと新 env が反映されません。
+         \`.env.cluebase\` の再生成が必要です。CLI setupを再実行し、frontend / backend dev server を再起動してから、もう一度 /cluebase-doctor を実行してください。
 
    When the user replies "NG" or you could not resolve all values:
      - Skip the auto-fix and fall through to manual instructions (step 4).
@@ -690,12 +655,12 @@ Respond with exactly:
       STEP 9（疎通確認）で問題が見つかりました（checks N_FAILED 件 / passed N_PASSED 件）。 以下を順番に直してください:
 
         [For each non-empty bucket, print one numbered line in this exact form:]
-        <N>. <bucket-specific human-readable instruction in Japanese — e.g. "frontend の env file (.env.local 等) に framework に合う public env 名で CLUEBASE_API_BASE_URL=<setup screen Step 2 の値> を追加し、 frontend dev server を再起動してください">
+        <N>. <bucket-specific human-readable instruction in Japanese — e.g. "CLI setupを再実行して .env.cluebase の [frontend] に framework に合う public env 名を生成し、frontend dev server を再起動してください">
 
-      修正後にもう一度 /cluebase-doctor を実行すると再チェックされます。 setup 画面の Step 2 (環境変数) の値もコピー元として使えます。
+      修正後にもう一度 /cluebase-doctor を実行すると再チェックされます。値が不明な場合は setup 画面の値を使ってCLI setupを再実行してください。
 
 Hard rules:
-- Do not edit \`.cluebase/setup-manifest.json\` or \`.cluebase/secrets.json\` in this STEP — STEP 9 is verification + (optional) env-file auto-fix only.
+- Do not edit \`.cluebase/setup-manifest.json\` or \`.env.cluebase\` in this STEP — STEP 9 is verification only.
 - Never write CLUEBASE_API_KEY into browser-public frontend SDK configuration. The value is only for server runtime and the authenticated Cluebase setup screen.
 - Never restart dev servers from this STEP. Always ask the user to restart manually after auto-fix.
 - TRANSPORT_FAILURE buckets are NOT auto-fixable — instruct the user to start the affected dev server / verify the URL and re-run /cluebase-doctor.

package/src/setup-step-commands.mjs

@@ -6,7 +6,7 @@
 //   - cluebase-discover-review.md   — STEP 2: self-review of STEP 1 output (AI)
 //   - cluebase-discover-context.md  — STEP 3: field-semantic enrichment (AI)
 //   - cluebase-discover-check.md    — STEP 4: bash validation of discoveries.json
-//   - cluebase-implement.md         — STEP 5: SDK call insertion + env file write
+//   - cluebase-implement.md         — STEP 5: SDK call insertion + env config check
 //   - cluebase-implement-check.md   — STEP 6: bash static check + diff snapshot
 //   - cluebase-implement-review.md  — STEP 7: self-review of inserted code (AI)
 //   - cluebase-events.md            — STEP 8: guided business value event track (AI)
@@ -88,7 +88,7 @@ const STEP_FILES = [
     id: "step1_discover",
     title: "STEP 1 — Discover (boundary enumeration)",
     singleGoal:
-      "The ONLY goal of this command is to grep + Read the customer codebase exhaustively and produce the initial `.cluebase/discoveries.json` (lifecycle boundary candidates + db_schema grounding + env file paths). SDK call insertion, env file writes, code changes, and connectivity checks are ALL out of scope.",
+      "The ONLY goal of this command is to grep + Read the customer codebase exhaustively and produce the initial `.cluebase/discoveries.json` (lifecycle boundary candidates + db_schema grounding). SDK call insertion, environment file writes, code changes, and connectivity checks are ALL out of scope.",
     scopeOut: [
       "STEP 2 (= /cluebase-discover-review): self-review / fix of discoveries.json",
       "STEP 3 (= /cluebase-discover-context): field-semantic enrichment (`available_fields` / `organization_context`)",
@@ -96,7 +96,7 @@ const STEP_FILES = [
       "STEP 5+ (= /cluebase-implement and later): any source code change",
     ],
     completion:
-      "`.cluebase/discoveries.json` is written with all boundaries + db_schema + env_files populated, `_progress.completed_substeps` is patched with `step1_discover`, and the Japanese hand-off line for STEP 2 is printed.",
+      "`.cluebase/discoveries.json` is written with all boundaries + db_schema, `_progress.completed_substeps` is patched with `step1_discover`, and the Japanese hand-off line for STEP 2 is printed.",
     nextHandoff: "/cluebase-discover-review",
   },
   {
@@ -125,15 +125,15 @@ const STEP_FILES = [
     id: "step3_context",
     title: "STEP 3 — Field semantic context enrichment",
     singleGoal:
-      "The ONLY goal of this command is to enrich `.cluebase/discoveries.json` with two new pieces: per-site `available_fields` (concrete variable paths reachable at each insertion line) + top-level `organization_context` (the customer's company/organization label) + `env_lines` pre-computed for STEP 5. The customer code is NOT modified.",
+      "The ONLY goal of this command is to enrich `.cluebase/discoveries.json` with per-site `available_fields` (concrete variable paths reachable at each insertion line) and top-level `organization_context` (the customer's company/organization label). The customer code and `.env.cluebase` are NOT modified.",
     scopeOut: [
       "STEP 1 (= /cluebase-discover): boundary discovery",
       "STEP 2 (= /cluebase-discover-review): rubric-based self-review",
       "STEP 4 (= /cluebase-discover-check): bash validation",
-      "STEP 5+ (= /cluebase-implement and later): code edits, env file writes",
+      "STEP 5+ (= /cluebase-implement and later): code edits, `.env.cluebase` handling, and connectivity checks",
     ],
     completion:
-      "`.cluebase/discoveries.json` gains `available_fields` / `organization_context` / `env_lines`, `_progress.completed_substeps` is patched with `step3_context`, and the Japanese hand-off line for STEP 4 is printed.",
+      "`.cluebase/discoveries.json` gains `available_fields` / `organization_context`, `_progress.completed_substeps` is patched with `step3_context`, and the Japanese hand-off line for STEP 4 is printed.",
     nextHandoff: "/cluebase-discover-check",
   },
   {
@@ -147,7 +147,7 @@ const STEP_FILES = [
       "The ONLY goal of this command is to mechanically validate `.cluebase/discoveries.json` via the `setup-discover-check` CLI helper, surface any error/warning, and (when an error is found) instruct the user which earlier STEP to re-run by removing the matching substepId from `_progress.completed_substeps`. No AI judgment, no code edits.",
     scopeOut: [
       "STEP 1-3: writing or modifying `.cluebase/discoveries.json` itself (only substepId removal allowed when re-running an earlier STEP)",
-      "STEP 5+ (= /cluebase-implement and later): code edits, env file writes",
+      "STEP 5+ (= /cluebase-implement and later): code edits, `.env.cluebase` handling, and connectivity checks",
     ],
     completion:
       "`setup-discover-check` reports passed=true, `_progress.completed_substeps` is patched with `step4_check`, and the Japanese hand-off line for STEP 5 is printed. On failure: the user is told exactly which earlier STEP to re-run.",
@@ -161,7 +161,7 @@ const STEP_FILES = [
     id: "step5_implement",
     title: "STEP 5 — Implement (SDK call insertion + env file write)",
     singleGoal:
-      "The ONLY goal of this command is to insert Cluebase SDK lifecycle calls (cluebase.init / cluebase.identify / cluebase.group / cluebase.reset + observer wire-ups) at the file:line positions recorded in `.cluebase/discoveries.json`, add the SDK as a package-manifest dependency, run the install command, and write the pre-computed `env_lines` into the customer's frontend/backend env files. NO discoveries.json edits, NO bash validation, NO connectivity checks.",
+      "The ONLY goal of this command is to insert Cluebase SDK lifecycle calls (cluebase.init / cluebase.identify / cluebase.group / cluebase.reset + observer wire-ups) at the file:line positions recorded in `.cluebase/discoveries.json`, add the SDK as a package-manifest dependency, run the install command, and verify the CLI-owned `.env.cluebase` configuration. Do not create or edit service-local `.env*` files. NO discoveries.json edits, NO bash validation, NO connectivity checks.",
     scopeOut: [
       "STEP 1-4: modifying `.cluebase/discoveries.json` (it is read-only here)",
       "STEP 6 (= /cluebase-implement-check): bash static check + diff snapshot generation",
@@ -170,7 +170,7 @@ const STEP_FILES = [
       "STEP 9 (= /cluebase-doctor): real-server connectivity check",
     ],
     completion:
-      "All lifecycle / observer call sites in discoveries.json are inserted via Edit, SDK install is run successfully, env files are upserted with `env_lines`, `_progress.completed_substeps` is patched with `step5_implement`, and the Japanese hand-off line for STEP 6 is printed.",
+      "All lifecycle / observer call sites in discoveries.json are inserted via Edit, SDK install is run successfully, `.env.cluebase` is verified without exposing its secret, `_progress.completed_substeps` is patched with `step5_implement`, and the Japanese hand-off line for STEP 6 is printed.",
     nextHandoff: "/cluebase-implement-check",
   },
   {
@@ -237,7 +237,7 @@ const STEP_FILES = [
     id: "step9_doctor",
     title: "STEP 9 — Production-level setup verification",
     singleGoal:
-      "The ONLY goal of this command is to run `setup-doctor --local` via Bash. It probes Cluebase token issue, browser ingest, and backend ingest with SDK-equivalent payloads from customer env files, checks downstream browser/backend batch publish evidence, scans for forbidden customer-backend Cluebase routes, and runs 30 data-quality checks. `/cluebase-doctor` is intentionally STATELESS — re-run any time after fixes.",
+      "The ONLY goal of this command is to run `setup-doctor --local` via Bash. It reads the root `.env.cluebase` sections, probes Cluebase token issue, browser ingest, and backend ingest with SDK-equivalent payloads, checks downstream browser/backend batch publish evidence, scans for forbidden customer-backend Cluebase routes, and runs 30 data-quality checks. `/cluebase-doctor` is intentionally STATELESS — re-run any time after fixes.",
     scopeOut: [
       "STEP 1-8 (= /cluebase-discover .. /cluebase-events): anything that modifies discoveries.json, customer code, business-events.json, or runs the static check",
       "Persisting progress (this STEP is stateless — DO NOT write to the `_progress` array; it is intentionally re-runnable)",