@botonic/nx-plugin 2.28.0 → 2.30.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 2.30.0 (2026-06-11)
+
+### 🚀 Features
+
+- update botonic-basic-template ([#932](https://github.com/metis-ai/hubtype-product/pull/932))
+- update plugins to last botonicV0 changes #BLT-2370 ([#920](https://github.com/metis-ai/hubtype-product/pull/920))
+- **@botonic/dx-bundling:** derive Lambda noExternal deps programmatically ([#918](https://github.com/metis-ai/hubtype-product/pull/918))
+- support botonic v2 preview in flow builder ([#916](https://github.com/metis-ai/hubtype-product/pull/916))
+- wire plugin-hubtype-analytics into bot apps ([#909](https://github.com/metis-ai/hubtype-product/pull/909))
+
+### 🩹 Fixes
+
+- allow multiple, only picking webchat app id ([#896](https://github.com/metis-ai/hubtype-product/pull/896))
+
+### ❤️ Thank You
+
+- Marc Rabat @vanbasten17
+- Oriol Raventós @Iru89
+
+## 2.29.0 (2026-05-12)
+
+### 🚀 Features
+
+- **botonic:** v2 refinements - update skills, serve-bot defaults, staging bot warning ([#888](https://github.com/metis-ai/hubtype-product/pull/888))
+
+### ❤️ Thank You
+
+- David Hidalgo @Davidhidalgo
+
 ## 2.28.0 (2026-05-06)
 
 ### 🚀 Features

package/migrations.json

@@ -1,3 +1,10 @@
 {
-  "generators": {}
+  "generators": {
+    "install-claude-update-skills": {
+      "version": "2.29.0",
+      "description": "Replace .cursor/.claude command stubs with .claude/skills/botonic-update and .claude/skills/botonic-bot-update",
+      "cli": "nx",
+      "implementation": "./src/migrations/install-claude-update-skills/install-claude-update-skills.migration"
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botonic/nx-plugin",
-  "version": "2.28.0",
+  "version": "2.30.0",
   "description": "Nx plugin for creating Botonic bot applications",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -42,7 +42,8 @@
     "fs-extra": "^11.1.1",
     "qs": "^6.11.0",
     "yaml": "^2.6.1",
-    "zip-a-folder": "^1.1.0"
+    "zip-a-folder": "^1.1.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "nx": ">=21.0.0"

package/src/executors/deploy-local-runtime/executor.js

@@ -130,12 +130,16 @@ async function deployLocalRuntime(botonicApiService, projectRoot, params) {
       lambdaEndpoint
     });
     const allProviders = await botonicApiService.getProviders();
-    const appId = allProviders.data.results.filter(
-      (provider) => provider.is_test && provider.is_active
-    )[0].id;
-    console.log("\u2705 Local runtime deployment completed!");
-    updateEnvLocal(projectRoot, appId);
-    console.log(`\u{1F194} APP_ID: ${appId}`);
+    const appId = (0, import_executor_helpers.getActiveTestWebchatProviderAppId)(allProviders.data?.results);
+    if (!appId) {
+      console.error(
+        "\u274C No active test webchat provider found. Local runtime needs a webchat test provider on this bot."
+      );
+    } else {
+      console.log("\u2705 Local runtime deployment completed!");
+      updateEnvLocal(projectRoot, appId);
+      console.log(`\u{1F194} APP_ID: ${appId}`);
+    }
   } catch (error) {
     console.error("\u274C Local runtime deployment failed");
     console.error(`${String(error)}`);

package/src/executors/serve-bot/schema.json

@@ -7,9 +7,8 @@
   "properties": {
     "configuration": {
       "type": "string",
-      "description": "Configuration/environment to use",
-      "enum": ["local", "dev", "dev2", "qa", "prod"],
-      "default": "local"
+      "description": "Configuration/environment to use. Defaults to 'prod' in generated workspaces; set defaultConfiguration: 'local' in project.json for development repos.",
+      "enum": ["local", "dev", "dev2", "qa", "prod"]
     },
     "skipWebviews": {
       "type": "boolean",

package/src/generators/bot-app/files/src/client/webchat/index.tsx.template

@@ -66,8 +66,10 @@ function App({
     <WebchatTrigger
       appId={webchatConfig.appId}
       position='bottom-right'
+      loader={() => import('./webchat')}
       onReady={handleReady}
       webchatConfig={{
+        ...webchatConfig,
         avatarConfig,
         customMessages,
         title: options.title || '<%= className %>',

package/src/generators/bot-app/files/src/client/webchat/webchat.tsx.template

@@ -0,0 +1,111 @@
+import type { WebchatController } from '@botonic/webchat-core'
+import type {
+  WebchatCompositionExtras,
+  WebchatCompositionProps,
+} from '@botonic/webchat-react'
+import {
+  useWebchatContext,
+  WebchatContainer,
+  WebchatHeader,
+  WebchatInput,
+  WebchatMessages,
+  WebchatProvider,
+} from '@botonic/webchat-react'
+import { useEffect, useRef } from 'react'
+
+function WebchatContent({
+  isOpen,
+  onClose,
+  onControllerReady,
+  title,
+  placeholder,
+  showBranding,
+}: {
+  isOpen: boolean
+  onClose: () => void
+  onControllerReady: (controller: WebchatController) => void
+  title?: string
+  placeholder?: string
+  showBranding?: boolean
+}) {
+  const { controller } = useWebchatContext()
+  const hasNotifiedRef = useRef(false)
+
+  useEffect(() => {
+    if (controller && !hasNotifiedRef.current) {
+      hasNotifiedRef.current = true
+      onControllerReady(controller)
+    }
+  }, [controller, onControllerReady])
+
+  useEffect(() => {
+    if (!controller) return
+    const snapshot = controller.machine.getSnapshot()
+    const currentIsOpen = snapshot.context.isOpen ?? false
+    if (isOpen && !currentIsOpen) {
+      controller.open()
+    } else if (!isOpen && currentIsOpen) {
+      controller.close()
+    }
+  }, [isOpen, controller])
+
+  const handleClose = () => {
+    controller?.close()
+    onClose()
+  }
+
+  return (
+    <WebchatContainer layout='default'>
+      <WebchatHeader title={title} onClose={handleClose} />
+      <WebchatMessages variant='default' />
+      <WebchatInput
+        placeholder={placeholder}
+        showBranding={showBranding ?? true}
+        variant='default'
+      />
+    </WebchatContainer>
+  )
+}
+
+export default function Webchat({
+  appId,
+  isOpen,
+  onClose,
+  onControllerReady,
+  ...extras
+}: WebchatCompositionProps) {
+  // `WebchatCompositionProps` exposes extras via a `[key: string]: unknown`
+  // index signature, so assert the concrete shape once instead of per field.
+  const {
+    title,
+    placeholder,
+    showBranding,
+    customMessages = {},
+    avatarConfig,
+    webchatClientSettings,
+    enableResponsiveHeroHeader,
+    storage,
+    previewUtils,
+  } = extras as WebchatCompositionExtras
+
+  return (
+    <WebchatProvider
+      appId={appId}
+      customMessages={customMessages}
+      avatarConfig={avatarConfig}
+      webchatClientSettings={webchatClientSettings}
+      enableResponsiveHeroHeader={enableResponsiveHeroHeader}
+      storage={storage}
+      previewUtils={previewUtils}
+    >
+      <WebchatContent
+        isOpen={isOpen}
+        onClose={onClose}
+        onControllerReady={onControllerReady}
+        title={title}
+        placeholder={placeholder}
+        showBranding={showBranding}
+      />
+    </WebchatProvider>
+  )
+}

package/src/generators/bot-app/files/src/server/bot/plugins/flow-builder/index.ts.template

@@ -1,12 +1,13 @@
+import { BotonicContext } from '@botonic/core'
 import { AiAgentArgs } from '@botonic/plugin-ai-agents'
+import { BotonicPluginHubtypeAnalytics } from '@botonic/plugin-hubtype-analytics'
 import {
   BotonicPluginFlowBuilder,
   BotonicPluginFlowBuilderOptions,
   FlowBuilderJSONVersion,
 } from '@botonic/plugin-flow-builder'
-import { BotonicContext } from '@botonic/core'
+import { EventAction, HtEventProps } from '@botonic/shared'
 
-import { trackEventToHubtypeAnalytics } from '../../tracking'
 import { isLambdaLocal } from '../../utils'
 import { getAiAgentResponse } from '../ai-agents'
 
@@ -14,8 +15,16 @@ export const flowBuilderConfig: BotonicPluginFlowBuilderOptions = {
   flowVersion: isLambdaLocal()
     ? FlowBuilderJSONVersion.DRAFT
     : FlowBuilderJSONVersion.LATEST,
-  trackEvent: async (botonicContext: BotonicContext, eventAction, args) => {
-    await trackEventToHubtypeAnalytics(botonicContext, eventAction, args)
+  trackEvent: async (
+    context: BotonicContext,
+    eventAction: EventAction,
+    args: Omit<HtEventProps, 'action'>
+  ): Promise<void> => {
+    const analyticsPlugin = new BotonicPluginHubtypeAnalytics()
+    await analyticsPlugin.trackEvent(context, {
+      action: eventAction,
+      ...args,
+    } as HtEventProps)
   },
   getAiAgentResponse: async (
     botonicContext: BotonicContext,

package/src/generators/bot-app/files/src/server/bot/plugins/index.ts.template

@@ -1,5 +1,3 @@
-import { BotonicPluginHubtypeAnalytics } from '@botonic/plugin-hubtype-analytics'
-
 import { aiAgentsPlugin } from './ai-agents'
 import { flowBuilderPlugin } from './flow-builder'
 
@@ -7,5 +5,4 @@ export const plugins = {
   flowBuilder: flowBuilderPlugin,
   // AI Agents plugin is only loaded if AZURE_OPENAI_API_KEY or OPENAI_API_KEY is set
   ...(aiAgentsPlugin && { aiAgents: aiAgentsPlugin }),
-  hubtypeAnalytics: new BotonicPluginHubtypeAnalytics(),
 }

package/src/generators/bot-app/files/src/server/lambda/handler.js.template

@@ -3,7 +3,7 @@
 /*
 	In lambda functions, it only have access to all files the first time it's invoked,
 	and placed into memory, after that it only calls the function that have the information
-	loadded in memory. For this reason, we initialize the bot the first time, and then we
+	loaded in memory. For this reason, we initialize the bot the first time, and then we
 	only execute the input function
 
 	https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html

package/src/generators/bot-app/files/src/server/lambda/package.json

@@ -12,9 +12,9 @@
   "description": "",
   "dependencies": {
     "uuid": "^11.1.0",
-    "@openai/agents": "^0.1.11",
-    "openai": "^5.23.2",
+    "@openai/agents": "^0.10.1",
+    "openai": "^6.0.0",
     "tslib": "^2.3.0",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   }
 }

package/src/generators/bot-app/files/vite/botonic-ssr-deps.ts.template

@@ -0,0 +1,56 @@
+import { readFileSync, readdirSync } from 'fs'
+import { resolve } from 'path'
+
+// Build-only tools — never needed at Lambda runtime.
+const BUILD_ONLY_DEPS = new Set(['tslib', 'vite', 'vitest'])
+
+// Browser/UI-only packages pulled in by client-side @botonic/* packages
+// (webchat-react, webchat-core). They are never imported by the server entry.
+const BROWSER_ONLY_DEPS = new Set([
+  'react',
+  'react-dom',
+  'react-aria',
+  '@xstate/react',
+  '@lilara/foundations',
+  '@lilara/ui-web-react',
+  'class-variance-authority',
+  'react-markdown',
+  'rehype-external-links',
+  'remark-breaks',
+  'remark-gfm',
+])
+
+/**
+ * Collects all third-party dependencies declared by the @botonic/* packages
+ * installed in this app's node_modules. The result is used in the Lambda node
+ * build's `ssr.noExternal` so that these packages are bundled into the artifact,
+ * where no node_modules are available at runtime.
+ *
+ * Deriving the list from the installed @botonic/* package.json files keeps it
+ * correct as plugins add new dependencies, instead of a hand-maintained array.
+ */
+export function getBotonicThirdPartyDeps(appRoot: string): string[] {
+  const botonicDir = resolve(appRoot, 'node_modules/@botonic')
+  const thirdParty = new Set<string>()
+  for (const name of readdirSync(botonicDir)) {
+    try {
+      const pkgPath = resolve(botonicDir, name, 'package.json')
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      for (const dep of Object.keys({
+        ...pkg.dependencies,
+        ...pkg.peerDependencies,
+      })) {
+        if (
+          !dep.startsWith('@botonic/') &&
+          !BUILD_ONLY_DEPS.has(dep) &&
+          !BROWSER_ONLY_DEPS.has(dep)
+        ) {
+          thirdParty.add(dep)
+        }
+      }
+    } catch {
+      // skip packages without a readable package.json
+    }
+  }
+  return [...thirdParty]
+}

package/src/generators/bot-app/files/vite/node.config.ts.template

@@ -1,6 +1,7 @@
 import { resolve } from 'path'
 import type { UserConfig } from 'vite'
 
+import { getBotonicThirdPartyDeps } from './botonic-ssr-deps'
 import { BUILD_CONFIG } from './build.config'
 
 const projectRoot = resolve(__dirname, '..')
@@ -12,11 +13,13 @@ export function getNodeConfig(): UserConfig {
     root: projectRoot,
     cacheDir: resolve(projectRoot, BUILD_CONFIG.CACHE_DIR.node),
 
-    // SSR configuration - bundle @botonic/* packages into the lambda
-    // By default, Vite externalizes node_modules in SSR mode, but we need
-    // @botonic packages bundled since they won't be available at runtime in Lambda
+    // Bundle all @botonic/* packages and their third-party deps into the Lambda
+    // artifact. By default Vite SSR externalizes node_modules, but Lambda has no
+    // node_modules at runtime so everything must be self-contained.
+    // Third-party deps are derived programmatically from the @botonic/* package.json
+    // files so this list stays correct as plugins add new dependencies.
     ssr: {
-      noExternal: [/@botonic\/.*/],
+      noExternal: [/@botonic\/.*/, ...getBotonicThirdPartyDeps(projectRoot)],
     },
 
     build: {

package/src/generators/bot-app/files/vite/webchat.config.ts.template

@@ -9,6 +9,25 @@ const projectRoot = resolve(__dirname, '..')
 const output = BUILD_CONFIG.OUTPUT.webchat
 const server = BUILD_CONFIG.SERVER.webchat
 
+/**
+ * Returns the Vite `base` for the webchat bundle.
+ *
+ * Why this matters: the dashboard's flow-builder preview panel
+ * (`PreviewWebchatAppV2`) loads this bundle cross-origin from the bot's Netlify
+ * deploy while running on a different origin (localhost:4200 in dev, the
+ * dashboard domain in prod). With an absolute base ('/'), Vite resolves the
+ * bundle's dynamically-imported chunks as `/chunk.js` against the *host page's*
+ * origin — so the preview requests them from the dashboard origin and they 404.
+ *
+ * A relative base ('') makes those chunks resolve against the entry module's own
+ * origin (import.meta.url = Netlify) instead, so the preview loads the whole
+ * bundle from Netlify with no chunk 404s and no service-worker proxy. The dev
+ * server keeps '/' so its own HMR/asset paths keep working.
+ */
+function getCrossOriginSafeBase(command: 'serve' | 'build'): string {
+  return command === 'build' ? '' : '/'
+}
+
 export function getWebchatConfig(command: 'serve' | 'build'): UserConfig {
   const openPath =
     command === 'serve' && process.env.LOG_VIEWER_PORT
@@ -26,7 +45,7 @@ export function getWebchatConfig(command: 'serve' | 'build'): UserConfig {
     cacheDir: resolve(projectRoot, BUILD_CONFIG.CACHE_DIR.webchat),
     publicDir: resolve(projectRoot, BUILD_CONFIG.PUBLIC_DIR),
     appType: 'spa',
-    base: '/',
+    base: getCrossOriginSafeBase(command),
 
     server: {
       port: server.port,

package/src/generators/bot-app/generator.js

@@ -158,10 +158,11 @@ function createPackageJson(tree, options, botonicVersion, lilaraVersion) {
       "@lilara/ui-web": lilaraVersion,
       "@lilara/ui-web-react": lilaraVersion,
       react: "18.3.1",
-      "react-dom": "18.3.1"
+      "react-dom": "18.3.1",
+      zod: "^4.4.3"
     },
     devDependencies: {
-      "@nx/vite": "21.6.3",
+      "@nx/vite": "21.6.11",
       "@types/node": "22.13.0",
       "@types/react": "18.3.1",
       "@types/react-dom": "18.3.0",
@@ -169,7 +170,7 @@ function createPackageJson(tree, options, botonicVersion, lilaraVersion) {
       "@vitejs/plugin-react-swc": "^3.5.0",
       typescript: "5.7.3",
       vite: "7.1.9",
-      vitest: "^4.0.15"
+      vitest: "4.1.1"
     }
   };
   (0, import_devkit.writeJson)(tree, `${options.projectRoot}/package.json`, packageJson);
@@ -257,7 +258,7 @@ function addBotonicDependencies(tree, botonicVersion) {
     },
     // devDependencies
     {
-      "@nx/vite": "21.6.3",
+      "@nx/vite": "21.6.11",
       "@types/node": "22.13.0",
       "@types/react": "18.3.1",
       "@types/react-dom": "18.3.0",
@@ -265,7 +266,7 @@ function addBotonicDependencies(tree, botonicVersion) {
       "@vitejs/plugin-react-swc": "3.5.0",
       typescript: "5.7.3",
       vite: "7.1.9",
-      vitest: "^4.0.15"
+      vitest: "4.1.1"
     }
   );
 }

package/src/generators/bot-app/lilara-version.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.7.0"
+  "version": "0.9.0"
 }

package/src/generators/preset/files/.claude/skills/botonic-bot-update/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: botonic-bot-update
+description: >
+  Update a single Botonic bot app to the current workspace version — applies pending bot-app
+  generators and bumps @botonic/* dependencies. Use when user says "update bot",
+  "apply bot migrations", or "update <bot-name>". Run /botonic-update first to upgrade the
+  workspace itself.
+---
+
+# Update Botonic Bot
+
+## Workflow: Update Bot App to Current Workspace Version
+
+### Step 0: Detect Package Manager
+
+Check which package manager the workspace uses:
+
+- If `pnpm-lock.yaml` exists → use `pnpm`
+- Else → use `npm`
+
+Use the detected package manager for all subsequent commands.
+
+### Step 1: Get Target Version
+
+Read `node_modules/@botonic/nx-plugin/package.json` → `.version` field.
+This is the version the workspace was updated to and the target for this bot.
+
+If the file does not exist, tell user: "Could not find @botonic/nx-plugin in node_modules. Run /botonic-update first to install the latest version."
+
+### Step 2: Discover Bots
+
+Run `bash .claude/scripts/update-bot/discover-bots.sh` from the workspace root.
+Expected output: JSON list of bots with name, path, current `@botonic/core` version.
+
+### Step 3: Ask Which Bot
+
+Present the bot list to the user. Ask which SINGLE bot to update.
+**CRITICAL**: Never accept more than one bot. If user asks for multiple, explain why and ask them to pick one.
+
+### Step 4: Check Bot's Current State
+
+Read the selected bot's `package.json` (at `<bot-path>/package.json`):
+
+- Extract the current `@botonic/core` version (strip `^` / `~` prefixes for comparison).
+
+Read `.botonic/pending-bot-migrations.json` if it exists:
+
+- Filter entries where `appliedTo` does NOT include `<bot-name>`.
+
+Determine:
+
+- `hasVersionGap`: bot's `@botonic/core` version ≠ target version
+- `hasPendingMigrations`: any filtered pending migration entries exist
+
+If **neither** is true, report: "`<bot-name>` is already at v`<target>` with no pending migrations. All up to date." and stop.
+
+### Step 5: Ask Target Version (only when pending migrations exist)
+
+If `hasPendingMigrations`:
+
+- Show distinct `version` values from the pending migrations (sorted ascending).
+- Ask the user: "Which version would you like to update to?" (default: latest in list).
+- Only apply migrations whose `version` ≤ chosen target version.
+
+If there are **no** pending migrations (version gap only), skip this step — use the target version from Step 1.
+
+### Step 6: Check Git State
+
+Run `git status --porcelain`. If output is non-empty, STOP.
+Tell user: "Please commit or stash changes before updating."
+
+### Step 7: Create Branch
+
+`git checkout -b update/<bot-name>-to-v<target>`
+
+### Step 8: Apply Pending Migrations (if any)
+
+For each pending migration (in version order, filtered to `version` ≤ target):
+
+1. Run: `<package-manager> nx g <generator> --project=<bot-name>`
+2. If `migrationGuide` path exists, READ it. Follow verification checklist and manual steps.
+3. `git add -A && git commit -m "chore(<bot-name>): apply <generator-name>"`
+4. Mark bot as applied: update `.botonic/pending-bot-migrations.json` — add `<bot-name>` to the `appliedTo` array for this entry.
+5. `git add .botonic/pending-bot-migrations.json && git commit --amend --no-edit`
+
+### Step 9: Bump @botonic/\* Versions
+
+Check if the bot's `@botonic/core` version (after any migrations) still differs from the target version.
+
+If it does, edit `<bot-path>/package.json`:
+
+- Update **all** `@botonic/*` entries in `dependencies`, `devDependencies`, and `peerDependencies` to the exact target version (no `^` or `~`).
+
+`git add <bot-path>/package.json && git commit -m "chore(<bot-name>): bump @botonic/* to v<target>"`
+
+Skip this step only if the versions already match.
+
+### Step 10: Final Verification
+
+- `nx build <bot-name>`
+- Report: list all commits made, any remaining manual steps from migration guides
+- Suggest: `nx serve-bot <bot-name>` for manual testing
+
+## Examples
+
+### Example 1: Bot with pending migrations and a version gap
+
+User says: "Update my-bot" (currently on v2.17.0, workspace on v2.19.0, 2 pending migrations)
+
+1. Target version: 2.19.0 (from node_modules)
+2. discover-bots.sh → my-bot on v2.17.0
+3. Check state: hasVersionGap=true, hasPendingMigrations=true (v2.18.0, v2.19.0)
+4. Ask target: "Available versions: 2.18.0, 2.19.0. Update to which? [default: 2.19.0]"
+5. Branch: update/my-bot-to-v2.19.0
+6. Apply v2.18.0 generator → commit → mark applied
+7. Apply v2.19.0 generator → commit → mark applied
+8. Bump @botonic/\* to 2.19.0 in package.json → commit
+9. Report: "Done. 2 generators applied + version bumped to v2.19.0."
+
+### Example 2: New version with no bot-app migrations (version gap only)
+
+User says: "Update my-bot" (currently on v2.17.0, workspace on v2.18.0, no pending migrations)
+
+1. Target version: 2.18.0 (from node_modules)
+2. discover-bots.sh → my-bot on v2.17.0
+3. Check state: hasVersionGap=true, hasPendingMigrations=false
+4. No version selection prompt needed
+5. Branch: update/my-bot-to-v2.18.0
+6. Skip Step 8 (no migrations)
+7. Bump @botonic/\* to 2.18.0 in package.json → commit
+8. Report: "Done. No migrations needed — @botonic/\* bumped to v2.18.0."
+
+### Example 3: Bot already up to date
+
+User says: "Update customer-bot" (on v2.19.0, workspace on v2.19.0, no pending migrations)
+
+1. Target version: 2.19.0
+2. Check state: hasVersionGap=false, hasPendingMigrations=false
+3. Report: "customer-bot is already at v2.19.0 with no pending migrations. All up to date."
+
+### Example 4: Multiple bots requested (refuse)
+
+User says: "Update all bots"
+Response: "I update one bot at a time to ensure each migration is properly verified. Which bot would you like to start with? [list bots]"
+
+## Troubleshooting
+
+### Error: Generator reports "already up to date"
+
+Cause: The bot code was already manually updated before running the generator.
+Solution: The generator is idempotent and skipped correctly. Mark it as applied and continue to the version bump step.
+
+### Error: Build fails after generator
+
+Cause: Custom bot code uses removed/changed APIs.
+Solution:
+
+1. Read the migration guide "What it cannot handle" section
+2. Follow "Manual migration steps" for custom patterns
+3. Check TypeScript: `npx tsc --noEmit`

package/src/generators/preset/files/.claude/{commands/update-botonic.md → skills/botonic-update/SKILL.md}

@@ -1,3 +1,12 @@
+---
+name: botonic-update
+description: >
+  Update the Botonic workspace to the latest version by running nx migrate. Use when user says
+  "update botonic", "upgrade botonic", "update workspace", or wants to update @botonic/nx-plugin
+  to the latest version. If pending bot migrations are queued afterward, instruct user to run
+  /botonic-bot-update per bot.
+---
+
 # Update Botonic Workspace
 
 ## Workflow: Update Botonic to Latest Version
@@ -47,7 +56,7 @@ If output says "no migrations to run" and `package.json` was already at the late
 
 This runs any workspace-level migrations shipped by the target `@botonic/nx-plugin` version.
 
-If that version also queues bot-app generators, it may write `.botonic/pending-bot-migrations.json` for `/update-bot`.
+If that version also queues bot-app generators, it may write `.botonic/pending-bot-migrations.json` for `/botonic-bot-update`.
 
 ### Step 6: Commit
 
@@ -62,4 +71,4 @@ Report:
 - New version installed
 - Any workspace changes applied
 - Whether `.botonic/pending-bot-migrations.json` was created and how many generators are pending
-- If generators are pending, instruct user to run `/update-bot` to apply them per bot
+- If generators are pending, instruct user to run `/botonic-bot-update` to apply them per bot

package/src/lib/bot-config.d.ts

@@ -1,3 +1,11 @@
+export interface ToolConfigJSON {
+    name: string;
+    schema?: Record<string, unknown>;
+    description: string;
+}
+export interface WebviewConfigJSON {
+    name: string;
+}
 export interface BotConfigJSON {
     build_info: {
         node_version: string;
@@ -7,14 +15,9 @@ export interface BotConfigJSON {
     packages: Record<string, {
         version: string;
     }>;
-    tools: Array<{
-        name: string;
-        description: string;
-    }>;
+    tools: ToolConfigJSON[];
     payloads: string[];
-    webviews: Array<{
-        name: string;
-    }>;
+    webviews: WebviewConfigJSON[];
 }
 export declare class BotConfig {
     static get(projectRoot: string): Promise<BotConfigJSON>;

package/src/lib/bot-config.js

@@ -35,6 +35,7 @@ var childProcess = __toESM(require("child_process"));
 var import_fs = require("fs");
 var import_path = require("path");
 var util = __toESM(require("util"));
+var import_zod = require("zod");
 const CONSTANTS_PATH = "src/shared/constants";
 const TOOLS_PATH = "src/server/bot/tools";
 class BotConfig {
@@ -108,7 +109,10 @@ class BotConfig {
         return toolsModule.customTools.map(
           (tool) => ({
             name: tool.name,
-            description: tool.description
+            description: tool.description,
+            schema: import_zod.z.toJSONSchema(tool.schema, {
+              target: "draft-07"
+            })
           })
         );
       }

package/src/lib/util/executor-helpers.d.ts

@@ -70,11 +70,18 @@ export declare function writeLocalRuntimeBotToAppFolder(projectRoot: string, bot
  * Removes the app folder .botonic.json so the next run will prompt to create/select a new bot (e.g. after 404 when bot was deleted).
  */
 export declare function removeAppBotonicJson(projectRoot: string): void;
+export declare function ensureLocalRuntimeBot(botonicApiService: BotonicAPIService): Promise<void>;
+export type ProviderAccountListItem = {
+    id: string;
+    provider?: string;
+    is_test?: boolean;
+    is_active?: boolean;
+};
 /**
- * Ensures a local runtime bot is set: reuses one from .botonic.json, or prompts to select an existing bot or create a new one by name.
- * Used when performing deploy_local_runtime with a tunnel URL from serve-bot or serve-dev-tunnel target.
+ * APP_ID for local runtime must be the webchat test provider — not WhatsApp
+ * or other channels, which may also be test+active on the same bot.
  */
-export declare function ensureLocalRuntimeBot(botonicApiService: BotonicAPIService): Promise<void>;
+export declare function getActiveTestWebchatProviderAppId(results: ProviderAccountListItem[] | undefined): string | undefined;
 export interface PerformDeployLocalRuntimeOptions {
     email?: string;
     password?: string;

package/src/lib/util/executor-helpers.js

@@ -26,6 +26,7 @@ __export(executor_helpers_exports, {
   ensureLocalRuntimeBot: () => ensureLocalRuntimeBot,
   ensureLocalRuntimeBotBeforeTunnel: () => ensureLocalRuntimeBotBeforeTunnel,
   findMatchingConfigurationKey: () => findMatchingConfigurationKey,
+  getActiveTestWebchatProviderAppId: () => getActiveTestWebchatProviderAppId,
   getAppIdFromEnvFile: () => getAppIdFromEnvFile,
   getAppIdFromEnvFileForConfig: () => getAppIdFromEnvFileForConfig,
   getAvailableBots: () => getAvailableBots,
@@ -416,6 +417,22 @@ function removeAppBotonicJson(projectRoot) {
     (0, import_fs.unlinkSync)(path);
   }
 }
+async function promptConfirmStagingBot(botName) {
+  console.log(
+    `
+\u26A0\uFE0F  Bot "${botName}" will be created as a staging bot on the Hubtype platform.`
+  );
+  console.log(
+    `   To create a production bot, use the Hubtype dashboard or the deploy-to-hubtype command instead.
+`
+  );
+  const confirmation = await (0, import_enquirer.prompt)({
+    type: "confirm",
+    name: "confirm_staging",
+    message: "\u{1F6A6} Do you want to proceed?"
+  });
+  return confirmation.confirm_staging;
+}
 async function ensureLocalRuntimeBot(botonicApiService) {
   if (botonicApiService.hasLocalRuntimeBot()) {
     return;
@@ -436,6 +453,9 @@ async function ensureLocalRuntimeBot(botonicApiService) {
       }
     });
     const name = response2.bot_name.trim();
+    if (!await promptConfirmStagingBot(name)) {
+      throw new Error("Bot creation cancelled.");
+    }
     await createNewBotWithName(botonicApiService, name);
     return;
   }
@@ -467,6 +487,9 @@ async function ensureLocalRuntimeBot(botonicApiService) {
       }
     });
     const name = nameResponse.bot_name.trim();
+    if (!await promptConfirmStagingBot(name)) {
+      throw new Error("Bot creation cancelled.");
+    }
     await createNewBotWithName(botonicApiService, name);
     return;
   }
@@ -478,6 +501,12 @@ async function ensureLocalRuntimeBot(botonicApiService) {
     throw new Error("Bot selection failed");
   }
 }
+const WEBCHAT_PROVIDER = "webchat";
+function getActiveTestWebchatProviderAppId(results) {
+  return results?.find(
+    (p) => Boolean(p.is_test) && Boolean(p.is_active) && p.provider === WEBCHAT_PROVIDER
+  )?.id;
+}
 async function performDeployLocalRuntimeWithEndpoint(context, projectRoot, endpoint, options = {}) {
   const { targetEnvironment, environmentVariables } = resolveHubtypeEnvironment(
     context,
@@ -512,15 +541,18 @@ async function performDeployLocalRuntimeWithEndpoint(context, projectRoot, endpo
         lambdaEndpoint: endpoint
       });
       const providersResp = await botonicApiService.getProviders();
-      const appId = providersResp.data.results?.filter(
-        (p) => p.is_test && p.is_active
-      )[0]?.id;
+      const appId = getActiveTestWebchatProviderAppId(
+        providersResp.data.results
+      );
+      if (!appId) {
+        throw new Error(
+          "No active test webchat provider found for this bot. Local runtime requires a webchat test provider account."
+        );
+      }
       const resolvedTargetEnv = TARGET_ENV_NAMES.includes(
         targetEnvironment
       ) ? targetEnvironment : "local";
-      if (appId) {
-        await writeAppIdToEnvFile(projectRoot, appId, resolvedTargetEnv);
-      }
+      await writeAppIdToEnvFile(projectRoot, appId, resolvedTargetEnv);
       botonicApiService.saveAllCredentials();
       return {
         botId: botonicApiService.botInfo().id,
@@ -550,6 +582,7 @@ async function performDeployLocalRuntimeWithEndpoint(context, projectRoot, endpo
   ensureLocalRuntimeBot,
   ensureLocalRuntimeBotBeforeTunnel,
   findMatchingConfigurationKey,
+  getActiveTestWebchatProviderAppId,
   getAppIdFromEnvFile,
   getAppIdFromEnvFileForConfig,
   getAvailableBots,

package/src/migrations/install-claude-update-skills/install-claude-update-skills.migration.d.ts

@@ -0,0 +1,2 @@
+import { Tree } from '@nx/devkit';
+export default function installClaudeUpdateSkills(tree: Tree): Promise<void>;

package/src/migrations/install-claude-update-skills/install-claude-update-skills.migration.js

@@ -0,0 +1,290 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var install_claude_update_skills_migration_exports = {};
+__export(install_claude_update_skills_migration_exports, {
+  default: () => installClaudeUpdateSkills
+});
+module.exports = __toCommonJS(install_claude_update_skills_migration_exports);
+var import_devkit = require("@nx/devkit");
+const BOTONIC_BOT_UPDATE_SKILL = `---
+name: botonic-bot-update
+description: >
+  Update a single Botonic bot app to the current workspace version \u2014 applies pending bot-app
+  generators and bumps @botonic/* dependencies. Use when user says "update bot",
+  "apply bot migrations", or "update <bot-name>". Run /botonic-update first to upgrade the
+  workspace itself.
+---
+
+# Update Botonic Bot
+
+## Workflow: Update Bot App to Current Workspace Version
+
+### Step 0: Detect Package Manager
+
+Check which package manager the workspace uses:
+
+- If \`pnpm-lock.yaml\` exists \u2192 use \`pnpm\`
+- Else \u2192 use \`npm\`
+
+Use the detected package manager for all subsequent commands.
+
+### Step 1: Get Target Version
+
+Read \`node_modules/@botonic/nx-plugin/package.json\` \u2192 \`.version\` field.
+This is the version the workspace was updated to and the target for this bot.
+
+If the file does not exist, tell user: "Could not find @botonic/nx-plugin in node_modules. Run /botonic-update first to install the latest version."
+
+### Step 2: Discover Bots
+
+Run \`bash .claude/scripts/update-bot/discover-bots.sh\` from the workspace root.
+Expected output: JSON list of bots with name, path, current \`@botonic/core\` version.
+
+### Step 3: Ask Which Bot
+
+Present the bot list to the user. Ask which SINGLE bot to update.
+**CRITICAL**: Never accept more than one bot. If user asks for multiple, explain why and ask them to pick one.
+
+### Step 4: Check Bot's Current State
+
+Read the selected bot's \`package.json\` (at \`<bot-path>/package.json\`):
+- Extract the current \`@botonic/core\` version (strip \`^\` / \`~\` prefixes for comparison).
+
+Read \`.botonic/pending-bot-migrations.json\` if it exists:
+- Filter entries where \`appliedTo\` does NOT include \`<bot-name>\`.
+
+Determine:
+- \`hasVersionGap\`: bot's \`@botonic/core\` version \u2260 target version
+- \`hasPendingMigrations\`: any filtered pending migration entries exist
+
+If **neither** is true, report: "\`<bot-name>\` is already at v\`<target>\` with no pending migrations. All up to date." and stop.
+
+### Step 5: Ask Target Version (only when pending migrations exist)
+
+If \`hasPendingMigrations\`:
+- Show distinct \`version\` values from the pending migrations (sorted ascending).
+- Ask the user: "Which version would you like to update to?" (default: latest in list).
+- Only apply migrations whose \`version\` \u2264 chosen target version.
+
+If there are **no** pending migrations (version gap only), skip this step \u2014 use the target version from Step 1.
+
+### Step 6: Check Git State
+
+Run \`git status --porcelain\`. If output is non-empty, STOP.
+Tell user: "Please commit or stash changes before updating."
+
+### Step 7: Create Branch
+
+\`git checkout -b update/<bot-name>-to-v<target>\`
+
+### Step 8: Apply Pending Migrations (if any)
+
+For each pending migration (in version order, filtered to \`version\` \u2264 target):
+
+1. Run: \`<package-manager> nx g <generator> --project=<bot-name>\`
+2. If \`migrationGuide\` path exists, READ it. Follow verification checklist and manual steps.
+3. \`git add -A && git commit -m "chore(<bot-name>): apply <generator-name>"\`
+4. Mark bot as applied: update \`.botonic/pending-bot-migrations.json\` \u2014 add \`<bot-name>\` to the \`appliedTo\` array for this entry.
+5. \`git add .botonic/pending-bot-migrations.json && git commit --amend --no-edit\`
+
+### Step 9: Bump @botonic/* Versions
+
+Check if the bot's \`@botonic/core\` version (after any migrations) still differs from the target version.
+
+If it does, edit \`<bot-path>/package.json\`:
+- Update **all** \`@botonic/*\` entries in \`dependencies\`, \`devDependencies\`, and \`peerDependencies\` to the exact target version (no \`^\` or \`~\`).
+
+\`git add <bot-path>/package.json && git commit -m "chore(<bot-name>): bump @botonic/* to v<target>"\`
+
+Skip this step only if the versions already match.
+
+### Step 10: Final Verification
+
+- \`nx build <bot-name>\`
+- Report: list all commits made, any remaining manual steps from migration guides
+- Suggest: \`nx serve-bot <bot-name>\` for manual testing
+
+## Examples
+
+### Example 1: Bot with pending migrations and a version gap
+
+User says: "Update my-bot" (currently on v2.17.0, workspace on v2.19.0, 2 pending migrations)
+
+1. Target version: 2.19.0 (from node_modules)
+2. discover-bots.sh \u2192 my-bot on v2.17.0
+3. Check state: hasVersionGap=true, hasPendingMigrations=true (v2.18.0, v2.19.0)
+4. Ask target: "Available versions: 2.18.0, 2.19.0. Update to which? [default: 2.19.0]"
+5. Branch: update/my-bot-to-v2.19.0
+6. Apply v2.18.0 generator \u2192 commit \u2192 mark applied
+7. Apply v2.19.0 generator \u2192 commit \u2192 mark applied
+8. Bump @botonic/* to 2.19.0 in package.json \u2192 commit
+9. Report: "Done. 2 generators applied + version bumped to v2.19.0."
+
+### Example 2: New version with no bot-app migrations (version gap only)
+
+User says: "Update my-bot" (currently on v2.17.0, workspace on v2.18.0, no pending migrations)
+
+1. Target version: 2.18.0 (from node_modules)
+2. discover-bots.sh \u2192 my-bot on v2.17.0
+3. Check state: hasVersionGap=true, hasPendingMigrations=false
+4. No version selection prompt needed
+5. Branch: update/my-bot-to-v2.18.0
+6. Skip Step 8 (no migrations)
+7. Bump @botonic/* to 2.18.0 in package.json \u2192 commit
+8. Report: "Done. No migrations needed \u2014 @botonic/* bumped to v2.18.0."
+
+### Example 3: Bot already up to date
+
+User says: "Update customer-bot" (on v2.19.0, workspace on v2.19.0, no pending migrations)
+
+1. Target version: 2.19.0
+2. Check state: hasVersionGap=false, hasPendingMigrations=false
+3. Report: "customer-bot is already at v2.19.0 with no pending migrations. All up to date."
+
+### Example 4: Multiple bots requested (refuse)
+
+User says: "Update all bots"
+Response: "I update one bot at a time to ensure each migration is properly verified. Which bot would you like to start with? [list bots]"
+
+## Troubleshooting
+
+### Error: Generator reports "already up to date"
+
+Cause: The bot code was already manually updated before running the generator.
+Solution: The generator is idempotent and skipped correctly. Mark it as applied and continue to the version bump step.
+
+### Error: Build fails after generator
+
+Cause: Custom bot code uses removed/changed APIs.
+Solution:
+
+1. Read the migration guide "What it cannot handle" section
+2. Follow "Manual migration steps" for custom patterns
+3. Check TypeScript: \`npx tsc --noEmit\`
+`;
+const BOTONIC_UPDATE_SKILL = `---
+name: botonic-update
+description: >
+  Update the Botonic workspace to the latest version by running nx migrate. Use when user says
+  "update botonic", "upgrade botonic", "update workspace", or wants to update @botonic/nx-plugin
+  to the latest version. If pending bot migrations are queued afterward, instruct user to run
+  /botonic-bot-update per bot.
+---
+
+# Update Botonic Workspace
+
+## Workflow: Update Botonic to Latest Version
+
+### Step 0: Detect Package Manager
+
+Check which package manager the workspace uses:
+
+- If \`pnpm-lock.yaml\` exists \u2192 use \`pnpm\`
+- Else \u2192 use \`npm\`
+
+Use the detected package manager for all subsequent commands.
+
+### Step 1: Check Current State
+
+Run \`npm view @botonic/nx-plugin version\` to get the latest available version.
+Check \`node_modules/@botonic/nx-plugin/package.json\` for the currently installed version.
+
+If already on latest, report "already up to date" and stop.
+
+### Step 2: Check Git State
+
+Run \`git status --porcelain\`. If output is non-empty, STOP.
+Tell user: "Please commit or stash changes before updating."
+
+### Step 3: Run Nx Migrate
+
+\`\`\`
+npx nx migrate @botonic/nx-plugin@latest
+\`\`\`
+
+This updates \`package.json\` and creates \`migrations.json\`.
+
+If output says "no migrations to run" and \`package.json\` was already at the latest version, stop and report "already up to date".
+
+### Step 4: Install Dependencies
+
+\`\`\`
+<package-manager> install
+\`\`\`
+
+### Step 5: Run Workspace Migrations
+
+\`\`\`
+<package-manager> nx migrate --run-migrations
+\`\`\`
+
+This runs any workspace-level migrations shipped by the target \`@botonic/nx-plugin\` version.
+
+If that version also queues bot-app generators, it may write \`.botonic/pending-bot-migrations.json\` for \`/botonic-bot-update\`.
+
+### Step 6: Commit
+
+\`\`\`
+git add -A && git commit -m "chore: update @botonic/nx-plugin to v<version>"
+\`\`\`
+
+### Step 7: Report
+
+Report:
+
+- New version installed
+- Any workspace changes applied
+- Whether \`.botonic/pending-bot-migrations.json\` was created and how many generators are pending
+- If generators are pending, instruct user to run \`/botonic-bot-update\` to apply them per bot
+`;
+const OLD_FILES = [
+  ".cursor/commands/update-bot.md",
+  ".cursor/commands/update-botonic.md",
+  ".claude/commands/update-bot.md",
+  ".claude/commands/update-botonic.md"
+];
+async function installClaudeUpdateSkills(tree) {
+  let removedCount = 0;
+  for (const filePath of OLD_FILES) {
+    if (tree.exists(filePath)) {
+      tree.delete(filePath);
+      removedCount++;
+    }
+  }
+  tree.write(
+    ".claude/skills/botonic-bot-update/SKILL.md",
+    BOTONIC_BOT_UPDATE_SKILL
+  );
+  tree.write(".claude/skills/botonic-update/SKILL.md", BOTONIC_UPDATE_SKILL);
+  await (0, import_devkit.formatFiles)(tree);
+  if (removedCount > 0) {
+    import_devkit.logger.info(
+      `  \u2705 Removed ${removedCount} old command stub(s) (.cursor/commands/, .claude/commands/)`
+    );
+  }
+  import_devkit.logger.info(
+    `  \u2705 Installed .claude/skills/botonic-bot-update/SKILL.md (was /update-bot)`
+  );
+  import_devkit.logger.info(
+    `  \u2705 Installed .claude/skills/botonic-update/SKILL.md (was /update-botonic)`
+  );
+  import_devkit.logger.info(
+    `  \u2139\uFE0F  Use /botonic-bot-update to apply pending bot migrations and /botonic-update to upgrade the workspace`
+  );
+}

package/src/plugin.js

@@ -102,7 +102,7 @@ const configurations = {
   dev: {
     configuration: "dev",
     env: {
-      VITE_HUBTYPE_CLIENT_ID: "AcIVeUMYaqH6O17LiCzbR3phZcRmfxYQNYFMr3BI",
+      VITE_HUBTYPE_CLIENT_ID: "WlvymZ703Y5zGnmaCZ9Da5vf0lNX08jFvgC4pRMT",
       VITE_HUBTYPE_API_URL: "https://api.dev.dev.dev.hubtype.com",
       VITE_PUSHER_API_PREFIX: "dev-dev-dev"
     }

package/src/generators/bot-app/files/src/server/bot/tracking.ts.template

@@ -1,35 +0,0 @@
-import {
-  BotonicPluginHubtypeAnalytics,
-  EventAction,
-  HtEventProps,
-} from '@botonic/plugin-hubtype-analytics'
-import { BotonicContext } from '@botonic/core'
-
-import { BotPlugins } from './types'
-
-export async function trackEventToHubtypeAnalytics(
-  botonicContext: BotonicContext<BotPlugins>,
-  eventName: EventAction,
-  args: Omit<HtEventProps, 'action'>
-): Promise<void> {
-  const hubtypeAnalyticsPlugin = botonicContext.plugins.hubtypeAnalytics
-  const htEventProps = {
-    action: eventName,
-    ...args,
-  } as HtEventProps
-
-  if (
-    !hubtypeAnalyticsPlugin ||
-    !(hubtypeAnalyticsPlugin instanceof BotonicPluginHubtypeAnalytics)
-  ) {
-    console.log('Hubtype Analytics Plugin not found')
-    return
-  }
-
-  const response = await hubtypeAnalyticsPlugin.trackEvent(
-    botonicContext,
-    htEventProps
-  )
-  console.log('TrackEvent Response', response, args)
-  return
-}

package/src/generators/preset/files/.claude/commands/update-bot.md

@@ -1,114 +0,0 @@
-# Update Botonic Bot
-
-## Workflow: Apply Pending Bot Migrations
-
-### Step 0: Detect Package Manager
-
-Check which package manager the workspace uses:
-
-- If `pnpm-lock.yaml` exists → use `pnpm`
-- Else → use `npm`
-
-Use the detected package manager for all subsequent commands.
-
-### Step 1: Check Pending Migrations
-
-Read `.botonic/pending-bot-migrations.json`.
-
-If the file does not exist, tell user: "No pending bot migrations found. Run /update-botonic first to update the workspace."
-
-If the `pending` array is empty, tell user: "All bot migrations are already applied."
-
-### Step 2: Discover Bots
-
-Run `bash .claude/scripts/update-bot/discover-bots.sh` from the workspace root.
-Expected output: JSON list of bots with name, path, current version.
-
-### Step 3: Ask Which Bot
-
-Present the bot list to the user. Ask which SINGLE bot to update.
-**CRITICAL**: Never accept more than one bot. If user asks for multiple, explain why and ask them to pick one.
-
-### Step 4: Ask Target Version
-
-Show the distinct `version` values from all pending migrations (sorted ascending, e.g. `2.16.0`, `2.17.0`, `2.18.0`).
-
-Ask the user: "Which version would you like to update to?" (default: the latest version in the list).
-
-Only apply migrations whose `version` ≤ the chosen target version.
-
-### Step 5: Find Pending Migrations for Selected Bot
-
-Filter `.botonic/pending-bot-migrations.json` entries where ALL of:
-
-- `appliedTo` does NOT include `<bot-name>`, AND
-- `version` ≤ chosen target version
-
-If none, report: "<bot-name> has no pending migrations up to v<target>. All up to date."
-
-### Step 6: Check Git State
-
-Run `git status --porcelain`. If output is non-empty, STOP.
-Tell user: "Please commit or stash changes before updating."
-
-### Step 7: Create Branch
-
-`git checkout -b update/<bot-name>-pending-migrations`
-
-### Step 8: Apply Each Pending Generator
-
-For each pending migration (in version order, filtered to `version` ≤ target):
-
-1. Run: `<package-manager> nx g <generator> --project=<bot-name>`
-2. If `migrationGuide` path exists, READ it. Follow verification checklist and manual steps.
-3. `git add -A && git commit -m "chore(<bot-name>): apply <generator-name>"`
-4. Mark bot as applied: update `.botonic/pending-bot-migrations.json` — add `<bot-name>` to the `appliedTo` array for this entry.
-5. `git add .botonic/pending-bot-migrations.json && git commit --amend --no-edit`
-
-### Step 9: Final Verification
-
-- `nx build <bot-name>`
-- Report: list all commits, any remaining manual steps from migration guides
-- Suggest: `nx serve-bot <bot-name>` for manual testing
-
-## Examples
-
-### Example 1: Bot with two pending migrations
-
-User says: "Update my-bot"
-
-1. Read pending-bot-migrations.json → 2 entries (v2.0.1, v2.1.0), my-bot not in appliedTo for either
-2. discover-bots.sh → my-bot on v2.0.0
-3. Ask target: "Available versions: 2.0.1, 2.1.0. Update to which? [default: 2.1.0]" → user picks 2.1.0
-4. Branch: update/my-bot-pending-migrations
-5. Run first pending generator (v2.0.1) → read guide if present → commit → mark applied
-6. Run second pending generator (v2.1.0) → commit → mark applied
-7. Report: "Done. 2 generators applied to my-bot up to v2.1.0."
-
-### Example 2: Bot already up to date
-
-User says: "Update customer-bot"
-
-1. Read pending-bot-migrations.json → customer-bot is in appliedTo for all entries
-2. Report: "customer-bot has no pending migrations. All up to date."
-
-### Example 3: Multiple bots requested (refuse)
-
-User says: "Update all bots"
-Response: "I update one bot at a time to ensure each migration is properly verified. Which bot would you like to start with? [list bots]"
-
-## Troubleshooting
-
-### Error: Generator reports "already up to date"
-
-Cause: The bot code was already manually updated before running the generator.
-Solution: The generator is idempotent and skipped correctly. Mark it as applied and continue.
-
-### Error: Build fails after generator
-
-Cause: Custom bot code uses removed/changed APIs.
-Solution:
-
-1. Read the migration guide "What it cannot handle" section
-2. Follow "Manual migration steps" for custom patterns
-3. Check TypeScript: `npx tsc --noEmit`

package/src/generators/preset/files/.cursor/commands/update-bot.md

@@ -1,3 +0,0 @@
-# Update Botonic Bot
-
-Follow the workflow in `.claude/commands/update-bot.md`

package/src/generators/preset/files/.cursor/commands/update-botonic.md

@@ -1,3 +0,0 @@
-# Update Botonic Workspace
-
-Follow the workflow in `.claude/commands/update-botonic.md`