@crossdelta/platform-sdk 0.5.12 → 0.7.0

package/bin/services/ai/instructions/ai-instructions.md

@@ -14,13 +14,43 @@ pf new hono-micro services/my-service -y
 
 Rules:
 - **ALWAYS** include this commands block as the FIRST thing in your output
-- Use exactly the path provided by the user
-- Do not alter naming or prepend paths
+- **CRITICAL:** Services MUST be created in `services/` directory (e.g., `services/orders`, `services/notifications`)
+- **If user provides just a service name** (e.g., "orders"), prepend `services/` → `services/orders`
+- **If user provides full path with `services/`** (e.g., "services/orders"), use as-is
 - The `-y` flag is REQUIRED to skip prompts
 
+**Path Examples:**
+- ✅ User says "orders" → Generate: `pf new hono-micro services/orders -y`
+- ✅ User says "payment processor" → Generate: `pf new hono-micro services/payment-processor -y`
+- ✅ User says "services/orders" → Generate: `pf new hono-micro services/orders -y`
+- ❌ NEVER generate: `pf new hono-micro orders -y` (missing services/ prefix)
+- ❌ NEVER generate: `pf new hono-micro backend/orders -y` (wrong directory)
+- ❌ NEVER generate: `pf new hono-micro apps/orders -y` (apps/ is for frontends)
+
+---
+
+# 2. Post-Generation Commands
+
+After generating a service with event **handlers** (Event Consumer or Hybrid), include a post-generation command to generate event mocks:
+
+```post-commands
+pf event:generate services/my-service --overwrite
+```
+
+This command:
+- Scans all `src/events/*.event.ts` files in the service
+- Generates mock JSON files based on the exported Zod schemas
+- Creates `*.mock.json` files in `packages/contracts/src/events/`
+- Enables testing with `pf event:publish <event-name>`
+
+**When to include this command:**
+- ✅ Service is an **Event Consumer** (has event handlers in `src/events/`)
+- ✅ Service is **Hybrid** (has both REST + event handlers)
+- ❌ Service is an **Event Publisher only** (only REST endpoints, NO event handlers)
+
 ---
 
-# 2. Dependencies Block
+# 3. Dependencies Block
 
 ```dependencies
 zod
@@ -32,26 +62,43 @@ Rules:
 - No versions.
 - Only packages not included in the scaffold.
 - **CRITICAL:** Only use packages that actually exist on npm. Verify package names are correct (e.g., `@pusher/push-notifications-server` not `pusher-beams`). When unsure, use well-known, established packages.
+- **IMPORTANT:** Workspace packages (like `{{scope}}/contracts`) are automatically detected and installed with `workspace:*` protocol. Just list the package name without version.
+
+### Core Package Names (ALWAYS USE THESE EXACT NAMES)
+
+**CRITICAL:** The following packages are part of the monorepo and MUST be imported with these exact names:
+
+- `@crossdelta/cloudevents` - CloudEvents/NATS utilities (`handleEvent`, `consumeJetStreamEvents`, `publish`)
+- `@crossdelta/telemetry` - OpenTelemetry setup
+- `@crossdelta/infrastructure` - Infrastructure builders (for infra/ files only)
+- `{{scope}}/contracts` - Shared event contracts (when using Advanced Mode)
+
+**DO NOT use invented package names like:**
+- ❌ `shared-events`
+- ❌ `@orderboss/cloudevents`
+- ❌ `@platform/events`
+- ❌ Any other variations
 
 ---
 
-# 3. Required Source Files
+# 4. Required Source Files
 
 Generated services must include:
 
 - `src/index.ts`
-- `src/handlers/*.event.ts`
+- `src/events/*.event.ts` (event handlers - NOT `src/handlers/`)
 - `src/use-cases/*.use-case.ts`
 - `src/use-cases/*.test.ts`
 - `README.md`
 
 Rules:
 - Paths must be relative to the service root.
+- Event handlers MUST go in `src/events/`, NOT `src/handlers/`.
 - Do NOT generate controller or module folders unless requested.
 
 ---
 
-# 4. Code Style
+# 5. Code Style
 
 - Biome-compatible formatting.
 - Strict TS.
@@ -62,11 +109,89 @@ Rules:
 
 ---
 
-# 5. Service Structure
+# 6. Service Structure
+
+## 🔑 CRITICAL: Event Publishers vs Event Consumers
+
+**Read the service description carefully to determine the service type:**
+
+### 📤 Event Publisher (REST API that publishes events)
+
+**Keywords in description:** "publishes", "creates", "manages", "REST API", "HTTP endpoints"
+
+**Example:** "Order management service that handles order creation. Publishes order.created events."
+
+**Structure:**
+- ✅ REST endpoints (POST, GET, PUT, DELETE)
+- ✅ Use `publish()` from `@crossdelta/cloudevents`
+- ✅ **RECOMMENDED:** Create contracts in `packages/contracts` for published events
+- ❌ NO event handlers in `src/events/`
+- ❌ NO `consumeJetStreamEvents()`
+
+**Event Publishing Strategy:**
+
+Publishers can use **contracts** (recommended) or **string literals**:
+
+```ts
+// Option 1: With contract (RECOMMENDED - type-safe)
+import { OrderCreatedContract } from '@scope/contracts'
+await publish(OrderCreatedContract, orderData)
+
+// Option 2: String literal (OK for prototyping)
+await publish('order.created', orderData, {
+  source: 'my-service',
+  subject: orderId,
+})
+```
+
+**When to create contracts for published events:**
+- ✅ **Default/Recommended** - Create contract in `packages/contracts` for type-safety
+- ✅ Event will be consumed by other services (now or future)
+- ✅ Event schema should be documented and versioned
+- ❌ Only skip if rapid prototyping or service-internal events
+
+**Example index.ts with contracts:**
+```ts
+import '@crossdelta/telemetry'
+
+import { publish } from '@crossdelta/cloudevents'
+import { OrderCreatedContract } from '@scope/contracts'
+import { Hono } from 'hono'
+import { CreateOrderSchema } from './types/orders'
+import { createOrder } from './use-cases/create-order.use-case'
+
+const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 4001
+const app = new Hono()
+const orders = new Map()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+app.post('/orders', async (c) => {
+  const data = CreateOrderSchema.parse(await c.req.json())
+  const order = await createOrder(data, orders)
+
+  // Publish with contract (type-safe)
+  await publish(OrderCreatedContract, order)
+
+  return c.json({ success: true, order }, 201)
+})
+
+Bun.serve({ port, fetch: app.fetch })
+```
+
+### 📥 Event Consumer (Reacts to events from other services)
+
+**Keywords in description:** "consumes", "listens to", "reacts to", "handles events", "processes events"
 
-### index.ts
-**IMPORTANT:** Telemetry MUST be the first import!
+**Example:** "Notification service that sends emails when orders are created. Consumes order.created events."
 
+**Structure:**
+- ✅ Event handlers in `src/events/*.event.ts`
+- ✅ Use `consumeJetStreamEvents()` in index.ts
+- ✅ Use `handleEvent()` for each event type
+- ❌ Usually NO REST endpoints (except /health)
+
+**Example index.ts:**
 ```ts
 import '@crossdelta/telemetry'
 
@@ -81,28 +206,154 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 // Start NATS consumer - handlers are auto-discovered
 consumeJetStreamEvents({
   stream: 'ORDERS',
-  subjects: ['orders.>'],
   consumer: 'my-service',
-  discover: './src/handlers/**/*.event.ts',
+  discover: './src/events/**/*.event.ts',
 })
 
 Bun.serve({ port, fetch: app.fetch })
 ```
 
+**IMPORTANT:** Do NOT include `subjects` parameter in `consumeJetStreamEvents` - it's not supported.
+
+### � HTTP CloudEvent Receiver (Receives CloudEvents via HTTP POST)
+
+**Keywords in description:** "webhook", "receives CloudEvents via HTTP", "HTTP push endpoint", "Pub/Sub Push"
+
+**Example:** "Webhook service that receives payment events from Stripe as CloudEvents via HTTP POST."
+
+**Structure:**
+- ✅ Event handlers in `src/events/*.event.ts`
+- ✅ Use `cloudEvents()` middleware in index.ts
+- ✅ Use `handleEvent()` for each event type
+- ❌ NO `consumeJetStreamEvents()` - events come via HTTP, not NATS
+
+**Example index.ts:**
+```ts
+import '@crossdelta/telemetry'
+
+import { cloudEvents } from '@crossdelta/cloudevents'
+import { Hono } from 'hono'
+
+const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 4003
+const app = new Hono()
+
+app.get('/health', (c) => c.json({ status: 'ok' }))
+
+// HTTP CloudEvent receiver - handlers are auto-discovered
+app.use('/webhooks/*', cloudEvents({
+  discover: './src/events/**/*.event.ts',
+  log: true
+}))
+
+Bun.serve({ port, fetch: app.fetch })
+```
+
+**When to use:**
+- ✅ Receiving webhooks (Stripe, GitHub, etc.)
+- ✅ Google Cloud Pub/Sub Push endpoints
+- ✅ CloudEvent-to-CloudEvent bridges
+- ❌ NOT for regular REST APIs (use Event Publisher pattern instead)
+
+### �🔄 Hybrid Service (Both Publisher and Consumer)
+
+Some services both consume events AND expose REST endpoints:
+
+**Example:** "Payment service that processes payments via REST API and listens for order.created events."
+
+**Structure:**
+- ✅ REST endpoints that publish events
+- ✅ Event handlers that consume events
+- ✅ Use both `publish()` and `consumeJetStreamEvents()`
+
+---
+
+### index.ts Rules
+
 Contains only:
 - Telemetry import (MUST be first)
 - Server setup (Hono)
 - Health endpoint
-- Event consumer registration (if consuming events)
+- REST endpoints (for Publishers/Hybrid)
+- Event consumer registration (for Consumers/Hybrid)
 - Port configuration from env vars
 
+**Import schemas and types from `src/types/` directory:**
+```ts
+import { CreateOrderSchema, UpdateOrderSchema } from './types/orders'
+
+app.post('/orders', async (c) => {
+  const data = CreateOrderSchema.parse(await c.req.json())
+  const order = await createOrder(data, orders)
+  await publish('order.created', order, { source: 'my-service' })
+  return c.json({ success: true, order }, 201)
+})
+```
+
+---
+
+# 6.5. Types & Schemas Structure
+
+**CRITICAL:** All Zod schemas and types must live in `src/types/` directory.
+
+```
+src/
+├── index.ts              # Adapters (REST endpoints)
+├── types/                # Schemas & Types (shared)
+│   ├── orders.ts        # Order-related schemas & types
+│   ├── payments.ts      # Payment-related schemas & types
+│   └── index.ts
+├── events/               # Event handlers (if Consumer)
+│   └── *.event.ts
+└── use-cases/            # Business logic
+    └── *.use-case.ts
+```
+
+**Types file structure:**
+```ts
+// src/types/orders.ts
+import { z } from 'zod'
+
+// Define Zod schemas
+export const CreateOrderSchema = z.object({
+  customerId: z.string().min(1),
+  items: z.array(z.object({
+    productId: z.string().min(1),
+    quantity: z.number().int().min(1),
+    price: z.number().min(0),
+  })).min(1),
+  total: z.number().min(0),
+})
+
+export const UpdateOrderSchema = z.object({
+  items: z.array(z.object({
+    productId: z.string().min(1),
+    quantity: z.number().int().min(1),
+    price: z.number().min(0),
+  })).optional(),
+  total: z.number().min(0).optional(),
+  status: z.enum(['created', 'updated', 'completed']).optional(),
+})
+
+// Export inferred types
+export type CreateOrderInput = z.infer<typeof CreateOrderSchema>
+export type UpdateOrderInput = z.infer<typeof UpdateOrderSchema>
+```
+
+**Why `src/types/`?**
+- ✅ Single source of truth (Zod schema → TypeScript types)
+- ✅ No circular dependencies (types → use-cases, types → adapters)
+- ✅ No duplication between schemas and types
+- ✅ Shared between adapters (REST, Events) and use-cases
+
 ---
 
-# 6. Use-Case Rules (Lean Hexagonal Architecture)
+# 7. Use-Case Rules (Lean Hexagonal Architecture)
 
 Services follow a **Lean Hexagonal Architecture** pattern:
-- **Handlers** = Adapters (receive events, delegate to use-cases)
-- **Use-Cases** = Application Core (business logic, orchestration)
+- **Types & Schemas** (in `src/types/`) = Zod schemas and inferred types (shared by all layers)
+- **Event Handlers** (in `src/events/`) = Adapters (receive events, validate, delegate to use-cases)
+- **REST Endpoints** (in `src/index.ts`) = Adapters (receive HTTP requests, validate, delegate to use-cases)
+- **Use-Cases** (in `src/use-cases/`) = Application Core (business logic, NO validation, NO schemas)
 - No explicit ports/interfaces unless needed
 
 **IMPORTANT:** A single service description may result in **multiple use-cases**. Break down complex functionality into focused, single-responsibility use-cases.
@@ -114,66 +365,400 @@ Example: "Payment processing service" might generate:
 - `refund-payment.use-case.ts` - Handle refund requests
 
 Use-Case Rules:
-- All domain logic lives in `use-cases/`
+- All domain logic lives in `src/use-cases/`
 - One use-case = one responsibility
 - Pure functions preferred
-- No framework imports
-- Use inferred schema types from handlers
+- No framework imports (no Hono, no Zod, no @crossdelta/cloudevents)
+- **CRITICAL: Import types from `src/types/`** - do NOT redefine types in use-cases
+- **CRITICAL: NO Zod schemas in use-cases!** Schemas live in `src/types/`
+- **CRITICAL: NO manual validation (if/throw) for input data!** Trust that adapters validated the data
+- **CRITICAL: NO globalThis hacks or in-memory state!** Pass state as parameters (Dependency Injection)
+- **DO NOT export domain entity types from use-cases** - define those in `src/types/` if needed
+- **DO NOT create repository interfaces** - keep it lean, inject concrete dependencies
+- For complex persistence needs, add `// TODO: Replace with proper database persistence`
+- Return plain data (no Response objects, no validation)
 - Compose use-cases when needed (call one from another)
 
+**Example - CORRECT use-case (Lean Hexagonal):**
+```ts
+// ✅ Import types from src/types/, concrete dependency injection
+import type { CreateOrderInput } from '../types/orders'
+
+// Inject concrete dependencies (Map, Set, etc.) - keep it lean
+export const createOrder = async (
+  input: CreateOrderInput,
+  orderStore: Map<string, any>  // Concrete dependency, but injected
+) => {
+  const orderId = `order-${Date.now()}`
+
+  const order = {
+    orderId,
+    customerId: input.customerId,
+    items: input.items,
+    total: input.total,
+    status: 'created',
+    createdAt: new Date().toISOString(),
+  }
+
+  orderStore.set(orderId, order)
+  return order
+}
+```
+
+**Example - CORRECT use-case with extended input:**
+```ts
+// ✅ Extend imported type for additional parameters
+import type { UpdateOrderInput } from '../types/orders'
+
+export const updateOrder = async (
+  input: UpdateOrderInput & { orderId: string },  // Extend with orderId
+  orderStore: Map<string, any>
+) => {
+  const order = orderStore.get(input.orderId)
+  if (!order) {
+    throw new Error('Order not found')  // ✅ Business logic validation OK
+  }
+
+  const updatedOrder = {
+    ...order,
+    ...input,
+    updatedAt: new Date().toISOString(),
+  }
+
+  orderStore.set(input.orderId, updatedOrder)
+  return updatedOrder
+}
+```
+
+**Example - CORRECT use-case with DB TODO:**
+```ts
+import type { CreateOrderInput } from '../types/orders'
+
+export const createOrder = async (
+  input: CreateOrderInput,
+  orderStore: Map<string, any>  // TODO: Replace with proper database persistence
+) => {
+  const orderId = `order-${Date.now()}`
+  const order = { orderId, ...input, status: 'created', createdAt: new Date().toISOString() }
+  orderStore.set(orderId, order)
+  return order
+}
+```
+
+**Example - WRONG use-case:**
+```ts
+// ❌ globalThis hack for state
+const orders = globalThis.__ORDERS__ || (globalThis.__ORDERS__ = {})  // ❌ NO!
+
+// ❌ Domain entity types exported from use-case
+export type Order = { ... }  // ❌ NO! Define in adapter
+
+// ❌ Repository interface (too complex for simple services)
+export interface OrderRepository {  // ❌ NO! Keep it lean
+  save: (order: any) => Promise<void>
+}
+
+// ❌ Manual validation in use-case
+export const createOrder = async (input: CreateOrderInput) => {
+  if (!input.customerId) throw new Error('Missing customerId')  // ❌ NO!
+**Example - WRONG use-case:**
+```ts
+// ❌ Defining types in use-case instead of importing from src/types/
+export type CreateOrderInput = { ... }  // ❌ NO! Import from src/types/
+
+// ❌ Zod schema in use-case
+import { z } from 'zod'
+const CreateOrderSchema = z.object({ ... })  // ❌ NO! Define in src/types/
+
+// ❌ Manual input validation
+export const createOrder = async (input: CreateOrderInput) => {
+  if (!input.customerId) throw new Error('Missing customerId')  // ❌ NO!
+  // Trust adapters validated the data!
+}
+```
+
+Types and schemas belong in **`src/types/`**, NOT in use-cases!
+
 ---
 
-# 7. Event Handler Rules
+# 8. Event Handler Rules (For Event Consumers Only!)
 
-Handlers MUST:
-- Live under `src/handlers/*.event.ts`
-- Use Zod for validation (NO `type` field in schema!)
-- Export inferred types for use in use-cases
-- Delegate ALL logic to use-cases
-- Contain NO business logic
+**CRITICAL:** Event handlers are ONLY for services that **consume/react to** events from other services!
 
-**CRITICAL:** Schema validates ONLY the event data payload (without `type` field). Event type is declared in the options object.
+**Do NOT create event handlers if:**
+- ❌ Service description says "publishes events" or "creates/manages X"
+- ❌ Service is a REST API that publishes events
+- ❌ Service is the source/origin of the events
 
-Example:
+**DO create event handlers if:**
+- ✅ Service description says "consumes", "listens to", "reacts to", "handles events"
+- ✅ Service processes events published by other services
+
+**CRITICAL: Event handlers MUST live in `src/events/` directory, NOT `src/handlers/`!**
+
+## Event Handling Modes
+
+The platform supports **Advanced Mode** (contracts) with automatic creation for missing contracts.
+
+### 🎯 DECISION RULE (CRITICAL - READ FIRST!)
+
+**Always use Advanced Mode (contracts) - Missing contracts are auto-created!**
+
+When generating an Event Consumer service:
+
+1. **Use contracts** from `{{scope}}/contracts` package
+2. **Import and use** the contract in the event handler (`import { OrderCreatedContract } from '{{scope}}/contracts'`)
+3. **If contract doesn't exist**, `pf event:generate` will create it automatically:
+   - Extracts event name from handler
+   - Creates contract in `packages/contracts/src/events/`
+   - Updates `packages/contracts/src/index.ts`
+   - Generates mock JSON file
+
+**Example Flow:**
+```
+User prompt: "Event Consumer that listens to order.created events"
+→ AI creates: src/events/order-created.event.ts (imports OrderCreatedContract from @scope/contracts)
+→ pf event:generate runs:
+  ✓ Detects missing contract
+  ✓ Creates packages/contracts/src/events/order-created.ts (contract)
+  ✓ Creates packages/contracts/src/events/order-created.mock.json
+```
+
+**Why This Approach?**
+- ✅ AI generates contracts reference (type-safe from start)
+- ✅ Automatic contract creation when missing
+- ✅ End result: Strong type-safety via Schema Registry Pattern
+- ✅ No manual contract creation needed
+
+**IMPORTANT:** Always include `pf event:generate` in post-commands block for Event Consumers!
+
+### 🟢 ADVANCED MODE (Default - Recommended)
+
+**Use Advanced Mode for Event Consumers** - contracts will be auto-created if missing:
+
+1. **Add dependency** `{{scope}}/contracts` in dependencies block
+2. **Import contract** in event handler
+3. **Use with `handleEvent`** for type-safe event handling
+
+**Example Event Handler:**
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { z } from 'zod'
+import { OrderCreatedContract, type OrderCreatedData } from '@scope/contracts'
 import { processOrder } from '../use-cases/process-order.use-case'
 
-const OrderCreatedSchema = z.object({
-  orderId: z.string(),
-  customerId: z.string(),
-  total: z.number(),
+export default handleEvent(OrderCreatedContract,
+  async (data: OrderCreatedData) => {
+    await processOrder(data)
+  },
+)
+```
+
+**Why Contracts as Default?**
+- ✅ Strong type-safety between Publisher and Consumer
+- ✅ Single source of truth for event schemas
+- ✅ Schema evolution and versioning
+- ✅ Automatic mock generation
+- ✅ Better documentation
+
+**IMPORTANT:** The `packages/contracts` package is your Schema Registry. Always use contracts from there for Event Consumers.
+
+### � ADVANCED MODE (Shared Contracts - RECOMMENDED DEFAULT)
+
+Use **Advanced Mode** for all production services:
+
+**Steps for Advanced Mode:**
+
+1. **Check if contract exists** in `packages/contracts/src/events/`
+2. **If exists:** Import and use the contract
+3. **If NOT exists:** Create contract first in `packages/contracts`, then use it
+
+**Advanced Mode Example:**
+
+```ts
+// packages/contracts/src/events/order-created.ts (create if not exists)
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrderCreatedContract = createContract({
+  type: 'order.created',
+  schema: z.object({
+    orderId: z.string(),
+    customerId: z.string(),
+    items: z.array(z.object({
+      productId: z.string(),
+      quantity: z.number(),
+      price: z.number(),
+    })),
+    total: z.number(),
+    status: z.enum(['created']),
+    createdAt: z.string(),
+  }),
 })
 
-// Export type for use in use-cases
-export type OrderCreatedEvent = z.infer<typeof OrderCreatedSchema>
+export type OrderCreatedData = z.infer<typeof OrderCreatedContract.schema>
+```
+
+```ts
+// services/my-service/src/events/order-created.event.ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrderCreatedContract, type OrderCreatedData } from '@scope/contracts'
+import { processOrder } from '../use-cases/process-order.use-case'
 
 export default handleEvent(
-  {
-    schema: OrderCreatedSchema,
-    type: 'orders.created',  // Event type here, NOT in schema
+  OrderCreatedContract,  // Type-safe contract
+  async (data: OrderCreatedData) => {
+    await processOrder(data)
   },
-  async (data) => {
+)
+```
+
+```ts
+// services/my-service/src/use-cases/process-order.use-case.ts
+import type { OrderCreatedData } from '@scope/contracts'
+
+export const processOrder = async (data: OrderCreatedData) => {
+  // Business logic with fully typed data
+}
+```
+
+**Dependencies:**
+Add `{{scope}}/contracts` to your service's `package.json`:
+```json
+{
+  "dependencies": {
+    "@scope/contracts": "workspace:*"
+  }
+}
+```
+
+### � DEPRECATED: Basic Mode
+
+**Basic Mode is deprecated and no longer recommended.**
+
+The platform automatically creates missing contracts when you run `pf event:generate`.
+
+**Previous Basic Mode approach:**
+- ❌ Local schemas in `src/types/events.ts`
+- ❌ String literals for event types
+- ❌ No type-safety between services
+
+**Current approach (Advanced Mode only):**
+- ✅ Always use contracts from `{{scope}}/contracts`
+- ✅ Contracts auto-created if missing
+- ✅ Type-safety across all services
+- ✅ Single source of truth
+
+**Migration:** If you have Basic Mode handlers, run `pf event:generate` to automatically migrate them to Advanced Mode.
+
+export const processOrder = async (data: OrderCreatedData) => {
+  // Use data.orderId, data.customerId, etc.
+}
+```
+
+{{AVAILABLE_CONTRACTS}}
+
+**DO NOT:**
+- ❌ Redefine schemas that exist in contracts
+- ❌ Create inline schemas for existing event types
+- ❌ Duplicate event type definitions
+
+**Advanced Mode Example:**
+```ts
+import { handleEvent } from '@crossdelta/cloudevents'
+import { OrderCreatedContract, type OrderCreatedData } from '{{scope}}/contracts'
+import { processOrder } from '../use-cases/process-order.use-case'
+
+export default handleEvent(
+  OrderCreatedContract,  // Import from contracts package
+  async (data: OrderCreatedData) => {
     await processOrder(data)
   },
 )
 ```
 
+**If you need only a subset of fields**, extract them in the handler:
+```ts
+export default handleEvent(
+  OrderCreatedContract,
+  async (data: OrderCreatedData) => {
+    // Extract only what you need
+    const { orderId, items } = data
+    await updateInventory({ orderId, items })
+  },
+)
+```
+
+**Contract Definition** (in `packages/contracts/src/schemas/order-created.schema.ts`):
+```ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrderCreatedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  total: z.number(),
+})
+
+export type OrderCreatedData = z.infer<typeof OrderCreatedSchema>
+
+export const OrderCreatedContract = createContract({
+  type: 'orders.created',
+  schema: OrderCreatedSchema,
+})
+```
+
+## General Event Handler Requirements
+
+- Live under `src/events/*.event.ts` (NOT `src/handlers/`)
+- Use Zod for validation (NO `type` field in schema!)
+- Delegate ALL logic to use-cases
+- Contain NO business logic
+- **ALWAYS import from `@crossdelta/cloudevents`** (NOT `shared-events` or any other package!)
+
+**CRITICAL:** Schema validates ONLY the event data payload (without `type` field). Event type is declared in the options object or contract.
+
+**CRITICAL:** ALWAYS use the exact import: `import { handleEvent } from '@crossdelta/cloudevents'`
+
 **Naming conventions:**
 - Schema constants: PascalCase with `Schema` suffix (e.g., `OrderCreatedSchema`)
-- Exported types: PascalCase with `Event` suffix (e.g., `OrderCreatedEvent`)
+- Exported types: PascalCase with `Data` suffix (e.g., `OrderCreatedData`)
+- Contract constants: PascalCase with `Contract` suffix (e.g., `OrderCreatedContract`)
+
+**Contract Structure (Advanced Mode - Default):**
+```ts
+// packages/contracts/src/events/order-created.ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
+
+export const OrderCreatedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  total: z.number(),
+})
+
+export const OrderCreatedContract = createContract({
+  type: 'order.created',
+  schema: OrderCreatedSchema,
+})
+
+export type OrderCreatedData = z.infer<typeof OrderCreatedContract.schema>
+```
+
+**Decision Rule:**
+- **Always use Advanced Mode** - contracts from `{{scope}}/contracts`
+- **Contracts auto-created** - `pf event:generate` creates missing contracts
+- Meaning → `packages/contracts`
+- Behavior → `services/*/src`
 
 Forbidden in handlers:
 - `type: z.literal('...')` in schema (redundant and causes errors)
 - DB access
-- External API calls
 - Multi-step logic
 - Env var parsing
 
 ---
 
-# 8. Testing Rules
+# 9. Testing Rules
 
 **CRITICAL:**
 - Test ONLY use-cases (NOT event handlers)
@@ -223,30 +808,134 @@ describe('Send Notification Use Case', () => {
 
 ---
 
-# 9. README Requirements
+# 10. README Requirements
 
 MUST include:
 - Description
+- Features list
 - Environment variable table
-- Published/consumed events
+- Published/consumed events (with schemas)
 - API endpoints
+- **Testing section with event mock examples**
 - Dev commands
 
+### README Structure
+
+```markdown
+# Service Name
+
+Brief description of what this service does.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `SERVICE_PORT` | Port the service runs on | No | 4001 |
+| `NATS_URL` | NATS server URL | Yes | - |
+
+## Events
+
+### Publishes
+- `orderboss.service.event` - Description
+  ```json
+  {
+    "field": "value"
+  }
+  ```
+
+### Consumes
+- `orderboss.other.event` - Description
+  ```json
+  {
+    "field": "value"
+  }
+  ```
+
+## API Endpoints
+
+### `GET /health`
+Health check endpoint.
+
+**Response:**
+\`\`\`json
+{ "status": "ok" }
+\`\`\`
+
+## Testing
+
+### Event Mocks
+
+This service includes generated mock files for all event handlers in `src/events/*.mock.json`. These mocks can be used for testing and development.
+
+**List all available event mocks:**
+\`\`\`bash
+pf event:list
+\`\`\`
+
+**Publish a test event using a mock:**
+\`\`\`bash
+pf event:publish order-created
+\`\`\`
+
+**Regenerate event mocks:**
+\`\`\`bash
+pf event:generate . --overwrite
+\`\`\`
+
+### Manual Testing
+
+To test event handlers manually:
+
+1. Start the service:
+   \`\`\`bash
+   bun dev
+   \`\`\`
+
+2. In another terminal, publish a test event:
+   \`\`\`bash
+   pf event:publish order-created
+   \`\`\`
+
+3. Check the service logs for the handler output
+
+### Unit Tests
+
+Run use-case tests:
+\`\`\`bash
+bun test
+\`\`\`
+
+## Development
+
+\`\`\`bash
+bun dev              # Start in development mode
+bun test             # Run tests
+bun lint             # Check code quality
+\`\`\`
+```
+
 ---
 
-# 10. Absolute Rules
+# 11. Absolute Rules
 
 DO NOT:
 - Generate full rewrites
 - Add new architecture concepts
 - Use raw NATS clients
-- Put logic in handlers or index.ts
+- Put logic in event handlers or index.ts
 - Insert semicolons
 - Add unused folders/files
+- **Use `src/handlers/` directory (use `src/events/` instead!)**
 
 DO:
 - Produce minimal, clean code
 - Follow structure and conventions strictly
 - Keep output compact and correct
+- **Always place event handlers in `src/events/` directory**
 
 ---