create-better-t-stack 3.40.4 → 3.41.0

package/README.md

@@ -128,6 +128,9 @@ This CLI collects anonymous usage data to help improve the tool. The data collec
 - CLI version
 - Node.js version
 - Platform (OS)
+- How the CLI was driven (prompts, flags, `--yes`, JSON, the programmatic API, or the MCP server)
+
+Separately, a small number of anonymous diagnostic events are sent for failures (stage and error class, never full messages or paths), cancelled prompts, other commands such as `add` and `history`, slow runs, and MCP tool usage. See the [analytics documentation](https://better-t-stack.dev/docs/analytics) for the exact list.
 
 **Telemetry is enabled by default in published versions** to help us understand usage patterns and improve the tool.
 
@@ -143,6 +146,8 @@ BTS_TELEMETRY_DISABLED=1 npx create-better-t-stack
 export BTS_TELEMETRY_DISABLED=1
 ```
 
+The CLI also honors the cross-tool `DO_NOT_TRACK=1` convention (https://consoledonottrack.com), and `--disable-analytics` skips telemetry for a single run.
+
 ## Examples
 
 Create a project with default configuration:

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli, v as types_exports, y as getLatestCLIVersion } from "./src-CpGAduw0.mjs";
+import { A as setProcessMode, S as getLatestCLIVersion, b as scrubReason, i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli, v as durationBucket, x as types_exports, y as reportDiagnostic } from "./src-NAkPN6DN.mjs";
 import z from "zod";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 //#region src/mcp.ts
 const ToolResponseSchema = z.object({
 	ok: z.boolean(),
@@ -58,6 +58,44 @@ function formatToolError(cause) {
 		isError: true
 	};
 }
+const reportedSessions = /* @__PURE__ */ new WeakSet();
+/** One session event per connection, sent when the client identity is first known. */
+function reportMcpSession(server) {
+	if (reportedSessions.has(server)) return;
+	reportedSessions.add(server);
+	const client = server.server.getClientVersion();
+	reportDiagnostic("mcp_session", {
+		client: client?.name ?? "unknown",
+		clientVersion: client?.version ?? "unknown"
+	});
+}
+/**
+* Times every tool call and reports the outcome. Diagnostics are fire-and-forget here
+* because the server process is long-lived and must not add latency to tool results.
+*/
+function instrumentTool(server, tool, handler, isOptedOut) {
+	return async (...args) => {
+		if (isOptedOut?.(...args)) return handler(...args);
+		reportMcpSession(server);
+		const startTime = Date.now();
+		const result = await handler(...args);
+		const ok = !("isError" in result);
+		reportDiagnostic("mcp_tool", {
+			tool,
+			ok,
+			duration: durationBucket(Date.now() - startTime)
+		});
+		if (!ok) reportDiagnostic("mcp_tool_error", {
+			tool,
+			error: "ToolError",
+			reason: scrubReason(result.structuredContent.error)
+		});
+		return result;
+	};
+}
+function isCreateOptedOut(input) {
+	return input.disableAnalytics === true;
+}
 function getProjectToolAnnotations() {
 	return {
 		destructiveHint: true,
@@ -79,7 +117,7 @@ function getStackGuidance() {
 			"For project creation, build a full explicit config before calling bts_plan_project.",
 			"Always call bts_plan_project before bts_create_project.",
 			"Only call bts_create_project after the plan succeeds and matches the user's intent.",
-			"Use bts_plan_addons before bts_add_addons for existing projects."
+			"Use bts_plan_addons before bts_add_addons when adding addons or scaffolding a workspace package in an existing project."
 		],
 		createContract: {
 			requiresExplicitFields: [
@@ -128,10 +166,14 @@ function getStackGuidance() {
 	};
 }
 function createBtsMcpServer() {
+	setProcessMode("mcp");
 	const server = new McpServer({
 		name: "create-better-t-stack",
 		version: getLatestCLIVersion()
-	}, { capabilities: { logging: {} } });
+	}, { cacheHints: { "tools/list": {
+		ttlMs: 3600 * 1e3,
+		cacheScope: "public"
+	} } });
 	server.registerTool("bts_get_stack_guidance", {
 		title: "Get Better T Stack MCP Guidance",
 		description: "Read MCP-specific guidance for choosing valid Better T Stack configurations. Use this before planning when user intent is ambiguous. This explains the full explicit config required by MCP project creation, plus important field semantics and ambiguity rules.",
@@ -143,13 +185,13 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async () => {
+	}, instrumentTool(server, "bts_get_stack_guidance", async () => {
 		try {
 			return formatToolSuccess(getStackGuidance());
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	server.registerTool("bts_get_schema", {
 		title: "Get Better T Stack Schemas",
 		description: "Inspect Better T Stack CLI and input schemas so agents can plan valid create/add requests. Use this together with bts_get_stack_guidance before creating a project if any part of the request is ambiguous.",
@@ -162,13 +204,13 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async ({ name }) => {
+	}, instrumentTool(server, "bts_get_schema", async ({ name }) => {
 		try {
 			return formatToolSuccess(getSchemaResult(name ?? "all"));
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	server.registerTool("bts_plan_project", {
 		title: "Plan Better T Stack Project",
 		description: "Validate and preview a Better T Stack project creation without writing files or provisioning resources. Always use this before bts_create_project. This tool requires an explicit full stack config rather than a partial payload with inferred defaults.",
@@ -181,7 +223,7 @@ function createBtsMcpServer() {
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_plan_project", async (input) => {
 		try {
 			const result = await create(input.projectName, {
 				...input,
@@ -200,7 +242,7 @@ function createBtsMcpServer() {
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}, isCreateOptedOut));
 	server.registerTool("bts_create_project", {
 		title: "Create Better T Stack Project",
 		description: "Create a Better T Stack project on disk using the same silent programmatic flow as the CLI JSON API. Call this only after bts_plan_project succeeds and the plan clearly matches the user's intent. This tool requires an explicit full stack config.",
@@ -210,69 +252,67 @@ function createBtsMcpServer() {
 			title: "Create Better T Stack Project",
 			...getProjectToolAnnotations()
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_create_project", async (input) => {
 		try {
 			if (input.install) return formatToolError(getMcpInstallTimeoutMessage(input.packageManager));
 			const result = await create(input.projectName, {
 				...input,
-				disableAnalytics: true
+				disableAnalytics: input.disableAnalytics ?? false
 			});
 			if (result.isErr()) return formatToolError(result.error);
 			return formatToolSuccess(result.value);
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}, isCreateOptedOut));
 	server.registerTool("bts_plan_addons", {
-		title: "Plan Better T Stack Addons",
-		description: "Validate and preview addon installation for an existing Better T Stack project without writing files. Always use this before bts_add_addons when the addon set or nested options are uncertain.",
+		title: "Plan Better T Stack Project Additions",
+		description: "Validate and preview addon installation or workspace package scaffolding for an existing Better T Stack project without writing files. Always use this before bts_add_addons.",
 		inputSchema: types_exports.AddInputSchema,
 		outputSchema: ToolResponseSchema,
 		annotations: {
-			title: "Plan Better T Stack Addons",
+			title: "Plan Better T Stack Project Additions",
 			readOnlyHint: true,
 			destructiveHint: false,
 			idempotentHint: true,
 			openWorldHint: false
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_plan_addons", async (input) => {
 		try {
 			const result = await add({
 				...input,
 				dryRun: true
 			});
-			if (!result?.success) return formatToolError(result?.error ?? "Failed to plan addon installation");
+			if (!result?.success) return formatToolError(result?.error ?? "Failed to plan project additions");
 			return formatToolSuccess(result);
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	server.registerTool("bts_add_addons", {
-		title: "Add Better T Stack Addons",
-		description: "Install addons into an existing Better T Stack project using the same silent flow as add-json. Call this only after bts_plan_addons succeeds and the planned changes match the user's intent.",
+		title: "Apply Better T Stack Project Additions",
+		description: "Install addons or scaffold a workspace package in an existing Better T Stack project using the same silent flow as add-json. Call this only after bts_plan_addons succeeds and the planned changes match the user's intent.",
 		inputSchema: types_exports.AddInputSchema,
 		outputSchema: ToolResponseSchema,
 		annotations: {
-			title: "Add Better T Stack Addons",
+			title: "Apply Better T Stack Project Additions",
 			destructiveHint: true,
 			idempotentHint: false,
 			openWorldHint: true
 		}
-	}, async (input) => {
+	}, instrumentTool(server, "bts_add_addons", async (input) => {
 		try {
 			const result = await add(input);
-			if (!result?.success) return formatToolError(result?.error ?? "Failed to add addons");
+			if (!result?.success) return formatToolError(result?.error ?? "Failed to update project");
 			return formatToolSuccess(result);
 		} catch (error) {
 			return formatToolError(error);
 		}
-	});
+	}));
 	return server;
 }
-async function startBtsMcpServer() {
-	const server = createBtsMcpServer();
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
+function startBtsMcpServer() {
+	return serveStdio(() => createBtsMcpServer());
 }
 //#endregion
 //#region src/cli.ts

package/dist/index.d.mts

@@ -12,9 +12,12 @@ declare const UserCancelledError_base: import("better-result").TaggedErrorClass<
  */
 declare class UserCancelledError extends UserCancelledError_base<{
   message: string;
+  /** Name of the prompt that was open when the user cancelled, when known. */
+  prompt?: string;
 }> {
   constructor(args?: {
     message?: string;
+    prompt?: string;
   });
 }
 declare const CLIError_base: import("better-result").TaggedErrorClass<"CLIError">;
@@ -153,6 +156,7 @@ interface AddResult {
   projectDir: string;
   dryRun?: boolean;
   plannedFileCount?: number;
+  addedPackage?: string;
   error?: string;
 }
 //#endregion
@@ -349,6 +353,7 @@ declare const router: import("@trpc/server").TRPCBuiltRouter<{
   add: import("@trpc/server").TRPCMutationProcedure<{
     input: {
       addons?: ("none" | "pwa" | "tauri" | "electrobun" | "starlight" | "biome" | "lefthook" | "husky" | "mcp" | "turborepo" | "nx" | "vite-plus" | "fumadocs" | "ultracite" | "oxlint" | "opentui" | "wxt" | "skills" | "evlog")[] | undefined;
+      package?: string | undefined;
       install?: boolean | undefined;
       packageManager?: "bun" | "npm" | "pnpm" | undefined;
       projectDir?: string | undefined;
@@ -360,6 +365,7 @@ declare const router: import("@trpc/server").TRPCBuiltRouter<{
   addJson: import("@trpc/server").TRPCMutationProcedure<{
     input: {
       addons?: ("none" | "pwa" | "tauri" | "electrobun" | "starlight" | "biome" | "lefthook" | "husky" | "mcp" | "turborepo" | "nx" | "vite-plus" | "fumadocs" | "ultracite" | "oxlint" | "opentui" | "wxt" | "skills" | "evlog")[] | undefined;
+      package?: string | undefined;
       addonOptions?: {
         wxt?: {
           template: "svelte" | "solid" | "vanilla" | "vue" | "react";
@@ -473,9 +479,9 @@ declare function builder(): Promise<void>;
  * ```
  */
 declare function createVirtual(options: Partial<Omit<types_d_exports.ProjectConfig, "projectDir" | "relativePath">>): Promise<Result$1<VirtualFileTree$1, GeneratorError$1>>;
-type AddOptions = Pick<types_d_exports.AddInput, "addons" | "addonOptions" | "install" | "packageManager" | "projectDir" | "dryRun">;
+type AddOptions = Pick<types_d_exports.AddInput, "addons" | "addonOptions" | "package" | "install" | "packageManager" | "projectDir" | "dryRun">;
 /**
- * Programmatic API to add addons to an existing Better-T-Stack project.
+ * Programmatic API to add addons or a workspace package to an existing Better-T-Stack project.
  *
  * @example
  * ```typescript

package/dist/index.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { C as DirectoryConflictError, E as ValidationError, S as DatabaseSetupError, T as UserCancelledError, _ as ProjectLauncherSchema, a as TEMPLATE_COUNT, b as CLIError, c as builder, d as createVirtual, f as docs, g as sponsors, h as router, i as SchemaNameSchema, l as create, m as getSchemaResult, n as GeneratorError, o as VirtualFileSystem, p as generate, r as Result, s as add, t as EMBEDDED_TEMPLATES, u as createBtsCli, w as ProjectCreationError, x as CompatibilityError } from "./src-CpGAduw0.mjs";
+import { C as CLIError, D as ProjectCreationError, E as DirectoryConflictError, O as UserCancelledError, T as DatabaseSetupError, _ as ProjectLauncherSchema, a as TEMPLATE_COUNT, c as builder, d as createVirtual, f as docs, g as sponsors, h as router, i as SchemaNameSchema, k as ValidationError, l as create, m as getSchemaResult, n as GeneratorError, o as VirtualFileSystem, p as generate, r as Result, s as add, t as EMBEDDED_TEMPLATES, u as createBtsCli, w as CompatibilityError } from "./src-NAkPN6DN.mjs";
 export { CLIError, CompatibilityError, DatabaseSetupError, DirectoryConflictError, EMBEDDED_TEMPLATES, GeneratorError, ProjectCreationError, ProjectLauncherSchema, Result, SchemaNameSchema, TEMPLATE_COUNT, UserCancelledError, ValidationError, VirtualFileSystem, add, builder, create, createBtsCli, createVirtual, docs, generate, getSchemaResult, router, sponsors };

package/dist/{src-CpGAduw0.mjs → src-NAkPN6DN.mjs}

@@ -234,6 +234,14 @@ const ADDON_COMPATIBILITY = {
 //#endregion
 //#region src/utils/context.ts
 const cliStorage = new AsyncLocalStorage();
+/** Process-wide mode for hosts that own the whole process, such as the MCP server. */
+let processMode;
+function setProcessMode(mode) {
+	processMode = mode;
+}
+function getProcessMode() {
+	return processMode;
+}
 function defaultContext() {
 	return {
 		navigation: {
@@ -241,7 +249,9 @@ function defaultContext() {
 			lastPromptShownUI: false
 		},
 		silent: false,
-		verbose: false
+		verbose: false,
+		promptShown: false,
+		analyticsDisabled: false
 	};
 }
 function getContext() {
@@ -264,6 +274,20 @@ function didLastPromptShowUI() {
 function getPromptProgress() {
 	return getContext().navigation.promptProgress;
 }
+function markPromptShown() {
+	const ctx = tryGetContext();
+	if (ctx) ctx.promptShown = true;
+}
+/**
+* How this run is being driven. Hosts that know (json, api, mcp) set it up front;
+* otherwise it is derived from whether prompts were rendered.
+*/
+function resolveInvocationMode(yes) {
+	const ctx = getContext();
+	if (ctx.mode) return ctx.mode;
+	if (yes) return "yes";
+	return ctx.promptShown ? "interactive" : "flags";
+}
 function setIsFirstPrompt$1(value) {
 	const ctx = tryGetContext();
 	if (ctx) ctx.navigation.isFirstPrompt = value;
@@ -276,19 +300,24 @@ function setPromptProgress(value) {
 	const ctx = tryGetContext();
 	if (ctx) ctx.navigation.promptProgress = value;
 }
-async function runWithContextAsync(options, fn) {
-	const ctx = {
+function createContext(options) {
+	return {
 		navigation: {
 			isFirstPrompt: false,
 			lastPromptShownUI: false
 		},
 		silent: options.silent ?? false,
 		verbose: options.verbose ?? false,
+		mode: options.mode ?? processMode,
+		promptShown: false,
+		analyticsDisabled: options.analyticsDisabled ?? false,
 		projectDir: options.projectDir,
 		projectName: options.projectName,
 		packageManager: options.packageManager
 	};
-	return cliStorage.run(ctx, fn);
+}
+async function runWithContextAsync(options, fn) {
+	return cliStorage.run(createContext(options), fn);
 }
 //#endregion
 //#region src/utils/terminal-output.ts
@@ -348,7 +377,10 @@ const cliConsola = {
 */
 var UserCancelledError = class extends TaggedError("UserCancelledError") {
 	constructor(args) {
-		super({ message: args?.message ?? "Operation cancelled" });
+		super({
+			message: args?.message ?? "Operation cancelled",
+			prompt: args?.prompt
+		});
 	}
 };
 /**
@@ -633,34 +665,36 @@ function formatHistoryEntry(entry, index) {
 	const details = rows.map(({ label, value }) => `${pc.dim(label.padEnd(labelWidth))}  ${value}`).join("\n");
 	return `${pc.cyan(pc.bold(`${index + 1}. ${entry.projectName}`))}\n${details}\n${pc.dim("Recreate")}\n${pc.cyan(entry.reproducibleCommand)}`;
 }
+/** Resolves to whether the command did what was asked; failures are reported to the user here. */
 async function historyHandler(input) {
 	if (input.clear) {
 		const clearResult = await clearHistory();
 		if (clearResult.isErr()) {
 			log.warn(pc.yellow(clearResult.error.message));
-			return;
+			return false;
 		}
 		log.success(pc.green("Project history cleared."));
-		return;
+		return true;
 	}
 	const historyResult = await getHistory(input.limit);
 	if (historyResult.isErr()) {
 		log.warn(pc.yellow(historyResult.error.message));
-		return;
+		return false;
 	}
 	const entries = historyResult.value;
 	if (input.json) {
 		console.log(JSON.stringify(entries, null, 2));
-		return;
+		return true;
 	}
 	renderTitle();
 	intro(pc.magenta(`Project history · ${entries.length}`));
 	if (entries.length === 0) {
 		outro(`${pc.dim("No saved projects yet · create one with")} ${pc.cyan("create-better-t-stack my-app")}`);
-		return;
+		return true;
 	}
 	log.message(entries.map(formatHistoryEntry).join("\n\n"));
 	outro(pc.dim("Run a command above to recreate that project"));
+	return true;
 }
 //#endregion
 //#region src/utils/open-url.ts
@@ -1704,6 +1738,125 @@ async function updateBtsConfig(projectDir, updates) {
 	} catch {}
 }
 //#endregion
+//#region src/utils/telemetry.ts
+/**
+* Returns true if telemetry/analytics should be enabled, false otherwise.
+*
+* - DO_NOT_TRACK=1 (the cross-tool convention from consoledonottrack.com) disables analytics.
+* - If BTS_TELEMETRY_DISABLED is present and "1", disables analytics.
+* - Otherwise, BTS_TELEMETRY: "0" disables, "1" enables (default: enabled).
+*/
+function isTelemetryEnabled() {
+	const DO_NOT_TRACK = process.env.DO_NOT_TRACK;
+	const BTS_TELEMETRY_DISABLED = process.env.BTS_TELEMETRY_DISABLED;
+	if (DO_NOT_TRACK === "1" || DO_NOT_TRACK?.toLowerCase() === "true") return false;
+	if (BTS_TELEMETRY_DISABLED !== void 0) return BTS_TELEMETRY_DISABLED !== "1";
+	return true;
+}
+//#endregion
+//#region src/utils/diagnostics.ts
+/**
+* Diagnostic events go to the self-hosted Umami instance (a separate "CLI" website),
+* not to the Convex project dataset. They cover what the project-creation event
+* cannot: failures, cancellations, non-create commands, slow stages, and MCP usage.
+* Everything is a no-op until UMAMI_CLI_WEBSITE_ID is baked in at build time.
+*/
+const UMAMI_HOST_URL = "https://umami.amanv.cloud";
+const UMAMI_CLI_WEBSITE_ID = "e658611d-dbcc-4d3a-bc4e-182b9f5b0d5d";
+const SEND_TIMEOUT_MS$1 = 3e3;
+const MAX_STRING_LENGTH = 500;
+const MAX_REASON_LENGTH = 160;
+const DURATION_BUCKETS = [
+	[1e3, "<1s"],
+	[5e3, "1-5s"],
+	[15e3, "5-15s"],
+	[6e4, "15-60s"],
+	[3e5, "1-5m"]
+];
+function durationBucket(elapsedMs) {
+	for (const [limit, label] of DURATION_BUCKETS) if (elapsedMs < limit) return label;
+	return ">5m";
+}
+/** Class name of the failure, which is stable and never carries user content. */
+function errorClass(cause) {
+	if (cause instanceof Error) return cause.name || cause.constructor.name || "Error";
+	return "UnknownError";
+}
+/** Coarse stage a create/add failure belongs to, derived from the tagged error types. */
+function failureStage(cause) {
+	if (ProjectCreationError.is(cause)) return cause.phase;
+	if (DatabaseSetupError.is(cause)) return "database-setup";
+	if (AddonSetupError.is(cause)) return "addons-setup";
+	if (DirectoryConflictError.is(cause)) return "directory";
+	if (ValidationError.is(cause) || CompatibilityError.is(cause)) return "validate";
+	if (CLIError.is(cause)) return "config";
+	return "unknown";
+}
+/**
+* First line of an error message with anything that could identify a machine or
+* project replaced by placeholders: file paths, URLs, emails, and quoted names.
+*/
+function scrubReason(cause) {
+	const scrubbed = ((cause instanceof Error ? cause.message : String(cause)).split(/\r?\n/, 1)[0] ?? "").replaceAll(/(["'`])(?:(?!\1).)*\1/g, "<name>").replaceAll(/https?:\/\/[^\s)\]"'>]+/gi, "<url>").replaceAll(/[\w.+-]+@[\w-]+\.[\w.-]+/g, "<email>").replaceAll(/(?:[a-zA-Z]:)?(?:[\\/][\w.@+ -]+)+[\\/][\w.@+-]+(?:[ \w.@+-]*\.\w+)?/g, "<path>").replaceAll(/\S*[\\/]\S*/g, "<path>").replaceAll(/\s+/g, " ").trim();
+	return scrubbed.length > MAX_REASON_LENGTH ? scrubbed.slice(0, MAX_REASON_LENGTH) : scrubbed;
+}
+function clampValue(value) {
+	const text = String(value);
+	return text.length > MAX_STRING_LENGTH ? text.slice(0, MAX_STRING_LENGTH) : value;
+}
+function isDiagnosticsEnabled() {
+	return Boolean(UMAMI_HOST_URL) && Boolean(UMAMI_CLI_WEBSITE_ID) && isTelemetryEnabled() && !getContext().analyticsDisabled;
+}
+function eventUrl(name, data) {
+	if (name.startsWith("mcp_")) return "/mcp";
+	const command = data.command;
+	return command === void 0 ? `/${name}` : `/${String(command)}`;
+}
+function buildDiagnosticPayload(name, data) {
+	const eventData = {};
+	for (const [key, value] of Object.entries(data)) if (value !== void 0) eventData[key] = clampValue(value);
+	return {
+		type: "event",
+		payload: {
+			website: UMAMI_CLI_WEBSITE_ID,
+			hostname: "cli",
+			url: eventUrl(name, eventData),
+			title: name,
+			name,
+			data: eventData
+		}
+	};
+}
+function diagnosticUserAgent() {
+	return `Mozilla/5.0 (compatible; create-better-t-stack/${getLatestCLIVersion()})`;
+}
+async function reportDiagnostic(name, data) {
+	if (!isDiagnosticsEnabled()) return;
+	await Result.tryPromise({
+		try: () => fetch(`${UMAMI_HOST_URL}/api/send`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"User-Agent": diagnosticUserAgent()
+			},
+			body: JSON.stringify(buildDiagnosticPayload(name, data)),
+			signal: AbortSignal.timeout(SEND_TIMEOUT_MS$1),
+			keepalive: true
+		}),
+		catch: () => void 0
+	});
+}
+/** Reports a stage only when it crossed the slow threshold, so the event is a signal. */
+async function reportSlowStage(command, stage, elapsedMs, packageManager) {
+	if (elapsedMs < 6e4) return;
+	await reportDiagnostic("cli_slow", {
+		command,
+		stage,
+		duration: durationBucket(elapsedMs),
+		packageManager
+	});
+}
+//#endregion
 //#region src/utils/input-hardening.ts
 function hasControlCharacters(value) {
 	for (const char of value) {
@@ -2561,6 +2714,7 @@ async function navigableGroup(prompts, opts) {
 			setIsFirstPrompt$1(currentIndex === 0);
 			setLastPromptShownUI(false);
 			const presetResult = opts?.preselected?.[name];
+			if (presetResult === void 0) markPromptShown();
 			const result = presetResult !== void 0 ? presetResult : await prompt({
 				results,
 				previousAnswer: previousAnswers[name]
@@ -2577,7 +2731,10 @@ async function navigableGroup(prompts, opts) {
 			if (isCancel$1(result)) {
 				if (opts?.onCancel) {
 					results[name] = "canceled";
-					opts.onCancel({ results });
+					opts.onCancel({
+						results,
+						prompt: String(name)
+					});
 				}
 				return results;
 			}
@@ -4653,6 +4810,68 @@ const TASK_RUNNER_ADDONS = [
 	"nx",
 	"vite-plus"
 ];
+const fileExistsErrorSchema = z.object({ code: z.literal("EEXIST") });
+const configPackageScopeSchema = z.object({ name: z.string().regex(/^@[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?\/config$/) }).transform(({ name }) => name.slice(0, -7));
+const rootTypescriptVersionSchema = z.object({ devDependencies: z.object({ typescript: z.string().min(1) }) }).transform(({ devDependencies }) => devDependencies.typescript);
+function isFileExistsError(cause) {
+	return fileExistsErrorSchema.safeParse(cause).success;
+}
+async function reserveWorkspacePackage(projectDir, packageName) {
+	const packageDir = path.join(projectDir, "packages", packageName);
+	return Result.tryPromise({
+		try: async () => {
+			await fs.mkdir(packageDir);
+			return packageDir;
+		},
+		catch: (cause) => new CLIError({
+			message: isFileExistsError(cause) ? `Workspace package already exists: packages/${packageName}` : `Failed to reserve workspace package: packages/${packageName}`,
+			cause
+		})
+	});
+}
+async function addWorkspacePackage(vfs, projectDir, packageName, packageManager) {
+	const packageDir = path.join(projectDir, "packages", packageName);
+	if (await fs.pathExists(packageDir)) return Result.err(new CLIError({ message: `Workspace package already exists: packages/${packageName}` }));
+	const configPackagePath = path.join(projectDir, "packages", "config", "package.json");
+	const packageScopeResult = await Result.tryPromise({
+		try: async () => configPackageScopeSchema.parse(await fs.readJson(configPackagePath)),
+		catch: (cause) => new CLIError({
+			message: "Cannot determine the workspace package scope. Expected packages/config/package.json to have a name like @my-app/config.",
+			cause
+		})
+	});
+	if (packageScopeResult.isErr()) return Result.err(packageScopeResult.error);
+	const typescriptVersionResult = await Result.tryPromise({
+		try: async () => rootTypescriptVersionSchema.parse(await fs.readJson(path.join(projectDir, "package.json"))),
+		catch: (cause) => new CLIError({
+			message: "Cannot determine the TypeScript version. Expected package.json to declare devDependencies.typescript.",
+			cause
+		})
+	});
+	if (typescriptVersionResult.isErr()) return Result.err(typescriptVersionResult.error);
+	const packageScope = packageScopeResult.value;
+	const fullPackageName = `${packageScope}/${packageName}`;
+	if (fullPackageName.length > 214) return Result.err(new CLIError({ message: "Workspace package name must not exceed 214 characters including its scope." }));
+	const packagePath = `packages/${packageName}`;
+	vfs.writeFile(`${packagePath}/package.json`, `${JSON.stringify({
+		name: fullPackageName,
+		version: "0.0.0",
+		private: true,
+		type: "module",
+		exports: { ".": "./src/index.ts" },
+		scripts: { "check-types": "tsc --noEmit" },
+		devDependencies: {
+			[`${packageScope}/config`]: packageManager === "npm" ? "*" : "workspace:*",
+			typescript: typescriptVersionResult.value
+		}
+	}, null, 2)}\n`);
+	vfs.writeFile(`${packagePath}/tsconfig.json`, `${JSON.stringify({
+		extends: `${packageScope}/config/tsconfig.base.json`,
+		include: ["src/**/*.ts"]
+	}, null, 2)}\n`);
+	vfs.writeFile(`${packagePath}/src/index.ts`, "export {};\n");
+	return Result.ok(void 0);
+}
 function mergeAddonOptions(existingAddonOptions, nextAddonOptions) {
 	if (!existingAddonOptions && !nextAddonOptions) return;
 	const mergeOption = (existing, next) => {
@@ -4697,9 +4916,14 @@ function updateViteConfigImportsForVitePlus(vfs) {
 	}
 }
 async function addHandler(input, options = {}) {
-	const { silent = false } = options;
-	return runWithContextAsync({ silent }, async () => {
+	const { silent = false, mode } = options;
+	return runWithContextAsync({
+		silent,
+		mode
+	}, async () => {
+		const startTime = Date.now();
 		const result = await addHandlerInternal(input);
+		await reportAddOutcome(input, result, Date.now() - startTime);
 		if (result.isOk()) return result.value;
 		const error = result.error;
 		if (UserCancelledError.is(error)) {
@@ -4721,6 +4945,42 @@ async function addHandler(input, options = {}) {
 		process.exit(1);
 	});
 }
+async function reportAddOutcome(input, result, elapsedMs) {
+	const mode = resolveInvocationMode(false);
+	const duration = durationBucket(elapsedMs);
+	if (result.isOk()) {
+		await reportDiagnostic("cli_command", {
+			command: "add",
+			mode,
+			ok: true,
+			duration
+		});
+		return;
+	}
+	const error = result.error;
+	if (UserCancelledError.is(error)) {
+		await reportDiagnostic("cli_cancelled", {
+			command: "add",
+			mode,
+			prompt: error.prompt ?? "unknown"
+		});
+		return;
+	}
+	await reportDiagnostic("cli_command", {
+		command: "add",
+		mode,
+		ok: false,
+		duration
+	});
+	await reportDiagnostic("cli_failed", {
+		command: "add",
+		mode,
+		stage: failureStage(error),
+		error: errorClass(error),
+		reason: scrubReason(error),
+		packageManager: input.packageManager
+	});
+}
 async function addHandlerInternal(input) {
 	const projectDir = input.projectDir || process.cwd();
 	const hardeningResult = validateAgentSafePathInput(projectDir, "projectDir");
@@ -4733,12 +4993,12 @@ async function addHandlerInternal(input) {
 		intro(pc.magenta("Add to your project"));
 	}
 	const existingConfig = await detectProjectConfig(projectDir);
-	if (!existingConfig) return Result.err(new CLIError({ message: `No Better-T-Stack project found in ${projectDir}. Make sure bts.jsonc exists.` }));
+	if (!existingConfig) return Result.err(new CLIError({ message: `No Better-T-Stack project found in "${projectDir}". Make sure bts.jsonc exists.` }));
 	if (!isSilent()) log.info(pc.dim(`Detected project: ${existingConfig.projectName}`));
 	let addonsToAdd;
 	if (input.addons && input.addons.length > 0) {
 		addonsToAdd = input.addons.filter((addon) => addon !== "none" && !existingConfig.addons.includes(addon));
-		if (addonsToAdd.length === 0) {
+		if (addonsToAdd.length === 0 && !input.package) {
 			if (!isSilent()) {
 				log.warn(pc.yellow("Nothing to add — those addons are already installed"));
 				outro(pc.dim("Project unchanged"));
@@ -4749,7 +5009,8 @@ async function addHandlerInternal(input) {
 				projectDir
 			});
 		}
-	} else if (isSilent()) return Result.err(new CLIError({ message: "Addons are required in silent mode. Provide them via add() or add-json." }));
+	} else if (input.package) addonsToAdd = [];
+	else if (isSilent()) return Result.err(new CLIError({ message: "Addons or a package are required in silent mode." }));
 	else {
 		const promptResult = await Result.tryPromise({
 			try: () => getAddonsToAdd(existingConfig),
@@ -4776,7 +5037,10 @@ async function addHandlerInternal(input) {
 	const updatedAddons = [...existingConfig.addons, ...addonsToAdd];
 	const addonsValidationResult = validateAddonsAgainstConfig(updatedAddons, existingConfig);
 	if (addonsValidationResult.isErr()) return Result.err(new CLIError({ message: addonsValidationResult.error.message }));
-	if (!isSilent()) log.info(`${pc.dim("Adding")} ${pc.cyan(formatConfigValue(addonsToAdd))}`);
+	if (!isSilent()) {
+		const additions = [addonsToAdd.length > 0 ? formatConfigValue(addonsToAdd) : void 0, input.package ? `package ${input.package}` : void 0].filter(Boolean);
+		log.info(`${pc.dim("Adding")} ${pc.cyan(additions.join(" and "))}`);
+	}
 	const mergedAddonOptions = mergeAddonOptions(existingConfig.addonOptions, input.addonOptions);
 	const config = {
 		projectName: existingConfig.projectName,
@@ -4804,33 +5068,41 @@ async function addHandlerInternal(input) {
 		...config,
 		addons: updatedAddons
 	};
-	const requirementsResult = await checkLocalRequirements(updatedConfig);
-	if (requirementsResult.isErr()) return Result.err(requirementsResult.error);
-	if (!isSilent()) for (const warning of requirementsResult.value.warnings) log.warn(pc.yellow(warning));
-	if (!isSilent()) log.info(pc.dim("Preparing addon files…"));
+	if (addonsToAdd.length > 0) {
+		const requirementsResult = await checkLocalRequirements(updatedConfig);
+		if (requirementsResult.isErr()) return Result.err(requirementsResult.error);
+		if (!isSilent()) for (const warning of requirementsResult.value.warnings) log.warn(pc.yellow(warning));
+	}
+	if (!isSilent()) log.info(pc.dim("Preparing files…"));
 	const vfs = new VirtualFileSystem();
-	for (const pkgPath of ADD_PACKAGE_JSON_PATHS) {
-		const fullPath = path.join(projectDir, pkgPath);
-		if (await fs.pathExists(fullPath)) {
-			const content = await fs.readFile(fullPath, "utf-8");
-			vfs.writeFile(pkgPath, content);
+	if (input.package) {
+		const packageResult = await addWorkspacePackage(vfs, projectDir, input.package, existingConfig.packageManager);
+		if (packageResult.isErr()) return Result.err(packageResult.error);
+	}
+	if (addonsToAdd.length > 0) {
+		for (const pkgPath of ADD_PACKAGE_JSON_PATHS) {
+			const fullPath = path.join(projectDir, pkgPath);
+			if (await fs.pathExists(fullPath)) {
+				const content = await fs.readFile(fullPath, "utf-8");
+				vfs.writeFile(pkgPath, content);
+			}
 		}
-	}
-	for (const filePath of ADD_TEXT_FILE_PATHS) {
-		const fullPath = path.join(projectDir, filePath);
-		if (await fs.pathExists(fullPath)) {
-			const content = await fs.readFile(fullPath, "utf-8");
-			vfs.writeFile(filePath, content);
+		for (const filePath of ADD_TEXT_FILE_PATHS) {
+			const fullPath = path.join(projectDir, filePath);
+			if (await fs.pathExists(fullPath)) {
+				const content = await fs.readFile(fullPath, "utf-8");
+				vfs.writeFile(filePath, content);
+			}
 		}
+		await processAddonTemplates(vfs, EMBEDDED_TEMPLATES, config);
+		processAddonsDeps(vfs, config);
+		if (addonsToAdd.includes("turborepo")) processTurboConfig(vfs, updatedConfig);
+		if (addonsToAdd.includes("nx")) processNxConfig(vfs, updatedConfig);
+		if (addonsToAdd.includes("vite-plus")) processVitePlusConfig(vfs, updatedConfig);
+		if (updatedAddons.some((addon) => TASK_RUNNER_ADDONS.includes(addon))) processPackageConfigs(vfs, updatedConfig);
+		if (updatedAddons.includes("vite-plus")) updateViteConfigImportsForVitePlus(vfs);
+		if (shouldRefreshLefthook(addonsToAdd, updatedAddons)) refreshLefthookTemplate(vfs, updatedConfig);
 	}
-	await processAddonTemplates(vfs, EMBEDDED_TEMPLATES, config);
-	processAddonsDeps(vfs, config);
-	if (addonsToAdd.includes("turborepo")) processTurboConfig(vfs, updatedConfig);
-	if (addonsToAdd.includes("nx")) processNxConfig(vfs, updatedConfig);
-	if (addonsToAdd.includes("vite-plus")) processVitePlusConfig(vfs, updatedConfig);
-	if (updatedAddons.some((addon) => TASK_RUNNER_ADDONS.includes(addon))) processPackageConfigs(vfs, updatedConfig);
-	if (updatedAddons.includes("vite-plus")) updateViteConfigImportsForVitePlus(vfs);
-	if (shouldRefreshLefthook(addonsToAdd, updatedAddons)) refreshLefthookTemplate(vfs, updatedConfig);
 	const tree = {
 		root: vfs.toTree(""),
 		fileCount: vfs.getFileCount(),
@@ -4840,7 +5112,7 @@ async function addHandlerInternal(input) {
 	if (input.dryRun) {
 		if (!isSilent()) {
 			log.success(pc.green("Dry run passed · no files written"));
-			log.message(pc.dim(`${vfs.getFileCount()} addon files planned`));
+			log.message(pc.dim(`${vfs.getFileCount()} files planned`));
 			outro(pc.dim("Project unchanged"));
 		}
 		return Result.ok({
@@ -4848,17 +5120,41 @@ async function addHandlerInternal(input) {
 			addedAddons: addonsToAdd,
 			projectDir,
 			dryRun: true,
-			plannedFileCount: vfs.getFileCount()
+			plannedFileCount: vfs.getFileCount(),
+			addedPackage: input.package
 		});
 	}
+	let reservedPackageDir;
+	if (input.package) {
+		const reservationResult = await reserveWorkspacePackage(projectDir, input.package);
+		if (reservationResult.isErr()) return Result.err(reservationResult.error);
+		reservedPackageDir = reservationResult.value;
+	}
 	const writeResult = await writeTree(tree, projectDir);
-	if (writeResult.isErr()) return Result.err(new CLIError({ message: `Failed to write addon files: ${writeResult.error.message}` }));
-	if (vfs.getFileCount() > 0 && !isSilent()) log.info(pc.dim(`Wrote ${vfs.getFileCount()} addon files`));
+	if (writeResult.isErr()) {
+		if (reservedPackageDir && input.package) {
+			const cleanupResult = await Result.tryPromise({
+				try: () => fs.remove(reservedPackageDir),
+				catch: (cause) => new CLIError({
+					message: `Failed to clean up incomplete workspace package: packages/${input.package}`,
+					cause
+				})
+			});
+			if (cleanupResult.isErr()) return Result.err(new CLIError({
+				message: `Failed to write files: ${writeResult.error.message}. ${cleanupResult.error.message}`,
+				cause: cleanupResult.error
+			}));
+		}
+		return Result.err(new CLIError({ message: `Failed to write files: ${writeResult.error.message}` }));
+	}
+	if (vfs.getFileCount() > 0 && !isSilent()) log.info(pc.dim(`Wrote ${vfs.getFileCount()} files`));
 	const setupResult = await Result.tryPromise({
-		try: () => setupAddons({
-			...config,
-			addons: getSetupAddons(addonsToAdd, updatedAddons)
-		}),
+		try: async () => {
+			if (addonsToAdd.length > 0) await setupAddons({
+				...config,
+				addons: getSetupAddons(addonsToAdd, updatedAddons)
+			});
+		},
 		catch: (cause) => {
 			if (UserCancelledError.is(cause)) return cause;
 			return new CLIError({
@@ -4868,7 +5164,7 @@ async function addHandlerInternal(input) {
 		}
 	});
 	if (setupResult.isErr()) return Result.err(setupResult.error);
-	await updateBtsConfig(projectDir, {
+	if (addonsToAdd.length > 0) await updateBtsConfig(projectDir, {
 		addons: updatedAddons,
 		addonOptions: updatedConfig.addonOptions
 	});
@@ -4877,7 +5173,8 @@ async function addHandlerInternal(input) {
 		packageManager: config.packageManager
 	});
 	if (!isSilent()) {
-		log.success(pc.green(`Added ${formatConfigValue(addonsToAdd)}`));
+		const additions = [addonsToAdd.length > 0 ? formatConfigValue(addonsToAdd) : void 0, input.package ? `package ${input.package}` : void 0].filter(Boolean);
+		log.success(pc.green(`Added ${additions.join(" and ")}`));
 		if (!input.install) {
 			const installCommand = config.packageManager === "npm" ? "npm install" : `${config.packageManager} install`;
 			log.message(`${pc.dim("Next step")}\n${pc.cyan(installCommand)}`);
@@ -4888,7 +5185,8 @@ async function addHandlerInternal(input) {
 		success: true,
 		addedAddons: addonsToAdd,
 		projectDir,
-		plannedFileCount: vfs.getFileCount()
+		plannedFileCount: vfs.getFileCount(),
+		addedPackage: input.package
 	});
 }
 //#endregion
@@ -5980,8 +6278,11 @@ async function gatherConfig(flags, projectName, projectDir, relativePath, option
 				]
 			}
 		],
-		onCancel: () => {
-			throw new UserCancelledError({ message: "Operation cancelled" });
+		onCancel: ({ prompt }) => {
+			throw new UserCancelledError({
+				message: "Operation cancelled",
+				prompt
+			});
 		}
 	});
 	return {
@@ -6051,6 +6352,7 @@ async function getProjectName(initialName) {
 		counter++;
 	}
 	while (!isValid) {
+		markPromptShown();
 		const response = await text({
 			message: "Where should we create your project?",
 			placeholder: defaultName,
@@ -6065,40 +6367,34 @@ async function getProjectName(initialName) {
 				}
 			}
 		});
-		if (isCancel(response)) throw new UserCancelledError({ message: "Operation cancelled." });
+		if (isCancel(response)) throw new UserCancelledError({
+			message: "Operation cancelled.",
+			prompt: "projectName"
+		});
 		projectPath = response || defaultName;
 		isValid = true;
 	}
 	return projectPath;
 }
 //#endregion
-//#region src/utils/telemetry.ts
-/**
-* Returns true if telemetry/analytics should be enabled, false otherwise.
-*
-* - If BTS_TELEMETRY_DISABLED is present and "1", disables analytics.
-* - Otherwise, BTS_TELEMETRY: "0" disables, "1" enables (default: enabled).
-*/
-function isTelemetryEnabled() {
-	const BTS_TELEMETRY_DISABLED = process.env.BTS_TELEMETRY_DISABLED;
-	if (BTS_TELEMETRY_DISABLED !== void 0) return BTS_TELEMETRY_DISABLED !== "1";
-	return true;
-}
-//#endregion
 //#region src/utils/analytics.ts
 const CONVEX_INGEST_URL = "https://striped-seahorse-863.convex.site/api/analytics/ingest";
+const SEND_TIMEOUT_MS = 3e3;
 async function sendConvexEvent(payload) {
 	await Result.tryPromise({
 		try: () => fetch(CONVEX_INGEST_URL, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify(payload)
+			body: JSON.stringify(payload),
+			signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+			keepalive: true
 		}),
 		catch: () => void 0
 	});
 }
-function buildAnalyticsEvent(config) {
+function buildAnalyticsEvent(config, mode) {
 	return types_exports.AnalyticsEventSchema.parse({
+		mode,
 		database: config.database,
 		orm: config.orm,
 		backend: config.backend,
@@ -6120,10 +6416,10 @@ function buildAnalyticsEvent(config) {
 		platform: process.platform
 	});
 }
-async function trackProjectCreation(config, disableAnalytics = false) {
+async function trackProjectCreation(config, disableAnalytics = false, mode) {
 	if (!isTelemetryEnabled() || disableAnalytics) return;
 	await Result.tryPromise({
-		try: () => sendConvexEvent(buildAnalyticsEvent(config)),
+		try: () => sendConvexEvent(buildAnalyticsEvent(config, mode)),
 		catch: () => void 0
 	});
 }
@@ -8709,10 +9005,14 @@ async function createProject(options, cliInput) {
 		}));
 		yield* Result.await(formatProject(projectDir));
 		if (!isSilent()) log.success("Project scaffolded");
-		if (options.install) yield* Result.await(installDependencies({
-			projectDir,
-			packageManager: options.packageManager
-		}));
+		if (options.install) {
+			const installStartTime = Date.now();
+			yield* Result.await(installDependencies({
+				projectDir,
+				packageManager: options.packageManager
+			}));
+			await reportSlowStage("create", "install", Date.now() - installStartTime, options.packageManager);
+		}
 		yield* Result.await(initializeGit(projectDir, options.git));
 		if (!isSilent()) await displayPostInstallInstructions({
 			...options,
@@ -8775,17 +9075,49 @@ function createEmptyResult(timeScaffolded, elapsedTimeMs, error) {
 	};
 }
 async function executeCreateProjectHandler(input, options) {
-	const { silent = false } = options;
-	return runWithContextAsync({ silent }, async () => {
+	const { silent = false, mode } = options;
+	return runWithContextAsync({
+		silent,
+		mode,
+		analyticsDisabled: input.disableAnalytics
+	}, async () => {
 		const startTime = Date.now();
 		const timeScaffolded = (/* @__PURE__ */ new Date()).toISOString();
+		const result = await createProjectHandlerInternal(input, startTime, timeScaffolded);
+		await reportCreateOutcome(input, result, Date.now() - startTime);
 		return {
-			result: await createProjectHandlerInternal(input, startTime, timeScaffolded),
+			result,
 			startTime,
 			timeScaffolded
 		};
 	});
 }
+/** Diagnostics for what the success-only project event cannot show; awaited so it beats process.exit. */
+async function reportCreateOutcome(input, result, elapsedMs) {
+	const mode = resolveInvocationMode(input.yes);
+	if (result.isOk()) {
+		if (!input.dryRun) await reportSlowStage("create", "create", elapsedMs, input.packageManager ?? "unknown");
+		return;
+	}
+	const error = result.error;
+	if (UserCancelledError.is(error)) {
+		await reportDiagnostic("cli_cancelled", {
+			command: "create",
+			mode,
+			prompt: error.prompt ?? "unknown"
+		});
+		return;
+	}
+	await reportDiagnostic("cli_failed", {
+		command: "create",
+		mode,
+		stage: failureStage(error),
+		error: errorClass(error),
+		reason: scrubReason(error),
+		packageManager: input.packageManager,
+		backend: input.backend
+	});
+}
 async function createProjectHandlerResult(input, options = {}) {
 	return (await executeCreateProjectHandler(input, options)).result;
 }
@@ -8958,7 +9290,7 @@ async function createProjectHandlerInternal(input, startTime, timeScaffolded) {
 			dbSetupOptions: effectiveDbSetupOptions,
 			packageManagerVersion: localRequirements.packageManagerVersion
 		}));
-		await trackProjectCreation(config, input.disableAnalytics);
+		await trackProjectCreation(config, input.disableAnalytics, resolveInvocationMode(input.yes));
 		const historyResult = await addToHistory(config, reproducibleCommand);
 		if (historyResult.isErr() && !isSilent()) {
 			log.warn(pc.yellow(historyResult.error.message));
@@ -9159,17 +9491,21 @@ const router = t.router({
 		description: "Create a project from a raw JSON payload (agent-friendly)",
 		jsonInput: "always"
 	}).input(types_exports.CreateInputSchema).mutation(async ({ input }) => {
-		const result = await createProjectHandler(input, { silent: true });
+		const result = await createProjectHandler(input, {
+			silent: true,
+			mode: "json"
+		});
 		if (!result) throw new UserCancelledError({ message: "Operation cancelled" });
 		if (!result.success) throw new CLIError({ message: result.error || "Unknown error occurred" });
 		return result;
 	}),
 	schema: t.procedure.meta({ description: "Show runtime CLI and input schemas as JSON" }).input(z.object({ name: SchemaNameSchema.describe("Schema name to inspect") })).query(({ input }) => getSchemaResult(input.name)),
-	sponsors: t.procedure.meta({ description: "Show Better-T-Stack sponsors" }).mutation(() => showSponsorsCommand()),
-	docs: t.procedure.meta({ description: "Open Better-T-Stack documentation" }).mutation(() => openDocsCommand()),
-	builder: t.procedure.meta({ description: "Open the web-based stack builder" }).mutation(() => openBuilderCommand()),
-	add: t.procedure.meta({ description: "Add addons to an existing Better-T-Stack project" }).input(z.object({
+	sponsors: t.procedure.meta({ description: "Show Better-T-Stack sponsors" }).mutation(() => trackCommand("sponsors", () => showSponsorsCommand())),
+	docs: t.procedure.meta({ description: "Open Better-T-Stack documentation" }).mutation(() => trackCommand("docs", () => openDocsCommand())),
+	builder: t.procedure.meta({ description: "Open the web-based stack builder" }).mutation(() => trackCommand("builder", () => openBuilderCommand())),
+	add: t.procedure.meta({ description: "Add addons or a workspace package to an existing Better-T-Stack project" }).input(z.object({
 		addons: z.array(types_exports.AddonsSchema).optional().describe("Addons to add"),
+		package: types_exports.WorkspacePackageNameSchema.optional(),
 		install: z.boolean().optional().default(false).describe("Install dependencies after adding"),
 		packageManager: types_exports.PackageManagerSchema.optional().describe("Package manager to use"),
 		projectDir: z.string().optional().describe("Project directory (defaults to current)"),
@@ -9178,10 +9514,13 @@ const router = t.router({
 		await addHandler(input);
 	}),
 	addJson: t.procedure.meta({
-		description: "Add addons from a raw JSON payload (agent-friendly)",
+		description: "Add addons or a workspace package from a raw JSON payload (agent-friendly)",
 		jsonInput: "always"
 	}).input(types_exports.AddInputSchema).mutation(async ({ input }) => {
-		const result = await addHandler(input, { silent: true });
+		const result = await addHandler(input, {
+			silent: true,
+			mode: "json"
+		});
 		if (!result) throw new UserCancelledError({ message: "Operation cancelled" });
 		if (!result.success) throw new CLIError({ message: result.error || "Unknown error occurred" });
 		return result;
@@ -9191,9 +9530,29 @@ const router = t.router({
 		clear: z.boolean().optional().default(false).describe("Clear all history"),
 		json: z.boolean().optional().default(false).describe("Output as JSON")
 	})).mutation(async ({ input }) => {
-		await historyHandler(input);
+		await trackCommand("history", () => historyHandler(input), (ok) => ok);
 	})
 });
+/** Usage diagnostics for commands that have no project event of their own. */
+async function trackCommand(command, run, isOk = () => true) {
+	const startTime = Date.now();
+	try {
+		const value = await run();
+		await reportDiagnostic("cli_command", {
+			command,
+			ok: isOk(value),
+			duration: durationBucket(Date.now() - startTime)
+		});
+		return value;
+	} catch (cause) {
+		await reportDiagnostic("cli_command", {
+			command,
+			ok: false,
+			duration: durationBucket(Date.now() - startTime)
+		});
+		throw cause;
+	}
+}
 function createBtsCli() {
 	return createCli({
 		router,
@@ -9251,7 +9610,10 @@ async function create(projectName, options) {
 	};
 	return Result.tryPromise({
 		try: async () => {
-			const result = await createProjectHandlerResult(input, { silent: true });
+			const result = await createProjectHandlerResult(input, {
+				silent: true,
+				mode: getProcessMode() ?? "api"
+			});
 			if (result.isErr()) throw result.error;
 			return result.value;
 		},
@@ -9342,7 +9704,7 @@ async function createVirtual(options) {
 	});
 }
 /**
-* Programmatic API to add addons to an existing Better-T-Stack project.
+* Programmatic API to add addons or a workspace package to an existing Better-T-Stack project.
 *
 * @example
 * ```typescript
@@ -9366,7 +9728,10 @@ async function add(options = {}) {
 		projectDir: "",
 		error: formatInputValidationError("add", parsedInput.error)
 	};
-	return await addHandler(parsedInput.data, { silent: true }) ?? {
+	return await addHandler(parsedInput.data, {
+		silent: true,
+		mode: getProcessMode() ?? "api"
+	}) ?? {
 		success: false,
 		addedAddons: [],
 		projectDir: parsedInput.data.projectDir ?? "",
@@ -9374,4 +9739,4 @@ async function add(options = {}) {
 	};
 }
 //#endregion
-export { DirectoryConflictError as C, ValidationError as E, DatabaseSetupError as S, UserCancelledError as T, ProjectLauncherSchema as _, TEMPLATE_COUNT as a, CLIError as b, builder as c, createVirtual as d, docs as f, sponsors as g, router as h, SchemaNameSchema as i, create as l, getSchemaResult as m, GeneratorError$1 as n, VirtualFileSystem$1 as o, generate$1 as p, Result$1 as r, add as s, EMBEDDED_TEMPLATES$1 as t, createBtsCli as u, types_exports as v, ProjectCreationError as w, CompatibilityError as x, getLatestCLIVersion as y };
+export { setProcessMode as A, CLIError as C, ProjectCreationError as D, DirectoryConflictError as E, UserCancelledError as O, getLatestCLIVersion as S, DatabaseSetupError as T, ProjectLauncherSchema as _, TEMPLATE_COUNT as a, scrubReason as b, builder as c, createVirtual as d, docs as f, sponsors as g, router as h, SchemaNameSchema as i, ValidationError as k, create as l, getSchemaResult as m, GeneratorError$1 as n, VirtualFileSystem$1 as o, generate$1 as p, Result$1 as r, add as s, EMBEDDED_TEMPLATES$1 as t, createBtsCli as u, durationBucket as v, CompatibilityError as w, types_exports as x, reportDiagnostic as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-better-t-stack",
-  "version": "3.40.4",
+  "version": "3.41.0",
   "description": "A modern CLI tool for scaffolding end-to-end type-safe TypeScript projects with best practices and customizable configurations",
   "keywords": [
     "better-auth",
@@ -69,11 +69,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@better-t-stack/template-generator": "^3.40.4",
-    "@better-t-stack/types": "^3.40.4",
+    "@better-t-stack/template-generator": "^3.41.0",
+    "@better-t-stack/types": "^3.41.0",
     "@clack/core": "^1.4.3",
     "@clack/prompts": "^1.7.0",
-    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@trpc/server": "^11.18.0",
     "better-result": "^3.0.0",
     "consola": "^3.4.2",
@@ -93,6 +93,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
     "@types/bun": "^1.3.14",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^26.1.2",