@crossdelta/platform-sdk 0.7.8 → 0.7.10

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

@@ -1,340 +1,61 @@
 # AI Generation Rules for CLI Code Output
 
-These rules define how AI-generated scaffolded services must be structured when produced by CLI tools.
-
-## 🚨 EMERGENCY RULES - READ FIRST 🚨
-
-**FOR EVENT CONSUMER SERVICES (services that "listen to", "consume", "react to" events):**
-
-**CRITICAL:** Contract schema fields MUST match event handler usage!
-
-**MANDATORY 4-STEP WORKFLOW:**
-
-1. **Analyze service description** → Extract required fields
-   Example: "needs orderId, customerId, total" → Fields: `orderId`, `customerId`, `total`
-
-2. **CREATE contract FIRST** (`packages/contracts/src/events/<event-name>.ts`):
-   ```ts
-   export const OrderCreatedContract = createContract({
-     type: 'order.created',
-     schema: z.object({
-       orderId: z.string(),      // ✅ From step 1
-       customerId: z.string(),   // ✅ From step 1
-       total: z.number(),        // ✅ From step 1
-     }),
-   })
-   ```
-
-3. **Export contract** (`packages/contracts/src/index.ts`):
-   ```ts
-   export * from './events/order-created'
-   ```
-
-4. **Create event handler** that uses SAME fields from contract:
-   ```ts
-   export default handleEvent(OrderCreatedContract, async (data) => {
-     await sendNotification({
-       orderId: data.orderId,       // ✅ Exists in contract
-       customerId: data.customerId, // ✅ Exists in contract
-       total: data.total,           // ✅ Exists in contract
-     })
-   })
-   ```
-
-**DO NOT create contracts with generic fields like `id`, `createdAt` - use the actual fields from the service description!**
+These rules define how AI-generated scaffolded services must be structured.
 
 ---
 
-## ⚠️ CRITICAL: Code Quality Guidelines
-
-**NEVER invent APIs, package names, or TypeScript types:**
-- ✅ **Research actual package documentation** before using third-party libraries
-- ✅ **Verify TypeScript types** match the actual library's type definitions
-- ✅ **Check npm registry** to confirm package names exist
-- ❌ **DO NOT hallucinate** API methods, properties, or function signatures
-- ❌ **DO NOT guess** at type structures - look them up or use `any` with a TODO comment
-
-**When unsure:**
-1. Use well-known, battle-tested packages (e.g., `@pusher/push-notifications-server`, not `pusher-beams`)
-2. Keep code simple and explicit
-3. Add TODO comments for unverified APIs: `// TODO: Verify this API signature`
-
----
-
-# 1. Commands Block (REQUIRED - MUST BE FIRST)
-
-**EVERY GENERATION MUST START WITH A COMMANDS BLOCK:**
-
-```commands
-pf new hono-micro services/my-service -y
-```
-
-Rules:
-- **ALWAYS** include this commands block as the FIRST thing in your output
-- **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)
-
----
-
-# 3. Dependencies Block
-
-```dependencies
-zod
-@pusher/push-notifications-server
-```
-
-Rules:
-- One package per line.
-- No versions.
-- Only packages not included in the scaffold.
-- **CRITICAL:** Only use packages that actually exist on npm. **Verify package names on npmjs.com** before using them (e.g., `@pusher/push-notifications-server` not `pusher-beams`).
-- **TypeScript safety:** Ensure your code respects the actual TypeScript types exported by the package. Do not invent properties or methods.
-- **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
-
----
-
-# 4. Required Source Files
-
-Generated services must include:
-
-**For Event Consumers:**
-- `src/index.ts` (with NATS setup)
-- `src/events/*.event.ts` (event handlers - NOT `src/handlers/`)
-- `src/use-cases/*.use-case.ts`
-- `src/use-cases/*.test.ts`
-- `src/types/*.ts` (Zod schemas and types)
-- `packages/contracts/src/events/*.ts` (event contracts)
-- `packages/contracts/src/index.ts` (export contract)
-- `README.md`
-
-**For Event Publishers:**
-- `src/index.ts` (REST API)
-- `src/use-cases/*.use-case.ts`
-- `src/use-cases/*.test.ts`
-- `src/types/*.ts` (Zod schemas and types)
-- `packages/contracts/src/events/*.ts` (RECOMMENDED: contracts for published events)
-- `packages/contracts/src/index.ts` (export contract)
-- `README.md`
-
-**Example for Event Consumer:**
-```
-services/order-notifications/
-├── src/
-│   ├── index.ts               # NATS consumer setup
-│   ├── events/
-│   │   └── order-created.event.ts  # Event handler
-│   ├── use-cases/
-│   │   ├── send-notification.use-case.ts
-│   │   └── send-notification.test.ts
-│   └── types/
-│       └── notifications.ts   # Zod schemas/types
-└── README.md
-
-packages/contracts/
-├── src/
-│   ├── events/
-│   │   └── order-created.ts   # Contract definition
-│   └── index.ts               # Export contract
-```
-
-Rules:
-- Paths must be relative to the service root.
-- Event handlers MUST go in `src/events/`, NOT `src/handlers/`.
-- Contracts MUST go in `packages/contracts/src/events/`, NOT in service directory.
-- Do NOT generate controller or module folders unless requested.
-
----
-
-# 5. Code Style
-
-- Biome-compatible formatting.
-- Strict TS.
-- Arrow functions only.
-- No semicolons.
-- Minimal comments.
-- Alphabetized imports.
-
----
-
-# 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"
+## 🚨 CRITICAL: Event Consumer Workflow
 
-**Example:** "Order management service that handles order creation. Publishes order.created events."
+**FOR EVENT CONSUMER SERVICES (services that "consume", "listen to", "react to" 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()`
+### Naming Convention (CRITICAL!)
 
-**Event Publishing Strategy:**
+**Event Type → Contract Name → File Name:**
 
-Publishers can use **contracts** (recommended) or **string literals**:
+| Event Type | Contract Name | File Name |
+|------------|---------------|-----------|
+| `orders.created` | `OrdersCreatedContract` | `orders-created.ts` |
+| `users.registered` | `UsersRegisteredContract` | `users-registered.ts` |
+| `payments.completed` | `PaymentsCompletedContract` | `payments-completed.ts` |
 
-```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,
-})
-```
+**Rule:** Always use **plural namespace** (`orders.`, `users.`, `payments.`) to match JetStream stream subjects (`orders.>`, `users.>`, etc.)
 
-**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
+### 4-Step Workflow
 
-**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"
-
-**Example:** "Notification service that sends emails when orders are created. Consumes order.created events."
-
-**⚠️⚠️⚠️ MANDATORY WORKFLOW FOR EVENT CONSUMERS ⚠️⚠️⚠️**
-
-**YOU MUST FOLLOW THIS EXACT ORDER:**
-
-**STEP 1: Analyze Service Description**
-Extract the required event data fields from the description.
-
-Example: "sends push notifications when orders are created. Needs orderId, customerId, and total"
-→ Required fields: `orderId`, `customerId`, `total`
-
-**STEP 2: CREATE Contract FIRST (packages/contracts/src/events/<event-name>.ts)**
+**STEP 1: CREATE Contract** (`packages/contracts/src/events/<event-name>.ts`):
 ```ts
 import { createContract } from '@crossdelta/cloudevents'
 import { z } from 'zod'
 
-export const OrderCreatedContract = createContract({
-  type: 'order.created',
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',  // plural namespace!
   schema: z.object({
-    orderId: z.string(),      // ✅ From Step 1
-    customerId: z.string(),   // ✅ From Step 1
-    total: z.number(),        // ✅ From Step 1
+    orderId: z.string(),
+    customerId: z.string(),
+    total: z.number(),
   }),
 })
 
-export type OrderCreatedData = z.infer<typeof OrderCreatedContract.schema>
+export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
 ```
 
-**STEP 3: Export Contract (packages/contracts/src/index.ts)**
+**STEP 2: Export Contract** (`packages/contracts/src/index.ts`):
 ```ts
-export * from './events/order-created'
+export * from './events/orders-created'
 ```
 
-**STEP 4: Create Event Handler (src/events/order-created.event.ts)**
+**STEP 3: Create Event Handler** (`src/events/orders-created.event.ts`):
 ```ts
 import { handleEvent } from '@crossdelta/cloudevents'
-import { OrderCreatedContract, type OrderCreatedData } from '@scope/contracts'
-import { sendNotification } from '../use-cases/send-notification.use-case'
-
-export default handleEvent(OrderCreatedContract, async (data: OrderCreatedData) => {
-  await sendNotification({
-    orderId: data.orderId,       // ✅ Field exists in contract
-    customerId: data.customerId, // ✅ Field exists in contract
-    total: data.total,           // ✅ Field exists in contract
-  })
+import { OrdersCreatedContract, type OrdersCreatedData } from '{{scope}}/contracts'
+import { processOrder } from '../use-cases/process-order.use-case'
+
+export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
+  await processOrder(data)
 })
 ```
 
-**CRITICAL:** The contract schema fields (Step 2) MUST match the event handler usage (Step 4)!
-
-**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)
-
-**⚠️ CRITICAL: Event Consumer index.ts Template - COPY THIS EXACTLY:**
-
+**STEP 4: Setup Consumer** (`src/index.ts`):
 ```ts
 import '@crossdelta/telemetry'
 
@@ -348,13 +69,11 @@ app.get('/health', (c) => c.json({ status: 'ok' }))
 
 Bun.serve({ port, fetch: app.fetch })
 
-// Ensure stream exists (idempotent - safe to call on every start)
 await ensureJetStreamStream({
   stream: 'ORDERS',
   subjects: ['orders.>'],
 })
 
-// Start NATS consumer - handlers are auto-discovered
 consumeJetStreamEvents({
   stream: 'ORDERS',
   consumer: 'my-service',
@@ -362,682 +81,184 @@ consumeJetStreamEvents({
 })
 ```
 
-**⚠️ MANDATORY CHECKLIST - Event Consumer index.ts MUST INCLUDE:**
-- [ ] `import { consumeJetStreamEvents, ensureJetStreamStream } from '@crossdelta/cloudevents'`
-- [ ] `await ensureJetStreamStream({ stream: 'ORDERS', subjects: ['orders.>'] })`
-- [ ] `consumeJetStreamEvents({ stream: 'ORDERS', consumer: 'service-name', discover: './src/events/**/*.event.ts' })`
-- [ ] Top-level await (Bun supports this natively)
-- [ ] `ensureJetStreamStream()` called BEFORE `consumeJetStreamEvents()`
-
-**CRITICAL ERRORS TO AVOID:**
-- ❌ Missing `ensureJetStreamStream()` → Stream won't exist, events won't be consumed
-- ❌ Missing `consumeJetStreamEvents()` → Service won't listen to events
-- ❌ Wrong import order → Telemetry must be first
-- ❌ Using `filterSubjects` in `ensureJetStreamStream()` → Use `subjects` parameter
-- ❌ Using `subjects` in `consumeJetStreamEvents()` → Use `filterSubjects` parameter if needed
-
-### � 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'
+## ⚠️ Code Quality Guidelines
 
-const port = Number(process.env.PORT || process.env.MY_SERVICE_PORT) || 4003
-const app = new Hono()
+- ✅ **Verify package names** on npmjs.com before using
+- ✅ Use exact package names: `@crossdelta/cloudevents`, `@crossdelta/telemetry`
+- ❌ **DO NOT hallucinate** APIs or package names
 
-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
-}))
+# 1. Commands Block (REQUIRED - MUST BE FIRST)
 
-Bun.serve({ port, fetch: app.fetch })
+```commands
+pf new hono-micro services/my-service -y
 ```
 
-**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()`
+- Services MUST be in `services/` directory
+- User says "orders" → Generate: `services/orders`
 
 ---
 
-### index.ts Rules
-
-Contains only:
-- Telemetry import (MUST be first)
-- Server setup (Hono)
-- Health endpoint
-- REST endpoints (for Publishers/Hybrid)
-- Event consumer registration (for Consumers/Hybrid)
-- Port configuration from env vars
+# 2. Post-Generation Commands
 
-**Import schemas and types from `src/types/` directory:**
-```ts
-import { CreateOrderSchema, UpdateOrderSchema } from './types/orders'
+For Event Consumer services:
 
-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)
-})
+```post-commands
+pf event:generate services/my-service --overwrite
 ```
 
 ---
 
-# 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),
-})
+# 3. Dependencies Block
 
-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(),
-})
+Only include packages not in the scaffold:
 
-// Export inferred types
-export type CreateOrderInput = z.infer<typeof CreateOrderSchema>
-export type UpdateOrderInput = z.infer<typeof UpdateOrderSchema>
+```dependencies
+zod
+@pusher/push-notifications-server
 ```
 
-**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
+**Note:** `{{scope}}/contracts` is already in the template's package.json.
 
 ---
 
-# 7. Use-Case Rules (Lean Hexagonal Architecture)
-
-Services follow a **Lean Hexagonal Architecture** pattern:
-- **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.
-
-Example: "Payment processing service" might generate:
-- `validate-payment.use-case.ts` - Validate payment details
-- `process-payment.use-case.ts` - Execute payment with provider
-- `notify-payment-status.use-case.ts` - Send payment notifications
-- `refund-payment.use-case.ts` - Handle refund requests
-
-Use-Case Rules:
-- All domain logic lives in `src/use-cases/`
-- One use-case = one responsibility
-- Pure functions preferred
-- 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'
+# 4. Required Files
 
-// 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
-}
+**Event Consumer:**
 ```
+services/my-service/
+├── src/
+│   ├── index.ts                    # NATS consumer setup
+│   ├── events/
+│   │   └── orders-created.event.ts # Event handler
+│   ├── use-cases/
+│   │   ├── process-order.use-case.ts
+│   │   └── process-order.test.ts
+│   └── types/
+│       └── orders.ts
+└── README.md
 
-**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
-}
+packages/contracts/
+├── src/
+│   ├── events/
+│   │   └── orders-created.ts       # Contract
+│   └── index.ts
 ```
 
-**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
-}
+**Event Publisher:**
 ```
-
-**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!
-}
+services/my-service/
+├── src/
+│   ├── index.ts                    # REST API + publish()
+│   ├── use-cases/
+│   │   ├── create-order.use-case.ts
+│   │   └── create-order.test.ts
+│   └── types/
+│       └── orders.ts
+└── README.md
 ```
 
-Types and schemas belong in **`src/types/`**, NOT in use-cases!
-
 ---
 
-# 8. Event Handler Rules (For Event Consumers Only!)
-
-**CRITICAL:** Event handlers are ONLY for services that **consume/react to** events from other services!
-
-**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
-
-**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) - You MUST create complete contracts!**
-
-When generating an Event Consumer service:
-
-1. **CREATE the contract** in `packages/contracts/src/events/` with **complete schema** based on the service description
-2. **Use the contract** in the event handler (`import { OrderCreatedContract } from '{{scope}}/contracts'`)
-3. **Export the contract** in `packages/contracts/src/index.ts`
-
-**⚠️ CRITICAL: Contract Schema Must Match Handler Usage!**
-
-If the event handler uses fields like `orderId`, `customerId`, `total`, the contract schema MUST include those exact fields!
-
-**Example Flow:**
-```
-User prompt: "Notification service that sends push notifications when orders are created"
-
-Step 1: Analyze what data the service needs:
-  - orderId (to identify the order)
-  - customerId (to send notification to customer)
-  - total (to show order amount)
-
-Step 2: CREATE contract with those fields:
-  packages/contracts/src/events/order-created.ts:
-    schema: z.object({
-      orderId: z.string(),
-      customerId: z.string(),
-      total: z.number(),
-      createdAt: z.string().optional(),  // Add optional context fields
-    })
-
-Step 3: CREATE event handler that uses those fields:
-  services/order-notifications/src/events/order-created.event.ts:
-    import { OrderCreatedContract, type OrderCreatedData } from '@scope/contracts'
-    export default handleEvent(OrderCreatedContract, async (data) => {
-      await sendNotification({ 
-        orderId: data.orderId,       // ✅ Field exists in contract
-        customerId: data.customerId, // ✅ Field exists in contract
-        total: data.total,           // ✅ Field exists in contract
-      })
-    })
-```
-
-**Why Create Contracts Immediately?**
-- ✅ Schema matches handler requirements from the start
-- ✅ No schema mismatch errors at runtime
-- ✅ Type-safety between contract and handler
-- ✅ Single source of truth for event structure
+# 5. Code Style
 
-**MANDATORY for Event Consumers:**
-- Always create `packages/contracts/src/events/<event-name>.ts` file
-- Schema must include ALL fields used by the event handler
-- Export contract in `packages/contracts/src/index.ts`
-- Include `pf event:generate` in post-commands to create mock JSON
+- Biome-compatible, strict TS, arrow functions only
+- No semicolons, minimal comments, alphabetized imports
 
-### 🟢 ADVANCED MODE (Default - Recommended)
+---
 
-**Use Advanced Mode for Event Consumers** - you MUST create contracts with complete schemas:
+# 6. Service Types
 
-**⚠️ CRITICAL CONTRACT CREATION RULES:**
+## 📤 Event Publisher (REST API)
 
-1. **Analyze service description** to determine required event fields
-2. **CREATE contract file** in `packages/contracts/src/events/<event-name>.ts`
-3. **Include ALL fields** that the event handler will use
-4. **Export in index** - add to `packages/contracts/src/index.ts`
-5. **Add dependency** `{{scope}}/contracts` to service's dependencies block
+**Keywords:** "publishes", "creates", "manages", "REST API"
 
-**Contract File Template:**
 ```ts
-// packages/contracts/src/events/<event-name>.ts
-import { createContract } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-
-export const OrderCreatedContract = createContract({
-  type: 'order.created',  // Exact event type string
-  schema: z.object({
-    // REQUIRED: Fields used by the event handler
-    orderId: z.string(),
-    customerId: z.string(),
-    total: z.number(),
-    
-    // OPTIONAL: Additional context fields
-    items: z.array(z.object({
-      productId: z.string(),
-      quantity: z.number(),
-      price: z.number(),
-    })).optional(),
-    status: z.enum(['created', 'processing', 'completed']).optional(),
-    createdAt: z.string().optional(),
-  }),
-})
+import '@crossdelta/telemetry'
 
-export type OrderCreatedData = z.infer<typeof OrderCreatedContract.schema>
-```
+import { publish } from '@crossdelta/cloudevents'
+import { Hono } from 'hono'
 
-**Export in Index:**
-```ts
-// packages/contracts/src/index.ts
-export * from './events/order-created'
-// ... other exports
-```
+const app = new Hono()
 
-**Event Handler Using Contract:**
-```ts
-// services/order-notifications/src/events/order-created.event.ts
-import { handleEvent } from '@crossdelta/cloudevents'
-import { OrderCreatedContract, type OrderCreatedData } from '@scope/contracts'
-import { sendNotification } from '../use-cases/send-notification.use-case'
-
-export default handleEvent(OrderCreatedContract, async (data: OrderCreatedData) => {
-  // data has all fields from contract schema
-  await sendNotification({
-    orderId: data.orderId,       // ✅ Exists in contract
-    customerId: data.customerId, // ✅ Exists in contract
-    total: data.total,           // ✅ Exists in contract
-  })
+app.post('/orders', async (c) => {
+  const data = await c.req.json()
+  await publish('orders.created', data, { source: 'my-service' })
+  return c.json({ success: true })
 })
-```
-
-**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 create complete contracts for Event Consumers.
+Bun.serve({ port: 4001, fetch: app.fetch })
+```
 
-### 📋 DEPRECATED: Basic Mode
+## 📥 Event Consumer (NATS)
 
-**Basic Mode is deprecated and no longer recommended.**
+**Keywords:** "consumes", "listens to", "reacts to", "handles events"
 
-Always use Advanced Mode (contracts) for Event Consumers.
+See 4-Step Workflow above.
 
-**Previous Basic Mode approach:**
-- ❌ Local schemas in `src/types/events.ts`
-- ❌ String literals for event types
-- ❌ No type-safety between services
+## 🔄 Hybrid (Both)
 
-**Current approach (Advanced Mode only):**
-- ✅ Always create contracts in `packages/contracts/src/events/`
-- ✅ Complete schemas with all required fields
-- ✅ Type-safety across all services
-- ✅ Single source of truth
+Combines REST endpoints + NATS consumer.
 
 ---
 
-## 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!)
+# 7. Use-Case Rules
 
-**CRITICAL:** Schema validates ONLY the event data payload (without `type` field). Event type is declared in the options object or contract.
+- Live in `src/use-cases/*.use-case.ts`
+- Pure functions, no framework imports
+- Import types from `src/types/`, NOT Zod schemas
+- Inject dependencies as parameters (Map, services, etc.)
+- NO manual validation (adapters handle that)
 
-**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 `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'
+import type { OrdersCreatedData } from '{{scope}}/contracts'
 
-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>
+export const processOrder = async (
+  data: OrdersCreatedData,
+  orderStore: Map<string, any>
+) => {
+  orderStore.set(data.orderId, { ...data, processedAt: new Date() })
+  return { success: true }
+}
 ```
 
-**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
-- Multi-step logic
-- Env var parsing
-
 ---
 
-# 9. Testing Rules
+# 8. Testing Rules
 
-**CRITICAL:**
-- Test ONLY use-cases (NOT event handlers)
-- Use Bun's native test runner: `import { describe, expect, it, beforeEach, afterEach } from 'bun:test'`
-- **NO mocking available** - Bun does NOT have `vi`, `mock`, `jest.fn()`, or module mocking
-- Focus on validation (input params, env vars) and error handling
-- Keep tests simple - avoid complex scenarios
+- Test ONLY use-cases
+- Use `import { describe, expect, it } from 'bun:test'`
+- NO mocking (Bun doesn't support it)
+- Focus on error handling and validation
 
-**What to test:**
-- ✅ Input validation (missing/empty parameters)
-- ✅ Environment variable validation
-- ✅ Error messages and error types
-- ❌ External API integrations (Pusher, AWS, etc.)
-- ❌ Complex mocking scenarios
-
-Example:
 ```ts
-import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
-import { sendNotification } from './send-notification.use-case'
-
-describe('Send Notification Use Case', () => {
-  const originalEnv = process.env
-
-  beforeEach(() => {
-    process.env = { ...originalEnv }
-  })
-
-  afterEach(() => {
-    process.env = originalEnv
-  })
-
-  it('should throw error if orderId is missing', async () => {
-    await expect(
-      sendNotification({ orderId: '', customerId: 'cust-1' })
-    ).rejects.toThrow('Missing orderId')
-  })
-
-  it('should throw error if credentials not set', async () => {
-    delete process.env.PUSHER_BEAMS_INSTANCE_ID
-
-    await expect(
-      sendNotification({ orderId: '123', customerId: 'cust-1' })
-    ).rejects.toThrow('Missing Pusher Beams credentials')
+import { describe, expect, it } from 'bun:test'
+import { processOrder } from './process-order.use-case'
+
+describe('Process Order', () => {
+  it('should store order', async () => {
+    const store = new Map()
+    const result = await processOrder({ orderId: '123', customerId: 'c1', total: 100 }, store)
+    expect(store.has('123')).toBe(true)
   })
 })
 ```
 
 ---
 
-# 10. README Requirements
-
-MUST include:
-- Description
-- Features list
-- Environment variable table
-- 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
-\`\`\`
-```
-
----
-
-# 11. Absolute Rules
+# 9. Absolute Rules
 
-DO NOT:
+**DO NOT:**
 - Generate full rewrites
-- Add new architecture concepts
 - Use raw NATS clients
-- Put logic in event handlers or index.ts
+- Put logic in handlers or index.ts
+- Use `src/handlers/` (use `src/events/`)
 - 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**
-
----
+**DO:**
+- Follow naming convention (plural event types)
+- Create contracts in `packages/contracts`
+- Keep code minimal and clean