@clue-ai/cli 0.0.13 → 0.0.15

package/README.md

@@ -62,13 +62,21 @@ leaks, and SDK lifecycle presence when requested. With
 installation, SDK imports in the target environments, app startup, and event
 delivery remain required before setup can be called complete.
 
-`npx -y @clue-ai/cli setup-watch` polls the Clue API setup-check endpoint while you operate
-the local service. `--clue-api-base-url` is the Clue API URL, not the customer
-frontend URL. Use `--watch-targets` to list every local frontend/backend app by
-service key and the lifecycle checks expected for that service, for example
+`npx -y @clue-ai/cli setup-watch` polls the Clue API setup-check endpoint in
+remote mode while you operate the service. `--clue-api-base-url` is the Clue API
+URL, not the customer frontend URL. Use `--watch-targets` to list every
+frontend/backend producer by service key and the lifecycle checks expected for
+that service, for example
 `frontend:web[init,identify,set-account,event-sent]=<frontend-url>,backend:api[init,identify,set-account,logout,event-sent]=<backend-url>`.
 Do not assume localhost ports; use the actual URLs printed by the repository's
 dev scripts or configured in its local env.
+In `--local` mode, the watcher stays open until the expected lifecycle checks
+pass or you stop it with Ctrl+C. The frontend/backend endpoint URLs printed by
+the command are local Clue receiver endpoints; configure the customer's Clue SDK
+ingest endpoint to those receiver URLs while testing. Local mode does not ask
+for or health-check customer service URLs. It prints a per-service Clue
+lifecycle checklist and only prints a new snapshot when the observed state
+changes.
 
 `npx -y @clue-ai/cli setup` reads Clue values from the setup screen flags, detects local
 services, writes `.clue/setup-manifest.json`, and prints service-specific env

package/bin/clue-cli.mjs

@@ -135,6 +135,15 @@ const DEFAULT_WATCH_LIFECYCLE = [
   "event-sent",
 ];
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const DEFAULT_REMOTE_SETUP_WATCH_TIMEOUT_MS = 120_000;
+
+const WATCH_LIFECYCLE_LABELS = new Map([
+  ["init", "ClueInit"],
+  ["identify", "ClueIdentify"],
+  ["set-account", "ClueSetAccount"],
+  ["logout", "ClueLogout"],
+  ["event-sent", "Event delivery"],
+]);
 
 const parseExpectedLifecycle = (value) => {
   if (typeof value !== "string" || !value.trim()) {
@@ -295,7 +304,18 @@ const maybeProtectEnvironmentGuide = async ({
   };
 };
 
-const confirmTargetUrls = async ({ flags, watchTargets, env }) => {
+const clearWatchTargetUrls = (watchTargets) =>
+  watchTargets.map((target) => ({
+    ...target,
+    url: null,
+    urlEnvName: null,
+    localUrlCandidates: [],
+  }));
+
+const confirmTargetUrls = async ({ flags, localMode, watchTargets, env }) => {
+  if (localMode) {
+    return clearWatchTargetUrls(watchTargets);
+  }
   const initialTargets = watchTargets.map((target) => ({
     ...target,
     url: resolveTargetUrlFromEnv({ target, env }),
@@ -333,6 +353,20 @@ const buildWatchProducerIds = ({ explicitProducerIds, watchTargets }) =>
     ...watchTargets.map((target) => target.producerId),
   ]);
 
+const parseSetupWatchTimeoutMs = ({ flags, localMode }) => {
+  if (!flags.has("timeout-ms")) {
+    return localMode ? null : DEFAULT_REMOTE_SETUP_WATCH_TIMEOUT_MS;
+  }
+  const timeoutMs = Number(flags.get("timeout-ms"));
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new Error("--timeout-ms must be a non-negative number");
+  }
+  return timeoutMs;
+};
+
+const isSetupWatchTimedOut = ({ started, timeoutMs }) =>
+  timeoutMs !== null && Date.now() - started > timeoutMs;
+
 const checkTargetUrl = async (url) => {
   if (!url) return { checked: true, reachable: false, status: null };
   try {
@@ -347,14 +381,20 @@ const checkTargetUrl = async (url) => {
   }
 };
 
-const evaluateWatchTargets = async ({ latest, watchTargets }) => {
+const evaluateWatchTargets = async ({
+  latest,
+  requireTargetUrl = true,
+  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 urlHealth = requireTargetUrl
+        ? await checkTargetUrl(target.url)
+        : { checked: false, reachable: true, status: null };
       const lifecycleStatus = {
         init: Boolean(producer?.clueInit ?? producer?.sdkInitialized),
         identify: Boolean(producer?.clueIdentify),
@@ -388,7 +428,7 @@ const evaluateWatchTargets = async ({ latest, watchTargets }) => {
         urlChecked: urlHealth.checked,
         urlReachable: urlHealth.reachable,
         urlStatus: urlHealth.status,
-        passed: producerPassed && urlHealth.reachable,
+        passed: producerPassed && (!requireTargetUrl || urlHealth.reachable),
       };
     }),
   );
@@ -543,25 +583,60 @@ const startLocalSetupReceiver = async ({ host, port }) => {
   };
 };
 
+const lifecycleLabel = (name) => WATCH_LIFECYCLE_LABELS.get(name) ?? name;
+
+const statusMark = (passed) => (passed ? "x" : " ");
+
+const lifecycleStatusText = (passed) => (passed ? "done!" : "pending...");
+
+const targetUrlStatusText = (target) => {
+  if (!target.urlChecked) return null;
+  return String(
+    target.urlReachable
+      ? target.urlStatus
+      : (target.urlStatus ?? "unreachable"),
+  );
+};
+
 const renderWatchTargets = (targetChecks) =>
   targetChecks
     .map((target) => {
-      const urlStatus = target.urlChecked
-        ? ` url:${target.urlReachable ? target.urlStatus : (target.urlStatus ?? "unreachable")}`
-        : "";
-      const lifecycle = target.expectedLifecycle
-        .map(
-          (name) =>
-            `${name}:${target.lifecycleStatus[name] ? "ok" : "waiting"}`,
-        )
-        .join(" ");
-      const unexpected = target.unexpectedLifecycle.length
-        ? ` unexpected:${target.unexpectedLifecycle.join(",")}`
-        : "";
-      return `${target.passed ? "[x]" : "[ ]"} ${target.kind}:${target.serviceKey} ${lifecycle} events:${target.eventCount}${urlStatus}${unexpected}`;
+      const lifecycleLines = target.expectedLifecycle.map((name) => {
+        const passed = Boolean(target.lifecycleStatus[name]);
+        return `  [${statusMark(passed)}] ${lifecycleLabel(name)} ${lifecycleStatusText(passed)}`;
+      });
+      const urlStatus = targetUrlStatusText(target);
+      const detailLines = [`  events: ${target.eventCount}`];
+      if (urlStatus !== null) {
+        detailLines.push(`  url: ${urlStatus}`);
+      }
+      if (target.unexpectedLifecycle.length) {
+        detailLines.push(
+          `  unexpected: ${target.unexpectedLifecycle.map(lifecycleLabel).join(", ")}`,
+        );
+      }
+      return [
+        `[${statusMark(target.passed)}] ${target.kind}:${target.serviceKey}`,
+        ...lifecycleLines,
+        ...detailLines,
+      ].join("\n");
     })
+    .join("\n\n");
+
+const renderSetupCheckEntries = (entries) =>
+  entries
+    .map(([id, status]) => `${status === "passed" ? "[x]" : "[ ]"} ${id}`)
     .join("\n");
 
+const joinRenderedSections = (...sections) =>
+  sections.filter((section) => section.trim()).join("\n\n");
+
+const writeChangedSetupWatchSnapshot = ({ rendered, state }) => {
+  if (!rendered || rendered === state.lastRendered) return;
+  process.stdout.write(`${rendered}\n\n`);
+  state.lastRendered = rendered;
+};
+
 const setupCheckUrl = ({
   clueApiBaseUrl,
   environment,
@@ -621,13 +696,14 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
   const startedAt = String(
     flags.get("started-at") || new Date().toISOString(),
   ).trim();
-  const timeoutMs = Number(flags.get("timeout-ms") || 120_000);
+  const timeoutMs = parseSetupWatchTimeoutMs({ flags, localMode });
   const pollIntervalMs = Number(flags.get("poll-interval-ms") || 3000);
   const limit = Number(flags.get("limit") || 200);
   const projectId = flags.get("project-id");
   const explicitWatchTargets = parseWatchTargets(flags.get("watch-targets"));
   const watchTargets = await confirmTargetUrls({
     flags,
+    localMode,
     watchTargets:
       explicitWatchTargets.length > 0
         ? explicitWatchTargets
@@ -639,6 +715,11 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
       "setup-watch requires --watch-targets or .clue/setup-manifest.json lifecycle_verification.watch_targets before setup can be treated as verified",
     );
   }
+  if (localMode && watchTargets.length === 0) {
+    throw new Error(
+      "setup-watch --local requires .clue/setup-manifest.json lifecycle_verification.watch_targets",
+    );
+  }
   const producerIds = buildWatchProducerIds({
     explicitProducerIds: flags.get("producer-ids"),
     watchTargets,
@@ -664,26 +745,38 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
           `Watching targets: ${watchTargets.map((target) => `${target.kind}:${target.serviceKey}`).join(", ")}\n`,
         );
       }
-      while (Date.now() - started <= timeoutMs) {
+      process.stdout.write(
+        timeoutMs === null
+          ? "No automatic timeout in local mode. Operate your local app, then press Ctrl+C to stop if needed.\n"
+          : `Timeout: ${timeoutMs}ms\n`,
+      );
+      const renderState = { lastRendered: "" };
+      while (!isSetupWatchTimedOut({ started, timeoutMs })) {
         latest = localSetupCheckSnapshot({
           receivedBatches: receiver.receivedBatches,
         });
         const targetChecks = await evaluateWatchTargets({
           latest,
+          requireTargetUrl: false,
           watchTargets,
         });
         const targetChecksPassed =
           targetChecks.length > 0 &&
           targetChecks.every((target) => target.passed);
         const renderedTargets = renderWatchTargets(targetChecks);
-        process.stdout.write(`${renderedTargets}\n\n`);
+        writeChangedSetupWatchSnapshot({
+          rendered: renderedTargets,
+          state: renderState,
+        });
         if (targetChecksPassed) {
           process.stdout.write("Clue local setup checks passed.\n");
           return { ...latest, local: true, watchTargets: targetChecks };
         }
         await sleep(pollIntervalMs);
       }
-      process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+      if (flags.has("json")) {
+        process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+      }
       throw new Error(
         "setup-watch --local timed out before all Clue setup checks passed",
       );
@@ -701,7 +794,8 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
     );
   }
 
-  while (Date.now() - started <= timeoutMs) {
+  const renderState = { lastRendered: "" };
+  while (!isSetupWatchTimedOut({ started, timeoutMs })) {
     const response = await fetch(
       setupCheckUrl({
         clueApiBaseUrl,
@@ -724,13 +818,12 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
     const targetChecks = await evaluateWatchTargets({ latest, watchTargets });
     const targetChecksPassed = targetChecks.every((target) => target.passed);
     const passed = setupChecksPassed && targetChecksPassed;
-    const rendered = entries
-      .map(([id, status]) => `${status === "passed" ? "[x]" : "[ ]"} ${id}`)
-      .join("\n");
+    const rendered = renderSetupCheckEntries(entries);
     const renderedTargets = renderWatchTargets(targetChecks);
-    process.stdout.write(
-      `${rendered}${renderedTargets ? `\n${renderedTargets}` : ""}\n\n`,
-    );
+    writeChangedSetupWatchSnapshot({
+      rendered: joinRenderedSections(rendered, renderedTargets),
+      state: renderState,
+    });
     if (passed) {
       process.stdout.write("Clue setup checks passed.\n");
       return { ...latest, watchTargets: targetChecks };
@@ -738,7 +831,9 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
     await sleep(pollIntervalMs);
   }
 
-  process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+  if (flags.has("json")) {
+    process.stdout.write(`${JSON.stringify(latest, null, 2)}\n`);
+  }
   throw new Error("setup-watch timed out before all Clue setup checks passed");
 };
 
@@ -753,7 +848,7 @@ const usage = () =>
     "",
     "Usage:",
     "  /clue-init",
-    `  ${clueCliCommand("setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev")}`,
+    `  ${clueCliCommand("setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment dev --documents-url <url>")}`,
     `  ${clueCliCommand("setup-detect --repo .")}`,
     `  ${clueCliCommand("semantic-inventory --framework fastapi --backend-root-path backend --repo .")}`,
     `  ${clueCliCommand("semantic-agent-skills --output .clue/semantic-agent-skills.json")}`,
@@ -827,6 +922,7 @@ const main = async () => {
   if (command === "setup") {
     const report = await installSetupSkills({
       repoRoot,
+      documentsUrl: flags.get("documents-url"),
       target:
         typeof flags.get("target") === "string"
           ? flags.get("target")
@@ -848,12 +944,13 @@ const main = async () => {
           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"),
-          },
+        setupContext: {
+          clueApiKey: flags.get("clue-api-key"),
+          clueApiBaseUrl: flags.get("clue-api-base-url"),
+          documentsUrl: flags.get("documents-url"),
+          projectKey: flags.get("project-key"),
+          environment: flags.get("environment"),
+        },
         });
     const environmentFileProtection =
       preEnvironmentFileProtection?.env_file_path ===

package/package.json

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

package/src/lifecycle-init.mjs

@@ -568,12 +568,19 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
       "Use environment variable names for Clue configuration values.",
       "For Python/FastAPI code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_API_KEY, and CLUE_INGEST_ENDPOINT from the backend env block.",
-      "CLUE_API_BASE_URL is for Clue CLI and semantic snapshot CI configuration, not backend SDK runtime configuration. Do not add it to application config unless existing non-Clue code already requires it.",
-      "For browser code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_SERVICE_KEY, and CLUE_INGEST_ENDPOINT from environment variables through the target framework's safe client config mechanism. Do not hard-code a Next.js-only prefix.",
+      "CLUE_API_BASE_URL is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
+      "For Next.js browser/client code, read NEXT_PUBLIC_CLUE_PROJECT_KEY, NEXT_PUBLIC_CLUE_ENVIRONMENT, NEXT_PUBLIC_CLUE_SERVICE_KEY, and NEXT_PUBLIC_CLUE_INGEST_ENDPOINT from the frontend .env.local block.",
+      "Do not read process.env.CLUE_PROJECT_KEY, process.env.CLUE_ENVIRONMENT, process.env.CLUE_SERVICE_KEY, or process.env.CLUE_INGEST_ENDPOINT in Next.js browser/client code, and do not add non-public CLUE_* fallbacks there.",
+      "For non-Next.js browser code, use the exact frontend env names written in .env.clue for that service instead of inventing a framework-specific prefix.",
       "Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
       "Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
+      "The local backend token endpoint is part of the customer app, not the Clue API. It may use the customer's route convention, but it must call Clue server-side at /api/v1/ingest/browser-tokens.",
+      "The frontend browserTokenProvider must send the same service key used by ClueInit to the customer backend token endpoint. For Next.js this value comes from NEXT_PUBLIC_CLUE_SERVICE_KEY.",
       "The browser token request must include project key, environment, service key, and the current browser origin; the backend must attach x-clue-api-key server-side when calling Clue.",
+      "For browser token proxy code, the service key sent to Clue must be the frontend ClueInit serviceKey from the browser request, not the backend service's CLUE_SERVICE_KEY.",
+      "If a backend-owned browser token endpoint is implemented, read CLUE_API_BASE_URL from the backend env block and normalize it so values with or without a trailing /api/v1 do not produce duplicate paths.",
+      "Do not add @clue-ai/browser-sdk or backend SDK dependencies with * or latest; use a concrete published version or package-manager-resolved semver range and update the repository lockfile when one exists.",
       "Prefer minimal edits that engineers can review in one PR.",
       "Do not run broad formatters, import sorters, cleanup tools, or style-only edits. Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring.",
       "If a lifecycle point is unclear, skip that edit and include a warning.",
@@ -584,13 +591,17 @@ const buildLifecyclePrompt = ({ request, files }) =>
       target_tool: request.target_tool,
       framework: request.framework,
       project_key_env: "CLUE_PROJECT_KEY",
-      browser_project_key_env: "CLUE_PROJECT_KEY",
+      browser_project_key_env: "framework_specific",
+      nextjs_browser_project_key_env: "NEXT_PUBLIC_CLUE_PROJECT_KEY",
       environment_env: "CLUE_ENVIRONMENT",
-      browser_environment_env: "CLUE_ENVIRONMENT",
+      browser_environment_env: "framework_specific",
+      nextjs_browser_environment_env: "NEXT_PUBLIC_CLUE_ENVIRONMENT",
       clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
       tooling_api_base_url_env: "CLUE_API_BASE_URL",
-      browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
+      browser_ingest_endpoint_env: "framework_specific",
+      nextjs_browser_ingest_endpoint_env: "NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
       browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
+      nextjs_browser_service_key_env: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
       service_key: request.service_key,
     },
     output_shape: {

package/src/public-schema.cjs

@@ -845,9 +845,23 @@ const semanticSnapshotRequestSchema = zod_1.z
         ], "semantic_meaning_candidates[].selection_ai_inference_evidence_ref");
     });
 });
+const semanticSnapshotResponseSchema = zod_1.z.object({
+    accepted: zod_1.z.literal(true),
+    duplicate: zod_1.z.boolean(),
+    semantic_snapshot_id: nonEmptyStringSchema,
+    route_count: zod_1.z.number().int().nonnegative(),
+    diff_summary: zod_1.z.object({
+        added_routes: zod_1.z.number().int().nonnegative(),
+        removed_routes: zod_1.z.number().int().nonnegative(),
+        changed_routes: zod_1.z.number().int().nonnegative(),
+        unchanged_routes: zod_1.z.number().int().nonnegative(),
+        low_confidence_routes: zod_1.z.number().int().nonnegative(),
+    }),
+});
 
   return {
     semanticSnapshotRequestSchema,
+    semanticSnapshotResponseSchema,
   };
 })();
 
@@ -855,6 +869,7 @@ const schemaPackage = {
   clueInitToolRequestSchema: toolingSchemas.clueInitToolRequestSchema,
   clueInitToolReportSchema: toolingSchemas.clueInitToolReportSchema,
   semanticSnapshotRequestSchema: semanticSchemas.semanticSnapshotRequestSchema,
+  semanticSnapshotResponseSchema: semanticSchemas.semanticSnapshotResponseSchema,
 };
 
 module.exports = schemaPackage;

package/src/semantic-ci.mjs

@@ -706,7 +706,7 @@ const FORBIDDEN_TARGET_TEXT_PATTERNS = [
   /\b[A-Za-z0-9_./-]+\.py\b/i,
   /\b(from\s+[A-Za-z_][A-Za-z0-9_.]*\s+import|import\s+[A-Za-z_][A-Za-z0-9_.]*)\b/i,
   /\b(class|def)\s+[A-Za-z_][A-Za-z0-9_]*/,
-  /\b(select|insert|update|delete)\s+.+\b(from|into|set)\b/i,
+  /\b(?:select\s+(?:\*|[a-z0-9_.,\s]+)\s+from|insert\s+into|update\s+[a-z0-9_."-]+\s+set|delete\s+from)\b/i,
   /\b(system|user|assistant)\s*:\s*.+\b(prompt|completion|transcript)\b/i,
   /\b[A-Z][A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY)\b(?:\s*=\s*["']?[^"'\s,;}]+)?/,
   /\b[A-Z][A-Z0-9_]{2,}\s*=\s*["']?[^"'\s,;}]+/,
@@ -1358,6 +1358,15 @@ const unresolvedEffect = ({
     .map((entry) => sanitizeText(entry.trim(), route)),
 });
 
+const findCatalogEntryByTargetObjectKey = (catalogByGroup, targetObjectKey) => {
+  for (const [mapKey, entry] of catalogByGroup.entries()) {
+    if (entry?.target_object_key === targetObjectKey) {
+      return { mapKey, entry };
+    }
+  }
+  return null;
+};
+
 const buildOperationAssignmentCollections = ({
   route,
   aiRoute,
@@ -1535,7 +1544,15 @@ const buildOperationAssignmentCollections = ({
     }
 
     const groupKey = `${concept.toLowerCase()}::${businessRole.toLowerCase()}`;
-    const existingCatalog = catalogByGroup.get(groupKey);
+    const existingCatalogByTarget = findCatalogEntryByTargetObjectKey(
+      catalogByGroup,
+      targetKeyCandidate,
+    );
+    const existingCatalog =
+      catalogByGroup.get(groupKey) ?? existingCatalogByTarget?.entry;
+    const catalogMapKey = catalogByGroup.has(groupKey)
+      ? groupKey
+      : (existingCatalogByTarget?.mapKey ?? groupKey);
     const targetObjectKey =
       existingCatalog?.target_object_key ?? targetKeyCandidate;
     const operationEffectKey = `${targetObjectKey}.${effectAction}`;
@@ -1706,7 +1723,7 @@ const buildOperationAssignmentCollections = ({
         catalogEntry.grouping_evidence_refs.push(ref);
       }
     }
-    catalogByGroup.set(groupKey, catalogEntry);
+    catalogByGroup.set(catalogMapKey, catalogEntry);
 
     mappings.push({
       id: mappingId,
@@ -1991,7 +2008,7 @@ const sanitizeText = (value, route) => {
   }
   result = result
     .replace(
-      /\b(select|insert|update|delete)\s+.+?\b(from|into|set)\b[^"',;}]+/gi,
+      /\b(?:select\s+(?:\*|[a-z0-9_.,\s]+)\s+from|insert\s+into|update\s+[a-z0-9_."-]+\s+set|delete\s+from)\b[^"',;}]+/gi,
       "[sql]",
     )
     .replace(
@@ -2036,25 +2053,80 @@ const sanitizeSemantics = (value, route) => {
     record && typeof record === "object" && !Array.isArray(record)
       ? record
       : {};
+  const routeConfidence = Number.isFinite(Number(safeRecord.route_confidence))
+    ? Math.max(0, Math.min(1, Number(safeRecord.route_confidence)))
+    : 0;
   return {
     route_summary:
       typeof safeRecord.route_summary === "string" &&
       safeRecord.route_summary.trim()
         ? safeRecord.route_summary
         : "unknown",
-    action_candidates: Array.isArray(safeRecord.action_candidates)
-      ? safeRecord.action_candidates
-      : [],
-    outcome_candidates: Array.isArray(safeRecord.outcome_candidates)
-      ? safeRecord.outcome_candidates
-      : [],
+    action_candidates: sanitizeSemanticCandidates(
+      safeRecord.action_candidates,
+      route,
+      routeConfidence,
+    ),
+    outcome_candidates: sanitizeSemanticCandidates(
+      safeRecord.outcome_candidates,
+      route,
+      routeConfidence,
+    ),
     value_event_candidates: [],
-    route_confidence: Number.isFinite(Number(safeRecord.route_confidence))
-      ? Math.max(0, Math.min(1, Number(safeRecord.route_confidence)))
-      : 0,
+    route_confidence: routeConfidence,
   };
 };
 
+const sanitizeSemanticCandidates = (value, route, routeConfidence) => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const label = sanitizeText(entry, route).trim();
+        return label
+          ? {
+              label,
+              confidence: routeConfidence > 0 ? routeConfidence : 0.5,
+            }
+          : null;
+      }
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return null;
+      }
+      const label =
+        typeof entry.label === "string" && entry.label.trim()
+          ? sanitizeText(entry.label, route).trim()
+          : "";
+      if (!label) {
+        return null;
+      }
+      const candidate = {
+        label,
+        confidence: Number.isFinite(Number(entry.confidence))
+          ? Math.max(0, Math.min(1, Number(entry.confidence)))
+          : routeConfidence > 0
+            ? routeConfidence
+            : 0.5,
+      };
+      for (const key of [
+        "subject_type",
+        "action_category",
+        "outcome_kind",
+        "value_kind",
+      ]) {
+        if (typeof entry[key] === "string" && entry[key].trim()) {
+          candidate[key] = sanitizeText(entry[key], route).trim();
+        } else if (entry[key] === null) {
+          candidate[key] = null;
+        }
+      }
+      return candidate;
+    })
+    .filter(Boolean);
+};
+
 const sanitizeForClueStorage = (value, route) => {
   if (typeof value === "string") {
     return sanitizeText(value, route);
@@ -2152,6 +2224,10 @@ const previousRouteMap = (previousSnapshot) =>
     ]),
   );
 
+const hasReusablePreviousRouteSemantics = (route) =>
+  Number(route?.semantics?.route_confidence ?? 0) > 0 &&
+  route?.semantics?.route_summary !== "unknown";
+
 const buildRouteEvidencePromptEntry = ({ route, hashScope }) => ({
   operation_source_key: route.operation_source_key,
   method: route.method,
@@ -2192,7 +2268,10 @@ const classifyRoutesForSnapshot = async ({
       continue;
     }
 
-    if (previousRoute.route_input_hash === currentHash) {
+    if (
+      previousRoute.route_input_hash === currentHash &&
+      hasReusablePreviousRouteSemantics(previousRoute)
+    ) {
       plans.set(route.operation_source_key, {
         origin: "unchanged_route_reused",
         route_input_hash: currentHash,
@@ -2206,6 +2285,21 @@ const classifyRoutesForSnapshot = async ({
       continue;
     }
 
+    if (previousRoute.route_input_hash === currentHash) {
+      plans.set(route.operation_source_key, {
+        origin: "changed_route_semantic_regenerated",
+        route_input_hash: currentHash,
+        previous_route: previousRoute,
+        previous_route_input_hash: previousRoute.route_input_hash,
+        previous_route_semantic_hash:
+          previousRoute.route_semantic_hash ?? routeSemanticHash(previousRoute),
+        semantic_change_reason:
+          "Previous route semantics had no reusable confidence, so the route was regenerated.",
+      });
+      routesRequiringGeneration.push(route);
+      continue;
+    }
+
     const decision = await callAiReuseDecisionProvider({
       request,
       env,
@@ -2483,7 +2577,8 @@ const FORBIDDEN_CODE_STRUCTURE_PATTERNS = [
   },
   {
     label: "raw sql",
-    pattern: /\b(select|insert|update|delete)\s+.+\b(from|into|set)\b/i,
+    pattern:
+      /\b(?:select\s+(?:\*|[a-z0-9_.,\s]+)\s+from|insert\s+into|update\s+[a-z0-9_."-]+\s+set|delete\s+from)\b/i,
   },
   {
     label: "raw prompt",
@@ -2627,6 +2722,9 @@ const fetchLatestSnapshot = async ({ request, env }) => {
     );
   }
   const body = await response.json();
+  if (body?.found === false && body?.snapshot === undefined) {
+    return null;
+  }
   const candidate = body?.snapshot ?? body;
   if (!candidate || !Array.isArray(candidate.routes)) {
     if (allowFullRegeneration) {
@@ -2664,7 +2762,16 @@ const sendSnapshot = async ({ request, env, snapshot }) => {
     body: JSON.stringify(validatedSnapshot),
   });
   if (!response.ok) {
-    throw new Error(`Clue semantic snapshot upload failed: ${response.status}`);
+    const responseBody =
+      typeof response.text === "function"
+        ? await response.text().catch(() => "")
+        : "";
+    const responseDetail = responseBody.trim()
+      ? `: ${responseBody.trim().slice(0, 1000)}`
+      : "";
+    throw new Error(
+      `Clue semantic snapshot upload failed: ${response.status}${responseDetail}`,
+    );
   }
   const body = await response.json();
   try {
@@ -2782,7 +2889,11 @@ export const runSemanticCi = async ({
   const previousRoutes = previousRouteMap(previousSnapshot);
   const routeNeedsAi = routes.some((route) => {
     const previousRoute = previousRoutes.get(route.operation_source_key);
-    return !previousRoute || previousRoute.route_input_hash !== routeInputHash(route);
+    return (
+      !previousRoute ||
+      previousRoute.route_input_hash !== routeInputHash(route) ||
+      !hasReusablePreviousRouteSemantics(previousRoute)
+    );
   });
   if (routeNeedsAi && !env.CLUE_AI_PROVIDER_API_KEY) {
     throw new Error("CLUE_AI_PROVIDER_API_KEY is required for semantic generation");