create-kuckit-app 0.3.5 → 0.4.1

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as createProject } from "./create-project-CP-h4Ygi.js";
+import { t as createProject } from "./create-project-CAsuZMK5.js";
 import { program } from "commander";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";

package/dist/{create-project-CP-h4Ygi.js → create-project-CAsuZMK5.js}

@@ -39,7 +39,8 @@ async function createProject(name, options) {
 	const replacements = {
 		__APP_NAME__: name,
 		__APP_NAME_LOWER__: name.toLowerCase(),
-		__APP_NAME_KEBAB__: name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+		__APP_NAME_KEBAB__: name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase(),
+		__APP_TITLE__: name
 	};
 	console.log("  Copying template files...");
 	await copyDir(templateDir, targetDir, replacements);
@@ -73,6 +74,11 @@ Next steps:
   bun run db:migrate       # Run database migrations
   bun run dev              # Start development server
 
+Deploy to GCP:
+
+  bun add -D @kuckit/infra-gcp
+  bunx kuckit infra up     # One-command deploy
+
 Inside that directory, you can run:
 
   bun run dev        Start the development server

package/dist/index.js

@@ -1,3 +1,3 @@
-import { t as createProject } from "./create-project-CP-h4Ygi.js";
+import { t as createProject } from "./create-project-CAsuZMK5.js";
 
 export { createProject };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-kuckit-app",
-	"version": "0.3.5",
+	"version": "0.4.1",
 	"description": "Create a new Kuckit application",
 	"type": "module",
 	"license": "MIT",

package/templates/base/.claude/CLAUDE.md

@@ -42,3 +42,86 @@ This is a Kuckit application using Clean Architecture patterns.
 - Adapters: `*.drizzle.ts`
 - Routers: `*.router.ts`
 - Use cases: verb-noun (e.g., `create-item.ts`, `list-items.ts`)
+
+<!-- MCP_AGENT_MAIL_AND_BEADS_SNIPPET_START -->
+
+## MCP Agent Mail: coordination for multi-agent workflows
+
+What it is
+
+- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
+- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.
+
+Why it's useful
+
+- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
+- Keeps communication out of your token budget by storing messages in a per-project archive.
+- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.
+
+How to use effectively
+
+1. Same repository
+   - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.
+   - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.
+   - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.
+   - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.
+   - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.
+
+2. Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
+   - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).
+   - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.
+
+Macros vs granular tools
+
+- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.
+- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.
+
+Common pitfalls
+
+- "from_agent not registered": always `register_agent` in the correct `project_key` first.
+- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
+- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.
+
+## Integrating with Beads (dependency-aware task planning)
+
+Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)
+
+Recommended conventions
+
+- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).
+- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.
+- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.
+
+Typical flow (agents)
+
+1. **Pick ready work** (Beads)
+   - `bd ready --json` → choose one item (highest priority, no blockers)
+2. **Reserve edit surface** (Mail)
+   - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
+3. **Announce start** (Mail)
+   - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`
+4. **Work and update**
+   - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
+5. **Complete and release**
+   - `bd close bd-123 --reason "Completed"` (Beads is status authority)
+   - `release_file_reservations(project_key, agent_name, paths=["src/**"])`
+   - Final Mail reply: `[bd-123] Completed` with summary and links
+
+Mapping cheat-sheet
+
+- **Mail `thread_id`** ↔ `bd-###`
+- **Mail subject**: `[bd-###] …`
+- **File reservation `reason`**: `bd-###`
+- **Commit messages (optional)**: include `bd-###` for traceability
+
+Event mirroring (optional automation)
+
+- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.
+- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.
+
+Pitfalls to avoid
+
+- Don't create or manage tasks in Mail; treat Beads as the single task queue.
+- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.
+
+<!-- MCP_AGENT_MAIL_AND_BEADS_SNIPPET_END -->

package/templates/base/.claude/skills/kuckit/SKILL.md

@@ -193,14 +193,34 @@ export const kuckitClientModule = defineKuckitClientModule({
 
 ### Module package.json Metadata
 
+Modules depend on `@kuckit/*` npm packages:
+
 ```json
 {
 	"name": "@acme/billing-module",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client-module.ts"
+	},
+	"peerDependencies": {
+		"@kuckit/sdk": "^1.0.0",
+		"@kuckit/sdk-react": "^1.0.0",
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@kuckit/api": "^1.0.0",
+		"@orpc/server": "^1.10.0",
+		"@orpc/zod": "^1.10.0",
+		"drizzle-orm": "^0.44.0",
+		"zod": "^3.23.0",
+		"react": "^19.0.0"
+	},
 	"kuckit": {
 		"id": "acme.billing",
 		"server": "./dist/module.js",
-		"client": "./dist/client/module.js",
-		"schema": "./src/server/schema/index.ts"
+		"client": "./dist/client-module.js"
 	}
 }
 ```

package/templates/base/.claude/skills/kuckit/references/MODULE-DEVELOPMENT.md

@@ -6,50 +6,61 @@ Complete guide for developing Kuckit modules.
 
 ### Generated Module Layout
 
+Modules follow Clean Architecture internally with all layers self-contained:
+
 ```
 packages/billing-module/
 ├── src/
-│   ├── module.ts              # Server module definition
-│   ├── index.ts               # Public exports
-│   ├── client/
-│   │   ├── module.ts          # Client module definition
-│   │   └── index.ts           # Client exports
-│   └── server/
-│       ├── schema/
-│       │   └── index.ts       # Drizzle schema
-│       ├── repositories/
-│       │   └── invoice.ts     # Repository implementations
-│       └── use-cases/
-│           └── create-invoice.ts
-├── package.json
+│   ├── domain/
+│   │   └── billing.entity.ts       # Zod schema for entity
+│   ├── ports/
+│   │   └── billing.repository.ts   # Repository interface
+│   ├── adapters/
+│   │   └── billing.drizzle.ts      # Drizzle implementation
+│   ├── usecases/
+│   │   ├── list-billings.ts
+│   │   ├── get-billing.ts
+│   │   ├── create-billing.ts
+│   │   └── delete-billing.ts
+│   ├── api/
+│   │   └── billings.router.ts      # oRPC router
+│   ├── ui/
+│   │   └── BillingsPage.tsx        # React component
+│   ├── module.ts                   # Server module
+│   ├── client-module.ts            # Client module
+│   └── index.ts
+├── package.json                    # Uses @kuckit/* from npm
 └── tsconfig.json
 ```
 
 ### package.json Metadata
 
+Modules depend on `@kuckit/*` npm packages:
+
 ```json
 {
 	"name": "@acme/billing-module",
 	"version": "1.0.0",
 	"type": "module",
-	"kuckit": {
-		"id": "acme.billing",
-		"server": "./dist/module.js",
-		"client": "./dist/client/module.js",
-		"schema": "./src/server/schema/index.ts"
-	},
 	"exports": {
-		".": {
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
-		},
-		"./client": {
-			"import": "./dist/client/index.js",
-			"types": "./dist/client/index.d.ts"
-		}
+		".": "./src/index.ts",
+		"./client": "./src/client-module.ts"
 	},
 	"peerDependencies": {
-		"@kuckit/sdk": ">=0.1.0"
+		"@kuckit/sdk": "^1.0.0",
+		"@kuckit/sdk-react": "^1.0.0",
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@kuckit/api": "^1.0.0",
+		"@orpc/server": "^1.10.0",
+		"drizzle-orm": "^0.44.0",
+		"zod": "^3.23.0"
+	},
+	"kuckit": {
+		"id": "acme.billing",
+		"server": "./dist/module.js",
+		"client": "./dist/client-module.js"
 	}
 }
 ```

package/templates/base/.claude/skills/kuckit/references/PACKAGES.md

@@ -1,67 +1,82 @@
 # Kuckit Package Reference
 
-Quick reference for all packages in the Kuckit monorepo.
-
-## Package Locations
-
-| Package                 | Path                                                                 | Description                          |
-| ----------------------- | -------------------------------------------------------------------- | ------------------------------------ |
-| @kuckit/sdk             | `/Users/themrb/Documents/personal/kuckit/packages/sdk`               | Backend DI container & module system |
-| @kuckit/sdk-react       | `/Users/themrb/Documents/personal/kuckit/packages/sdk-react`         | Frontend module system               |
-| @kuckit/cli             | `/Users/themrb/Documents/personal/kuckit/packages/kuckit-cli`        | CLI tooling                          |
-| create-kuckit-app       | `/Users/themrb/Documents/personal/kuckit/packages/create-kuckit-app` | Project scaffolding                  |
-| @kuckit/domain          | `/Users/themrb/Documents/personal/kuckit/packages/domain`            | Business entities                    |
-| @kuckit/application     | `/Users/themrb/Documents/personal/kuckit/packages/application`       | Use cases                            |
-| @kuckit/contracts       | `/Users/themrb/Documents/personal/kuckit/packages/contracts`         | DTOs & Zod schemas                   |
-| @kuckit/infrastructure  | `/Users/themrb/Documents/personal/kuckit/packages/infrastructure`    | Repository implementations           |
-| @kuckit/api             | `/Users/themrb/Documents/personal/kuckit/packages/api`               | oRPC procedures                      |
-| @kuckit/db              | `/Users/themrb/Documents/personal/kuckit/packages/db`                | Drizzle ORM schemas                  |
-| @kuckit/auth            | `/Users/themrb/Documents/personal/kuckit/packages/auth`              | Better-Auth config                   |
-| @kuckit/infra           | `/Users/themrb/Documents/personal/kuckit/packages/infra`             | Pulumi infrastructure                |
-| @kuckit/users-module    | `/Users/themrb/Documents/personal/kuckit/packages/users-module`      | Reference module                     |
-| @kuckit/landing-module  | `/Users/themrb/Documents/personal/kuckit/packages/landing-module`    | Landing page module                  |
-| @kuckit/cli-auth-module | `/Users/themrb/Documents/personal/kuckit/packages/cli-auth-module`   | CLI auth module                      |
-
-## Key Files Per Package
+Quick reference for all `@kuckit/*` packages from npm.
+
+## Framework Packages
+
+These are installed from npm as dependencies, not copied into your project:
+
+| Package             | Description                                            |
+| ------------------- | ------------------------------------------------------ |
+| `@kuckit/sdk`       | Server-side module system, DI container, core services |
+| `@kuckit/sdk-react` | Client-side module system, hooks, providers            |
+| `@kuckit/api`       | oRPC procedures (publicProcedure, protectedProcedure)  |
+| `@kuckit/db`        | Drizzle ORM utilities and connection                   |
+| `@kuckit/auth`      | Better-Auth configuration                              |
+| `@kuckit/domain`    | Base types, Logger, Clock interfaces                   |
+| `@kuckit/contracts` | Shared DTOs and Zod schemas                            |
+
+## Your Project Structure
+
+```
+your-app/
+├── apps/
+│   ├── server/              # Express bootstrap (imports @kuckit/* from npm)
+│   └── web/                 # React bootstrap (imports @kuckit/* from npm)
+├── packages/
+│   └── your-module/         # Your modules with Clean Architecture
+├── node_modules/
+│   └── @kuckit/             # Framework packages from npm
+├── package.json             # Lists @kuckit/* deps
+└── drizzle.config.ts        # Points to @kuckit/db + module schemas
+```
+
+## Key Files Per Framework Package
 
 ### @kuckit/sdk
 
-| File                           | Purpose                       |
-| ------------------------------ | ----------------------------- |
-| `src/index.ts`                 | Public exports                |
-| `src/core/container.ts`        | DI container creation         |
-| `src/core/core.module.ts`      | Core services registration    |
-| `src/modules/define-module.ts` | `defineKuckitModule()` helper |
-| `src/modules/loader.ts`        | Module loading logic          |
-| `src/modules/types.ts`         | Module type definitions       |
-| `src/config/loader.ts`         | Configuration loading         |
-| `src/schema/registry.ts`       | Schema registry               |
-
-### @kuckit/cli
-
-| File                              | Purpose                        |
-| --------------------------------- | ------------------------------ |
-| `src/bin.ts`                      | CLI entry point (Commander.js) |
-| `src/commands/generate-module.ts` | Module scaffolding             |
-| `src/commands/add-module.ts`      | Module installation            |
-| `src/commands/discover-module.ts` | Module discovery               |
-| `src/commands/doctor.ts`          | Project validation             |
-| `src/commands/auth.ts`            | Authentication commands        |
-| `src/commands/db.ts`              | Database commands              |
-| `src/commands/infra/*.ts`         | Infrastructure commands        |
-| `src/lib/credentials.ts`          | Token storage                  |
-| `src/lib/sdk-loader.ts`           | Dynamic SDK loading            |
+| Export                  | Purpose                  |
+| ----------------------- | ------------------------ |
+| `createKuckitContainer` | DI container creation    |
+| `loadKuckitModules`     | Module loading           |
+| `defineKuckitModule`    | Server module definition |
+| `disposeContainer`      | Container cleanup        |
+| `asClass`, `asFunction` | DI registration helpers  |
+| `asValue`               | DI value registration    |
 
 ### @kuckit/sdk-react
 
-| File                                  | Purpose                  |
-| ------------------------------------- | ------------------------ |
-| `src/modules/define-client-module.ts` | Client module definition |
-| `src/modules/loader.ts`               | Client module loading    |
-| `src/registries/route-registry.ts`    | Route management         |
-| `src/registries/nav-registry.ts`      | Navigation management    |
-| `src/registries/slot-registry.ts`     | UI slot management       |
-| `src/context/*.ts`                    | React context providers  |
+| Export                     | Purpose                  |
+| -------------------------- | ------------------------ |
+| `defineKuckitClientModule` | Client module definition |
+| `loadKuckitClientModules`  | Client module loading    |
+| `KuckitNavProvider`        | Navigation provider      |
+| `useKuckitNav`             | Navigation hook          |
+| `useRpc`                   | RPC client hook          |
+
+### @kuckit/api
+
+| Export               | Purpose                 |
+| -------------------- | ----------------------- |
+| `publicProcedure`    | Public oRPC procedure   |
+| `protectedProcedure` | Auth-required procedure |
+| `createContext`      | oRPC context factory    |
+| `appRouter`          | Base app router         |
+
+### @kuckit/db
+
+| Export       | Purpose                    |
+| ------------ | -------------------------- |
+| `createDb`   | Drizzle instance factory   |
+| `createPool` | PostgreSQL pool factory    |
+| `authSchema` | Better-Auth schema exports |
+
+### @kuckit/auth
+
+| Export       | Purpose               |
+| ------------ | --------------------- |
+| `auth`       | Better-Auth instance  |
+| `authClient` | Client auth utilities |
 
 ## Import Patterns
 
@@ -83,30 +98,35 @@ import {
 	loadKuckitClientModules,
 	KuckitNavProvider,
 	useKuckitNav,
+	useRpc,
 } from '@kuckit/sdk-react'
 
-// CLI programmatic usage
-import { generateModule, addModule, discoverModules } from '@kuckit/cli'
+// API imports (for modules)
+import { protectedProcedure, publicProcedure } from '@kuckit/api'
 
-// Domain imports (from within the monorepo)
-import { User, type UserPort } from '@kuckit/domain'
-
-// Contracts imports
-import { CreateUserInput, UserDTO, createUserSchema } from '@kuckit/contracts'
+// Database imports
+import { createDb, createPool } from '@kuckit/db/connection'
 ```
 
 ## Package Dependencies
 
 ### What Each Package Can Import
 
-| Package        | Allowed Imports                |
-| -------------- | ------------------------------ |
-| domain         | (none - pure business logic)   |
-| contracts      | zod                            |
-| application    | domain                         |
-| infrastructure | domain, external libs          |
-| api            | domain, application, contracts |
-| sdk            | all core packages, awilix      |
-| sdk-react      | sdk types                      |
-| server         | ALL packages                   |
-| web            | sdk-react, contracts           |
+| Package      | Allowed Imports                 |
+| ------------ | ------------------------------- |
+| Your modules | @kuckit/\* packages, zod        |
+| apps/server  | @kuckit/\*, your modules        |
+| apps/web     | @kuckit/sdk-react, your modules |
+
+### Module Internal Layers
+
+Within your modules, follow Clean Architecture:
+
+| Layer    | Can Import                    |
+| -------- | ----------------------------- |
+| domain   | (none - pure Zod schemas)     |
+| ports    | domain                        |
+| usecases | domain, ports                 |
+| adapters | domain, drizzle-orm           |
+| api      | domain, usecases, @kuckit/api |
+| ui       | @kuckit/sdk-react, react      |

package/templates/base/AGENTS.md

@@ -1,11 +1,13 @@
 # AGENTS.md - **APP_NAME**
 
+> **Main Documentation**: [Kuckit SDK](https://github.com/draphonix/kuckit)
+
 ## Quick Start
 
 ```bash
 bun install              # Install dependencies
 docker compose up -d     # Start PostgreSQL
-bun run db:migrate       # Run database migrations
+bun run db:push          # Sync schema to database (dev) or db:migrate (prod)
 bun run dev              # Start dev servers (web + server)
 ```
 
@@ -17,15 +19,99 @@ __APP_NAME_KEBAB__/
 │   ├── server/              # Express + oRPC backend (port 3000)
 │   └── web/                 # React + TanStack Router frontend (port 3001)
 ├── packages/
-│   ├── api/                 # Shared API context and types
-│   ├── auth/                # Better-Auth configuration
-│   ├── db/                  # Drizzle ORM, migrations, schema
 │   └── items-module/        # Example Kuckit module (reference implementation)
 ├── .env.example             # Environment template
 ├── docker-compose.yml       # PostgreSQL container
+├── drizzle.config.ts        # Drizzle pointing to @kuckit/db + module schemas
 └── turbo.json               # Turborepo configuration
 ```
 
+**Note:** Core packages (`api`, `auth`, `db`, `domain`, `contracts`) are installed from npm as `@kuckit/*` dependencies, not copied into your project.
+
+## Bootstrap Architecture
+
+Kuckit uses **bootstrap packages** to minimize boilerplate in your apps:
+
+### Server Bootstrap (`@kuckit/app-server`)
+
+```typescript
+// apps/server/src/server.ts
+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)
+})
+```
+
+**What `runKuckitServer` handles automatically:**
+
+- Express app creation with CORS, JSON parsing
+- DI container setup with per-request scoping
+- Module loading and API route wiring
+- Auth, health, metrics endpoints
+- Graceful shutdown
+
+**Customization via hooks:**
+
+```typescript
+runKuckitServer({
+	loadConfig,
+	getModuleSpecs,
+	hooks: {
+		onAppCreated: (app) => app.use(helmet()),
+		onContainerReady: (container) => {
+			/* warm caches */
+		},
+		onServerReady: (port) => console.log(`Listening on ${port}`),
+	},
+})
+```
+
+### Web Bootstrap (`@kuckit/app-web`)
+
+```typescript
+// apps/web/src/main.tsx
+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_API_URL,
+})
+
+const KuckitProvider = createKuckitWebProvider({
+  config,
+  authClient,
+})
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <KuckitProvider>
+      <App />
+    </KuckitProvider>
+  </StrictMode>
+)
+```
+
+**Access registries and auth via hooks:**
+
+```typescript
+import { useKuckitWeb, useAuth } from '@kuckit/app-web'
+
+function MyComponent() {
+	const { routeRegistry, navRegistry, slotRegistry } = useKuckitWeb()
+	const authClient = useAuth()
+	const { data: session } = authClient.useSession()
+}
+```
+
 ## Module Development
 
 Kuckit uses a **module-based architecture** where each module contains its own Clean Architecture layers internally.
@@ -47,15 +133,21 @@ packages/your-module/
 
 ### Creating a New Module
 
-1. Copy `packages/items-module` as a template
-2. Rename and update `package.json`
-3. Implement your domain entities in `domain/`
-4. Define repository interfaces in `ports/`
-5. Implement adapters in `adapters/`
-6. Create use cases in `usecases/`
-7. Expose API in `api/` via oRPC router
-8. Register module in `apps/server/src/config/modules.ts`
-9. Add client module to `apps/web/src/modules.client.ts`
+```bash
+bunx kuckit generate module your-module
+```
+
+This scaffolds a full Clean Architecture module. Then:
+
+1. Implement your domain entities in `domain/`
+2. Define repository interfaces in `ports/`
+3. Implement adapters in `adapters/`
+4. Create use cases in `usecases/`
+5. Expose API in `api/` via oRPC router
+6. Register module in `apps/server/src/config/modules.ts`
+7. Add client module to `apps/web/src/modules.client.ts`
+8. Add schema path to `drizzle.config.ts` in project root
+9. Run `bun run db:push` to create the table
 
 ### Dependency Rules
 
@@ -256,6 +348,26 @@ export const wireModuleRpcRouters = (registrations: ApiRegistration[]) => {
 }
 ```
 
+### REST Router Pattern
+
+For modules that need direct Express response access (e.g., AI streaming with `pipeUIMessageStreamToResponse`), use REST routers instead of oRPC:
+
+```typescript
+// In your module's registerApi()
+ctx.addApiRegistration({
+	type: 'rest-router',
+	name: 'ai',
+	router: createAiRouter(),
+	prefix: '/ai', // Optional, defaults to /<name>
+})
+```
+
+REST routers are mounted at `/api<prefix>` (e.g., `/api/ai/chat`). They receive:
+
+- Per-request scoped container via `req.scope`
+- Session via `req.scope.cradle.session`
+- Full Express `Request` and `Response` objects
+
 ### Typing DI in Routers
 
 Use a module-local interface to type `context.di.cradle`:
@@ -284,14 +396,14 @@ export const invoicesRouter = {
 
 ### Add a new database table
 
-1. Define schema in your module's `adapters/` or `packages/db/src/schema/`
+1. Define schema in your module's `adapters/` directory
 2. Run `bun run db:generate`
 3. Run `bun run db:migrate`
 
 ### Add authentication to an endpoint
 
 ```typescript
-import { protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+import { protectedProcedure } from '@kuckit/api'
 
 export const myRouter = {
 	protectedRoute: protectedProcedure.input(mySchema).handler(async ({ input, context }) => {
@@ -363,12 +475,12 @@ See `.env.example` for required variables:
 
 **Cause**: Module schema not registered in `drizzle.config.ts`.
 
-**Fix**: Add the module's schema path to `packages/db/drizzle.config.ts`:
+**Fix**: Add the module's schema path to `drizzle.config.ts` (in project root):
 
 ```typescript
 schema: [
-	resolve(currentDirPath, './src/schema'),
-	resolve(currentDirPath, '../your-module/src/adapters/schema.drizzle.ts'),
+	'./node_modules/@kuckit/db/dist/schema/auth.js',
+	'./packages/your-module/src/adapters',
 ],
 ```