@clue-ai/cli 0.0.8 → 0.0.10

package/src/setup-help.mjs

@@ -0,0 +1,69 @@
+import {
+  CLUE_CLI_INVOCATION_CONTRACT,
+  clueCliCommand,
+} from "./cli-invocation.mjs";
+
+export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v1";
+
+export const buildAiSetupHelp = () => ({
+  name: "@clue-ai/cli AI setup help",
+  version: AI_SETUP_HELP_VERSION,
+  purpose:
+    "Machine-readable Clue setup contract for AI coding agents. Use this before editing a customer repository for Clue setup.",
+  cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
+  setup_execution_contract: {
+    agent_primary_task:
+      "Decide where to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing repository lifecycle boundaries, then apply only those minimal Clue SDK wiring changes.",
+    implementation_workstreams: ["sdk_lifecycle_placement"],
+    lifecycle_apis_in_scope: [
+      "ClueInit",
+      "ClueIdentify",
+      "ClueSetAccount",
+      "ClueLogout",
+    ],
+    lifecycle_apis_out_of_scope_by_default: ["ClueTrack"],
+    allowed_change_scope: {
+      rule: "Only changes required to place ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout are allowed.",
+      allowed: [
+        "Clue SDK dependency declarations and lockfile changes needed to install those SDKs",
+        "Clue SDK imports, bootstrap adapters, and single initialization points",
+        "backend-owned browser token endpoints required so frontend SDK code never exposes CLUE_API_KEY",
+        "Clue lifecycle calls at existing clear login, logout, account, workspace, organization, or tenant boundaries",
+        "tests or verification scripts directly proving the four lifecycle API placement decisions",
+      ],
+      forbidden: [
+        "ClueTrack instrumentation unless the user explicitly requested product event tracking",
+        "semantic snapshot implementation or CI workflow edits during lifecycle placement",
+        "unrelated refactors, renames, file moves, formatting churn, or broad cleanup",
+        "business logic changes that are not required for Clue setup",
+        "auth/session flow rewrites beyond the minimal Clue hook insertion point",
+        "UI layout, styling, copy, or navigation changes unrelated to Clue setup",
+        "dependency upgrades unrelated to Clue SDK installability",
+        "hand-authored semantic snapshot artifacts or runtime request files",
+      ],
+    },
+    setup_watch: {
+      owner: "user",
+      ai_agent_must_run: false,
+      command: clueCliCommand("setup-watch --local"),
+      rule: "Do not run setup-watch during implementation. setup-watch and the Clue setup screen require user-operated local services and real login/logout/account flows.",
+      ai_agent_responsibility:
+        "Report the command and required user verification as pending when it was not run by the user.",
+    },
+    completion_boundary: {
+      ai_may_claim: [
+        "Clue setup code changes were applied",
+        "static setup-check passed",
+        "SDK dependency install/import/build/typecheck checks passed when actually run",
+      ],
+      ai_must_not_claim: [
+        "setup completed",
+        "event delivery verified",
+        "setup-watch passed",
+        "Clue setup screen verification passed",
+      ],
+      final_status_when_setup_watch_not_user_verified:
+        "user_verification_pending",
+    },
+  },
+});

package/src/setup-prepare.mjs

@@ -4,6 +4,10 @@ import {
   buildSemanticWorkflowRequestFromFlags,
   writeSemanticWorkflow,
 } from "./init-tool.mjs";
+import {
+  CLUE_CLI_INVOCATION_CONTRACT,
+  clueCliCommand,
+} from "./cli-invocation.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
@@ -222,6 +226,9 @@ const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
         },
       ],
       variables: [
+        { name: "CLUE_PROJECT_KEY", value: setupContext.project_key },
+        { name: "CLUE_ENVIRONMENT", value: setupContext.environment },
+        { name: "CLUE_API_BASE_URL", value: setupContext.clue_api_base_url },
         {
           name: "CLUE_AI_PROVIDER",
           value: aiProviderGuide.provider,
@@ -282,8 +289,7 @@ const summarizeEnvironmentInstructions = (instructions) => {
   return {
     status: "ready",
     env_file_path: instructions.env_file_path,
-    message:
-      `${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets に反映してください。`,
+    message: `${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets に反映してください。`,
     service_env_block_count: instructions.service_env_blocks.length,
     github_secret_names: instructions.ci_github.secrets.map(
       (entry) => entry.name,
@@ -326,8 +332,18 @@ export const runSetupPrepare = async ({
       ai_next_scope: "blocked_until_backend_routes_are_detected",
       machine_owned_artifacts: [],
       ai_owned_workstreams: [
-        "sdk_lifecycle_implementation_after_blockers_are_resolved",
+        "sdk_lifecycle_placement_after_blockers_are_resolved",
       ],
+      ai_implementation_scope: {
+        rule: "AI implementation is limited to placing ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing lifecycle boundaries after blockers are resolved.",
+        lifecycle_apis: [
+          "ClueInit",
+          "ClueIdentify",
+          "ClueSetAccount",
+          "ClueLogout",
+        ],
+        out_of_scope_by_default: ["ClueTrack"],
+      },
     };
     await writeJson({
       repoRoot: resolvedRepoRoot,
@@ -340,8 +356,9 @@ export const runSetupPrepare = async ({
     });
     return {
       ...manifest,
-      environment_instructions:
-        summarizeEnvironmentInstructions(environmentInstructions),
+      environment_instructions: summarizeEnvironmentInstructions(
+        environmentInstructions,
+      ),
     };
   }
 
@@ -349,9 +366,6 @@ export const runSetupPrepare = async ({
     framework: candidate.framework,
     backendRootPath: candidate.backend_root_path,
     serviceKey: candidate.service_key,
-    projectKey: setupContext.project_key,
-    environment: setupContext.environment,
-    clueApiBaseUrl: setupContext.clue_api_base_url,
   });
   const workflow = await writeSemanticWorkflow({
     repoRoot: resolvedRepoRoot,
@@ -373,6 +387,7 @@ export const runSetupPrepare = async ({
       frontend_env_name: "CLUE_SERVICE_KEY",
       producer_id_derivation: "producer_id defaults to service_key",
     },
+    cli_invocation: CLUE_CLI_INVOCATION_CONTRACT,
     clue_context: {
       project_key: setupContext.project_key,
       environment: setupContext.environment,
@@ -391,9 +406,11 @@ export const runSetupPrepare = async ({
         : null,
     },
     lifecycle_verification: {
+      owner: "user",
+      ai_agent_must_run_setup_watch: false,
       watch_target_format:
         "frontend:<service-key>[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>",
-      rule: "setup-watch --local uses the structured watch_targets below. Lifecycle checks are fixed for setup verification and are evaluated per service_key.",
+      rule: "setup-watch --local uses the structured watch_targets below, but it is user-operated verification. AI implementation agents must not run setup-watch automatically.",
       watch_targets: buildWatchTargets(detection, candidate),
     },
     artifacts: {
@@ -403,12 +420,54 @@ export const runSetupPrepare = async ({
     },
     machine_owned_artifacts: [workflow.ci_workflow_path, setupManifestPath],
     ai_must_not_edit: [workflow.ci_workflow_path],
-    ai_owned_workstreams: ["sdk_lifecycle_implementation"],
+    ai_owned_workstreams: ["sdk_lifecycle_placement"],
+    ai_implementation_scope: {
+      rule: "AI implementation is limited to placing ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout in existing lifecycle boundaries plus the minimal SDK wiring required for those calls.",
+      lifecycle_apis: [
+        "ClueInit",
+        "ClueIdentify",
+        "ClueSetAccount",
+        "ClueLogout",
+      ],
+      out_of_scope_by_default: ["ClueTrack"],
+    },
     required_final_check: {
-      command:
-        `npx @clue-ai/cli setup-check --framework ${candidate.framework} ` +
-        `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+      command: clueCliCommand(
+        `setup-check --framework ${candidate.framework} ` +
+          `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+      ),
     },
+    required_final_verification: [
+      {
+        id: "static_setup_check",
+        command: clueCliCommand(
+          `setup-check --framework ${candidate.framework} ` +
+            `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+        ),
+        completion_meaning:
+          "static_passed_only_dependency_install_import_app_startup_and_event_delivery_still_required",
+      },
+      {
+        id: "sdk_dependency_install_and_import",
+        command:
+          "run the repository package-manager install plus frontend/backend SDK import checks in the target environments",
+        completion_meaning:
+          "required before claiming SDK lifecycle setup is complete",
+      },
+      {
+        id: "app_startup",
+        command:
+          "start the affected frontend/backend services and verify their configured local URLs respond",
+        completion_meaning:
+          "required before setup-watch local completion can be trusted",
+      },
+      {
+        id: "local_event_delivery",
+        command: `user runs ${clueCliCommand("setup-watch --local")}`,
+        completion_meaning:
+          "requires user-operated local services plus expected lifecycle event delivery; AI agents must report user_verification_pending when user evidence is not provided",
+      },
+    ],
     required_env_names: [
       "CLUE_SERVICE_KEY",
       "CLUE_API_KEY",
@@ -450,7 +509,8 @@ export const runSetupPrepare = async ({
       ...manifestWithEnvironmentArtifact.artifacts,
       environment_file_path: environmentFilePath,
     },
-    environment_instructions:
-      summarizeEnvironmentInstructions(environmentInstructions),
+    environment_instructions: summarizeEnvironmentInstructions(
+      environmentInstructions,
+    ),
   };
 };

package/src/setup-tool.mjs

@@ -1,6 +1,12 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import readline from "node:readline/promises";
+import {
+  CLUE_CLI_BINARY_NAME,
+  CLUE_CLI_PACKAGE_NAME,
+  CLUE_CLI_RECOMMENDED_PREFIX,
+  clueCliCommand,
+} from "./cli-invocation.mjs";
 
 const SKILL_NAMES = [
   "clue-setup-orchestrator",
@@ -11,6 +17,7 @@ const SKILL_NAMES = [
   "clue-local-verification",
   "clue-setup-report",
 ];
+const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v1";
 
 const TARGETS = new Set(["codex", "claude_code"]);
 
@@ -33,11 +40,11 @@ const normalizeTarget = (target) => {
 const skillBody = (name) => {
   const descriptions = {
     "clue-setup-orchestrator":
-      "Use first when running the full Clue setup so one execution agent per implementation workstream and multiple monitoring agents coordinate separate setup phases.",
+      "Use first when running Clue setup so lifecycle placement remains the only implementation workstream and read-only checks stay separate.",
     "clue-route-semantic-snapshot":
       "Use when checking backend route coverage and semantic snapshot readiness without hand-authoring generated snapshot files.",
     "clue-semantic-gen":
-      "Use when adding or updating Clue semantic snapshot CI for this repository.",
+      "Use when verifying the generated Clue semantic snapshot CI workflow without editing it during lifecycle placement.",
     "clue-sdk-instrumentation":
       "Use when adding ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout lifecycle calls to a customer repository.",
     "clue-setup-audit":
@@ -54,13 +61,13 @@ const skillBody = (name) => {
     "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":
-      "Semantic generation CI agent. Owns machine-owned CI workflow verification/refresh only. It must not hand-write snapshot content or SDK lifecycle code.",
+      "Semantic generation CI verification agent. Owns read-only machine-owned CI workflow verification only during lifecycle placement. It must not hand-write snapshot content, refresh CI, or edit SDK lifecycle code.",
     "clue-sdk-instrumentation":
-      "SDK lifecycle implementation agent. Owns Clue SDK dependency, initialization, and lifecycle call implementation only.",
+      "SDK lifecycle placement agent. Owns Clue SDK dependency, initialization, and ClueInit/ClueIdentify/ClueSetAccount/ClueLogout placement only.",
     "clue-setup-audit":
       "Read-only monitoring agent. Owns P0/P1 review for one completed workstream at a time. It must not edit files.",
     "clue-local-verification":
-      "Read-only verification agent. Owns setup-check/setup-watch evidence and local verification readiness. It must not edit files.",
+      "Read-only verification agent. Owns static setup checks, dependency/import/startup evidence, and user verification handoff. It must not edit files or run setup-watch automatically.",
     "clue-setup-report":
       "Final reporting agent. Owns concise completion evidence only after execution and monitoring gates pass.",
   };
@@ -68,7 +75,7 @@ const skillBody = (name) => {
   const owns = {
     "clue-setup-orchestrator": [
       "read `.clue/setup-manifest.json` first",
-      "assign exactly one execution agent per implementation workstream",
+      "assign exactly one implementation agent for SDK lifecycle placement",
       "assign multiple read-only monitoring agents",
       "stop on manifest blockers or P0/P1 findings",
     ],
@@ -98,7 +105,7 @@ const skillBody = (name) => {
     ],
     "clue-local-verification": [
       "`setup-check` evidence",
-      "`setup-watch --local` readiness",
+      "user-operated `setup-watch --local` handoff readiness",
       "local URL confirmation without assuming ports",
     ],
     "clue-setup-report": [
@@ -139,7 +146,8 @@ const skillBody = (name) => {
     "clue-local-verification": [
       "make edits",
       "assume localhost ports",
-      "treat setup-watch as complete before every expected implemented lifecycle check passes or is reported blocked",
+      "run `setup-watch --local` automatically during implementation",
+      "treat user-operated setup-watch or setup-screen event delivery as complete without user-provided evidence",
     ],
     "clue-setup-report": [
       "claim complete with unverified workstreams",
@@ -159,7 +167,7 @@ const skillBody = (name) => {
     ],
     "clue-semantic-gen": [
       "CI workflow verification result",
-      "whether regeneration was required and which command was used",
+      "blocker details when generated CI is missing or stale",
     ],
     "clue-sdk-instrumentation": [
       "implemented lifecycle locations",
@@ -171,7 +179,8 @@ const skillBody = (name) => {
       "approval or blocked status for the reviewed workstream",
     ],
     "clue-local-verification": [
-      "setup-check/setup-watch command evidence",
+      "setup-check, dependency/import/startup command evidence",
+      "user-operated setup-watch/setup-screen handoff status",
       "passed, blocked, or cannot-run status with reasons",
     ],
     "clue-setup-report": [
@@ -181,18 +190,22 @@ const skillBody = (name) => {
 
   const steps = {
     "clue-setup-orchestrator": [
-      "Use one execution agent per implementation workstream.",
-      "Each execution agent owns exactly one workstream and its tests.",
-      "Required execution agents: SDK Lifecycle Execution Agent, Semantic Snapshot Readiness Execution Agent, and Semantic Snapshot CI Execution Agent.",
+      "Use one implementation agent for SDK lifecycle placement.",
+      "That implementation agent owns only ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout placement plus minimal SDK wiring.",
+      "Required implementation agent: SDK Lifecycle Placement Agent only.",
+      "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.",
       "Run execution agents in parallel only when file ownership does not conflict; otherwise run them sequentially with monitor gates between workstreams.",
       "Use multiple monitoring agents for read-only checks, or named review passes if subagents are unavailable.",
-      "The initial `clue-ai 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.",
+      `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` `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 only semantic snapshot readiness, semantic snapshot CI, and SDK lifecycle implementation as implementation workstreams with execution agents.",
-      "Before each workstream, read and apply the matching Clue setup skill.",
-      "After each implementation workstream, run a monitoring check with `clue-setup-audit` before continuing.",
+      "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, 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.",
@@ -203,12 +216,12 @@ const skillBody = (name) => {
       "Do not create or commit `.clue/semantic-request.runtime.json`; the semantic CI request must be passed through the generated workflow environment instead of a repository file.",
       "Keep route coverage/readiness checks separate from CI workflow creation and SDK lifecycle implementation.",
       "Do not create CI workflow files or SDK lifecycle calls from this skill.",
-      "Do not create or commit `.clue/semantic-routes.json`; route inventory is dynamic and must be recomputed mechanically by `clue-ai semantic-inventory`, `clue-ai setup-check`, or `clue-ai semantic-gen`.",
-      "If route inventory must be inspected locally, run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` and review stdout instead of writing a repo file.",
+      `Do not create or commit \`.clue/semantic-routes.json\`; route inventory is dynamic and must be recomputed mechanically by \`${clueCliCommand("semantic-inventory")}\`, \`${clueCliCommand("setup-check")}\`, or \`${clueCliCommand("semantic-gen")}\`.`,
+      `If route inventory must be inspected locally, run \`${clueCliCommand("semantic-inventory --framework <framework> --backend-root-path <path> --repo .")}\` and review stdout instead of writing a repo file.`,
       "Inspect only allowed source paths.",
       "Identify the backend framework, backend root path, route files, controllers, handlers, and route declaration patterns from privacy-safe evidence.",
-      "Run `npx @clue-ai/cli semantic-inventory --framework <framework> --backend-root-path <path> --repo .` whenever possible to verify route discovery without AI or secrets.",
-      "If `npx` cannot be used in the current environment, use the local `clue-ai semantic-inventory` command equivalent.",
+      `Run \`${clueCliCommand("semantic-inventory --framework <framework> --backend-root-path <path> --repo .")}\` whenever possible to verify route discovery without AI or secrets.`,
+      "If npm/npx cannot fetch the Clue CLI package, report a blocker with the exact command and error instead of searching for another CLI path.",
       "Verify that every API route can be discovered from the selected backend root path and that unsupported frameworks are reported as blockers.",
       "The semantic snapshot CI command must mechanically enumerate operation_source_key, method, path_template, route fingerprints, and privacy-safe evidence before AI interpretation.",
       "AI interpretation may summarize each mechanically discovered route, but it must not create missing routes or operation_source_key values.",
@@ -222,10 +235,10 @@ const skillBody = (name) => {
       "Use this skill as the source of truth for semantic snapshot CI workflow format.",
       "Keep CI workflow creation separate from route coverage/readiness checks and SDK lifecycle implementation.",
       "Do not author semantic snapshot content, runtime request files, or SDK lifecycle calls from this skill.",
-      "Treat `.github/workflows/clue-semantic-snapshot.yml` as a machine-owned artifact generated by `clue-ai setup`; do not hand-edit it.",
-      "Create or update `.github/workflows/clue-semantic-snapshot.yml` only by running `npx @clue-ai/cli semantic-workflow --framework <framework> --backend-root-path <path> --repo .` when it must be refreshed.",
-      "If `npx` cannot be used in the current environment, use the local `clue-ai semantic-workflow` command equivalent instead of hand-writing the workflow.",
-      "The workflow must pass `CLUE_SEMANTIC_REQUEST_JSON` through the workflow environment and then call `npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .`.",
+      `Treat \`.github/workflows/clue-semantic-snapshot.yml\` as a machine-owned artifact generated by \`${clueCliCommand("setup")}\`; do not hand-edit it.`,
+      "During lifecycle placement, do not create, refresh, or hand-edit `.github/workflows/clue-semantic-snapshot.yml`; report a blocker if the generated workflow is missing or stale.",
+      "If npm/npx cannot fetch the Clue CLI package, report a blocker with the exact command and error instead of hand-writing the workflow.",
+      `The workflow must pass \`CLUE_SEMANTIC_REQUEST_JSON\` through the workflow environment and then call \`${clueCliCommand("semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .")}\`.`,
       "Do not create, commit, or stage `.clue/semantic-request.runtime.json` in the customer repository.",
       "The workflow must not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "The workflow should send only repository id, commit sha, workflow run id, project key variable, service key, framework, source path allowlist, source path denylist, and Clue API base URL variable.",
@@ -238,23 +251,30 @@ const skillBody = (name) => {
     ],
     "clue-sdk-instrumentation": [
       "Use this skill as the source of truth for Clue SDK lifecycle implementation.",
+      "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.",
       "Do not create no-op wrappers around nonexistent `window.Clue*` globals or local placeholder functions.",
       "Lifecycle calls must resolve to real Clue SDK imports or a real repository adapter that forwards to the Clue SDK.",
-      "Every Clue lifecycle call must be failure-isolated with try/catch, try/except, `.catch`, or an explicit safe Clue helper so Clue failure never stops the host service.",
+      "Official Clue SDK public lifecycle APIs are no-throw and own SDK failure isolation.",
+      "Do not add per-call try/catch, try/except, `.catch`, or custom safe wrappers solely around official Clue SDK public lifecycle calls.",
       "Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
       "Add or report the required SDK dependency instead of fabricating lifecycle APIs.",
-      "When lifecycle edits are clear, write an exact replacement plan to a temporary local JSON file and apply it with `npx @clue-ai/cli lifecycle-apply --plan <plan-file> --repo .`.",
-      "If `npx` cannot be used in the current environment, use the local `clue-ai lifecycle-apply` command equivalent instead of manually applying the exact replacements.",
+      "For frontend code, add the real `@clue-ai/browser-sdk` dependency when missing. Do not invent `clue-js-sdk`, `@clue/browser-sdk`, local placeholder modules, or dynamic imports that hide a missing SDK.",
+      `When lifecycle edits are clear, write an exact replacement plan to a temporary local JSON file and apply it with \`${clueCliCommand("lifecycle-apply --plan <plan-file> --repo .")}\`.`,
+      "If npm/npx cannot fetch the Clue CLI package, report a blocker with the exact command and error instead of manually applying replacement plans.",
       "Delete the temporary lifecycle plan file after applying it unless the user explicitly asks to keep it for review.",
       "Use environment variable names for Clue configuration values; do not paste project keys or API keys into code.",
-      "For local env files, use the service-specific env blocks written to `.env.clue` by `clue-ai setup`; do not ask the user to guess `CLUE_SERVICE_KEY`.",
-      "For browser code, use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, and `CLUE_INGEST_ENDPOINT`. Let the target framework expose or inject those values safely without hard-coding a Next.js-only prefix.",
+      `For local env files, use the service-specific env blocks written to \`.env.clue\` by \`${clueCliCommand("setup")}\`; do not ask the user to guess \`CLUE_SERVICE_KEY\`.`,
+      "For browser code, use `CLUE_PROJECT_KEY`, `CLUE_ENVIRONMENT`, `CLUE_SERVICE_KEY`, and `CLUE_INGEST_ENDPOINT`. Let the target framework expose or inject those values safely without hard-coding a Next.js-only prefix.",
+      "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 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 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`.",
       "Use `CLUE_SERVICE_KEY` as the canonical local service identifier. Do not ask the user to manage a separate producer id; SDKs should send producer id as the service key for setup verification compatibility.",
       "For frontend code, pass `serviceKey` from `CLUE_SERVICE_KEY` to `ClueInit`. Do not require a separate producer id unless the repository already has one for compatibility.",
-      "For Django code, add `clue-django-sdk` to the backend dependency file when missing and use the Django SDK lifecycle helpers.",
+      "For Django code, use `clue-django-sdk` only after package-manager or registry verification confirms it is installable; if it is not published or cannot be verified, report a blocker instead of adding a guessed dependency or import.",
       "For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
       "Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
       "Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
@@ -272,16 +292,20 @@ const skillBody = (name) => {
       "Review changed files line by line.",
       "Verify semantic snapshot, semantic CI, and SDK lifecycle responsibilities did not bleed into each other.",
       "Reject hand-authored semantic snapshot content and runtime request files.",
-      "Reject semantic CI workflows that were not generated by or equivalent to `clue-ai semantic-workflow`.",
+      `Reject semantic CI workflows that were not generated by or equivalent to \`${clueCliCommand("semantic-workflow")}\`.`,
       "Reject semantic CI workflows that send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "Reject no-op lifecycle wrappers or lifecycle calls that do not resolve to a real Clue SDK import.",
+      "Reject wrong SDK package names. Frontend must use `@clue-ai/browser-sdk`; FastAPI must use `clue-fastapi-sdk`; Django must use `clue-django-sdk`.",
+      "Reject Django SDK setup when `clue-django-sdk` installability has not been verified.",
       "Reject backend setup when backend routes exist but no backend Clue SDK dependency/import/init was added.",
-      "Reject lifecycle calls that are not failure-isolated; Clue failure must never stop the host service.",
+      "Reject awaited lifecycle calls that can block host service behavior.",
       "Reject setup that covers only one login path when multiple login success paths are clearly present.",
       "Reject ClueInit inside React component lifecycle hooks, page components, sidebars, login/register success callbacks, or any repeated user interaction path.",
       "Reject broad ClueTrack instrumentation and DOM clue tags.",
+      "Reject ClueTrack instrumentation unless the user explicitly requested product event tracking.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
+      "Reject unrelated refactors, renames, file moves, formatting churn, broad cleanup, business logic rewrites, auth/session rewrites beyond minimal Clue hook insertion, and UI changes unrelated to Clue setup.",
     ],
     "clue-local-verification": [
       "Act as a read-only monitoring agent for local verification evidence.",
@@ -289,19 +313,28 @@ const skillBody = (name) => {
       "Confirm generated skill files exist.",
       "Confirm workflow files and SDK lifecycle imports/calls exist when those phases have run.",
       "Confirm backend routes have a backend Clue SDK dependency/import/init when a backend exists.",
-      "Confirm `.github/workflows/clue-semantic-snapshot.yml` calls `npx @clue-ai/cli semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON`.",
+      "Confirm install/import readiness separately from static lifecycle checks. `setup-check --require-sdk-lifecycle` is a static source check only and does not prove that npm/pip install, imports, app startup, or event delivery work.",
+      "Verify frontend SDK installability/import when frontend lifecycle code was added. Run the repository's package-manager install command when possible, then run a package-manager-level import/build/typecheck command. If this cannot run, report `blocked` or `partially complete`; do not call setup complete.",
+      'Verify backend SDK installability/import when backend lifecycle code was added. Run the repository\'s Python dependency install command when possible, then run an import check such as `python -c "import clue_fastapi_sdk"` or `python -c "import clue_django_sdk"` in the target environment. If this cannot run, report `blocked` or `partially complete`; do not call setup complete.',
+      `Confirm \`.github/workflows/clue-semantic-snapshot.yml\` calls \`${clueCliCommand("semantic-gen --request-env CLUE_SEMANTIC_REQUEST_JSON --repo .")}\`.`,
       "Confirm the semantic workflow does not send GitHub actor, triggering_actor, sender, repository owner, repository name, or default branch to Clue.",
       "Confirm `.clue/semantic-request.runtime.json` is not created, committed, or staged.",
-      "Run `npx @clue-ai/cli setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle` when possible.",
-      "For interactive local verification, run `npx @clue-ai/cli setup-watch --local` and operate every local frontend/backend service until all expected checks pass.",
+      `Run \`${clueCliCommand("setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle")}\` when possible.`,
+      `Do not run \`${clueCliCommand("setup-watch --local")}\` automatically. setup-watch requires the user to operate real local frontend/backend services and login/logout/account flows.`,
+      "If the user has not provided setup-watch or setup-screen evidence, report event delivery verification as `user_verification_pending` and do not state `setup completed`.",
+      "Local static verification passed does not mean setup complete unless dependency install, SDK imports, app startup, and user-provided setup-watch or setup-screen event delivery were all verified.",
       "Only include lifecycle checks that the implementation ownership plan expects for that service. If a service emits an undeclared lifecycle event, treat it as a possible duplicate instrumentation issue.",
       "Never assume localhost ports. Ask the repository scripts, env examples, or the running service output for the actual frontend/backend URLs.",
-      "If `npx` cannot be used in the current environment, use the local `clue-ai setup-check` command equivalent.",
+      "If npm/npx cannot fetch the Clue CLI package, report a blocker with the exact command and error instead of searching for another CLI path.",
       "Confirm only env names are reported.",
-      "Leave event delivery verification to the Clue setup screen.",
+      "Leave event delivery verification to the user-operated Clue setup screen or user-operated setup-watch.",
     ],
     "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.",
+      "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.",
       "Summarize changed files.",
       "List completed setup phases.",
       "List skills used for each workstream.",
@@ -317,6 +350,7 @@ const skillBody = (name) => {
     "---",
     `name: ${name}`,
     `description: ${descriptions[name]}`,
+    `setup_skill_version: ${SETUP_SKILL_CONTENT_VERSION}`,
     "---",
     "",
     "# Agent Role",
@@ -337,9 +371,20 @@ const skillBody = (name) => {
     "",
     "# Shared Rules",
     "",
-    "- For full Clue setup, use one execution agent per implementation workstream and multiple monitoring agents for read-only checks.",
+    "- For full Clue setup, use one SDK lifecycle placement implementation agent and multiple monitoring agents for read-only checks.",
+    `- Clue CLI public npm package: \`${CLUE_CLI_PACKAGE_NAME}\`.`,
+    `- Clue CLI binary name exposed by that package: \`${CLUE_CLI_BINARY_NAME}\`; a global \`${CLUE_CLI_BINARY_NAME}\` install is not required.`,
+    `- 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.`,
+    `- 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 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 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`.",
-    "- Each execution agent owns exactly one workstream; monitoring agents review one workstream at a time and report P0/P1 issues.",
+    "- The implementation agent owns only lifecycle placement; monitoring agents review one surface at a time and report P0/P1 issues.",
     "- Do not continue past a P0/P1 monitoring finding until it is fixed or explicitly reported as blocked.",
     "- If subagents are unavailable, run the same structure as separate named review passes and say so in the final report.",
     "- Do not expose project keys, API keys, secrets, tokens, or environment variable values.",
@@ -347,6 +392,7 @@ const skillBody = (name) => {
     "- Do not read `.env`, `.env.*`, secret files, logs, dumps, build output, coverage output, `node_modules`, vendor directories, dependency directories, or dependency output.",
     "- Report only environment variable names, never values.",
     "- Do not commit or push changes.",
+    "- Execution agents must not approve, certify, or mark their own work complete. Completion evidence must come from independent monitoring passes, command output, runtime checks, or user-provided setup-watch/setup-screen evidence.",
     "- Prefer existing repository patterns and minimal diffs.",
     "- If evidence is unclear, report a blocker instead of guessing.",
     "- Do not merge semantic snapshot, semantic CI, SDK lifecycle, audit, verification, and report responsibilities into one undifferentiated task.",