@clue-ai/cli 0.0.15 → 0.0.17

package/src/setup-help.mjs

@@ -2,9 +2,15 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import {
+  AI_SETUP_CONTRACT_VERSION,
+  API_CONNECTIVITY_CONTRACT,
+  DETERMINISTIC_CONTROL_MODEL,
+  SETUP_DOCTRINE,
+} from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
-export const AI_SETUP_HELP_VERSION = "2026-05-10.lifecycle-placement-only.v4";
+export const AI_SETUP_HELP_VERSION = AI_SETUP_CONTRACT_VERSION;
 
 export const buildAiSetupHelp = () => ({
   name: "@clue-ai/cli AI setup help",
@@ -13,6 +19,9 @@ export const buildAiSetupHelp = () => ({
     "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: {
+    setup_doctrine: SETUP_DOCTRINE,
+    deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
+    api_connectivity_contract: API_CONNECTIVITY_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"],
@@ -57,6 +66,8 @@ 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. 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.",
+        origin_rule:
+          "The backend proxy must derive request origin from trusted request headers or server request metadata. Project key and environment must come from server configuration or be validated against it. Do not forward origin, projectKey, or environment from JSON/body payload fields under server CLUE_API_KEY.",
       },
     },
     documentation_contract: buildSetupDocumentationContract(),
@@ -68,6 +79,13 @@ export const buildAiSetupHelp = () => ({
       ai_agent_responsibility:
         "Report the command and required user verification as pending when it was not run by the user.",
     },
+    setup_doctor: {
+      owner: "ai_or_user",
+      ai_agent_may_run: true,
+      command: clueCliCommand("setup-doctor --local"),
+      rule: "Run setup-doctor after local frontend/backend services and required env are available. It checks API connectivity only and does not replace user-operated setup-watch.",
+      checked_hops: Object.keys(API_CONNECTIVITY_CONTRACT.hops),
+    },
     completion_boundary: {
       ai_may_claim: [
         "Clue setup code changes were applied",

package/src/setup-prepare.mjs

@@ -8,6 +8,7 @@ import {
   CLUE_CLI_INVOCATION_CONTRACT,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import { API_CONNECTIVITY_CONTRACT } from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
@@ -488,6 +489,7 @@ export const runSetupPrepare = async ({
       project_key: setupContext.project_key,
       environment: setupContext.environment,
       clue_api_base_url: setupContext.clue_api_base_url,
+      api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
       ingest_endpoints: setupContext.clue_api_base_url
         ? {
             browser: buildEndpoint(
@@ -557,6 +559,12 @@ export const runSetupPrepare = async ({
         completion_meaning:
           "required before setup-watch local completion can be trusted",
       },
+      {
+        id: "local_api_connectivity_preflight",
+        command: clueCliCommand("setup-doctor --local"),
+        completion_meaning:
+          "required before user setup-watch; verifies customer proxy, Clue browser-token issuance, browser ingest, and backend ingest connectivity when local services and required env are available",
+      },
       {
         id: "local_event_delivery",
         command: `user runs ${clueCliCommand("setup-watch --local")}`,

package/src/setup-tool.mjs

@@ -7,6 +7,11 @@ import {
   CLUE_CLI_RECOMMENDED_PREFIX,
   clueCliCommand,
 } from "./cli-invocation.mjs";
+import {
+  AI_SETUP_CONTRACT_VERSION,
+  API_CONNECTIVITY_CONTRACT,
+  setupDoctrineSkillLines,
+} from "./setup-ai-contract.mjs";
 import { buildSetupDocumentationContract } from "./setup-documents.mjs";
 
 const SKILL_NAMES = [
@@ -19,7 +24,7 @@ const SKILL_NAMES = [
   "clue-local-verification",
   "clue-setup-report",
 ];
-const SETUP_SKILL_CONTENT_VERSION = "2026-05-10.lifecycle-placement-only.v4";
+const SETUP_SKILL_CONTENT_VERSION = AI_SETUP_CONTRACT_VERSION;
 
 const TARGETS = new Set(["codex", "claude_code"]);
 
@@ -82,7 +87,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "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 static setup checks, dependency/import/startup evidence, and user verification handoff. It must not edit files or run setup-watch automatically.",
+      "Read-only verification agent. Owns static setup checks, setup-doctor API connectivity preflight, 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.",
   };
@@ -128,6 +133,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     ],
     "clue-local-verification": [
       "`setup-check` evidence",
+      "`setup-doctor --local` API connectivity preflight when local services and required env are available",
       "user-operated `setup-watch --local` handoff readiness",
       "local URL confirmation without assuming ports",
     ],
@@ -322,9 +328,10 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "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 local backend token endpoint is part of the customer app, not the Clue API. Place it under a Clue-reserved local route such as `/api/v1/clue/browser-tokens`; do not use a generic path such as `/browser-tokens` that could be confused with product behavior. 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.",
+      "The browser token request must include the frontend service key used by `ClueInit`. Project key and environment may be included only as public consistency hints; the backend must use server configuration or validate them against server configuration before calling Clue.",
+      "The backend browser token proxy must derive origin from trusted request headers or server request metadata. Do not forward `origin`, `projectKey`, or `environment` from JSON/body payload fields under server `CLUE_API_KEY`.",
       "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.",
@@ -359,6 +366,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "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 awaited lifecycle calls that can block host service behavior.",
+      "Reject browser token proxy code that forwards origin, projectKey, or environment from request JSON/body under server `CLUE_API_KEY`.",
       "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.",
@@ -384,6 +392,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
       "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 \`${clueCliCommand("setup-check --framework <framework> --backend-root-path <path> --repo . --target <codex|claude_code> --require-sdk-lifecycle")}\` when possible.`,
+      `Run \`${clueCliCommand("setup-doctor --local")}\` when local frontend/backend services are running and required env values are available. Report skipped_setup_doctor with the missing service URL or env name when it cannot run.`,
       `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.",
@@ -436,6 +445,7 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "",
     "# Shared Rules",
     "",
+    ...setupDoctrineSkillLines(),
     "- 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.`,
@@ -451,7 +461,11 @@ const skillBody = (name, { documentsUrl } = {}) => {
     "- 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.",
+    "- A customer backend browser-token endpoint is only a proxy for browser SDK token issuance. It must live under a Clue-reserved local route such as `/api/v1/clue/browser-tokens`, not a generic product-looking path such as `/browser-tokens`. 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 and server-owned project/environment values.",
+    `- Setup API connectivity has four distinct hops: ${Object.entries(API_CONNECTIVITY_CONTRACT.hops)
+      .map(([name, hop]) => `${name}=${hop.method} ${hop.path}`)
+      .join(", ")}.`,
+    `- Run \`${clueCliCommand("setup-doctor --local")}\` when local services and required env are available. This checks API connectivity only; it does not replace user-operated setup-watch.`,
     "- 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`.",