@clue-ai/cli 0.0.5 → 0.0.6

package/bin/clue-cli.mjs

@@ -5,9 +5,9 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { commandSpecs } from "../src/command-spec.mjs";
 import {
-	buildSemanticWorkflowRequestFromFlags,
-	runInitTool,
-	writeSemanticWorkflow,
+  buildSemanticWorkflowRequestFromFlags,
+  runInitTool,
+  writeSemanticWorkflow,
 } from "../src/init-tool.mjs";
 import { applyLifecyclePlan } from "../src/lifecycle-init.mjs";
 import { runSemanticCi, runSemanticInventory } from "../src/semantic-ci.mjs";
@@ -17,843 +17,886 @@ import { runSetupPrepare } from "../src/setup-prepare.mjs";
 import { installSetupSkills } from "../src/setup-tool.mjs";
 
 const parseArgs = (argv) => {
-	const [command = "help", ...tokens] = argv;
-	const flags = new Map();
-	for (let index = 0; index < tokens.length; index += 1) {
-		const token = tokens[index];
-		if (!token.startsWith("--")) continue;
-		const key = token.slice(2);
-		const next = tokens[index + 1];
-		if (next && !next.startsWith("--")) {
-			flags.set(key, next);
-			index += 1;
-		} else {
-			flags.set(key, true);
-		}
-	}
-	return { command, flags };
+  const [command = "help", ...tokens] = argv;
+  const flags = new Map();
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = tokens[index + 1];
+    if (next && !next.startsWith("--")) {
+      flags.set(key, next);
+      index += 1;
+    } else {
+      flags.set(key, true);
+    }
+  }
+  return { command, flags };
 };
 
 const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
 
 const writeJsonIfRequested = async ({ repoRoot, outputPath, value }) => {
-	if (typeof outputPath !== "string") return false;
-	const resolvedRepoRoot = resolve(repoRoot);
-	const resolvedOutputPath = resolve(resolvedRepoRoot, outputPath);
-	const relativeOutputPath = relative(resolvedRepoRoot, resolvedOutputPath);
-	if (relativeOutputPath.startsWith("..") || isAbsolute(relativeOutputPath)) {
-		throw new Error(`output path escapes repo root: ${outputPath}`);
-	}
-	await mkdir(dirname(resolvedOutputPath), { recursive: true });
-	await writeFile(
-		resolvedOutputPath,
-		`${JSON.stringify(value, null, 2)}\n`,
-		"utf8",
-	);
-	return true;
+  if (typeof outputPath !== "string") return false;
+  const resolvedRepoRoot = resolve(repoRoot);
+  const resolvedOutputPath = resolve(resolvedRepoRoot, outputPath);
+  const relativeOutputPath = relative(resolvedRepoRoot, resolvedOutputPath);
+  if (relativeOutputPath.startsWith("..") || isAbsolute(relativeOutputPath)) {
+    throw new Error(`output path escapes repo root: ${outputPath}`);
+  }
+  await mkdir(dirname(resolvedOutputPath), { recursive: true });
+  await writeFile(
+    resolvedOutputPath,
+    `${JSON.stringify(value, null, 2)}\n`,
+    "utf8",
+  );
+  return true;
 };
 
 const sleep = (ms) =>
-	new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+  new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 
 const splitCsv = (value) =>
-	typeof value === "string"
-		? value
-				.split(",")
-				.map((entry) => entry.trim())
-				.filter(Boolean)
-		: [];
+  typeof value === "string"
+    ? value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+    : [];
 
 const splitWatchTargetEntries = (value) => {
-	if (typeof value !== "string") return [];
-	const entries = [];
-	let current = "";
-	let bracketDepth = 0;
-	for (const char of value) {
-		if (char === "[") bracketDepth += 1;
-		if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
-		if (char === "," && bracketDepth === 0) {
-			if (current.trim()) entries.push(current.trim());
-			current = "";
-			continue;
-		}
-		current += char;
-	}
-	if (current.trim()) entries.push(current.trim());
-	return entries;
+  if (typeof value !== "string") return [];
+  const entries = [];
+  let current = "";
+  let bracketDepth = 0;
+  for (const char of value) {
+    if (char === "[") bracketDepth += 1;
+    if (char === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+    if (char === "," && bracketDepth === 0) {
+      if (current.trim()) entries.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) entries.push(current.trim());
+  return entries;
 };
 
 const WATCH_LIFECYCLE_ALIASES = new Map([
-	["clue-init", "init"],
-	["init", "init"],
-	["sdk-initialized", "init"],
-	["clue-identify", "identify"],
-	["identify", "identify"],
-	["identified", "identify"],
-	["clue-set-account", "set-account"],
-	["set-account", "set-account"],
-	["account", "set-account"],
-	["clue-logout", "logout"],
-	["logout", "logout"],
-	["event-sent", "event-sent"],
-	["event", "event-sent"],
-	["log", "event-sent"],
+  ["clue-init", "init"],
+  ["init", "init"],
+  ["sdk-initialized", "init"],
+  ["clue-identify", "identify"],
+  ["identify", "identify"],
+  ["identified", "identify"],
+  ["clue-set-account", "set-account"],
+  ["set-account", "set-account"],
+  ["account", "set-account"],
+  ["clue-logout", "logout"],
+  ["logout", "logout"],
+  ["event-sent", "event-sent"],
+  ["event", "event-sent"],
+  ["log", "event-sent"],
 ]);
 
 const DEFAULT_WATCH_LIFECYCLE = [
-	"init",
-	"identify",
-	"set-account",
-	"logout",
-	"event-sent",
+  "init",
+  "identify",
+  "set-account",
+  "logout",
+  "event-sent",
 ];
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
 
 const parseExpectedLifecycle = (value) => {
-	if (typeof value !== "string" || !value.trim()) {
-		return DEFAULT_WATCH_LIFECYCLE;
-	}
-	const entries = value
-		.split(/[,+]/)
-		.map((entry) => entry.trim().toLowerCase())
-		.filter(Boolean);
-	const normalized = entries.map((entry) => {
-		const lifecycle = WATCH_LIFECYCLE_ALIASES.get(entry);
-		if (!lifecycle) {
-			throw new Error(
-				`invalid lifecycle check: ${entry}; expected init, identify, set-account, logout, or event-sent`,
-			);
-		}
-		return lifecycle;
-	});
-	return [...new Set(normalized)];
+  if (typeof value !== "string" || !value.trim()) {
+    return DEFAULT_WATCH_LIFECYCLE;
+  }
+  const entries = value
+    .split(/[,+]/)
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean);
+  const normalized = entries.map((entry) => {
+    const lifecycle = WATCH_LIFECYCLE_ALIASES.get(entry);
+    if (!lifecycle) {
+      throw new Error(
+        `invalid lifecycle check: ${entry}; expected init, identify, set-account, logout, or event-sent`,
+      );
+    }
+    return lifecycle;
+  });
+  return [...new Set(normalized)];
 };
 
 const parseWatchTargets = (value) =>
-	splitWatchTargetEntries(value).map((entry) => {
-		const match =
-			/^(frontend|backend):([^[\]=\s]+)(?:\[([^\]]+)\])?(?:=(\S+))?$/.exec(
-				entry,
-			);
-		if (!match) {
-			throw new Error(
-				`invalid --watch-targets entry: ${entry}; expected frontend:<service-key>[init,identify,set-account,logout,event-sent][=<url>] or backend:<service-key>[...][=<url>]`,
-			);
-		}
-		const serviceKey = match[2];
-		return {
-			kind: match[1],
-			serviceKey,
-			producerId: serviceKey,
-			expectedLifecycle: parseExpectedLifecycle(match[3]),
-			url: match[4] ?? null,
-		};
-	});
+  splitWatchTargetEntries(value).map((entry) => {
+    const match =
+      /^(frontend|backend):([^[\]=\s]+)(?:\[([^\]]+)\])?(?:=(\S+))?$/.exec(
+        entry,
+      );
+    if (!match) {
+      throw new Error(
+        `invalid --watch-targets entry: ${entry}; expected frontend:<service-key>[init,identify,set-account,logout,event-sent][=<url>] or backend:<service-key>[...][=<url>]`,
+      );
+    }
+    const serviceKey = match[2];
+    return {
+      kind: match[1],
+      serviceKey,
+      producerId: serviceKey,
+      expectedLifecycle: parseExpectedLifecycle(match[3]),
+      url: match[4] ?? null,
+    };
+  });
 
 const normalizeManifestWatchTarget = (target) => {
-	if (!target || typeof target !== "object") {
-		throw new Error("invalid setup manifest watch target");
-	}
-	const kind = target.kind;
-	const serviceKey = target.service_key ?? target.serviceKey;
-	if (kind !== "frontend" && kind !== "backend") {
-		throw new Error("setup manifest watch target kind must be frontend or backend");
-	}
-	if (typeof serviceKey !== "string" || !serviceKey.trim()) {
-		throw new Error("setup manifest watch target service_key is required");
-	}
-	const localUrlCandidates = Array.isArray(target.local_url_candidates)
-		? target.local_url_candidates
-				.map((entry) => String(entry).trim())
-				.filter(Boolean)
-		: [];
-	const urlEnvName =
-		typeof target.url_env_name === "string" && target.url_env_name.trim()
-			? target.url_env_name.trim()
-			: null;
-	const explicitUrl =
-		typeof target.url === "string" && target.url.trim()
-			? target.url.trim()
-			: null;
-	const expectedLifecycle = Array.isArray(target.expected_lifecycle)
-		? parseExpectedLifecycle(target.expected_lifecycle.join(","))
-		: DEFAULT_WATCH_LIFECYCLE;
-	return {
-		kind,
-		serviceKey: serviceKey.trim(),
-		producerId:
-			typeof target.producer_id === "string" && target.producer_id.trim()
-				? target.producer_id.trim()
-				: serviceKey.trim(),
-		expectedLifecycle,
-		url: explicitUrl,
-		urlEnvName,
-		localUrlCandidates,
-	};
+  if (!target || typeof target !== "object") {
+    throw new Error("invalid setup manifest watch target");
+  }
+  const kind = target.kind;
+  const serviceKey = target.service_key ?? target.serviceKey;
+  if (kind !== "frontend" && kind !== "backend") {
+    throw new Error(
+      "setup manifest watch target kind must be frontend or backend",
+    );
+  }
+  if (typeof serviceKey !== "string" || !serviceKey.trim()) {
+    throw new Error("setup manifest watch target service_key is required");
+  }
+  const localUrlCandidates = Array.isArray(target.local_url_candidates)
+    ? target.local_url_candidates
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+    : [];
+  const urlEnvName =
+    typeof target.url_env_name === "string" && target.url_env_name.trim()
+      ? target.url_env_name.trim()
+      : null;
+  const explicitUrl =
+    typeof target.url === "string" && target.url.trim()
+      ? target.url.trim()
+      : null;
+  const expectedLifecycle = Array.isArray(target.expected_lifecycle)
+    ? parseExpectedLifecycle(target.expected_lifecycle.join(","))
+    : DEFAULT_WATCH_LIFECYCLE;
+  return {
+    kind,
+    serviceKey: serviceKey.trim(),
+    producerId:
+      typeof target.producer_id === "string" && target.producer_id.trim()
+        ? target.producer_id.trim()
+        : serviceKey.trim(),
+    expectedLifecycle,
+    url: explicitUrl,
+    urlEnvName,
+    localUrlCandidates,
+  };
 };
 
 const readSetupManifest = async ({ repoRoot, manifestPath }) => {
-	const resolvedPath = resolve(repoRoot, manifestPath);
-	return readJson(resolvedPath);
+  const resolvedPath = resolve(repoRoot, manifestPath);
+  return readJson(resolvedPath);
 };
 
 const manifestWatchTargets = (manifest) => {
-	const targets = manifest?.lifecycle_verification?.watch_targets;
-	if (!Array.isArray(targets) || targets.length === 0) {
-		return [];
-	}
-	return targets.map(normalizeManifestWatchTarget);
+  const targets = manifest?.lifecycle_verification?.watch_targets;
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return [];
+  }
+  return targets.map(normalizeManifestWatchTarget);
 };
 
 const resolveTargetUrlFromEnv = ({ target, env }) => {
-	if (target.url) return target.url;
-	if (target.urlEnvName && typeof env[target.urlEnvName] === "string") {
-		const value = env[target.urlEnvName].trim();
-		if (value) return value;
-	}
-	return target.localUrlCandidates[0] ?? null;
+  if (target.url) return target.url;
+  if (target.urlEnvName && typeof env[target.urlEnvName] === "string") {
+    const value = env[target.urlEnvName].trim();
+    if (value) return value;
+  }
+  return target.localUrlCandidates[0] ?? null;
 };
 
 const shouldAskQuestions = ({ flags }) =>
-	!flags.has("yes") && process.stdin.isTTY && process.stdout.isTTY;
+  !flags.has("yes") && process.stdin.isTTY && process.stdout.isTTY;
 
 const confirmTargetUrls = async ({ flags, watchTargets, env }) => {
-	const initialTargets = watchTargets.map((target) => ({
-		...target,
-		url: resolveTargetUrlFromEnv({ target, env }),
-	}));
-	if (!shouldAskQuestions({ flags })) {
-		return initialTargets;
-	}
-	const readline = createInterface({
-		input: process.stdin,
-		output: process.stdout,
-	});
-	try {
-		const confirmedTargets = [];
-		for (const target of initialTargets) {
-			const currentUrl = target.url ?? "";
-			const answer = await readline.question(
-				`${target.kind}のローカルURL(${target.serviceKey})はこちらで正しいですか？ ${currentUrl || "(未設定)"}\nEnterで決定、違う場合はURLを入力: `,
-			);
-			confirmedTargets.push({
-				...target,
-				url: answer.trim() || currentUrl || null,
-			});
-		}
-		return confirmedTargets;
-	} finally {
-		readline.close();
-	}
+  const initialTargets = watchTargets.map((target) => ({
+    ...target,
+    url: resolveTargetUrlFromEnv({ target, env }),
+  }));
+  if (!shouldAskQuestions({ flags })) {
+    return initialTargets;
+  }
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    const confirmedTargets = [];
+    for (const target of initialTargets) {
+      const currentUrl = target.url ?? "";
+      const answer = await readline.question(
+        `${target.kind}のローカルURL(${target.serviceKey})はこちらで正しいですか？ ${currentUrl || "(未設定)"}\nEnterで決定、違う場合はURLを入力: `,
+      );
+      confirmedTargets.push({
+        ...target,
+        url: answer.trim() || currentUrl || null,
+      });
+    }
+    return confirmedTargets;
+  } finally {
+    readline.close();
+  }
 };
 
 const uniqueCsv = (values) => [...new Set(values.filter(Boolean))].join(",");
 
 const buildWatchProducerIds = ({ explicitProducerIds, watchTargets }) =>
-	uniqueCsv([
-		...splitCsv(explicitProducerIds),
-		...watchTargets.map((target) => target.producerId),
-	]);
+  uniqueCsv([
+    ...splitCsv(explicitProducerIds),
+    ...watchTargets.map((target) => target.producerId),
+  ]);
 
 const checkTargetUrl = async (url) => {
-	if (!url) return { checked: false, reachable: true, status: null };
-	try {
-		const response = await fetch(url, { method: "GET" });
-		return {
-			checked: true,
-			reachable: response.status < 500,
-			status: response.status,
-		};
-	} catch {
-		return { checked: true, reachable: false, status: null };
-	}
+  if (!url) return { checked: false, reachable: true, status: null };
+  try {
+    const response = await fetch(url, { method: "GET" });
+    return {
+      checked: true,
+      reachable: response.status < 500,
+      status: response.status,
+    };
+  } catch {
+    return { checked: true, reachable: false, status: null };
+  }
 };
 
 const evaluateWatchTargets = async ({ latest, watchTargets }) => {
-	const producers = Array.isArray(latest?.producers) ? latest.producers : [];
-	return Promise.all(
-		watchTargets.map(async (target) => {
-			const producer = producers.find(
-				(entry) => entry.id === target.producerId,
-			);
-			const urlHealth = await checkTargetUrl(target.url);
-			const lifecycleStatus = {
-				init: Boolean(producer?.clueInit ?? producer?.sdkInitialized),
-				identify: Boolean(producer?.clueIdentify),
-				"set-account": Boolean(producer?.clueSetAccount),
-				logout: Boolean(producer?.clueLogout),
-				"event-sent": Boolean(producer?.logStored),
-			};
-			const expectedLifecycle = target.expectedLifecycle;
-			const unexpectedLifecycle = Object.entries(lifecycleStatus)
-				.filter(
-					([name, passed]) =>
-						passed &&
-						name !== "event-sent" &&
-						name !== "init" &&
-						!expectedLifecycle.includes(name),
-				)
-				.map(([name]) => name);
-			const producerPassed =
-				expectedLifecycle.every((name) => lifecycleStatus[name]) &&
-				unexpectedLifecycle.length === 0;
-			return {
-				...target,
-				expectedLifecycle,
-				eventCount: producer?.eventCount ?? 0,
-				latestOccurredAt: producer?.latestOccurredAt ?? null,
-				logStored: Boolean(producer?.logStored),
-				requestStored: Boolean(producer?.requestStored),
-				sdkInitialized: Boolean(producer?.sdkInitialized),
-				lifecycleStatus,
-				unexpectedLifecycle,
-				urlChecked: urlHealth.checked,
-				urlReachable: urlHealth.reachable,
-				urlStatus: urlHealth.status,
-				passed: producerPassed && urlHealth.reachable,
-			};
-		}),
-	);
+  const producers = Array.isArray(latest?.producers) ? latest.producers : [];
+  return Promise.all(
+    watchTargets.map(async (target) => {
+      const producer = producers.find(
+        (entry) => entry.id === target.producerId,
+      );
+      const urlHealth = await checkTargetUrl(target.url);
+      const lifecycleStatus = {
+        init: Boolean(producer?.clueInit ?? producer?.sdkInitialized),
+        identify: Boolean(producer?.clueIdentify),
+        "set-account": Boolean(producer?.clueSetAccount),
+        logout: Boolean(producer?.clueLogout),
+        "event-sent": Boolean(producer?.logStored),
+      };
+      const expectedLifecycle = target.expectedLifecycle;
+      const unexpectedLifecycle = Object.entries(lifecycleStatus)
+        .filter(
+          ([name, passed]) =>
+            passed &&
+            name !== "event-sent" &&
+            name !== "init" &&
+            !expectedLifecycle.includes(name),
+        )
+        .map(([name]) => name);
+      const producerPassed =
+        expectedLifecycle.every((name) => lifecycleStatus[name]) &&
+        unexpectedLifecycle.length === 0;
+      return {
+        ...target,
+        expectedLifecycle,
+        eventCount: producer?.eventCount ?? 0,
+        latestOccurredAt: producer?.latestOccurredAt ?? null,
+        logStored: Boolean(producer?.logStored),
+        requestStored: Boolean(producer?.requestStored),
+        sdkInitialized: Boolean(producer?.sdkInitialized),
+        lifecycleStatus,
+        unexpectedLifecycle,
+        urlChecked: urlHealth.checked,
+        urlReachable: urlHealth.reachable,
+        urlStatus: urlHealth.status,
+        passed: producerPassed && urlHealth.reachable,
+      };
+    }),
+  );
 };
 
 const lifecycleStatusFromEvents = (events) => {
-	const customEventNames = new Set(
-		events
-			.map((event) => event.custom_event_name ?? event.customEventName)
-			.filter((value) => typeof value === "string"),
-	);
-	return {
-		init: customEventNames.has("sdk_initialized"),
-		identify: customEventNames.has("identity_identified"),
-		"set-account": customEventNames.has("account_associated"),
-		logout: customEventNames.has("identity_logged_out"),
-		"event-sent": events.length > 0,
-	};
+  const customEventNames = new Set(
+    events
+      .map((event) => event.custom_event_name ?? event.customEventName)
+      .filter((value) => typeof value === "string"),
+  );
+  return {
+    init: customEventNames.has("sdk_initialized"),
+    identify: customEventNames.has("identity_identified"),
+    "set-account": customEventNames.has("account_associated"),
+    logout: customEventNames.has("identity_logged_out"),
+    "event-sent": events.length > 0,
+  };
 };
 
 const localSetupCheckSnapshot = ({ receivedBatches }) => {
-	const producerEvents = new Map();
-	for (const batch of receivedBatches) {
-		const producerId =
-			batch.producerId ||
-			batch.payload?.producer_metadata?.producer_id ||
-			batch.payload?.producer_id;
-		if (typeof producerId !== "string" || !producerId.trim()) continue;
-		const events = Array.isArray(batch.payload?.events)
-			? batch.payload.events
-			: [];
-		const existing = producerEvents.get(producerId) ?? [];
-		producerEvents.set(producerId, [...existing, ...events]);
-	}
-	const producers = [...producerEvents.entries()].map(([id, events]) => {
-		const lifecycleStatus = lifecycleStatusFromEvents(events);
-		return {
-			id,
-			eventCount: events.length,
-			clueInit: lifecycleStatus.init,
-			clueIdentify: lifecycleStatus.identify,
-			clueSetAccount: lifecycleStatus["set-account"],
-			clueLogout: lifecycleStatus.logout,
-			sdkInitialized: lifecycleStatus.init,
-			logStored: lifecycleStatus["event-sent"],
-			requestStored: events.some((event) => event.event_category === "request"),
-			internalFlowStored: events.some(
-				(event) => event.event_category === "internal_flow",
-			),
-			latestOccurredAt:
-				events
-					.map((event) => event.occurred_at)
-					.filter((value) => typeof value === "string")
-					.sort()
-					.at(-1) ?? null,
-		};
-	});
-	const lifecycleChecks = producers.flatMap((producer) => [
-		["frontend_sdk_initialized", producer.sdkInitialized],
-		["backend_sdk_initialized", producer.sdkInitialized],
-		["frontend_log_sent", producer.logStored],
-		["backend_log_sent", producer.logStored],
-		["identified_event", producer.clueIdentify],
-		["account_event", producer.clueSetAccount],
-		["logout_reset", producer.clueLogout],
-	]);
-	const checks = Object.fromEntries(
-		lifecycleChecks.map(([name, passed]) => [
-			name,
-			passed ? "passed" : "waiting",
-		]),
-	);
-	return { checks, producers };
+  const producerEvents = new Map();
+  for (const batch of receivedBatches) {
+    const producerId =
+      batch.producerId ||
+      batch.payload?.producer_metadata?.producer_id ||
+      batch.payload?.producer_id;
+    if (typeof producerId !== "string" || !producerId.trim()) continue;
+    const events = Array.isArray(batch.payload?.events)
+      ? batch.payload.events
+      : [];
+    const existing = producerEvents.get(producerId) ?? [];
+    producerEvents.set(producerId, [...existing, ...events]);
+  }
+  const producers = [...producerEvents.entries()].map(([id, events]) => {
+    const lifecycleStatus = lifecycleStatusFromEvents(events);
+    return {
+      id,
+      eventCount: events.length,
+      clueInit: lifecycleStatus.init,
+      clueIdentify: lifecycleStatus.identify,
+      clueSetAccount: lifecycleStatus["set-account"],
+      clueLogout: lifecycleStatus.logout,
+      sdkInitialized: lifecycleStatus.init,
+      logStored: lifecycleStatus["event-sent"],
+      requestStored: events.some((event) => event.event_category === "request"),
+      internalFlowStored: events.some(
+        (event) => event.event_category === "internal_flow",
+      ),
+      latestOccurredAt:
+        events
+          .map((event) => event.occurred_at)
+          .filter((value) => typeof value === "string")
+          .sort()
+          .at(-1) ?? null,
+    };
+  });
+  const lifecycleChecks = producers.flatMap((producer) => [
+    ["frontend_sdk_initialized", producer.sdkInitialized],
+    ["backend_sdk_initialized", producer.sdkInitialized],
+    ["frontend_log_sent", producer.logStored],
+    ["backend_log_sent", producer.logStored],
+    ["identified_event", producer.clueIdentify],
+    ["account_event", producer.clueSetAccount],
+    ["logout_reset", producer.clueLogout],
+  ]);
+  const checks = Object.fromEntries(
+    lifecycleChecks.map(([name, passed]) => [
+      name,
+      passed ? "passed" : "waiting",
+    ]),
+  );
+  return { checks, producers };
 };
 
 const readRequestJson = async (request) => {
-	const chunks = [];
-	for await (const chunk of request) {
-		chunks.push(chunk);
-	}
-	const body = Buffer.concat(chunks).toString("utf8");
-	if (!body.trim()) return {};
-	return JSON.parse(body);
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(chunk);
+  }
+  const body = Buffer.concat(chunks).toString("utf8");
+  if (!body.trim()) return {};
+  return JSON.parse(body);
 };
 
 const startLocalSetupReceiver = async ({ host, port }) => {
-	const receivedBatches = [];
-	const server = createServer(async (request, response) => {
-		response.setHeader("access-control-allow-origin", "*");
-		response.setHeader("access-control-allow-methods", "POST, OPTIONS");
-		response.setHeader("access-control-allow-headers", "*");
-		if (request.method === "OPTIONS") {
-			response.writeHead(204);
-			response.end();
-			return;
-		}
-		if (request.method !== "POST") {
-			response.writeHead(404, { "content-type": "application/json" });
-			response.end(JSON.stringify({ accepted: false }));
-			return;
-		}
-		try {
-			const payload = await readRequestJson(request);
-			receivedBatches.push({
-				payload,
-				producerId:
-					payload?.producer_metadata?.producer_id ?? payload?.producer_id ?? null,
-				path: request.url,
-			});
-			response.writeHead(202, { "content-type": "application/json" });
-			response.end(
-				JSON.stringify({
-					accepted: true,
-					status: "accepted",
-					duplicate: false,
-					eventCount: Array.isArray(payload?.events) ? payload.events.length : 0,
-				}),
-			);
-		} catch (error) {
-			response.writeHead(400, { "content-type": "application/json" });
-			response.end(
-				JSON.stringify({
-					accepted: false,
-					reason: error instanceof Error ? error.message : String(error),
-				}),
-			);
-		}
-	});
-	await new Promise((resolveListen, rejectListen) => {
-		server.once("error", rejectListen);
-		server.listen(port, host, () => {
-			server.off("error", rejectListen);
-			resolveListen();
-		});
-	});
-	const address = server.address();
-	if (!address || typeof address === "string") {
-		throw new Error("local setup receiver failed to bind");
-	}
-	const baseUrl = `http://${host}:${address.port}`;
-	return {
-		baseUrl,
-		receivedBatches,
-		close: () =>
-			new Promise((resolveClose) => {
-				server.close(() => resolveClose());
-			}),
-	};
+  const receivedBatches = [];
+  const server = createServer(async (request, response) => {
+    response.setHeader("access-control-allow-origin", "*");
+    response.setHeader("access-control-allow-methods", "POST, OPTIONS");
+    response.setHeader("access-control-allow-headers", "*");
+    if (request.method === "OPTIONS") {
+      response.writeHead(204);
+      response.end();
+      return;
+    }
+    if (request.method !== "POST") {
+      response.writeHead(404, { "content-type": "application/json" });
+      response.end(JSON.stringify({ accepted: false }));
+      return;
+    }
+    try {
+      const payload = await readRequestJson(request);
+      receivedBatches.push({
+        payload,
+        producerId:
+          payload?.producer_metadata?.producer_id ??
+          payload?.producer_id ??
+          null,
+        path: request.url,
+      });
+      response.writeHead(202, { "content-type": "application/json" });
+      response.end(
+        JSON.stringify({
+          accepted: true,
+          status: "accepted",
+          duplicate: false,
+          eventCount: Array.isArray(payload?.events)
+            ? payload.events.length
+            : 0,
+        }),
+      );
+    } catch (error) {
+      response.writeHead(400, { "content-type": "application/json" });
+      response.end(
+        JSON.stringify({
+          accepted: false,
+          reason: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+  });
+  await new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen(port, host, () => {
+      server.off("error", rejectListen);
+      resolveListen();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("local setup receiver failed to bind");
+  }
+  const baseUrl = `http://${host}:${address.port}`;
+  return {
+    baseUrl,
+    receivedBatches,
+    close: () =>
+      new Promise((resolveClose) => {
+        server.close(() => resolveClose());
+      }),
+  };
 };
 
 const renderWatchTargets = (targetChecks) =>
-	targetChecks
-		.map((target) => {
-			const urlStatus = target.urlChecked
-				? ` url:${target.urlReachable ? 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}`;
-		})
-		.join("\n");
+  targetChecks
+    .map((target) => {
+      const urlStatus = target.urlChecked
+        ? ` url:${target.urlReachable ? 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}`;
+    })
+    .join("\n");
 
 const setupCheckUrl = ({
-	clueApiBaseUrl,
-	environment,
-	limit,
-	producerIds,
-	projectId,
-	projectKey,
-	startedAt,
+  clueApiBaseUrl,
+  environment,
+  limit,
+  producerIds,
+  projectId,
+  projectKey,
+  startedAt,
 }) => {
-	const normalizedBaseUrl = String(clueApiBaseUrl).replace(/\/+$/, "");
-	const url = new URL(`${normalizedBaseUrl}/api/v1/events/setup-check`);
-	url.searchParams.set("projectKey", projectKey);
-	url.searchParams.set("environment", environment);
-	url.searchParams.set("startedAt", startedAt);
-	url.searchParams.set("limit", String(limit));
-	if (typeof projectId === "string" && projectId.trim()) {
-		url.searchParams.set("project_id", projectId.trim());
-	}
-	if (typeof producerIds === "string" && producerIds.trim()) {
-		url.searchParams.set("producerIds", producerIds.trim());
-	}
-	return url;
+  const normalizedBaseUrl = String(clueApiBaseUrl).replace(/\/+$/, "");
+  const url = new URL(`${normalizedBaseUrl}/api/v1/events/setup-check`);
+  url.searchParams.set("projectKey", projectKey);
+  url.searchParams.set("environment", environment);
+  url.searchParams.set("startedAt", startedAt);
+  url.searchParams.set("limit", String(limit));
+  if (typeof projectId === "string" && projectId.trim()) {
+    url.searchParams.set("project_id", projectId.trim());
+  }
+  if (typeof producerIds === "string" && producerIds.trim()) {
+    url.searchParams.set("producerIds", producerIds.trim());
+  }
+  return url;
 };
 
 const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
-	const localMode = flags.has("local");
-	const manifestPath = String(
-		flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
-	);
-	const manifest = localMode
-		? await readSetupManifest({ repoRoot, manifestPath })
-		: null;
-	if (localMode && manifest?.status !== "ready_for_ai") {
-		throw new Error(
-			`setup-watch --local requires a ready setup manifest at ${manifestPath}`,
-		);
-	}
-	const projectKey = String(
-		flags.get("project-key") ||
-			env.CLUE_PROJECT_KEY ||
-			manifest?.project_key ||
-			"",
-	).trim();
-	if (!projectKey && !localMode) {
-		throw new Error("--project-key or CLUE_PROJECT_KEY is required");
-	}
-	const environment = String(
-		flags.get("environment") ||
-			env.CLUE_ENVIRONMENT ||
-			manifest?.environment ||
-			"dev",
-	).trim();
-	const clueApiBaseUrl = String(
-		flags.get("clue-api-base-url") || env.CLUE_API_BASE_URL || "",
-	).trim();
-	if (!clueApiBaseUrl && !localMode) {
-		throw new Error("--clue-api-base-url or CLUE_API_BASE_URL is required");
-	}
-	const startedAt = String(
-		flags.get("started-at") || new Date().toISOString(),
-	).trim();
-	const timeoutMs = Number(flags.get("timeout-ms") || 120_000);
-	const pollIntervalMs = Number(flags.get("poll-interval-ms") || 3000);
-	const limit = Number(flags.get("limit") || 200);
-	const projectId = flags.get("project-id");
-	const explicitWatchTargets = parseWatchTargets(flags.get("watch-targets"));
-	const watchTargets = await confirmTargetUrls({
-		flags,
-		watchTargets:
-			explicitWatchTargets.length > 0
-				? explicitWatchTargets
-				: manifestWatchTargets(manifest),
-		env,
-	});
-	const producerIds = buildWatchProducerIds({
-		explicitProducerIds: flags.get("producer-ids"),
-		watchTargets,
-	});
-	const started = Date.now();
-	let latest = null;
-
-	if (localMode) {
-		const receiver = await startLocalSetupReceiver({
-			host: String(flags.get("host") || "127.0.0.1"),
-			port: Number(flags.get("port") || 0),
-		});
-		try {
-			process.stdout.write(
-				`Local Clue setup receiver: ${receiver.baseUrl}\n`,
-			);
-			process.stdout.write(
-				`Frontend endpoint: ${receiver.baseUrl}/api/v1/ingest/browser\n`,
-			);
-			process.stdout.write(
-				`Backend endpoint: ${receiver.baseUrl}/api/v1/ingest/backend\n`,
-			);
-			if (watchTargets.length > 0) {
-				process.stdout.write(
-					`Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
-				);
-			}
-			while (Date.now() - started <= timeoutMs) {
-				latest = localSetupCheckSnapshot({
-					receivedBatches: receiver.receivedBatches,
-				});
-				const targetChecks = await evaluateWatchTargets({
-					latest,
-					watchTargets,
-				});
-				const targetChecksPassed =
-					targetChecks.length > 0 &&
-					targetChecks.every((target) => target.passed);
-				const renderedTargets = renderWatchTargets(targetChecks);
-				process.stdout.write(`${renderedTargets}\n\n`);
-				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`);
-			throw new Error(
-				"setup-watch --local timed out before all Clue setup checks passed",
-			);
-		} finally {
-			await receiver.close();
-		}
-	}
-
-	process.stdout.write(
-		`Waiting for Clue setup checks since ${startedAt} (${environment})...\n`,
-	);
-	if (watchTargets.length > 0) {
-		process.stdout.write(
-			`Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
-		);
-	}
-
-	while (Date.now() - started <= timeoutMs) {
-		const response = await fetch(
-			setupCheckUrl({
-				clueApiBaseUrl,
-				environment,
-				limit,
-				producerIds,
-				projectId,
-				projectKey,
-				startedAt,
-			}),
-		);
-		if (!response.ok) {
-			throw new Error(`setup-check request failed: ${response.status}`);
-		}
-		latest = await response.json();
-		const checks = latest?.checks ?? {};
-		const entries = Object.entries(checks);
-		const setupChecksPassed =
-			entries.length > 0 && entries.every(([, status]) => status === "passed");
-		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 renderedTargets = renderWatchTargets(targetChecks);
-		process.stdout.write(
-			`${rendered}${renderedTargets ? `\n${renderedTargets}` : ""}\n\n`,
-		);
-		if (passed) {
-			process.stdout.write("Clue setup checks passed.\n");
-			return { ...latest, watchTargets: targetChecks };
-		}
-		await sleep(pollIntervalMs);
-	}
-
-	process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
-	throw new Error("setup-watch timed out before all Clue setup checks passed");
+  const localMode = flags.has("local");
+  const manifestPath = String(
+    flags.get("manifest") || DEFAULT_SETUP_MANIFEST_PATH,
+  );
+  const manifest = localMode
+    ? await readSetupManifest({ repoRoot, manifestPath })
+    : null;
+  if (localMode && manifest?.status !== "ready_for_ai") {
+    throw new Error(
+      `setup-watch --local requires a ready setup manifest at ${manifestPath}`,
+    );
+  }
+  const projectKey = String(
+    flags.get("project-key") ||
+      env.CLUE_PROJECT_KEY ||
+      manifest?.project_key ||
+      "",
+  ).trim();
+  if (!projectKey && !localMode) {
+    throw new Error("--project-key or CLUE_PROJECT_KEY is required");
+  }
+  const environment = String(
+    flags.get("environment") ||
+      env.CLUE_ENVIRONMENT ||
+      manifest?.environment ||
+      "dev",
+  ).trim();
+  const clueApiBaseUrl = String(
+    flags.get("clue-api-base-url") || env.CLUE_API_BASE_URL || "",
+  ).trim();
+  if (!clueApiBaseUrl && !localMode) {
+    throw new Error("--clue-api-base-url or CLUE_API_BASE_URL is required");
+  }
+  const startedAt = String(
+    flags.get("started-at") || new Date().toISOString(),
+  ).trim();
+  const timeoutMs = Number(flags.get("timeout-ms") || 120_000);
+  const pollIntervalMs = Number(flags.get("poll-interval-ms") || 3000);
+  const limit = Number(flags.get("limit") || 200);
+  const projectId = flags.get("project-id");
+  const explicitWatchTargets = parseWatchTargets(flags.get("watch-targets"));
+  const watchTargets = await confirmTargetUrls({
+    flags,
+    watchTargets:
+      explicitWatchTargets.length > 0
+        ? explicitWatchTargets
+        : manifestWatchTargets(manifest),
+    env,
+  });
+  const producerIds = buildWatchProducerIds({
+    explicitProducerIds: flags.get("producer-ids"),
+    watchTargets,
+  });
+  const started = Date.now();
+  let latest = null;
+
+  if (localMode) {
+    const receiver = await startLocalSetupReceiver({
+      host: String(flags.get("host") || "127.0.0.1"),
+      port: Number(flags.get("port") || 0),
+    });
+    try {
+      process.stdout.write(`Local Clue setup receiver: ${receiver.baseUrl}\n`);
+      process.stdout.write(
+        `Frontend endpoint: ${receiver.baseUrl}/api/v1/ingest/browser\n`,
+      );
+      process.stdout.write(
+        `Backend endpoint: ${receiver.baseUrl}/api/v1/ingest/backend\n`,
+      );
+      if (watchTargets.length > 0) {
+        process.stdout.write(
+          `Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
+        );
+      }
+      while (Date.now() - started <= timeoutMs) {
+        latest = localSetupCheckSnapshot({
+          receivedBatches: receiver.receivedBatches,
+        });
+        const targetChecks = await evaluateWatchTargets({
+          latest,
+          watchTargets,
+        });
+        const targetChecksPassed =
+          targetChecks.length > 0 &&
+          targetChecks.every((target) => target.passed);
+        const renderedTargets = renderWatchTargets(targetChecks);
+        process.stdout.write(`${renderedTargets}\n\n`);
+        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`);
+      throw new Error(
+        "setup-watch --local timed out before all Clue setup checks passed",
+      );
+    } finally {
+      await receiver.close();
+    }
+  }
+
+  process.stdout.write(
+    `Waiting for Clue setup checks since ${startedAt} (${environment})...\n`,
+  );
+  if (watchTargets.length > 0) {
+    process.stdout.write(
+      `Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
+    );
+  }
+
+  while (Date.now() - started <= timeoutMs) {
+    const response = await fetch(
+      setupCheckUrl({
+        clueApiBaseUrl,
+        environment,
+        limit,
+        producerIds,
+        projectId,
+        projectKey,
+        startedAt,
+      }),
+    );
+    if (!response.ok) {
+      throw new Error(`setup-check request failed: ${response.status}`);
+    }
+    latest = await response.json();
+    const checks = latest?.checks ?? {};
+    const entries = Object.entries(checks);
+    const setupChecksPassed =
+      entries.length > 0 && entries.every(([, status]) => status === "passed");
+    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 renderedTargets = renderWatchTargets(targetChecks);
+    process.stdout.write(
+      `${rendered}${renderedTargets ? `\n${renderedTargets}` : ""}\n\n`,
+    );
+    if (passed) {
+      process.stdout.write("Clue setup checks passed.\n");
+      return { ...latest, watchTargets: targetChecks };
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+  throw new Error("setup-watch timed out before all Clue setup checks passed");
 };
 
 const usage = () =>
-	[
-		"Usage:",
-		"  /clue-init",
-		"  clue-ai setup",
-		"  clue-ai setup-detect --repo .",
-		"  clue-ai semantic-inventory --framework fastapi --backend-root-path backend --repo . --output .clue/semantic-routes.json",
-		"  clue-ai semantic-workflow --framework fastapi --backend-root-path backend --repo .",
-		"  clue-ai lifecycle-apply --plan clue-lifecycle-plan.json --repo .",
-		"  clue-ai setup-check --framework fastapi --backend-root-path backend --repo .",
-		"  clue-ai setup-watch --local",
-		"  clue-ai setup-watch --project-key <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>",
-		"  clue-ai init --request clue-init-request.json --repo .",
-		"  clue-ai semantic-ci --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]",
-		"  clue-ai semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
-	].join("\n");
+  [
+    "Usage:",
+    "  /clue-init",
+    "  clue-ai setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev",
+    "  clue-ai setup-detect --repo .",
+    "  clue-ai semantic-inventory --framework fastapi --backend-root-path backend --repo . --output .clue/semantic-routes.json",
+    "  clue-ai semantic-workflow --framework fastapi --backend-root-path backend --repo .",
+    "  clue-ai lifecycle-apply --plan clue-lifecycle-plan.json --repo .",
+    "  clue-ai setup-check --framework fastapi --backend-root-path backend --repo .",
+    "  clue-ai setup-watch --local",
+    "  clue-ai setup-watch --project-key <key> --environment dev --clue-api-base-url <clue-api-base-url> --watch-targets frontend:web[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>",
+    "  clue-ai init --request clue-init-request.json --repo .",
+    "  clue-ai semantic-ci --request clue-semantic-request.json --repo . [--previous-snapshot-file previous.json]",
+    "  clue-ai semantic-ci --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .",
+  ].join("\n");
+
+const renderEnvironmentInstructions = (instructions) => {
+  if (!instructions || instructions.status !== "ready") {
+    return "";
+  }
+  const lines = ["", instructions.message, ""];
+  for (const block of instructions.service_env_blocks) {
+    lines.push(
+      `[${block.kind}] ${block.root_path} (${block.env_file_candidates.join(" or ")})`,
+      block.env_block,
+      "",
+    );
+  }
+  lines.push(
+    "GitHub Secrets",
+    ...instructions.ci_github.secrets.map(
+      (entry) => `${entry.name}=${entry.value}`,
+    ),
+    "",
+    "GitHub Variables",
+    ...instructions.ci_github.variables.map(
+      (entry) => `${entry.name}=${entry.value}`,
+    ),
+    "",
+  );
+  return `${lines.join("\n")}\n`;
+};
 
 const main = async () => {
-	const { command, flags } = parseArgs(process.argv.slice(2));
-	if (command === "help" || flags.has("help")) {
-		process.stdout.write(`${usage()}\n`);
-		return;
-	}
-
-	if (command === "commands") {
-		process.stdout.write(
-			`${JSON.stringify({ commands: commandSpecs }, null, 2)}\n`,
-		);
-		return;
-	}
-
-	const requestPath = flags.get("request");
-	const repoRoot = resolve(String(flags.get("repo") || "."));
-
-	if (command === "setup-watch") {
-		const report = await runSetupWatch({ flags, repoRoot });
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		return;
-	}
-
-	if (command === "setup") {
-		const report = await installSetupSkills({
-			repoRoot,
-			target:
-				typeof flags.get("target") === "string"
-					? flags.get("target")
-					: undefined,
-		});
-		const preparation = flags.has("skills-only")
-			? {
-					status: "skipped",
-					reason: "skills-only flag was provided",
-				}
-			: await runSetupPrepare({
-					repoRoot,
-					target: report.target,
-					skillRoot: report.skill_root,
-				});
-		process.stdout.write(
-			`${JSON.stringify({ ...report, preparation }, null, 2)}\n`,
-		);
-		return;
-	}
-
-	if (command === "setup-detect") {
-		const report = await runSetupDetect({
-			repoRoot,
-			excludedSourcePaths:
-				typeof flags.get("excluded-source-paths") === "string"
-					? flags
-							.get("excluded-source-paths")
-							.split(",")
-							.map((entry) => entry.trim())
-							.filter(Boolean)
-					: [],
-		});
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		if (!report.detected) {
-			process.exitCode = 1;
-		}
-		return;
-	}
-
-	if (command === "semantic-workflow") {
-		const request = buildSemanticWorkflowRequestFromFlags({
-			framework: flags.get("framework"),
-			backendRootPath: flags.get("backend-root-path"),
-			allowedSourcePaths: flags.get("allowed-source-paths"),
-			excludedSourcePaths: flags.get("excluded-source-paths"),
-			serviceKey: flags.get("service-key"),
-			workflowPath: flags.get("workflow-path"),
-		});
-		const report = await writeSemanticWorkflow({ repoRoot, request });
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		return;
-	}
-
-	if (command === "semantic-inventory") {
-		const request = buildSemanticWorkflowRequestFromFlags({
-			framework: flags.get("framework"),
-			backendRootPath: flags.get("backend-root-path"),
-			allowedSourcePaths: flags.get("allowed-source-paths"),
-			excludedSourcePaths: flags.get("excluded-source-paths"),
-			serviceKey: flags.get("service-key"),
-			workflowPath: flags.get("workflow-path"),
-		});
-		const report = await runSemanticInventory({ repoRoot, request });
-		await writeJsonIfRequested({
-			repoRoot,
-			outputPath: flags.get("output"),
-			value: report,
-		});
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		return;
-	}
-
-	if (command === "lifecycle-apply") {
-		const planPath = flags.get("plan");
-		if (typeof planPath !== "string") {
-			throw new Error("--plan is required");
-		}
-		const plan = await readJson(resolve(planPath));
-		const report = await applyLifecyclePlan({ repoRoot, plan });
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		return;
-	}
-
-	if (command === "setup-check") {
-		const hasInventoryFlags =
-			typeof flags.get("framework") === "string" &&
-			typeof flags.get("backend-root-path") === "string";
-		const request = hasInventoryFlags
-			? buildSemanticWorkflowRequestFromFlags({
-					framework: flags.get("framework"),
-					backendRootPath: flags.get("backend-root-path"),
-					allowedSourcePaths: flags.get("allowed-source-paths"),
-					excludedSourcePaths: flags.get("excluded-source-paths"),
-					serviceKey: flags.get("service-key"),
-					workflowPath: flags.get("workflow-path"),
-				})
-			: undefined;
-		const report = await runSetupCheck({
-			repoRoot,
-			request,
-			target:
-				typeof flags.get("target") === "string"
-					? flags.get("target")
-					: undefined,
-			requireSdkLifecycle: flags.has("require-sdk-lifecycle"),
-		});
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		if (!report.passed) {
-			process.exitCode = 1;
-		}
-		return;
-	}
-
-	const requestEnvName = flags.get("request-env");
-	if (typeof requestPath !== "string" && typeof requestEnvName !== "string") {
-		throw new Error("--request is required");
-	}
-	const request =
-		typeof requestEnvName === "string"
-			? JSON.parse(process.env[requestEnvName] ?? "")
-			: await readJson(resolve(requestPath));
-
-	if (command === "init") {
-		const report = await runInitTool({ repoRoot, request });
-		process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-		return;
-	}
-
-	if (command === "semantic-ci") {
-		const previousSnapshotPath =
-			flags.get("previous-snapshot") ?? flags.get("previous-snapshot-file");
-		const previousSnapshot =
-			typeof previousSnapshotPath === "string"
-				? await readJson(resolve(previousSnapshotPath))
-				: undefined;
-		const result = await runSemanticCi({
-			repoRoot,
-			request,
-			env: process.env,
-			previousSnapshot,
-		});
-		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-		return;
-	}
-
-	throw new Error(`Unknown command: ${command}\n${usage()}`);
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  if (command === "help" || flags.has("help")) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  if (command === "commands") {
+    process.stdout.write(
+      `${JSON.stringify({ commands: commandSpecs }, null, 2)}\n`,
+    );
+    return;
+  }
+
+  const requestPath = flags.get("request");
+  const repoRoot = resolve(String(flags.get("repo") || "."));
+
+  if (command === "setup-watch") {
+    const report = await runSetupWatch({ flags, repoRoot });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (command === "setup") {
+    const report = await installSetupSkills({
+      repoRoot,
+      target:
+        typeof flags.get("target") === "string"
+          ? flags.get("target")
+          : undefined,
+    });
+    const preparation = flags.has("skills-only")
+      ? {
+          status: "skipped",
+          reason: "skills-only flag was provided",
+        }
+      : await runSetupPrepare({
+          repoRoot,
+          target: report.target,
+          skillRoot: report.skill_root,
+          setupContext: {
+            clueApiKey: flags.get("clue-api-key"),
+            clueApiBaseUrl: flags.get("clue-api-base-url"),
+            projectKey: flags.get("project-key"),
+            environment: flags.get("environment"),
+          },
+        });
+    const environmentInstructions = renderEnvironmentInstructions(
+      preparation.environment_instructions,
+    );
+    if (environmentInstructions) {
+      process.stderr.write(environmentInstructions);
+    }
+    process.stdout.write(
+      `${JSON.stringify({ ...report, preparation }, null, 2)}\n`,
+    );
+    return;
+  }
+
+  if (command === "setup-detect") {
+    const report = await runSetupDetect({
+      repoRoot,
+      excludedSourcePaths:
+        typeof flags.get("excluded-source-paths") === "string"
+          ? flags
+              .get("excluded-source-paths")
+              .split(",")
+              .map((entry) => entry.trim())
+              .filter(Boolean)
+          : [],
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.detected) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (command === "semantic-workflow") {
+    const request = buildSemanticWorkflowRequestFromFlags({
+      framework: flags.get("framework"),
+      backendRootPath: flags.get("backend-root-path"),
+      allowedSourcePaths: flags.get("allowed-source-paths"),
+      excludedSourcePaths: flags.get("excluded-source-paths"),
+      serviceKey: flags.get("service-key"),
+      workflowPath: flags.get("workflow-path"),
+    });
+    const report = await writeSemanticWorkflow({ repoRoot, request });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (command === "semantic-inventory") {
+    const request = buildSemanticWorkflowRequestFromFlags({
+      framework: flags.get("framework"),
+      backendRootPath: flags.get("backend-root-path"),
+      allowedSourcePaths: flags.get("allowed-source-paths"),
+      excludedSourcePaths: flags.get("excluded-source-paths"),
+      serviceKey: flags.get("service-key"),
+      workflowPath: flags.get("workflow-path"),
+    });
+    const report = await runSemanticInventory({ repoRoot, request });
+    await writeJsonIfRequested({
+      repoRoot,
+      outputPath: flags.get("output"),
+      value: report,
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (command === "lifecycle-apply") {
+    const planPath = flags.get("plan");
+    if (typeof planPath !== "string") {
+      throw new Error("--plan is required");
+    }
+    const plan = await readJson(resolve(planPath));
+    const report = await applyLifecyclePlan({ repoRoot, plan });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (command === "setup-check") {
+    const hasInventoryFlags =
+      typeof flags.get("framework") === "string" &&
+      typeof flags.get("backend-root-path") === "string";
+    const request = hasInventoryFlags
+      ? buildSemanticWorkflowRequestFromFlags({
+          framework: flags.get("framework"),
+          backendRootPath: flags.get("backend-root-path"),
+          allowedSourcePaths: flags.get("allowed-source-paths"),
+          excludedSourcePaths: flags.get("excluded-source-paths"),
+          serviceKey: flags.get("service-key"),
+          workflowPath: flags.get("workflow-path"),
+        })
+      : undefined;
+    const report = await runSetupCheck({
+      repoRoot,
+      request,
+      target:
+        typeof flags.get("target") === "string"
+          ? flags.get("target")
+          : undefined,
+      requireSdkLifecycle: flags.has("require-sdk-lifecycle"),
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.passed) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const requestEnvName = flags.get("request-env");
+  if (typeof requestPath !== "string" && typeof requestEnvName !== "string") {
+    throw new Error("--request is required");
+  }
+  const request =
+    typeof requestEnvName === "string"
+      ? JSON.parse(process.env[requestEnvName] ?? "")
+      : await readJson(resolve(requestPath));
+
+  if (command === "init") {
+    const report = await runInitTool({ repoRoot, request });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (command === "semantic-ci") {
+    const previousSnapshotPath =
+      flags.get("previous-snapshot") ?? flags.get("previous-snapshot-file");
+    const previousSnapshot =
+      typeof previousSnapshotPath === "string"
+        ? await readJson(resolve(previousSnapshotPath))
+        : undefined;
+    const result = await runSemanticCi({
+      repoRoot,
+      request,
+      env: process.env,
+      previousSnapshot,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}\n${usage()}`);
 };
 
 main().catch((error) => {
-	process.stderr.write(
-		`${error instanceof Error ? error.message : String(error)}\n`,
-	);
-	process.exitCode = 1;
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
 });