Fix apps-mcp agent behavior: localhost preference and deployment conf…

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/CLAUDE.md

@@ -8,8 +8,8 @@ TypeScript full-stack template powered by **Databricks AppKit** with tRPC for ad
 ## NPM Scripts
 
 ### Development
-- `npm run dev` - Start dev server with hot reload (use during active development)
-- `npm start` - Start production server (requires `npm run build` first)
+- `npm run dev` - Start dev server with hot reload (**ALWAYS use this during development**)
+- `npm start` - Start production server (**NEVER use during development - production only!**)
 
 ### Build
 - `npm run build` - Full build (server + client) - use before deployment
@@ -35,7 +35,152 @@ TypeScript full-stack template powered by **Databricks AppKit** with tRPC for ad
 **Common workflows:**
 - Development: `npm run dev` → make changes → `npm run typecheck` → `npm run lint:fix`
 - Pre-commit: `npm run typecheck && npm run lint:fix && npm run format:fix && npm test`
-- Pre-deploy: `npm run build && npm start` (test locally) → `npm test`
+- Pre-deploy: Validate with `databricks experimental apps-mcp tools validate .`
+
+**CRITICAL - npm run dev vs npm start:**
+```
+┌─────────────────────────────────────────────────────┐
+│ DURING DEVELOPMENT: ALWAYS use `npm run dev`       │
+│ - Hot reload enabled                                │
+│ - Fast iteration                                    │
+│ - Runs on localhost:8000                           │
+│                                                     │
+│ NEVER use `npm start` during development!          │
+│ - npm start is for production deployment only      │
+│ - No hot reload                                     │
+│ - Requires build step first                        │
+└─────────────────────────────────────────────────────┘
+```
+
+## Deployment Procedures
+
+**CRITICAL**: Deployment is a significant action that affects live environments. NEVER deploy without explicit user confirmation.
+
+### Before Deploying
+
+**ALWAYS** confirm with the user first by asking: "Ready to deploy to [environment]?"
+
+Pre-deployment checklist:
+1. ✅ App validated successfully (`databricks experimental apps-mcp tools validate .`)
+2. ✅ Local testing completed (`npm run dev` and manual verification)
+3. ✅ User explicitly approved deployment
+4. ✅ Code committed to git (recommended)
+
+### Deployment Commands
+
+```bash
+databricks bundle deploy              # Deploy app infrastructure
+databricks bundle run app            # Start the app
+databricks bundle summary            # Get deployed app URL
+```
+
+Or use the all-in-one command:
+```bash
+databricks experimental apps-mcp tools deploy  # Validates, deploys, and runs
+```
+
+**DO NOT** run deployment commands unless the user explicitly requests it or confirms when asked.
+
+## Local Development vs Deployed Apps
+
+**CRITICAL**: Understand the difference between local development and deployed environments.
+
+### During Development (Before Deployment)
+
+When the user asks to "open the app", "see the app", "view the app", or "open a dev copy":
+
+- ✅ **Use localhost**: `http://localhost:8000`
+- ✅ **Requires**: `npm run dev` must be running
+- ✅ **Purpose**: Hot reload, fast iteration, debugging
+
+**DO NOT** suggest deployed URLs (staging/production) during active development!
+
+### After Deployment
+
+Only after running `databricks bundle deploy && databricks bundle run app`:
+
+- ✅ **Use deployed URL**: Get from `databricks bundle summary`
+- ✅ **Purpose**: Production/staging environment, sharing with others
+
+### Decision Tree
+
+```
+User asks to "open the app" or "see the app"
+│
+├─ Has the app been deployed in this session?
+│  ├─ No  → Use http://localhost:8000 (start with `npm run dev` if needed)
+│  └─ Yes → Ask user which environment they want:
+│           • localhost (development)
+│           • deployed URL (production/staging)
+│
+└─ User explicitly says "localhost" or "local"
+   → Always use http://localhost:8000
+```
+
+## Deployment Procedures
+
+**CRITICAL**: Deployment is a significant action that affects live environments. NEVER deploy without explicit user confirmation.
+
+### Before Deploying
+
+**ALWAYS** confirm with the user first by asking: "Ready to deploy to [environment]?"
+
+Pre-deployment checklist:
+1. ✅ App validated successfully (`databricks experimental apps-mcp tools validate .`)
+2. ✅ Local testing completed (`npm run dev` and manual verification)
+3. ✅ User explicitly approved deployment
+4. ✅ Code committed to git (recommended)
+
+### Deployment Commands
+
+```bash
+databricks bundle deploy              # Deploy app infrastructure
+databricks bundle run app            # Start the app
+databricks bundle summary            # Get deployed app URL
+```
+
+Or use the all-in-one command:
+```bash
+databricks experimental apps-mcp tools deploy  # Validates, deploys, and runs
+```
+
+**DO NOT** run deployment commands unless the user explicitly requests it or confirms when asked.
+
+## Local Development vs Deployed Apps
+
+**CRITICAL**: Understand the difference between local development and deployed environments.
+
+### During Development (Before Deployment)
+
+When the user asks to "open the app", "see the app", "view the app", or "open a dev copy":
+
+- ✅ **Use localhost**: `http://localhost:8000`
+- ✅ **Requires**: `npm run dev` must be running
+- ✅ **Purpose**: Hot reload, fast iteration, debugging
+
+**DO NOT** suggest deployed URLs (staging/production) during active development!
+
+### After Deployment
+
+Only after running `databricks bundle deploy && databricks bundle run app`:
+
+- ✅ **Use deployed URL**: Get from `databricks bundle summary`
+- ✅ **Purpose**: Production/staging environment, sharing with others
+
+### Decision Tree
+
+```
+User asks to "open the app" or "see the app"
+│
+├─ Has the app been deployed in this session?
+│  ├─ No  → Use http://localhost:8000 (start with `npm run dev` if needed)
+│  └─ Yes → Ask user which environment they want:
+│           • localhost (development)
+│           • deployed URL (production/staging)
+│
+└─ User explicitly says "localhost" or "local"
+   → Always use http://localhost:8000
+```
 
 ## App Naming Constraints