@clue-ai/cli 0.0.14 → 0.0.15

package/README.md

@@ -62,16 +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. It prints a per-service Clue lifecycle
-checklist and only prints a new snapshot when the observed state changes.
+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

@@ -304,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 }),
@@ -370,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),
@@ -411,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),
       };
     }),
   );
@@ -686,6 +703,7 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
   const explicitWatchTargets = parseWatchTargets(flags.get("watch-targets"));
   const watchTargets = await confirmTargetUrls({
     flags,
+    localMode,
     watchTargets:
       explicitWatchTargets.length > 0
         ? explicitWatchTargets
@@ -739,6 +757,7 @@ const runSetupWatch = async ({ flags, repoRoot = ".", env = process.env }) => {
         });
         const targetChecks = await evaluateWatchTargets({
           latest,
+          requireTargetUrl: false,
           watchTargets,
         });
         const targetChecksPassed =
@@ -829,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")}`,
@@ -903,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")
@@ -924,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.14",
+  "version": "0.0.15",
   "type": "module",
   "bin": {
     "clue-ai": "bin/clue-cli.mjs"

package/src/lifecycle-init.mjs

@@ -575,7 +575,10 @@ const buildLifecyclePrompt = ({ request, files }) =>
       "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.",

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");

package/src/setup-check.mjs

@@ -27,7 +27,7 @@ const SETUP_SKILLS = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v3";
+const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v4";
 const REQUIRED_SETUP_SKILL_PHRASES = {
   "clue-sdk-instrumentation": [
     "Do not create no-op wrappers",
@@ -40,6 +40,8 @@ const REQUIRED_SETUP_SKILL_PHRASES = {
     "CLUE_API_BASE_URL` is not part of backend SDK initialization",
     "Do not add `@clue-ai/browser-sdk` or backend SDK dependencies with `*` or `latest`",
     "Whitespace-only changes are allowed only on lines directly changed for Clue SDK wiring",
+    "The local backend token endpoint is part of the customer app, not the Clue API",
+    "The frontend `browserTokenProvider` must send the same service key used by `ClueInit`",
     "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable",
   ],
   "clue-setup-audit": [
@@ -335,7 +337,9 @@ const readAllowedSourceText = async ({
 
 const readDependencyText = async ({ repoRoot, roots }) => {
   const expandedRoots = roots.flatMap((root) =>
-    root.endsWith("/src") ? [root, dirname(root)] : [root],
+    root.endsWith("/src") || root.endsWith("/app")
+      ? [root, dirname(root)]
+      : [root],
   );
   const candidatePaths = [
     ...DEPENDENCY_FILE_CANDIDATES,
@@ -764,6 +768,65 @@ const findWildcardFrontendSdkDependencyFiles = (dependencySources) =>
     })
     .map((source) => source.file_path);
 
+const sourceLooksLikeBrowserTokenProvider = (source) => {
+  const text = stripSourceNoise(source.text);
+  return (
+    sourceImportsFrontendSdk(source) &&
+    /browserTokenProvider|browser[-_]?tokens/i.test(text)
+  );
+};
+
+const findBrowserTokenProviderMissingServiceKeyFiles = (frontendSources) =>
+  frontendSources
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      if (/body\s*:\s*JSON\.stringify\s*\(\s*{\s*}\s*\)/.test(text)) {
+        return true;
+      }
+      return !/body\s*:\s*JSON\.stringify\s*\(\s*{[^}]*\b(?:service_key|serviceKey)\b/.test(
+        text,
+      );
+    })
+    .map((source) => source.file_path);
+
+const findNextBrowserTokenProviderMissingPublicServiceKeyFiles = ({
+  dependencySources,
+  frontendSources,
+}) => {
+  const roots = nextPackageRoots(dependencySources);
+  if (roots.length === 0) return [];
+  return frontendSources
+    .filter((source) => sourceIsUnderAnyRoot(source, roots))
+    .filter(sourceLooksLikeBrowserTokenProvider)
+    .filter(
+      (source) =>
+        !/\bprocess\.env\.NEXT_PUBLIC_CLUE_SERVICE_KEY\b/.test(source.text),
+    )
+    .map((source) => source.file_path);
+};
+
+const sourceLooksLikeBrowserTokenProxy = (source) => {
+  const text = stripSourceNoise(source.text);
+  return (
+    /browser[-_]?tokens|ingest\/browser-tokens/i.test(text) &&
+    /CLUE_API_KEY|x-clue-api-key/i.test(text)
+  );
+};
+
+const findBrowserTokenProxyUsingBackendServiceKeyFiles = (backendSources) =>
+  backendSources
+    .filter(sourceLooksLikeBrowserTokenProxy)
+    .filter((source) => {
+      const text = stripSourceNoise(source.text);
+      return [
+        /["']service_key["']\s*:\s*[^,\n}]*CLUE_SERVICE_KEY\b/i,
+        /\bserviceKey\s*:\s*[^,\n}]*CLUE_SERVICE_KEY\b/i,
+        /\b(?:browser_)?service_key\s*=\s*[^,\n]*CLUE_SERVICE_KEY\b/i,
+      ].some((pattern) => pattern.test(text));
+    })
+    .map((source) => source.file_path);
+
 const backendSdkSpec = (framework) =>
   BACKEND_SDK_BY_FRAMEWORK[String(framework ?? "").toLowerCase()] ?? {
     packages: Object.values(BACKEND_SDK_BY_FRAMEWORK).flatMap(
@@ -882,6 +945,15 @@ const checkSdkLifecycle = ({
   });
   const wildcardFrontendSdkDependencyFiles =
     findWildcardFrontendSdkDependencyFiles(dependencySources);
+  const browserTokenProviderMissingServiceKeyFiles =
+    findBrowserTokenProviderMissingServiceKeyFiles(frontendSources);
+  const nextBrowserTokenProviderMissingPublicServiceKeyFiles =
+    findNextBrowserTokenProviderMissingPublicServiceKeyFiles({
+      dependencySources,
+      frontendSources,
+    });
+  const browserTokenProxyUsingBackendServiceKeyFiles =
+    findBrowserTokenProxyUsingBackendServiceKeyFiles(backendSources);
   const backendIdentityRequired =
     backendPresent &&
     /\b(login|signin|sign_in|auth|token|session)\b/i.test(backendCombined);
@@ -940,6 +1012,12 @@ const checkSdkLifecycle = ({
       wrong_sdk_packages: wrongFrontendSdkPackages,
       next_lifecycle_non_public_env_files: nextLifecycleNonPublicEnvFiles,
       wildcard_sdk_dependency_files: wildcardFrontendSdkDependencyFiles,
+      browser_token_provider_missing_service_key_files:
+        browserTokenProviderMissingServiceKeyFiles,
+      next_browser_token_provider_missing_public_service_key_files:
+        nextBrowserTokenProviderMissingPublicServiceKeyFiles,
+      browser_token_proxy_uses_backend_service_key_files:
+        browserTokenProxyUsingBackendServiceKeyFiles,
     },
     has_noop_wrapper: noOpPattern.test(combined),
     component_lifecycle_init_files: componentLifecycleInitFiles,
@@ -958,6 +1036,9 @@ const checkSdkLifecycle = ({
       wrongFrontendSdkPackages.length === 0 &&
       nextLifecycleNonPublicEnvFiles.length === 0 &&
       wildcardFrontendSdkDependencyFiles.length === 0 &&
+      browserTokenProviderMissingServiceKeyFiles.length === 0 &&
+      nextBrowserTokenProviderMissingPublicServiceKeyFiles.length === 0 &&
+      browserTokenProxyUsingBackendServiceKeyFiles.length === 0 &&
       !noOpPattern.test(combined) &&
       componentLifecycleInitFiles.length === 0 &&
       blockingLifecycleFiles.length === 0,

package/src/setup-documents.mjs

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

package/src/setup-help.mjs

@@ -2,8 +2,9 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
-export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v3";
+export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v4";
 
 export const buildAiSetupHelp = () => ({
   name: "@clue-ai/cli AI setup help",
@@ -55,9 +56,10 @@ export const buildAiSetupHelp = () => ({
       },
       backend_browser_token_proxy_env: {
         variables: ["CLUE_API_KEY", "CLUE_API_BASE_URL"],
-        rule: "CLUE_API_KEY stays server-side. CLUE_API_BASE_URL is used only by backend-owned browser token proxy code and is not part of backend SDK initialization.",
+        rule: "CLUE_API_KEY stays server-side. CLUE_API_BASE_URL is used only by backend-owned browser token proxy code and is not part of backend SDK initialization. The proxy endpoint belongs to the customer backend, but it calls the Clue API server-side at /api/v1/ingest/browser-tokens. The frontend browserTokenProvider must send the frontend ClueInit serviceKey to that customer backend proxy, and the proxy must issue browser tokens for that frontend serviceKey, not the backend service key.",
       },
     },
+    documentation_contract: buildSetupDocumentationContract(),
     setup_watch: {
       owner: "user",
       ai_agent_must_run: false,

package/src/setup-prepare.mjs

@@ -8,6 +8,7 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
@@ -167,6 +168,7 @@ const aiProviderGuideForTarget = (target) =>
 const setupContextFromInput = (input = {}) => ({
   clue_api_key: optionalString(input.clueApiKey),
   clue_api_base_url: optionalString(input.clueApiBaseUrl),
+  documents_url: optionalString(input.documentsUrl),
   project_key: optionalString(input.projectKey),
   environment: optionalString(input.environment),
 });
@@ -386,10 +388,22 @@ export const runSetupPrepare = async ({
   const detection = await runSetupDetect({ repoRoot: resolvedRepoRoot });
   const { candidate, blockers } = firstCandidateOrBlocker(detection);
   if (!candidate) {
+    const detectedFrameworks = [
+      ...(Array.isArray(detection.services?.frontend)
+        ? detection.services.frontend.map((service) => service.framework)
+        : []),
+      ...(Array.isArray(detection.services?.backend)
+        ? detection.services.backend.map((service) => service.framework)
+        : []),
+    ];
     const manifest = {
       status: "blocked",
       target,
       skill_root: skillRoot,
+      documentation: buildSetupDocumentationContract({
+        documentsUrl: setupContext.documents_url,
+        frameworks: detectedFrameworks,
+      }),
       blockers,
       detection,
       ai_next_scope: "blocked_until_backend_routes_are_detected",
@@ -435,6 +449,10 @@ export const runSetupPrepare = async ({
     request,
   });
   const watchTargets = buildWatchTargets(detection, candidate);
+  const detectedFrameworks = [
+    candidate.framework,
+    ...watchTargets.map((target) => target.framework),
+  ];
   const frontendRuntimeEnvNames = requiredFrontendEnvNames(watchTargets);
   const backendRuntimeEnvNames = requiredBackendEnvNames(watchTargets);
   const serviceRuntimeEnvNames = [
@@ -450,6 +468,11 @@ export const runSetupPrepare = async ({
       backend_root_path: candidate.backend_root_path,
       service_key: candidate.service_key,
     },
+    documentation: buildSetupDocumentationContract({
+      documentsUrl: setupContext.documents_url,
+      framework: candidate.framework,
+      frameworks: detectedFrameworks,
+    }),
     service_identity: {
       canonical_field: "service_key",
       backend_env_name: "CLUE_SERVICE_KEY",

package/src/setup-tool.mjs

@@ -7,9 +7,11 @@ import {
   CLUE_CLI_RECOMMENDED_PREFIX,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
 const SKILL_NAMES = [
   "clue-setup-orchestrator",
+  "clue-setup-reference",
   "clue-route-semantic-snapshot",
   "clue-semantic-gen",
   "clue-sdk-instrumentation",
@@ -17,7 +19,7 @@ const SKILL_NAMES = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v3";
+const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v4";
 
 const TARGETS = new Set(["codex", "claude_code"]);
 
@@ -37,10 +39,21 @@ const normalizeTarget = (target) => {
   return normalized;
 };
 
-const skillBody = (name) => {
+const skillBody = (name, { documentsUrl } = {}) => {
+  const documentationContract = buildSetupDocumentationContract({
+    documentsUrl,
+  });
+  const requiredDocIds = documentationContract.required_doc_ids.join(", ");
+  const frameworkDocIds = Object.entries(
+    documentationContract.framework_doc_ids_by_framework,
+  )
+    .map(([framework, docId]) => `${framework} -> ${docId}`)
+    .join(", ");
   const descriptions = {
     "clue-setup-orchestrator":
       "Use first when running Clue setup so lifecycle placement remains the only implementation workstream and read-only checks stay separate.",
+    "clue-setup-reference":
+      "Use before Clue setup implementation to read the public setup documents contract, select framework-specific docs, and record consulted document ids.",
     "clue-route-semantic-snapshot":
       "Use when checking backend route coverage and semantic snapshot readiness without hand-authoring generated snapshot files.",
     "clue-semantic-gen":
@@ -58,6 +71,8 @@ const skillBody = (name) => {
   const agentRoles = {
     "clue-setup-orchestrator":
       "Coordinator agent. Owns sequencing, agent assignment, gates, and blocker handling. It must not edit product code directly.",
+    "clue-setup-reference":
+      "Documentation reference agent. Owns reading the Clue setup docs contract, selecting relevant document ids, and reporting documentation blockers. It must not edit product code.",
     "clue-route-semantic-snapshot":
       "Semantic route readiness agent. Owns backend route inventory/readiness validation only. It must not author generated snapshot content or SDK code.",
     "clue-semantic-gen":
@@ -75,10 +90,18 @@ const skillBody = (name) => {
   const owns = {
     "clue-setup-orchestrator": [
       "read `.clue/setup-manifest.json` first",
+      "require `clue-setup-reference` before any SDK lifecycle placement",
       "assign exactly one implementation agent for SDK lifecycle placement",
       "assign multiple read-only monitoring agents",
       "stop on manifest blockers or P0/P1 findings",
     ],
+    "clue-setup-reference": [
+      "read `.clue/setup-manifest.json` documentation contract",
+      "open the public setup documents URL when tool access allows it",
+      "select required lifecycle docs and the detected framework doc",
+      "report documentation_access_blocked when docs cannot be opened",
+      "produce consulted_document_ids for downstream implementation and final report",
+    ],
     "clue-route-semantic-snapshot": [
       "backend route discovery readiness",
       "route coverage gaps and unsupported-framework blockers",
@@ -122,6 +145,12 @@ const skillBody = (name) => {
       "merge workstreams into one broad task",
       "continue after a blocker without reporting it",
     ],
+    "clue-setup-reference": [
+      "edit product code",
+      "infer setup behavior from memory when the docs contract is available",
+      "skip framework-specific docs when a framework doc id is available",
+      "claim docs were read without listing consulted_document_ids",
+    ],
     "clue-route-semantic-snapshot": [
       "create SDK lifecycle calls",
       "create or edit the CI workflow",
@@ -161,6 +190,12 @@ const skillBody = (name) => {
       "agent plan with execution agents, monitoring agents, file ownership, and gate order",
       "blocker list if setup cannot proceed",
     ],
+    "clue-setup-reference": [
+      "documentation readiness result: ready or blocked",
+      "documents_url used",
+      "consulted_document_ids or documentation_access_blocked reason",
+      "framework document id selected from the manifest",
+    ],
     "clue-route-semantic-snapshot": [
       "route readiness result: ready or blocked",
       "route coverage evidence and blocker details",
@@ -198,18 +233,32 @@ const skillBody = (name) => {
       "Use multiple monitoring agents for read-only checks, or named review passes if subagents are unavailable.",
       `The initial \`${clueCliCommand("setup --clue-api-key <key> --clue-api-base-url <url> --project-key <key> --environment <environment>")}\` command already performs repository discovery, semantic CI workflow generation, setup manifest generation, and writes service-specific environment guidance to \`.env.clue\` when backend routes can be detected.`,
       "Before implementation, read `.clue/setup-manifest.json` and treat it as the mechanical setup source of truth.",
+      "Read `.clue/setup-manifest.json` `documentation` and run `clue-setup-reference` before assigning SDK lifecycle placement.",
       "Read `.clue/setup-manifest.json` `cli_invocation` before running any Clue CLI subcommand.",
       `Before editing a customer repository, run \`${clueCliCommand("help --json")}\` and follow its setup_execution_contract.`,
       "Use the service keys and watch targets from `.clue/setup-manifest.json`; do not invent service keys.",
       "If `.clue/setup-manifest.json` has status `blocked`, stop and report its blockers instead of guessing.",
       "Treat semantic snapshot readiness and semantic CI as generated/static verification surfaces, not AI implementation workstreams.",
       "Do not implement or refresh semantic snapshot CI during lifecycle placement; report a blocker if generated semantic artifacts are missing or stale.",
+      "Before lifecycle placement, require `clue-setup-reference` to produce consulted_document_ids.",
       "Before lifecycle placement, read and apply `clue-sdk-instrumentation`.",
       "After lifecycle placement, run a monitoring check with `clue-setup-audit` before continuing.",
       "For final local verification, read and apply `clue-local-verification`.",
       "For the final report, read and apply `clue-setup-report`.",
       "Do not continue past P0/P1 monitoring findings until fixed or reported as blocked.",
     ],
+    "clue-setup-reference": [
+      "Read `.clue/setup-manifest.json` first.",
+      "Find the `documentation` object. If it is missing, run `npx -y @clue-ai/cli help --json` and use `setup_execution_contract.documentation_contract` as the fallback contract.",
+      "Use `documentation.documents_url` as the public docs page.",
+      "Open the docs page when the AI tool has browser or HTTP access. If it cannot be opened, continue only from the generated skill text and manifest doc ids, then report `documentation_access_blocked`.",
+      "Read all ids in `documentation.required_doc_ids` that apply to the detected repository.",
+      "For framework-specific implementation, select ids from `documentation.selected_framework_doc_ids` first. If empty, use `documentation.framework_doc_ids_by_framework` for the detected framework.",
+      "Minimum lifecycle docs before implementation: ai-setup-order, environment-and-secrets, browser-token-endpoint, clue-init, clue-identify, clue-set-account, clue-logout, setup-verification, forbidden-patterns.",
+      "For Next.js, read framework-nextjs. For React, Vite, Vue, or Angular browser apps, read framework-react-spa. For FastAPI, read framework-fastapi. For Django, read framework-django.",
+      "Return `consulted_document_ids` to the orchestrator and final report.",
+      "If a document contradicts `.clue/setup-manifest.json` or generated skills, stop and report a blocker instead of choosing behavior silently.",
+    ],
     "clue-route-semantic-snapshot": [
       "Use this skill as the source of truth for semantic snapshot readiness and route coverage verification.",
       "Do not hand-author semantic snapshot content files.",
@@ -251,6 +300,7 @@ const skillBody = (name) => {
     ],
     "clue-sdk-instrumentation": [
       "Use this skill as the source of truth for Clue SDK lifecycle implementation.",
+      "Before editing, confirm `clue-setup-reference` has produced consulted_document_ids for the relevant framework and lifecycle docs.",
       "The implementation scope is only ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout placement in existing lifecycle boundaries.",
       "Keep SDK lifecycle implementation separate from semantic snapshot and CI workflow work.",
       "Do not create semantic snapshot content or semantic snapshot CI workflow files from this skill.",
@@ -272,7 +322,10 @@ const skillBody = (name) => {
       "Never put `CLUE_API_KEY` in frontend code, frontend env files, browser bundles, or client-readable config.",
       "When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side `CLUE_API_KEY` and requests `POST /api/v1/ingest/browser-tokens` from Clue.",
       "Configure frontend `ClueInit` with `browserTokenProvider` that calls the local backend token endpoint and returns the token string.",
+      "The local backend token endpoint is part of the customer app, not the Clue API. It may be named with the customer app'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.",
       "For FastAPI code, add `clue-fastapi-sdk` to the backend dependency file when missing, import `clue_init_fastapi` plus `ClueIdentify`, `ClueSetAccount`, and `ClueLogout` where needed, and use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_API_KEY`, and `CLUE_INGEST_ENDPOINT` from the backend env block.",
       "`CLUE_API_BASE_URL` is not part of backend SDK initialization. Use it only when the application backend owns a browser-token proxy for a frontend service.",
@@ -294,6 +347,7 @@ const skillBody = (name) => {
     ],
     "clue-setup-audit": [
       "Act as a read-only monitoring agent, not the execution agent.",
+      "Confirm the final report draft includes consulted_document_ids and that lifecycle edits do not contradict the referenced docs.",
       "Check one completed workstream at a time and report P0/P1 issues before more implementation continues.",
       "Review changed files line by line.",
       "Verify semantic snapshot, semantic CI, and SDK lifecycle responsibilities did not bleed into each other.",
@@ -318,6 +372,7 @@ const skillBody = (name) => {
     ],
     "clue-local-verification": [
       "Act as a read-only monitoring agent for local verification evidence.",
+      "Confirm documentation_access_blocked is reported if docs could not be opened, and do not treat that as event delivery verification.",
       "Verify each workstream independently before the final setup report.",
       "Confirm generated skill files exist.",
       "Confirm workflow files and SDK lifecycle imports/calls exist when those phases have run.",
@@ -341,6 +396,7 @@ const skillBody = (name) => {
     "clue-setup-report": [
       "Use this skill only after execution and monitoring passes are finished.",
       "Never claim `setup completed` from `setup-check --require-sdk-lifecycle` alone. That check is static and does not verify dependency installation, imports, app startup, or event delivery.",
+      "Include `consulted_document_ids` from `clue-setup-reference`; if docs could not be opened, include `documentation_access_blocked` with the reason.",
       "Completion requires all applicable evidence: SDK dependencies install successfully, SDK imports work in the target frontend/backend environments, the app starts, `setup-check --require-sdk-lifecycle` passes, and user-provided `setup-watch --local` or Clue setup screen evidence confirms expected event delivery.",
       "If any SDK package is unpublished, install/import checks were not run, app startup was not verified, or user-operated setup-watch/setup-screen evidence was not provided, the final status must be `blocked`, `partially complete`, or `user_verification_pending`; it must not be `complete`.",
       "For every completion claim, include the evidence source: command, exit status, output summary, file path, runtime URL, user-provided setup-watch result, or user-provided setup-screen result.",
@@ -386,11 +442,16 @@ const skillBody = (name) => {
     `- Use \`${CLUE_CLI_RECOMMENDED_PREFIX} <command>\` for Clue CLI commands unless \`.clue/setup-manifest.json\` explicitly provides a different invocation.`,
     `- If checking Clue CLI availability, run \`${CLUE_CLI_RECOMMENDED_PREFIX} --version\` or \`${CLUE_CLI_RECOMMENDED_PREFIX} --help\` and report the exact fetch/runtime error if it fails.`,
     `- Before editing a customer repository, run \`${clueCliCommand("help --json")}\` and follow its setup_execution_contract.`,
+    `- Public Clue setup docs: \`${documentationContract.documents_url}\`.`,
+    `- Required setup doc ids: ${requiredDocIds}.`,
+    `- Framework setup doc mapping: ${frameworkDocIds}.`,
+    "- Before editing, read `.clue/setup-manifest.json` `documentation`, run `clue-setup-reference`, and carry `consulted_document_ids` into the final report.",
     `- Do not search for a global \`${CLUE_CLI_BINARY_NAME}\` binary or block on \`which ${CLUE_CLI_BINARY_NAME}\`; missing global binary is normal.`,
     "- The AI implementation task is only to decide where ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout belong in existing code and apply the minimal SDK wiring for those calls.",
     "- Only exact changes required to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout are allowed. Do not perform ClueTrack instrumentation unless the user explicitly requested product event tracking.",
     "- Do not perform unrelated refactors, renames, file moves, formatting churn, broad cleanup, business logic rewrites, auth/session rewrites beyond minimal Clue hook insertion, UI changes unrelated to Clue setup, or unrelated dependency upgrades.",
     "- Do not run broad formatters or make whitespace-only cleanup. Keep formatting changes limited to lines directly touched for Clue SDK wiring.",
+    "- A customer backend browser-token endpoint is only a proxy for browser SDK token issuance. It is not the Clue API itself; the backend must call Clue server-side at `/api/v1/ingest/browser-tokens` with the frontend `ClueInit` service key supplied by the browser token provider.",
     "- Do not implement or refresh semantic snapshot CI during lifecycle placement; report a blocker if generated semantic artifacts are missing or stale.",
     `- Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch and the Clue setup screen are user-operated verification steps, not implementation-agent responsibility.`,
     "- The full setup must start with `clue-setup-orchestrator`.",
@@ -432,6 +493,7 @@ const askTarget = async ({
 export const installSetupSkills = async ({
   repoRoot,
   target,
+  documentsUrl,
   input,
   output,
 } = {}) => {
@@ -449,7 +511,7 @@ export const installSetupSkills = async ({
     const skillDir = join(skillRoot, skillName);
     const skillPath = join(skillDir, "SKILL.md");
     await mkdir(skillDir, { recursive: true });
-    await writeFile(skillPath, skillBody(skillName), "utf8");
+    await writeFile(skillPath, skillBody(skillName, { documentsUrl }), "utf8");
     installed.push(skillPath);
   }