create-kuckit-app 2.0.2 → 2.2.0

package/templates/base/docs/MIGRATION.md

@@ -0,0 +1,989 @@
+# Migration Guide
+
+This guide covers migrating Kuckit applications between major versions.
+
+---
+
+## Migrating from v2 to v3 (SDK v3.0.0 / CLI v4.0.0)
+
+Kuckit v3.0 introduces a packages-first architecture inversion, new module patterns, and infrastructure improvements. This is a **major breaking release**.
+
+### Overview of Breaking Changes
+
+| Area                | v2 Pattern                          | v3 Pattern                                                    |
+| ------------------- | ----------------------------------- | ------------------------------------------------------------- |
+| Architecture        | Apps contain logic, import packages | Packages contain all logic, apps are minimal bootstrap shells |
+| Module Structure    | Flat `src/` layout                  | `src/server/` + `src/client/` separation                      |
+| Canonical Reference | `users-module`                      | `items-module` (users deprecated)                             |
+| CSS Aggregation     | Manual imports                      | `@source` scans `.js` files, `styles.css` → `dist/`           |
+| Schema Discovery    | `src/server/schema` default         | `src/server/adapters` default                                 |
+| Environment Vars    | `VITE_API_URL`                      | `VITE_SERVER_URL`                                             |
+| Infrastructure      | `kuckit-gcp-infra` project          | `kuckit-infra` + per-env configs                              |
+
+---
+
+### 1. Architecture Inversion
+
+v3.0 inverts the architecture: **packages are primary, apps are minimal bootstrap shells**.
+
+#### Before (v2)
+
+- `apps/server` contained ~400 lines of bootstrap, middleware, DI wiring
+- `apps/web` contained provider setup, route configuration
+- Packages provided utilities that apps consumed
+
+#### After (v3)
+
+- `apps/server` is ~10 lines calling `runKuckitServer()`
+- `apps/web` is ~10 lines with `KuckitWebProvider`
+- All logic lives in `packages/*` and SDK packages
+
+**Impact**: Your apps should import bootstrap from SDK packages, not contain custom wiring.
+
+---
+
+### 2. Module Structure Migration
+
+Modules now use a `src/server/` + `src/client/` split architecture.
+
+#### Before (v2)
+
+```
+my-module/
+├── src/
+│   ├── domain/
+│   ├── ports/
+│   ├── adapters/
+│   ├── usecases/
+│   ├── api/
+│   ├── ui/
+│   ├── module.ts
+│   └── client-module.ts
+└── package.json
+```
+
+#### After (v3)
+
+```
+my-module/
+├── src/
+│   ├── server/          # Server-side code
+│   │   ├── domain/
+│   │   ├── ports/
+│   │   ├── adapters/
+│   │   ├── usecases/
+│   │   ├── api/
+│   │   ├── config.ts    # Zod config schema
+│   │   ├── module.ts
+│   │   └── index.ts     # Server exports
+│   └── client/          # Client-side code
+│       ├── ui/
+│       ├── client-module.ts
+│       └── index.ts     # Client exports
+├── package.json         # With kuckit metadata
+└── styles.css           # Copied to dist/ for CSS aggregation
+```
+
+#### Migration Steps
+
+1. Create `src/server/` and `src/client/` directories
+2. Move server code to `src/server/`
+3. Move client code to `src/client/`
+4. Update package.json exports:
+
+```json
+{
+	"exports": {
+		".": "./src/server/index.ts",
+		"./client": "./src/client/index.ts"
+	},
+	"kuckit": {
+		"id": "my-org.my-module",
+		"server": "src/server/index.ts",
+		"client": "src/client/index.ts"
+	}
+}
+```
+
+5. Add Zod config schema in `src/server/config.ts`:
+
+```typescript
+import { z } from 'zod'
+
+export const myModuleConfigSchema = z.object({
+	myOption: z.string().optional().default('default'),
+})
+
+export type MyModuleConfig = z.infer<typeof myModuleConfigSchema>
+```
+
+See [items-module](../packages/create-kuckit-app/templates/base/packages/items-module/) as the canonical reference.
+
+---
+
+### 3. CSS Aggregator Pattern
+
+Tailwind v4 requires CSS `@source` directives to scan compiled `.js` files, not source `.tsx`.
+
+#### Before (v2)
+
+```css
+/* Manual @source directives pointing to tsx */
+@source "../../node_modules/@my-org/my-module/src/**/*.tsx";
+```
+
+#### After (v3)
+
+```css
+/* @source directives scan compiled .js */
+@source "../../node_modules/@my-org/my-module/dist/**/*.js";
+```
+
+#### Module Migration
+
+1. Create `styles.css` in module root (or `src/styles.css`)
+2. Add build step to copy to `dist/`:
+
+```json
+{
+	"scripts": {
+		"build": "tsup && cp styles.css dist/"
+	}
+}
+```
+
+3. Add to package.json kuckit metadata:
+
+```json
+{
+	"kuckit": {
+		"styles": "dist/styles.css"
+	}
+}
+```
+
+The CLI `add-module` command will automatically detect and inject CSS imports.
+
+See [MODULE_CSS.md](./MODULE_CSS.md) for complete documentation.
+
+---
+
+### 4. Schema Discovery Path Change
+
+The default schema directory changed from `src/server/schema` to `src/server/adapters`.
+
+#### Before (v2)
+
+Drizzle looked for schemas in `src/server/schema/`.
+
+#### After (v3)
+
+Priority-based discovery:
+
+1. Explicit `schemaDir` in `kuckit.config.ts`
+2. `kuckit.schemaDir` in module's `package.json`
+3. Default: `src/server/adapters`
+
+#### Migration
+
+If your schemas are in `src/server/schema`, either:
+
+**Option A**: Move schemas to `src/server/adapters`
+
+**Option B**: Configure explicit path in package.json:
+
+```json
+{
+	"kuckit": {
+		"schemaDir": "src/server/schema"
+	}
+}
+```
+
+See [ARCHITECTURE.md#schema-discovery](./ARCHITECTURE.md#schema-discovery-v30) for details.
+
+---
+
+### 5. Environment Variable Rename
+
+#### Before (v2)
+
+```env
+VITE_API_URL=http://localhost:3000
+```
+
+#### After (v3)
+
+```env
+VITE_SERVER_URL=http://localhost:3000
+POLAR_ENVIRONMENT=sandbox  # If using Polar payments
+```
+
+#### Migration
+
+1. Rename in all `.env*` files
+2. Update code references:
+
+```typescript
+// Before
+const baseURL = import.meta.env.VITE_API_URL
+
+// After
+const baseURL = import.meta.env.VITE_SERVER_URL
+```
+
+---
+
+### 6. Infrastructure Configuration
+
+The Pulumi project was renamed and now supports per-environment configs.
+
+#### Before (v2)
+
+- Pulumi project name: `kuckit-gcp-infra`
+- Single config file: `.kuckit/infra.json`
+
+#### After (v3)
+
+- Pulumi project name: `kuckit-infra`
+- Per-environment configs: `infra.dev.json`, `infra.prod.json`
+
+#### Migration
+
+1. Rename Pulumi project in existing stack:
+
+```bash
+# In Pulumi.yaml
+name: kuckit-infra  # was kuckit-gcp-infra
+```
+
+2. Create per-environment configs:
+
+```bash
+# infra.dev.json
+{
+  "env": "dev",
+  "gcpProject": "my-project-dev",
+  "region": "us-central1"
+}
+
+# infra.prod.json
+{
+  "env": "prod",
+  "gcpProject": "my-project-prod",
+  "region": "us-central1"
+}
+```
+
+3. Use `--env` flag with infra commands:
+
+```bash
+bunx kuckit infra deploy --env dev
+bunx kuckit infra deploy --env prod
+```
+
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for complete infrastructure documentation.
+
+---
+
+### Step-by-Step Migration Checklist
+
+#### Phase 1: Update Dependencies
+
+- [ ] Update `@kuckit/sdk` to `^3.0.0`
+- [ ] Update `@kuckit/cli` to `^4.0.0`
+- [ ] Update all module packages to `^3.0.0`
+
+#### Phase 2: Environment Variables
+
+- [ ] Rename `VITE_API_URL` to `VITE_SERVER_URL` in all `.env*` files
+- [ ] Add `POLAR_ENVIRONMENT` if using Polar payments
+- [ ] Update code references to use new variable names
+
+#### Phase 3: Module Structure (per module)
+
+- [ ] Create `src/server/` and `src/client/` directories
+- [ ] Move server code to `src/server/`
+- [ ] Move client code to `src/client/`
+- [ ] Add Zod config schema
+- [ ] Update package.json exports and kuckit metadata
+- [ ] Update relative imports
+
+#### Phase 4: Schema Discovery
+
+- [ ] Move schemas to `src/server/adapters/`, OR
+- [ ] Add explicit `schemaDir` in package.json kuckit metadata
+
+#### Phase 5: CSS Aggregation
+
+- [ ] Create module `styles.css` if module has custom styles
+- [ ] Add build step to copy CSS to `dist/`
+- [ ] Add `styles` field to package.json kuckit metadata
+- [ ] Update `@source` directives to scan `.js` not `.tsx`
+
+#### Phase 6: Infrastructure (if applicable)
+
+- [ ] Rename Pulumi project to `kuckit-infra`
+- [ ] Create per-environment config files
+- [ ] Update deployment scripts to use `--env` flag
+
+#### Phase 7: Verification
+
+- [ ] Run `bun run check-types` - all types pass
+- [ ] Run `bun run build` - build succeeds
+- [ ] Run `bunx kuckit doctor` - validates setup
+- [ ] Run `bun run dev` - dev server starts
+- [ ] Test module functionality
+
+---
+
+### Troubleshooting v3 Migration
+
+#### "Cannot find module './server' or './client'"
+
+Your package.json exports are incorrect. Update:
+
+```json
+{
+	"exports": {
+		".": "./src/server/index.ts",
+		"./client": "./src/client/index.ts"
+	}
+}
+```
+
+#### "Schema not found during migration"
+
+Schema discovery now defaults to `src/server/adapters`. Either:
+
+- Move your schemas there, or
+- Set `kuckit.schemaDir` in package.json
+
+#### "Tailwind not picking up module styles"
+
+Ensure `@source` scans `.js` files in `dist/`, not `.tsx` in `src/`:
+
+```css
+@source "../../node_modules/@my-org/my-module/dist/**/*.js";
+```
+
+#### "Environment variable undefined"
+
+`VITE_API_URL` was renamed to `VITE_SERVER_URL`. Update your `.env` files.
+
+#### "Pulumi stack name mismatch"
+
+The project was renamed from `kuckit-gcp-infra` to `kuckit-infra`. Update `Pulumi.yaml`.
+
+---
+
+## Migrating from v1 to v2
+
+Kuckit v2 introduces significant architectural improvements including zero-bootstrap templates, factory patterns, and new hook APIs. This guide covers all breaking changes and migration steps.
+
+### Overview of Breaking Changes
+
+| Area                | v1 Pattern                      | v2 Pattern                                |
+| ------------------- | ------------------------------- | ----------------------------------------- |
+| Server Bootstrap    | Custom `server.ts` (~400 lines) | `runKuckitServer()` (~12 lines)           |
+| Client Provider     | Local `useKuckit` hook          | `useKuckitWeb` from `@kuckit/app-web`     |
+| Auth Client         | Global `authClient` import      | `useAuth()` hook                          |
+| Auth Setup          | Singleton `auth` export         | `createAuth()` factory                    |
+| Database            | Singleton `db` export           | `createDb()` / `createDbPool()` factories |
+| Module Dependencies | `workspace:*` references        | Published npm versions                    |
+| oRPC Routers        | Dynamic wiring                  | Mutable root pattern                      |
+
+---
+
+### 1. Server Bootstrap Migration
+
+The most significant change is the extraction of server bootstrap logic into `@kuckit/app-server`.
+
+#### Before (v1)
+
+```typescript
+// apps/server/src/server.ts - v1 (~400 lines)
+import express from 'express'
+import { createContainer, asValue, asFunction } from 'awilix'
+import { auth } from '@kuckit/auth'
+import { db } from '@kuckit/db'
+// ... 350+ more lines of bootstrap code
+```
+
+#### After (v2)
+
+```typescript
+// apps/server/src/server.ts - v2 (~12 lines)
+import 'dotenv/config'
+import { runKuckitServer } from '@kuckit/app-server'
+import { loadConfig } from './config/server'
+import { getModuleSpecs } from './config/modules'
+
+runKuckitServer({
+	loadConfig,
+	getModuleSpecs,
+}).catch((error) => {
+	console.error('Failed to start server:', error)
+	process.exit(1)
+})
+```
+
+#### Migration Steps
+
+1. **Install bootstrap package**:
+
+   ```bash
+   bun add @kuckit/app-server
+   ```
+
+2. **Create config loader** (`apps/server/src/config/server.ts`):
+
+   ```typescript
+   import type { KuckitServerConfig } from '@kuckit/app-server'
+
+   export const loadConfig = (): KuckitServerConfig => ({
+   	databaseUrl: process.env.DATABASE_URL!,
+   	port: parseInt(process.env.PORT || '3000', 10),
+   	corsOrigin: process.env.CORS_ORIGIN || '*',
+   	env: process.env.NODE_ENV as 'development' | 'production',
+   	logLevel: 'INFO',
+   	enableFileLogging: false,
+   	logDir: './logs',
+   })
+   ```
+
+3. **Create module specs** (`apps/server/src/config/modules.ts`):
+
+   ```typescript
+   import type { ModuleSpec } from '@kuckit/sdk'
+
+   export const getModuleSpecs = (): ModuleSpec[] => [
+   	{ package: '@kuckit/users-module' },
+   	{ package: '@kuckit/landing-module' },
+   ]
+   ```
+
+4. **Replace server.ts** with the minimal version shown above.
+
+5. **Move custom logic to hooks** (if needed):
+   ```typescript
+   runKuckitServer({
+   	loadConfig,
+   	getModuleSpecs,
+   	hooks: {
+   		onAppCreated: async (app) => {
+   			app.use(customMiddleware)
+   		},
+   		onContainerReady: async (container) => {
+   			// Custom initialization
+   		},
+   	},
+   })
+   ```
+
+---
+
+### 2. Client Provider Migration (`useKuckit` → `useKuckitWeb`)
+
+The client-side provider has moved from a local implementation to `@kuckit/app-web`.
+
+#### Before (v1)
+
+```typescript
+// apps/web/src/providers/KuckitProvider.tsx - v1
+import { createContext, useContext } from 'react'
+import { authClient } from '@/lib/auth-client'
+
+const KuckitContext = createContext(...)
+
+export const useKuckit = () => useContext(KuckitContext)
+
+// Usage in components
+import { useKuckit } from '@/providers/KuckitProvider'
+import { authClient } from '@/lib/auth-client'
+
+function MyComponent() {
+  const { routeRegistry } = useKuckit()
+  const { data: session } = authClient.useSession()
+  // ...
+}
+```
+
+#### After (v2)
+
+```typescript
+// apps/web/src/main.tsx - v2
+import { createKuckitWebProvider } from '@kuckit/app-web'
+import { createAuthClient } from 'better-auth/react'
+import config from '../kuckit.config'
+
+const authClient = createAuthClient({
+	baseURL: import.meta.env.VITE_SERVER_URL || 'http://localhost:3000',
+})
+
+const KuckitProvider = createKuckitWebProvider({
+	config,
+	authClient,
+})
+
+// Usage in components
+import { useKuckitWeb, useAuth } from '@kuckit/app-web'
+
+function MyComponent() {
+	const { routeRegistry } = useKuckitWeb()
+	const authClient = useAuth()
+	const { data: session } = authClient.useSession()
+	// ...
+}
+```
+
+#### Migration Steps
+
+1. **Install bootstrap package**:
+
+   ```bash
+   bun add @kuckit/app-web
+   ```
+
+2. **Update main.tsx**:
+
+   ```typescript
+   import { createKuckitWebProvider } from '@kuckit/app-web'
+
+   const KuckitProvider = createKuckitWebProvider({
+   	config,
+   	authClient,
+   })
+   ```
+
+3. **Find and replace imports** in all components:
+
+   ```typescript
+   // Before
+   import { useKuckit } from '@/providers/KuckitProvider'
+   import { authClient } from '@/lib/auth-client'
+
+   // After
+   import { useKuckitWeb, useAuth } from '@kuckit/app-web'
+   ```
+
+4. **Update hook usage**:
+
+   ```typescript
+   // Before
+   const { routeRegistry } = useKuckit()
+   // authClient was imported globally
+
+   // After
+   const { routeRegistry } = useKuckitWeb()
+   const authClient = useAuth()
+   ```
+
+5. **Delete old files**:
+   - `apps/web/src/providers/KuckitProvider.tsx`
+   - `apps/web/src/lib/auth-client.ts` (if only used for export)
+
+---
+
+### 3. Factory Pattern Migration
+
+v2 replaces singleton exports with factory functions to prevent import-time side effects.
+
+#### Auth Factory
+
+##### Before (v1)
+
+```typescript
+// ❌ WRONG - Triggers DB connection at import time
+import { auth } from '@kuckit/auth'
+```
+
+##### After (v2)
+
+```typescript
+// ✅ CORRECT - Deferred initialization
+import { createAuth } from '@kuckit/auth'
+
+const auth = createAuth({
+	db,
+	config: {
+		trustedOrigins: ['http://localhost:5173'],
+	},
+})
+```
+
+#### Database Factory
+
+##### Before (v1)
+
+```typescript
+// ❌ WRONG - Connects at import time
+import { db } from '@kuckit/db'
+```
+
+##### After (v2)
+
+```typescript
+// ✅ CORRECT - Explicit connection control
+import { createDbPool, createDb } from '@kuckit/db'
+
+const pool = createDbPool(process.env.DATABASE_URL!)
+const db = createDb(pool)
+
+// Or use the combined helper
+import { createDatabase } from '@kuckit/db'
+const { pool, db } = createDatabase(process.env.DATABASE_URL!)
+```
+
+#### Why This Matters
+
+The factory pattern solves the "import-time side effects" problem:
+
+1. **v1 Problem**: Importing `kuckit.config.ts` → imports SDK → imports auth → imports db → **triggers database connection**
+2. **v2 Solution**: Imports only load pure code; connections happen at runtime when you call factories
+
+---
+
+### 4. Module Dependencies Migration
+
+Modules must now use published npm versions instead of `workspace:*` references.
+
+#### Before (v1)
+
+```json
+{
+	"dependencies": {
+		"@kuckit/sdk": "workspace:*",
+		"@kuckit/db": "workspace:*"
+	}
+}
+```
+
+#### After (v2)
+
+```json
+{
+	"dependencies": {
+		"@kuckit/sdk": "^1.0.0",
+		"@kuckit/db": "^1.0.0"
+	}
+}
+```
+
+#### Migration Steps
+
+1. **Update package.json** in each module
+2. **Run the workspace protocol resolver** (for publishing):
+   ```bash
+   node scripts/resolve-workspace-protocols.cjs
+   ```
+3. **Verify no workspace references remain**:
+   ```bash
+   node scripts/check-no-workspace-protocol.cjs
+   ```
+
+---
+
+### 5. oRPC Router Wiring Pattern
+
+Module routers must now follow the "mutable root pattern" to wire correctly.
+
+#### Key Concept
+
+oRPC's `RPCHandler` captures the router object at construction time. Module routers must be wired **before** the handler is created.
+
+#### Correct Implementation
+
+```typescript
+// 1. Create mutable root router from app router
+const rpcRouter = { ...appRouter }
+
+// 2. Wire module routers into it
+onApiRegistrations((registrations) => {
+	for (const reg of registrations) {
+		if (reg.type === 'rpc-router') {
+			rpcRouter[reg.name] = reg.router // Mutate before RPCHandler
+		}
+	}
+})
+
+// 3. THEN create RPCHandler with the populated router
+const rpcHandler = new RPCHandler(rpcRouter, {
+	/* ... */
+})
+```
+
+#### Common Mistakes
+
+- ❌ Don't create a new router object after `RPCHandler` is constructed
+- ❌ Don't call `setupRPC()` before modules are loaded
+- ✅ Do mutate the same router object that `RPCHandler` holds
+- ✅ Do ensure `loadKuckitModules()` completes before `setupRPC()`
+
+---
+
+### 6. Config Subpaths
+
+v2 introduces side-effect-free subpath exports for configuration.
+
+#### Usage
+
+```typescript
+// Pure types and config helpers (no side effects)
+import { defineConfig } from '@kuckit/sdk/config'
+import { getModuleSchemaPaths } from '@kuckit/db/config'
+
+// Safe to use in kuckit.config.ts and drizzle.config.ts
+export default defineConfig({
+	modules: [{ package: '@kuckit/users-module' }],
+})
+```
+
+#### Why This Matters
+
+These subpaths are safe to import in configuration files without triggering database connections or other side effects.
+
+---
+
+### Step-by-Step Migration Checklist
+
+#### Phase 1: Install New Packages
+
+- [ ] `bun add @kuckit/app-server` (server)
+- [ ] `bun add @kuckit/app-web` (web)
+
+#### Phase 2: Server Migration
+
+- [ ] Create `apps/server/src/config/server.ts`
+- [ ] Create `apps/server/src/config/modules.ts`
+- [ ] Replace `apps/server/src/server.ts` with minimal `runKuckitServer()` call
+- [ ] Move custom middleware to hooks if needed
+- [ ] Delete old container setup files
+
+#### Phase 3: Client Migration
+
+- [ ] Update `apps/web/src/main.tsx` to use `createKuckitWebProvider`
+- [ ] Find/replace `useKuckit` → `useKuckitWeb` in all components
+- [ ] Find/replace `authClient` imports → `useAuth()` hook
+- [ ] Delete `apps/web/src/providers/KuckitProvider.tsx`
+- [ ] Delete `apps/web/src/lib/auth-client.ts`
+
+#### Phase 4: Module Updates
+
+- [ ] Update module dependencies from `workspace:*` to npm versions
+- [ ] Verify module client components use `useKuckitWeb` + `useAuth`
+- [ ] Test each module individually
+
+#### Phase 5: Verification
+
+- [ ] Run `bun run check-types` - all types pass
+- [ ] Run `bun run build` - build succeeds
+- [ ] Run `bun run dev` - server starts correctly
+- [ ] Test authentication flows
+- [ ] Test module routes and navigation
+
+---
+
+### Troubleshooting
+
+#### "Cannot find module '@kuckit/app-server'"
+
+Install the bootstrap packages:
+
+```bash
+bun add @kuckit/app-server @kuckit/app-web
+```
+
+#### "useKuckitWeb must be used within KuckitWebProvider"
+
+Ensure your app is wrapped with the provider from `createKuckitWebProvider()`.
+
+#### "Database connection failed at import time"
+
+You're still using singleton imports. Update to factory pattern:
+
+```typescript
+// Before
+import { db } from '@kuckit/db'
+
+// After
+import { createDatabase } from '@kuckit/db'
+const { db } = createDatabase(process.env.DATABASE_URL!)
+```
+
+#### "Module router not appearing in API"
+
+Ensure modules are loaded before RPC setup. The `@kuckit/app-server` handles this automatically with the mutable root pattern.
+
+---
+
+## Migrating from packages/infra to @kuckit/infra-gcp
+
+If you have an existing Kuckit project with a `packages/infra` directory, follow this guide to migrate to the new provider-based infrastructure system.
+
+### Why Migrate?
+
+The new provider-based system offers:
+
+- **Simpler setup** - Install an npm package instead of managing Pulumi code
+- **Automatic updates** - Get infrastructure improvements via package updates
+- **Multi-cloud support** - Switch providers without rewriting infrastructure
+- **Dockerfile generation** - Auto-generated, optimized Dockerfiles
+
+### Before You Start
+
+1. **Backup your Pulumi state** - Ensure your Pulumi state is saved (Pulumi Cloud or local backend)
+2. **Note your current stack name** - Run `cd packages/infra && pulumi stack ls`
+3. **Document customizations** - List any modifications to the default Pulumi program
+
+### Migration Steps
+
+#### Step 1: Check Current State
+
+```bash
+cd packages/infra
+pulumi stack ls
+pulumi stack output --json > ../outputs-backup.json
+```
+
+#### Step 2: Install the Provider Package
+
+```bash
+bun add -D @kuckit/infra-gcp
+```
+
+#### Step 3: Initialize with Existing Stack
+
+The CLI will detect your existing `.kuckit/infra.json` and migrate it:
+
+```bash
+bunx kuckit infra init --provider gcp
+```
+
+If you have customizations you want to keep, use the eject command after migration:
+
+```bash
+bunx kuckit infra eject
+```
+
+This copies the provider's Pulumi code to `infra/` where you can customize it.
+
+#### Step 4: Verify Configuration
+
+Check that `.kuckit/infra.json` contains the correct values:
+
+```json
+{
+	"provider": "gcp",
+	"providerPackage": "@kuckit/infra-gcp",
+	"region": "us-central1",
+	"env": "dev",
+	"providerConfig": {
+		"gcpProject": "your-project-id"
+	},
+	"outputs": {
+		"registryUrl": "...",
+		"databaseConnectionName": "..."
+	}
+}
+```
+
+#### Step 5: Test Deployment
+
+Run a preview to verify everything works:
+
+```bash
+bunx kuckit infra deploy --preview
+```
+
+If the preview looks correct, deploy:
+
+```bash
+bunx kuckit infra deploy
+```
+
+#### Step 6: Clean Up Legacy Directory
+
+Once verified, you can remove the old infrastructure code:
+
+```bash
+rm -rf packages/infra
+```
+
+Update `package.json` to remove the workspace entry if applicable.
+
+### Handling Customizations
+
+If you had custom Pulumi code in `packages/infra`:
+
+#### Option 1: Eject and Customize
+
+```bash
+# Eject provider code to local directory
+bunx kuckit infra eject
+
+# Your customizations go in infra/
+# CLI will use local infra/ instead of node_modules provider
+```
+
+#### Option 2: Create Custom Provider
+
+For significant customizations, create your own provider package:
+
+```bash
+# Copy @kuckit/infra-gcp as starting point
+cp -r node_modules/@kuckit/infra-gcp packages/my-infra-provider
+
+# Customize as needed
+# Update .kuckit/infra.json to use your provider
+```
+
+### Troubleshooting
+
+#### "Pulumi stack already exists"
+
+The CLI reuses existing Pulumi stacks. If you see conflicts:
+
+```bash
+cd packages/infra
+pulumi stack select your-stack-name
+pulumi stack export > stack-backup.json
+
+# Then continue with migration
+bunx kuckit infra init --provider gcp
+```
+
+#### "Missing outputs after migration"
+
+Run a deployment to regenerate outputs:
+
+```bash
+bunx kuckit infra deploy
+```
+
+#### "My customizations are lost"
+
+Use `kuckit infra eject` to get a local copy of the infrastructure code, then reapply your customizations.
+
+### Legacy Command Compatibility
+
+Some commands still support legacy `packages/infra` paths as a fallback:
+
+| Command         | Provider-based | Legacy fallback |
+| --------------- | -------------- | --------------- |
+| `infra up`      | ✅ Yes         | ❌ No           |
+| `infra init`    | ✅ Yes         | ❌ No           |
+| `infra deploy`  | ✅ Yes         | ❌ No           |
+| `infra destroy` | ⚠️ Partial     | ✅ Yes          |
+| `infra status`  | ⚠️ Partial     | ✅ Yes          |
+| `infra outputs` | ⚠️ Partial     | ✅ Yes          |
+
+Commands marked "Partial" will be updated in a future release to fully support the provider interface.
+
+### Getting Help
+
+If you encounter issues during migration:
+
+1. Check the [Troubleshooting Guide](./TROUBLESHOOTING.md)
+2. Open an issue on [GitHub](https://github.com/draphonix/kuckit/issues)
+3. Include your `.kuckit/infra.json` and any error messages