@genn-inc/cluebase-cli 0.0.1

package/src/contracts.mjs

@@ -0,0 +1,36 @@
+// 環境別 key (Stripe 流) の prefix から environment を導出する。
+// apps/api/src/common/security/project-api-key.crypto.ts の
+// deriveEnvironmentFromProjectKey と完全一致するロジック。
+//
+// - `pk_dev_` で始まる project_key は環境 "dev"
+// - `pk_prod_` で始まる project_key は環境 "prod"
+// - 上記以外の prefix は null を返す → caller が早期 error 化
+//
+// SPEC: docs/contracts/project-keys/environment-prefixes.md
+export const PROJECT_KEY_ENVIRONMENT_PREFIX = Object.freeze({
+	dev: "pk_dev_",
+	prod: "pk_prod_",
+});
+
+export const PROJECT_API_KEY_ENVIRONMENT_PREFIX = Object.freeze({
+	dev: "ak_dev_",
+	prod: "ak_prod_",
+});
+
+export const deriveEnvironmentFromProjectKey = (projectKey) => {
+	if (typeof projectKey !== "string") return null;
+	for (const [env, prefix] of Object.entries(PROJECT_KEY_ENVIRONMENT_PREFIX)) {
+		if (projectKey.startsWith(prefix)) return env;
+	}
+	return null;
+};
+
+export const deriveEnvironmentFromProjectApiKey = (apiKey) => {
+	if (typeof apiKey !== "string") return null;
+	for (const [env, prefix] of Object.entries(
+		PROJECT_API_KEY_ENVIRONMENT_PREFIX,
+	)) {
+		if (apiKey.startsWith(prefix)) return env;
+	}
+	return null;
+};

package/src/generated-code-evidence-contract.mjs

@@ -0,0 +1,22 @@
+// Generated from packages/cluebase-schema/src/github/code-evidence.schema.ts.
+// Run `node scripts/generate-code-evidence-contract.mjs` after changing the schema.
+export const CODE_EVIDENCE_ANALYZER_VERSION = "code-evidence-v1";
+export const CODE_EVIDENCE_OPERATION_DISCRIMINATOR_FIELD = "action";
+export const CODE_EVIDENCE_ROUTE_METHODS = Object.freeze([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+  "HEAD",
+  "TRACE",
+  "ALL"
+]);
+export const CODE_EVIDENCE_DATA_OPERATIONS = Object.freeze([
+  "read",
+  "create",
+  "update",
+  "delete",
+  "unknown"
+]);

package/src/generated-sdk-version-contract.mjs

@@ -0,0 +1,5 @@
+// Generated from the official SDK package versions.
+// Run `node scripts/generate-sdk-version-contract.mjs` after changing an SDK version.
+export const RECOMMENDED_BACKEND_SDK_VERSION = "0.0.1";
+export const RECOMMENDED_BACKEND_SDK_PACKAGE_SPEC = "@genn-inc/cluebase-backend-sdk";
+export const RECOMMENDED_PYTHON_BACKEND_SDK_PACKAGE_SPEC = "cluebase-backend-sdk";

package/src/generated-source-path-policy.mjs

@@ -0,0 +1,20 @@
+// Generated from packages/cluebase-schema/src/source-path-policy.ts.
+// Regenerate with node scripts/generate-source-path-policy.mjs after changing the schema policy.
+const DEFAULT_EXCLUDED_PATH_PARTS = Object.freeze([".git",".env",".venv",".next","venv","site-packages","node_modules","dist","build","coverage","logs","tmp","vendor","credentials","secrets","__pycache__"]);
+const DEFAULT_EXCLUDED_PATH_PREFIXES = Object.freeze([".venv-",".venv_","venv-","venv_"]);
+const SENSITIVE_PATH_PART_PATTERN = /^(?:\.env(?:[._-].*)?|credentials(?:[._-].*)?|secrets(?:[._-].*)?)$/i;
+
+export function isExcludedSourcePath(relativePath, excludedPathParts = []) {
+  const excluded = new Set([
+    ...DEFAULT_EXCLUDED_PATH_PARTS,
+    ...excludedPathParts,
+  ]);
+  return relativePath
+    .split(/[\\/]+/)
+    .filter(Boolean)
+    .some((part) =>
+      excluded.has(part) ||
+      SENSITIVE_PATH_PART_PATTERN.test(part) ||
+      DEFAULT_EXCLUDED_PATH_PREFIXES.some((prefix) => part.startsWith(prefix)),
+    );
+}

package/src/lifecycle-guard.mjs

@@ -0,0 +1,202 @@
+const LIFECYCLE_CALL_PATTERN =
+	/\b(cluebase\.init|cluebase_init_fastapi|cluebase\.identify|cluebase\.group|cluebase\.reset|cluebase\.track)\s*\(/g;
+
+export const stripSourceNoise = (text, { stripStrings = false } = {}) => {
+	let output = "";
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index];
+		const next = text[index + 1];
+		if (char === "/" && next === "/") {
+			while (index < text.length && text[index] !== "\n") index += 1;
+			continue;
+		}
+		if (char === "#") {
+			while (index < text.length && text[index] !== "\n") index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			index += 2;
+			while (
+				index < text.length &&
+				!(text[index] === "*" && text[index + 1] === "/")
+			) {
+				if (text[index] === "\n") output += "\n";
+				index += 1;
+			}
+			index += index < text.length ? 2 : 0;
+			continue;
+		}
+		if (char === "'" || char === '"' || char === "`") {
+			const quote = char;
+			const triple =
+				quote !== "`" && text.slice(index, index + 3) === quote.repeat(3);
+			const endToken = triple ? quote.repeat(3) : quote;
+			if (!stripStrings) {
+				output += triple ? endToken : quote;
+			} else {
+				output += quote === "`" ? "``" : `${quote}${quote}`;
+			}
+			index += triple ? 3 : 1;
+			while (index < text.length) {
+				if (!triple && text[index] === "\\") {
+					if (!stripStrings) output += text.slice(index, index + 2);
+					index += 2;
+					continue;
+				}
+				if (text.slice(index, index + endToken.length) === endToken) {
+					if (!stripStrings) output += endToken;
+					index += endToken.length;
+					break;
+				}
+				if (text[index] === "\n") output += "\n";
+				if (!stripStrings && text[index] !== "\n") output += text[index];
+				index += 1;
+			}
+			continue;
+		}
+		output += char;
+		index += 1;
+	}
+	return output;
+};
+
+const isIdentifierCharacter = (character) =>
+	typeof character === "string" && /[A-Za-z0-9_$]/.test(character);
+
+const startsKeyword = (text, index, keyword) =>
+	text.startsWith(keyword, index) &&
+	!isIdentifierCharacter(text[index - 1]) &&
+	!isIdentifierCharacter(text[index + keyword.length]);
+
+const advanceQuotedString = (text, startIndex, { preserve = false } = {}) => {
+	const quote = text[startIndex];
+	const triple = quote !== "`" && text.slice(startIndex, startIndex + 3) === quote.repeat(3);
+	const endToken = triple ? quote.repeat(3) : quote;
+	let index = startIndex + (triple ? 3 : 1);
+	let value = preserve ? (triple ? endToken : quote) : "";
+	while (index < text.length) {
+		if (!triple && text[index] === "\\") {
+			if (preserve) value += text.slice(index, index + 2);
+			index += 2;
+			continue;
+		}
+		if (text.slice(index, index + endToken.length) === endToken) {
+			if (preserve) value += endToken;
+			index += endToken.length;
+			break;
+		}
+		if (preserve) value += text[index];
+		index += 1;
+	}
+	return { index, value };
+};
+
+export const extractExecutableModuleStatements = (text) => {
+	const statements = [];
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index];
+		const next = text[index + 1];
+		if (char === "/" && next === "/") {
+			while (index < text.length && text[index] !== "\n") index += 1;
+			continue;
+		}
+		if (char === "#") {
+			while (index < text.length && text[index] !== "\n") index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			index += 2;
+			while (
+				index < text.length &&
+				!(text[index] === "*" && text[index + 1] === "/")
+			) {
+				index += 1;
+			}
+			index += index < text.length ? 2 : 0;
+			continue;
+		}
+		if (char === "'" || char === '"' || char === "`") {
+			index = advanceQuotedString(text, index).index;
+			continue;
+		}
+		if (!startsKeyword(text, index, "import") && !startsKeyword(text, index, "export")) {
+			index += 1;
+			continue;
+		}
+		let statement = "";
+		let depth = 0;
+		while (index < text.length) {
+			const current = text[index];
+			const following = text[index + 1];
+			if (current === "/" && following === "/") {
+				while (index < text.length && text[index] !== "\n") index += 1;
+				continue;
+			}
+			if (current === "/" && following === "*") {
+				index += 2;
+				while (
+					index < text.length &&
+					!(text[index] === "*" && text[index + 1] === "/")
+				) {
+					index += 1;
+				}
+				index += index < text.length ? 2 : 0;
+				continue;
+			}
+			if (current === "'" || current === '"' || current === "`") {
+				const quoted = advanceQuotedString(text, index, { preserve: true });
+				statement += quoted.value;
+				index = quoted.index;
+				continue;
+			}
+			statement += current;
+			if (current === "{" || current === "(" || current === "[") depth += 1;
+			if (current === "}" || current === ")" || current === "]") {
+				depth = Math.max(0, depth - 1);
+			}
+			index += 1;
+			if (current === ";" && depth === 0) break;
+			if (current === "\n" && depth === 0) break;
+		}
+		const trimmed = statement.trim();
+		if (trimmed) statements.push(trimmed);
+	}
+	return statements;
+};
+
+const lineNumberForIndex = (text, index) =>
+	text.slice(0, index).split("\n").length;
+
+const isAwaitedOnCallLine = (text, callIndex) => {
+	const lineStart = text.lastIndexOf("\n", callIndex - 1) + 1;
+	return /\bawait\b/.test(text.slice(lineStart, callIndex));
+};
+
+const canonicalLifecycleApiName = (apiName) =>
+	apiName === "cluebase_init_fastapi" ? "cluebase.init" : apiName;
+
+export const findLifecycleGuardViolations = (text) => {
+	const violations = [];
+	for (const match of text.matchAll(LIFECYCLE_CALL_PATTERN)) {
+		const callIndex = match.index ?? 0;
+		const apiName = canonicalLifecycleApiName(match[1]);
+		if (isAwaitedOnCallLine(text, callIndex)) {
+			violations.push({
+				api_name: apiName,
+				line: lineNumberForIndex(text, callIndex),
+				reason: "awaited_lifecycle_call",
+			});
+		}
+	}
+	return violations;
+};
+
+export const findLifecycleCallApiNames = (text) => [
+	...new Set(
+		[...text.matchAll(LIFECYCLE_CALL_PATTERN)].map((match) =>
+			canonicalLifecycleApiName(match[1]),
+		),
+	),
+];

package/src/path-policy.mjs

@@ -0,0 +1,81 @@
+import { lstat, readdir } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { isExcludedSourcePath as isExcludedSourcePathFromSchema } from "./generated-source-path-policy.mjs";
+
+export const isExcludedSourcePath = (
+  relativePath,
+  excludedSourcePaths = [],
+) => {
+  return isExcludedSourcePathFromSchema(relativePath, excludedSourcePaths);
+};
+
+const isInsideRoot = (root, absolutePath) => {
+  const relativePath = relative(root, absolutePath);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
+};
+
+export const listAllowedSourceFiles = async ({
+  repoRoot,
+  allowedSourcePaths,
+  excludedSourcePaths,
+  extensions,
+}) => {
+  const root = resolve(repoRoot);
+  const normalizedAllowedSourcePaths =
+    Array.isArray(allowedSourcePaths) && allowedSourcePaths.length > 0
+      ? allowedSourcePaths
+      : ["."];
+  const normalizedExcludedSourcePaths = Array.isArray(excludedSourcePaths)
+    ? excludedSourcePaths
+    : [];
+  const files = [];
+  const allowedExtensions = new Set(extensions);
+
+  const walk = async (absolutePath) => {
+    const relativePath = relative(root, absolutePath);
+    if (
+      relativePath &&
+      isExcludedSourcePathFromSchema(
+        relativePath,
+        normalizedExcludedSourcePaths,
+      )
+    ) {
+      return;
+    }
+		const currentStat = await lstat(absolutePath);
+		if (currentStat.isSymbolicLink()) {
+			throw new Error(`symbolic links are not allowed in source paths: ${relativePath}`);
+		}
+    if (currentStat.isDirectory()) {
+      const entries = await readdir(absolutePath);
+      for (const entry of entries) {
+        await walk(join(absolutePath, entry));
+      }
+      return;
+    }
+    if (
+      currentStat.isFile() &&
+      [...allowedExtensions].some((extension) =>
+        absolutePath.endsWith(extension),
+      )
+    ) {
+      files.push(absolutePath);
+    }
+  };
+
+  for (const sourcePath of normalizedAllowedSourcePaths) {
+    const absolutePath = resolve(root, sourcePath);
+    if (!isInsideRoot(root, absolutePath)) {
+      throw new Error(`allowed_source_paths escapes repo root: ${sourcePath}`);
+    }
+    await walk(absolutePath);
+  }
+
+	return [...new Set(files)].sort();
+};
+
+export const listAllowedPythonFiles = async (options) =>
+  listAllowedSourceFiles({ ...options, extensions: [".py"] });

package/src/setup-ai-contract.mjs

@@ -0,0 +1,221 @@
+export const AI_SETUP_CONTRACT_VERSION =
+  "1";
+
+export const SETUP_DOCTRINE = {
+  purpose:
+    "Cluebase setup installs an external SDK integration so observed product facts can reach Cluebase's Customer Value Understanding Engine. It is not an opportunity to improve, refactor, redesign, or reinterpret the host application.",
+  minimal_diff_reason:
+    "The customer must be able to review and merge the setup diff with confidence. Extra formatting, refactors, auth rewrites, UI changes, or unrelated cleanup make the integration harder to trust.",
+  ai_decision_boundary:
+    "The AI should use repository understanding only to choose existing lifecycle boundaries for cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset.",
+  deterministic_control_boundary:
+    "Everything that can be controlled mechanically should be controlled by the CLI, generated skills, documentation contract, setup manifest, generated STEP commands, and setup-check static guards.",
+  documentation_reason:
+    "SDK signatures, environment variable names, browser token behavior, and verification ownership are contracts. The AI must read the setup documents instead of relying on memory.",
+  failure_posture:
+    "For supported setup paths, prefer completing safe minimal Cluebase wiring and reporting unclear lifecycle points as warnings. Reserve blockers for truly unsupported frameworks, unavailable SDK contracts, missing AI configuration, or edits that cannot be applied without guessing outside Cluebase setup scope.",
+};
+
+export const DETERMINISTIC_CONTROL_MODEL = {
+  ai_should_decide: [
+    "which existing bootstrap point owns cluebase.init",
+    "which existing one-time auth success boundary owns cluebase.identify",
+    "which existing organization/company resolution point owns cluebase.group",
+    "which existing logout/session reset point owns cluebase.reset",
+    "whether a lifecycle point is unclear and should be skipped with a warning instead of guessed",
+    "which additional repository files or plain-text searches should be inspected through CLI-owned read-only tools before lifecycle placement",
+  ],
+  cli_should_control: [
+    "read-only repository exploration tools, allowed paths, file inventory, read limits, search limits, and secret/path exclusions",
+    "official SDK package names",
+    "supported Cluebase SDK package names from the official package contract",
+    "official public SDK function names and supported lifecycle API set",
+    "environment variable names produced by setup and consumed by setup code",
+    "machine-owned semantic workflow generation and verification",
+    "static rejection of known unsafe wiring such as leaked secrets, wrong SDKs, blocking lifecycle calls, and broad cluebase.track setup",
+    "local API connectivity preflight for the three required setup hops before real product-flow log verification",
+    "canonical frontend SDK adapter env names and initialization safety checks",
+    "static rejection of hardcoded cluebase.identify and cluebase.group identity values",
+    "static rejection of cluebase.identify in repeated auth helper paths unless the helper is proven to be the one-time auth success boundary",
+  ],
+};
+
+export const IDENTITY_BOUNDARY_CONTRACT = {
+  purpose:
+    "cluebase.identify records the authoritative identity event. It belongs only at the real auth success boundary that can prove the user identity and preserve browser linkage context when available.",
+  valid_boundaries: [
+    "frontend-owned login, sign-up, OAuth callback, magic-link, or OTP verification success",
+    "backend-owned auth success when the backend is the first reliable place that knows authentication succeeded",
+    "token exchange only when that exchange completes initial authentication, not when it only refreshes or rotates tokens",
+    "backend-only auth success without browser context, reported as backend-only evidence instead of browser-joinable identity",
+  ],
+  repeated_helper_exclusions: [
+    "token refresh",
+    "current-user or /me sync",
+    "session polling",
+    "request exchange helpers that only rotate or hydrate credentials",
+    "read hooks and query functions",
+    "repeated local helpers that run after identity is already established",
+  ],
+  rule:
+    "Do not add cluebase.identify to repeated helper paths by default. A repeated helper may emit identity only when repository evidence proves it is the actual one-time auth success boundary.",
+};
+
+export const GROUP_BOUNDARY_CONTRACT = {
+  purpose:
+    "cluebase.group records the active organization context. Setup must choose one organization-association owner per runtime surface instead of adding SDK calls to every place where the active organization becomes visible.",
+  owner_kinds: {
+    initial_context:
+      "Auth success that returns the initial active organization. Place immediately after cluebase.identify in that success branch.",
+    active_context_owner:
+      "Existing singleton provider, auth-state listener, or guarded active-context effect that observes user id + organization id/name and dedupes by userId:organizationId. This is the only owner for that surface when it observes active organization changes.",
+    context_change:
+      "Create, join, accept-invite, switch, or onboarding success handler. Use only when no active_context_owner on the same surface emits the same change.",
+  },
+  duplicate_owner_rule:
+    "Do not place cluebase.group in both a guarded active-context owner and create/join/switch handlers on the same surface. The SDK must not hide duplicate organization_associated rows caused by duplicate setup call sites.",
+};
+
+export const OTEL_FIRST_SETUP_CONTRACT = {
+  purpose:
+    "OpenTelemetry is the primary collection path wherever OpenTelemetry provides the signal. Setup guidance must teach OpenTelemetry, OpenLLMetry, and GenAI semantic instrumentation first.",
+  rules: [
+    "For backend request, ORM/database, AI, agent, tool, MCP, and framework signals covered by OpenTelemetry or current GenAI semantic conventions, install/use the OTel-primary SDK helper or standard OpenTelemetry/OpenLLMetry instrumentor first.",
+    "Cluebase helpers may enrich, correlate, mask, classify, or provide a fallback for unavailable OTel libraries; they must not replace OTel as the primary source for an OTel-available signal.",
+    "Do not pass raw prompts, completions, tool arguments, request bodies, SQL, bind values, or resource bodies into Cluebase helper arguments.",
+  ],
+};
+
+export const API_CONNECTIVITY_CONTRACT = {
+  purpose:
+    "Cluebase setup has three integration endpoints plus one setup-owned batch-status polling endpoint. setup-doctor probes the Cluebase endpoints with SDK-equivalent payloads and customer env files. The customer backend never carries a Cluebase browser-token route: the frontend SDK calls the Cluebase backend directly using the public project key, request Origin, and a short-lived browser token.",
+  hops: {
+    cluebase_backend_browser_token_issue: {
+      owner: "cluebase_backend",
+      method: "POST",
+      path: "/api/v1/ingest/browser-tokens",
+      caller: "customer_frontend_sdk",
+      purpose:
+        "Cluebase backend validates the project key and request Origin, then returns a short-lived browser token. Called directly by the frontend SDK; no customer backend route in between.",
+    },
+    browser_ingest: {
+      owner: "cluebase_backend",
+      method: "POST",
+      path: "/api/v1/ingest/browser",
+      caller: "customer_frontend_sdk",
+      env_name:
+        "framework-specific public CLUEBASE_API_BASE_URL name; Next.js uses NEXT_PUBLIC_CLUEBASE_API_BASE_URL",
+      purpose:
+        "Frontend SDK sends canonical observation source event batches with x-cluebase-browser-token.",
+    },
+    backend_ingest: {
+      owner: "cluebase_backend",
+      method: "POST",
+      path: "/api/v1/ingest/backend",
+      caller: "setup-doctor using backend SDK-equivalent payload",
+      env_name: "CLUEBASE_INGEST_ENDPOINT",
+      purpose:
+        "setup-doctor verifies backend ingest acceptance with server-side CLUEBASE_API_KEY. Real customer backend lifecycle emission is verified by product logs after the customer runs the local service.",
+    },
+    batch_status: {
+      owner: "cluebase_backend",
+      method: "GET",
+      path: "/api/v1/ingest/batch-status/:batchId",
+      caller: "setup-doctor",
+      env_name: "CLUEBASE_INGEST_ENDPOINT",
+      purpose:
+        "Setup verification polls accepted ingest batches until worker publish and durable publish evidence are proven.",
+    },
+  },
+  universal_http_fallback:
+    "The three ingest endpoints are the stable contract; the Cluebase SDKs are a convenience over them. Any stack with no matching Cluebase SDK integrates by calling POST /api/v1/ingest/browser-tokens, POST /api/v1/ingest/browser (x-cluebase-browser-token), and POST /api/v1/ingest/backend (x-cluebase-api-key) directly. The Cluebase environment is derived from the project key prefix; do not add customer-backend Cluebase proxy routes.",
+  preflight_command: "setup-doctor --local",
+  verification_states: [
+    "accepted",
+    "received",
+    "completed",
+    "published",
+  ],
+  product_flow_verification_boundary:
+    "setup-doctor verifies canonical ingest acceptance and records downstream publish evidence. Real customer frontend/backend lifecycle emission is verified from Cluebase setup logs after the customer runs the local product flow.",
+};
+
+export const FRONTEND_ADAPTER_CONTRACT = {
+  purpose:
+    "Frontend SDK adapter code is part of the Cluebase setup contract. The AI may choose where the adapter is imported, but must not invent token URL, env, or initialization semantics. The frontend SDK calls the Cluebase backend directly.",
+  nextjs_public_env: [
+    "NEXT_PUBLIC_CLUEBASE_PROJECT_KEY",
+    "NEXT_PUBLIC_CLUEBASE_API_BASE_URL",
+  ],
+  rules: [
+    "For Next.js App Router, prefer a client bootstrap module such as src/lib/cluebase.ts that calls cluebase.init once after required NEXT_PUBLIC_CLUEBASE_* values are present, exports a tiny Client Component such as CluebaseInit, and is rendered once from app/layout.tsx or the existing app bootstrap.",
+    "For non-Next.js browser/client code, use the framework-specific public env names generated by Cluebase setup instead of NEXT_PUBLIC_*.",
+    "Next.js frontend SDK adapter files must start with \"use client\".",
+    "Do not create a React component whose useEffect calls cluebase.init. Component lifecycle hooks, page components, sidebars, login/register success callbacks, and other repeated UI paths are rejected setup locations.",
+    "Do not call cluebase.init with empty-string fallbacks for required public Cluebase env values.",
+    "If a singleton guard is used, do not mark initialized=true before cluebase.init has been called with required config present.",
+    "Do not add a customer-backend route under /api/v1/cluebase/*. The frontend SDK calls the Cluebase backend directly for browser tokens.",
+  ],
+};
+
+export const OFFICIAL_SDK_CONTRACT = {
+  purpose:
+    "This bundled contract is the authoritative Cluebase SDK contract for Cluebase setup wiring. A customer repository is expected to start without Cluebase SDK imports or dependencies; absence of existing Cluebase code is not a blocker.",
+  frontend_sdk_hop: {
+    package_name: "@genn-inc/cluebase-frontend-sdk",
+    dependency_specifier: "@genn-inc/cluebase-frontend-sdk@latest",
+    import_path: "@genn-inc/cluebase-frontend-sdk",
+    public_lifecycle_apis: {
+      "cluebase.init":
+        "cluebase.init(options: { endpoint: string; projectKey: string; ... }): void  // environment (dev/prod) is derived from projectKey prefix (pk_dev_ vs pk_prod_). Browser token issuance is built in from the Cluebase API base URL, projectKey, and request Origin.",
+      "cluebase.identify":
+        "cluebase.identify(userId: string, traits?: Record<string, string | number | boolean | null>): void",
+      "cluebase.group":
+        'cluebase.group("organization", organizationId: string, traits?: Record<string, string | number | boolean | null>): void',
+      "cluebase.reset": "cluebase.reset(): void",
+    },
+    safety_contract:
+      "Public lifecycle APIs are no-throw wrappers. Do not add custom per-call try/catch or await them.",
+  },
+  backend_fastapi_sdk: {
+    package_name: "cluebase-backend-sdk",
+    dependency_specifier: "cluebase-backend-sdk",
+    python_import:
+      "from cluebase_backend_sdk._integrations.fastapi import cluebase_init_fastapi",
+    public_lifecycle_apis: {
+      "cluebase.init":
+        "cluebase_init_fastapi(app, project_key: str, api_key: str, service_key: str, ...) -> bool  // environment (dev/prod) is derived from project_key prefix (pk_dev_ vs pk_prod_)",
+      "cluebase.identify":
+        "cluebase.identify(user_id: str, traits: Mapping[str, object] | None = None) -> None",
+      "cluebase.group":
+        'cluebase.group("organization", organization_id: str, traits: Mapping[str, object] | None = None) -> None',
+      "cluebase.reset": "cluebase.reset() -> None",
+    },
+    safety_contract:
+      "Public lifecycle APIs catch SDK errors internally; FastAPI initialization reports success as bool and namespace lifecycle calls return None. Do not wrap each call solely for Cluebase failure isolation. Backend initialization must include the required SDK options. Cluebase env reads must be non-crashing; do not use os.environ[\"CLUEBASE_*\"] required indexing.",
+  },
+  minimal_file_creation_contract: {
+    allowed_when:
+      "No existing Cluebase adapter or client bootstrap wrapper exists in the customer repo.",
+    allowed_files:
+      "Only Cluebase-owned minimal SDK wiring files under existing frontend/backend source roots, plus exact replacements in existing files to import/register those files.",
+    rule:
+      "Creating a minimal Cluebase adapter is allowed setup wiring, not a host application refactor. Customer-backend routes such as /api/v1/cluebase/* are outside the Cluebase setup contract because the frontend SDK calls the Cluebase backend directly.",
+  },
+};
+
+export const setupDoctrineSkillLines = () => [
+  `- Purpose: ${SETUP_DOCTRINE.purpose}`,
+  `- Minimal diff reason: ${SETUP_DOCTRINE.minimal_diff_reason}`,
+  `- AI decision boundary: ${SETUP_DOCTRINE.ai_decision_boundary}`,
+  `- Static control boundary: ${SETUP_DOCTRINE.deterministic_control_boundary}`,
+  `- Documentation reason: ${SETUP_DOCTRINE.documentation_reason}`,
+  `- Failure posture: ${SETUP_DOCTRINE.failure_posture}`,
+  `- Group boundary: ${GROUP_BOUNDARY_CONTRACT.duplicate_owner_rule}`,
+  "- Read-only exploration boundary: the AI may choose additional repository files or plain-text searches, but the CLI owns the actual read/search tools, allowed paths, limits, and secret exclusions.",
+  `- Official SDK contract: ${OFFICIAL_SDK_CONTRACT.purpose}`,
+  `- API connectivity: ${API_CONNECTIVITY_CONTRACT.purpose}`,
+  `- Universal HTTP fallback: ${API_CONNECTIVITY_CONTRACT.universal_http_fallback}`,
+  `- Frontend adapter: ${FRONTEND_ADAPTER_CONTRACT.purpose}`,
+  `- API preflight: run ${API_CONNECTIVITY_CONTRACT.preflight_command} when local services and required env are available; then verify real product-flow event delivery from Cluebase setup logs or published batch evidence.`,
+];