@clue-ai/cli 0.0.13 → 0.0.15

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.v2";
+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.",
@@ -266,15 +316,22 @@ const skillBody = (name) => {
       "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 \`${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.",
+      "For Next.js browser/client code, use only `NEXT_PUBLIC_CLUE_PROJECT_KEY`, `NEXT_PUBLIC_CLUE_ENVIRONMENT`, `NEXT_PUBLIC_CLUE_SERVICE_KEY`, and `NEXT_PUBLIC_CLUE_INGEST_ENDPOINT` from the frontend `.env.local` block.",
+      "Do not read `process.env.CLUE_PROJECT_KEY`, `process.env.CLUE_ENVIRONMENT`, `process.env.CLUE_SERVICE_KEY`, or `process.env.CLUE_INGEST_ENDPOINT` in Next.js browser/client code, and do not add non-public `CLUE_*` fallbacks there.",
+      "For non-Next.js browser code, use the exact frontend env names written in `.env.clue` for that service instead of inventing a framework-specific prefix.",
       "Never 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 for Clue CLI and semantic snapshot CI configuration, not backend SDK runtime configuration. Do not add it to application config unless existing non-Clue code already requires it.",
+      "`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.",
+      "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.",
       "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 frontend code, pass `serviceKey` from the frontend service env name written by `.env.clue` to `ClueInit`; in Next.js browser/client code that name is `NEXT_PUBLIC_CLUE_SERVICE_KEY`.",
       "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.",
@@ -290,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.",
@@ -305,6 +363,8 @@ const skillBody = (name) => {
       "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.",
+      "Reject Next.js browser/client code that reads non-public `process.env.CLUE_*` variables.",
+      "Reject Clue SDK dependency entries that use `*` or `latest` instead of a concrete published version or package-manager-resolved semver range.",
       "Confirm no project key, API key, secret, or env value appears in diff or report.",
       "Confirm lifecycle insertions are minimal and reviewable.",
       "Reject whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Clue SDK wiring lines.",
@@ -312,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.",
@@ -335,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.",
@@ -343,7 +405,7 @@ const skillBody = (name) => {
       "List skills used for each workstream.",
       "List execution agent and monitoring agents, or named review passes if subagents were unavailable.",
       "List blockers with exact file or environment names when available.",
-      "List required env names without values and group them by scope: service runtime env blocks versus GitHub Secrets/Variables. Do not report `CLUE_API_BASE_URL` as a backend SDK runtime env; it belongs to Clue CLI and semantic snapshot CI configuration.",
+      "List required env names without values and group them by scope: frontend runtime, backend runtime, GitHub Secrets, and GitHub Variables. Do not report `CLUE_API_BASE_URL` as a backend SDK init env; it belongs to Clue CLI/semantic CI and to backend browser-token proxy config only when a frontend service exists.",
       "List P0/P1 monitoring findings and fixes.",
       "State that commit and push were not performed.",
     ],
@@ -380,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`.",
@@ -426,6 +493,7 @@ const askTarget = async ({
 export const installSetupSkills = async ({
   repoRoot,
   target,
+  documentsUrl,
   input,
   output,
 } = {}) => {
@@ -443,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);
   }