@crossdelta/platform-sdk 0.7.21 → 0.8.0

package/README.md

@@ -11,48 +11,59 @@
 <p align="center">
   <strong>Opinionated platform toolkit for event-driven microservices.</strong><br />
   Scaffold <a href="https://turbo.build/repo">Turborepo</a> workspaces, generate services from natural language,<br />
-  and deploy via <a href="https://www.pulumi.com">Pulumi</a> — DigitalOcean-first, provider-agnostic by design.
+  and deploy via <a href="https://www.pulumi.com">Pulumi</a> — DigitalOcean-first for speed and simplicity, providers replaceable by design.
 </p>
 
 <p align="center">
-  <strong>🚀 Scaffold • 🤖 Generate • ☁️ Deploy</strong>
+  <em>Platform SDK (<code>pf</code>) is a platform opinion, not a generator.<br />
+  It encodes architectural decisions so teams don't have to rediscover them.</em>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@crossdelta/platform-sdk"><img src="https://img.shields.io/npm/v/@crossdelta/platform-sdk.svg?style=flat-square" alt="npm version" /></a>
+  <em>Includes optional AI-assisted service generation (OpenAI / Anthropic).</em>
+</p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@crossdelta/platform-sdk"><img src="https://img.shields.io/npm/v/@crossdelta/platform-sdk.svg?style=flat-square" alt="npm version" /></a>
   <img src="https://img.shields.io/badge/bun-%E2%9A%A1-f9f1e1?style=flat-square" alt="Bun" />
   <img src="https://img.shields.io/badge/pulumi-ready-blueviolet?style=flat-square" alt="Pulumi" />
   <img src="https://img.shields.io/badge/DigitalOcean-App_Platform_|_DOKS-0080FF?style=flat-square" alt="DigitalOcean" />
 </p>
 
 <p align="center">
-  <em><code>pf</code> enforces conventions that keep application code and cloud infrastructure in lockstep — from local development to production.</em>
+  <img src="https://img.shields.io/badge/Hono-E36002?style=flat-square&logo=hono&logoColor=white" alt="Hono" />
+  <img src="https://img.shields.io/badge/NestJS-E0234E?style=flat-square&logo=nestjs&logoColor=white" alt="NestJS" />
+  <img src="https://img.shields.io/badge/NATS-27AAE1?style=flat-square&logo=natsdotio&logoColor=white" alt="NATS" />
 </p>
 
-<br />
+---
+
+## Who is this for?
+
+- **Teams building event-driven backends** — NATS, CloudEvents, type-safe contracts
+- **Startups & internal platforms** that want long-term consistency over short-term speed
+- **Engineers tired of infra & app drift** — ports, env vars, deployments always in sync
+
+You can start without understanding all the pieces. The depth reveals itself as you grow.
 
 ---
 
 ## Installation
 
 ```bash
-# Pick your package manager
 bun add -g @crossdelta/platform-sdk
-npm install -g @crossdelta/platform-sdk
-pnpm add -g @crossdelta/platform-sdk
+# or: npm install -g @crossdelta/platform-sdk
 ```
 
 <details>
-<summary>Alternative: Auto-installer or use without installing</summary>
+<summary>Alternative: Auto-installer or run without installing</summary>
 
 ```bash
-# Auto-installer (detects package manager, offers to install Bun if needed)
+# Auto-installer (installs CLI globally, prompts to install Bun if missing)
 curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
 
-# Or run directly without global install
+# Or run directly without installing
 bunx @crossdelta/platform-sdk new workspace my-platform
-npx @crossdelta/platform-sdk new workspace my-platform
 ```
 
 </details>
@@ -62,277 +73,120 @@ npx @crossdelta/platform-sdk new workspace my-platform
 ## Quick Start
 
 ```bash
-# Create workspace
-pf new workspace my-platform -y
-cd my-platform
-
-# Generate microservice with AI
-pf setup --ai                    # Configure AI provider (first time only)
-pf new hono-micro services/orders --ai -d "Handle order creation and payment"
-
-# Start development
+pf new workspace my-platform -y && cd my-platform
 pf dev
 ```
 
-**What you get in minutes:**
-
-- ✔ Turborepo monorepo with Biome linting
-- ✔ NATS + event-driven microservices
-- ✔ Pulumi infrastructure (`infra/services/*.ts`)
-- ✔ Auto-generated `.env.local` with service ports
-- ✔ AI-generated service code
-
-All wired automatically. Local + production infra in lockstep.
-
-### ⚡ One CLI for everything
-
-`pf` runs your workspace scripts from anywhere:
-
-```bash
-pf test         # → turbo run test
-pf build        # → turbo run build
-pf pulumi up    # → runs in infra/ directory
-```
-
-**Why:** Keeps commands consistent across the team and works from any subdirectory.
-
-> **📖 Note:** You can be productive with `pf` in minutes using the commands above. The sections below are reference documentation—explore them when you need specific details.
-
-<br />
-
----
-
-## 🎯 Why This Exists
-
-**`pf` solves these platform engineering problems:**
-
-- **Infrastructure drift** — Infra configs live in separate repos, diverge from code
-- **Manual wiring** — Ports, env vars, service discovery configured by hand
-- **Slow onboarding** — New devs spend days setting up local environment
-
-**`pf` is lockstep infra + code:** Services auto-generate `infra/services/*.ts`, ports/env derived automatically, event handlers type-safe and auto-discovered.
+**What you get:**
+- Turborepo monorepo with Biome linting
+- NATS + JetStream for event-driven messaging
+- Pulumi infrastructure (`infra/services/*.ts`)
+- Auto-generated `.env.local` with service ports
 
-<br />
+> **Lockstep by design:**
+> In `pf`, application code and infrastructure are generated from the same source of truth.
+> Service metadata defines ports, env vars, event wiring, and Pulumi configs —
+> eliminating drift between local development, CI, and production.
 
 ---
 
-## 🧩 What This SDK Is / Is Not
+## Day 1 with pf
 
-### ✅ `pf` is:
+**5 minutes to your first event-driven system:**
 
-- **Opinionated platform toolkit** for event-driven microservices
-- **[Turborepo](https://turbo.build/repo) scaffolder** with [Pulumi](https://www.pulumi.com) IaC and [NATS](https://nats.io) messaging built-in
-- **AI-assisted code generator** that creates service boilerplate from descriptions
-- **Unified dev workflow** — one command to run all services (`pf dev`)
-- **[DigitalOcean](https://www.digitalocean.com)-first** deployment target (App Platform + DOKS)
-
-### ❌ `pf` is not:
+```bash
+# 1. Create a new platform
+pf new workspace my-platform -y && cd my-platform
 
-- **Generic microservice generator** — makes architectural choices for you
-- **Multi-cloud** (not yet) — DigitalOcean first, extensible provider architecture
-- **Runtime manager** — scaffolds code, you deploy with Pulumi
-- **Kubernetes replacement** — generates K8s configs via Pulumi
+# 2. Add two services
+pf new hono-micro services/orders
+pf new hono-micro services/notifications
 
-**Note:** `pf` runs nothing implicitly—no hidden daemons, no automatic deployments or provisioning. You maintain explicit control over when code runs and infrastructure is deployed.
+# 3. Wire an event between them
+pf event add orders.created --service services/notifications
 
-### 🔥 Why `pf` vs other tools?
+# 4. Start everything
+pf dev
 
-- **🔗 Lockstep infra + code** — `infra/services/*.ts` auto-generated from service metadata, ports/env derived automatically
-- **⚡ Event-driven by default** — [NATS](https://nats.io) + JetStream built-in with auto-discovered handlers (`*.event.ts`) and Zod-validated payloads
-- **🤖 Automation through conventions** — New service = infra config + env vars + port assignment happens automatically
+# 5. Publish a test event — watch notifications react
+pf event publish orders.created
+```
 
-<br />
+That's it. Two services, one event contract, auto-discovered handlers, no manual wiring.
 
 ---
 
-## 🏗️ Architecture at 10,000 ft
+## 🧭 How You Work With pf (Happy Paths)
 
-When you create a workspace with `pf`, you get a **Turborepo monorepo** with this structure:
+### Start a new platform
 
-```
-my-platform/
-├── services/              # Microservices (generate with pf new hono-micro)
-│   ├── nats/              # NATS message broker (auto-scaffolded)
-│   └── <service>/         # Your services go here
-│       └── src/
-│           ├── events/    # Event handlers (*.event.ts)
-│           ├── use-cases/ # Business logic (*.use-case.ts)
-│           ├── types/     # Zod schemas & types
-│           └── index.ts   # Service entrypoint
-├── apps/                  # Frontend apps (optional)
-├── packages/
-│   └── contracts/         # Event contracts (Schema Registry)
-│       └── src/
-│           └── events/    # Event schemas (single source of truth)
-├── infra/                 # Pulumi Infrastructure-as-Code
-│   ├── index.ts           # Main Pulumi program
-│   └── services/          # Per-service K8s configs (auto-generated)
-├── .github/
-│   └── workflows/         # CI/CD pipelines
-├── turbo.json             # Turborepo task orchestration
-└── .env.local             # Auto-generated from infra configs
+```bash
+pf new workspace my-platform --github-owner my-org --pulumi-stack dev -y
+cd my-platform
+pf dev
 ```
 
-### Key Conventions
+This scaffolds a complete Turborepo monorepo with NATS, Pulumi infrastructure, GitHub Actions workflows, and auto-generated environment variables.
 
-| Location | Purpose |
-|----------|---------|
-| `services/*/src/events/*.event.ts` | Event handlers (auto-discovered) |
-| `services/*/src/use-cases/*.use-case.ts` | Business logic (pure functions) |
-| `services/*/src/types/*.ts` | Service-local Zod schemas |
-| `packages/contracts/src/events/*.ts` | Event contracts (Schema Registry) |
-| `infra/services/*.ts` | Pulumi configs per service |
-
-### Key Rules
-
-- **Never duplicate schemas** — Contracts in `packages/contracts` are the single source of truth
-- **Event handlers stay thin** — Delegate to use-cases, no business logic in handlers
-- **Infrastructure is explicit** — Ports, env vars derived from `infra/services/*.ts`
-
-### Event-Driven Mental Model
-
-Services communicate via **CloudEvents** over **NATS JetStream** using the **Schema Registry** as single source of truth:
-
-**1. Define contract (Schema Registry):**
-
-```typescript
-// packages/contracts/src/events/orders-created.ts
-import { createContract } from '@crossdelta/cloudevents'
-import { z } from 'zod'
-
-export const OrdersCreatedContract = createContract({
-  type: 'orders.created',
-  schema: z.object({
-    orderId: z.string(),
-    customerId: z.string(),
-    total: z.number(),
-  }),
-})
+### Add a new microservice
 
-export type OrdersCreatedData = z.infer<typeof OrdersCreatedContract.schema>
+**Hono** (lightweight, Bun-optimized):
+```bash
+pf new hono-micro services/orders
 ```
 
-**2. Service A publishes an event:**
-
-```typescript
-// services/orders/src/index.ts
-import { publish } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract } from '@my-platform/contracts'
-
-await publish(OrdersCreatedContract, {
-  orderId: '123',
-  customerId: 'cust-456',
-  total: 99.99
-})
+**NestJS** (full-featured, decorator-based):
+```bash
+pf new nest-micro services/orders
 ```
 
-**3. Service B auto-discovers and handles it:**
-
-```typescript
-// services/notifications/src/events/orders-created.event.ts
-import { handleEvent } from '@crossdelta/cloudevents'
-import { OrdersCreatedContract, type OrdersCreatedData } from '@my-platform/contracts'
-import { sendOrderNotification } from '../use-cases/send-order-notification.use-case'
+Or use AI generation with either:
 
-export default handleEvent(OrdersCreatedContract, async (data: OrdersCreatedData) => {
-  await sendOrderNotification(data)  // Delegate to use-case
-})
+```bash
+pf new hono-micro services/orders --ai -d "Handle order creation and publish order events"
 ```
 
-No manual NATS subscriptions. No boilerplate. Just **convention over configuration**.
+Both generate the service structure, Pulumi config in `infra/services/`, and wire everything automatically.
 
-<br />
+### Generate with AI (optional)
 
----
-
-## 🧭 Design Principles
-
-These principles guide every decision in `pf`:
-
-- **🥟 Bun-first DX** — Leverage Bun's speed for installs, tests, and dev mode (npm/yarn fallback supported)
-- **📦 Monorepo-centric** — One repo to rule them all. Turborepo for caching and parallel builds
-- **🏗️ Infrastructure-as-Code by default** — No ClickOps. Every service has Pulumi config
-- **🔁 Event-driven communication baked in** — NATS + JetStream are first-class citizens, not afterthoughts
-- **🌊 DigitalOcean-first, cloud-agnostic later** — Start simple with DO, expand to AWS/GCP when needed
-- **🤖 AI-augmented development** — Use AI to generate complete services, not just snippets
-- **📏 Convention over configuration** — Strong opinions enable automation
-
-<br />
-
----
-
-## 👥 Who Is This For?
-
-`pf` is designed for **small to mid-sized teams building event-driven systems** who want strong conventions, infra parity, and fast onboarding — without maintaining their own internal platform.
-
-<br />
-
----
-
-## 📚 Deep Dive & Reference
+Configure your AI provider once:
 
-The sections below cover architectural details, workflows, and advanced usage.
-**You don't need to read them to get started** — they're here when you need them.
-
----
-
-## 📘 Workflows
-
-### Generate microservices
-
-**Manual scaffolding:**
-```bash
-pf new hono-micro services/orders
-pf new nest-micro services/api-gateway
-```
-
-**AI-powered generation:**
 ```bash
-# First time: configure AI provider (OpenAI or Anthropic)
-pf setup --ai
-
-# Generate service with AI
-pf new hono-micro services/payments --ai \
-  -d "Handle Stripe webhooks and send payment confirmations"
+pf setup --ai   # OpenAI or Anthropic
 ```
 
-**✨ AI generates:**
-- ✅ Complete service with event handlers & use cases
-- ✅ Pulumi infrastructure configuration
-- ✅ Test files with validation logic
-- ✅ Complete README documentation
-
-> **Note:** AI-generated code is a starting point. Always review and test before deploying to production. `pf` never deploys or provisions infrastructure automatically — deployment always happens explicitly via Pulumi.
-
-### Start local development
+Then use `--ai` with any service generator:
 
 ```bash
-cd my-platform
-pf dev
+pf new hono-micro services/notifications --ai -d "Send emails on order events"
 ```
 
-This will:
-- 🔄 Auto-generate `.env.local` from infrastructure config
-- 🚀 Start NATS + all services in watch mode (via Turbo)
-- 🔌 Auto-assign unique ports per service
-- 📦 Monitor for file changes and hot-reload
+AI generates: service code, event handlers, use cases, tests, and documentation.
 
-### 4. Essential workspace commands
+AI is a productivity layer — all generated code follows the same conventions and can be written manually without loss of functionality.
 
-```bash
-# Run all tests across the monorepo
-pf test
+### Daily commands
 
-# Lint and format all code with Biome
-pf lint
+| Command | What it does |
+|---------|--------------|
+| `pf dev` | Start NATS + all services in watch mode |
+| `pf test` | Run tests across the monorepo |
+| `pf lint` | Lint and format with Biome |
+| `pf build` | Build all packages and services |
+| `pf new hono-micro <path>` | Create Hono microservice (lightweight) |
+| `pf new nest-micro <path>` | Create NestJS microservice (full-featured) |
+| `pf event add <type> --service <path>` | Add contract, mock, handler + wire stream |
+| `pf event list` | List available events and their consumers |
+| `pf event publish <type>` | Publish mock event to NATS |
+| `pf pulumi up` | Deploy infrastructure (runs in `infra/`) |
 
-# Build all packages and services
-pf build
-```
+`pf` proxies to Turborepo from any subdirectory.
 
-### 5. Workspace Configuration
+### Configuration (advanced)
 
-Configure workspace behavior via the `pf` field in your root `package.json`:
+<details>
+<summary>Workspace configuration via <code>package.json</code></summary>
 
 ```json
 {
@@ -343,238 +197,207 @@ Configure workspace behavior via the `pf` field in your root `package.json`:
       "deploy": { "cwd": "infra", "command": "pulumi up --yes" }
     },
     "paths": {
-      "services": {
-        "path": "services",
-        "watch": true
-      },
-      "apps": {
-        "path": "apps",
-        "watch": true
-      },
-      "packages": {
-        "path": "packages",
-        "watch": true,
-        "ignorePatterns": ["packages/some-internal-package"]
-      },
-      "contracts": {
-        "path": "packages/contracts"
-      }
+      "services": { "path": "services", "watch": true },
+      "apps": { "path": "apps", "watch": true },
+      "packages": { "path": "packages", "watch": true },
+      "contracts": { "path": "packages/contracts" }
     }
   }
 }
 ```
 
-**Options:**
-- `commands`: Custom command shortcuts with `cwd` (working directory) and `command` overrides
-- `paths.<type>.path`: Directory path for each workspace type
-- `paths.<type>.watch`: Whether to watch this directory in dev mode (default: `false`)
-- `paths.<type>.ignorePatterns`: Glob patterns to ignore within this path (optional)
-
-<br />
+- `commands`: Custom shortcuts with working directory overrides
+- `paths.<type>.watch`: Enable file watching in dev mode
+- `paths.<type>.ignorePatterns`: Glob patterns to exclude
 
----
-
-## 📘 Typical Workflows
-
-Here's how developers actually use `pf` in real-world scenarios:
+</details>
 
 <details>
-<summary><strong>Workflow 1: Start a New Platform</strong></summary>
-
-<br />
-
-You're building a new product from scratch and want to establish a solid foundation.
-
-```bash
-# Step 1: Scaffold the workspace
-bunx @crossdelta/platform-sdk new workspace my-platform \
-  --github-owner my-platform \
-  --pulumi-stack dev \
-  -y
-
-cd my-platform
+<summary>Infrastructure configuration via <code>infra/services/*.ts</code></summary>
 
-# Step 2: Configure infrastructure (optional)
-# Edit infra/config.ts to customize:
-# - DigitalOcean region (defaults to nyc3)
-# - Kubernetes cluster size
-# - Database instance sizes
+```ts
+import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'
 
-# Step 3: Start local development
-pf dev
+export const config: K8sServiceConfig = {
+  name: 'orders',
+  ports: ports().http(4001).build(),
+  replicas: 1,
+  healthCheck: { httpPath: '/health' },
+  resources: {
+    requests: { cpu: '50m', memory: '64Mi' },
+    limits: { cpu: '150m', memory: '128Mi' },
+  },
+}
 ```
 
-**What you get:**
-- ✅ Turborepo monorepo with Biome linting/formatting
-- ✅ NATS service running in Docker
-- ✅ Pulumi infrastructure setup for DigitalOcean
-- ✅ GitHub Actions workflows for CI/CD
-- ✅ `.env.local` auto-generated with all service ports
+See [@crossdelta/infrastructure](https://www.npmjs.com/package/@crossdelta/infrastructure) for full options.
 
 </details>
 
 ---
 
-### Workflow 2: Add a New Microservice
+## 🎯 Why This Exists
 
-```bash
-# Generate with AI (optional: use --ai flag)
-pf new hono-micro services/payments --ai \
-  -d "Stripe payment processing: handle webhooks, publish events"
+`pf` solves platform engineering problems:
 
-# Auto-generated: service code + infra config + tests + README
-# Start the service
-pf dev
-```
+- **Infrastructure drift** — Infra configs diverge from code in separate repos
+- **Manual wiring** — Ports, env vars, service discovery configured by hand
+- **Slow onboarding** — New devs spend days setting up local environments
+
+**Solution:** Services auto-generate `infra/services/*.ts`, ports/env derived automatically, event handlers type-safe and auto-discovered.
 
-**AI generates:** Service structure, event handlers, use cases, tests, and documentation. Always review before deploying.
+**In short: docker-compose starts services — `pf` prevents systems from drifting apart over time.**
 
 ---
 
-## ⚡ NATS Message Broker
+## 🧩 What pf Is / Is Not
 
-Every workspace includes a pre-configured NATS service with JetStream:
+**✅ pf is:**
+- Opinionated platform toolkit for event-driven microservices
+- Turborepo scaffolder with Pulumi IaC and NATS messaging built-in
+- AI-assisted code generator from natural language descriptions
+- Unified dev workflow — one command to run everything
+- DigitalOcean-first for speed and simplicity — providers replaceable by design
 
-```
-services/nats/
-├── nats.conf              # Local dev config (JetStream enabled)
-├── nats.prod.conf         # Production config (auth + persistence)
-├── scripts/start-dev.sh   # Docker startup script
-└── README.md              # Full NATS documentation
-```
+**❌ pf is not:**
+- Generic microservice generator — makes architectural choices for you
+- Multi-cloud out of the box — DigitalOcean first, extensible to other providers
+- Runtime manager — scaffolds code, you deploy with Pulumi
 
-**Local Development:**
-- Auto-started with `pf dev`
-- Runs in Docker on ports `4222` (client) and `8222` (HTTP monitoring)
-- Data persisted in `.nats-data/` directory
-- Health check: `curl http://localhost:8222/healthz`
-
-**📚 Learn more:** See `services/nats/README.md` in your workspace for monitoring, configuration, and JetStream details.
-
-<br />
+**Note:** `pf` runs nothing implicitly. No hidden daemons, no automatic deployments. You control when code runs and infrastructure deploys.
 
 ---
 
-## 🛠 CLI Commands
+## 🏗️ Architecture
 
-<details>
-<summary><strong>📖 View Full Command Reference</strong></summary>
+```
+my-platform/
+├── services/              # Microservices
+│   ├── nats/              # NATS message broker (auto-scaffolded)
+│   └── <service>/
+│       └── src/
+│           ├── events/    # Event handlers (*.event.ts)
+│           ├── use-cases/ # Business logic (*.use-case.ts)
+│           ├── types/     # Zod schemas
+│           └── index.ts
+├── packages/
+│   └── contracts/         # Event contracts (Schema Registry)
+├── infra/                 # Pulumi Infrastructure-as-Code
+│   └── services/          # Per-service K8s configs
+└── .env.local             # Auto-generated from infra
+```
 
-<br />
+### Conventions
 
-### Workspace Commands
+| Location | Purpose |
+|----------|---------|
+| `services/*/src/events/*.event.ts` | Event handlers (auto-discovered) |
+| `services/*/src/use-cases/*.use-case.ts` | Business logic (pure functions) |
+| `packages/contracts/src/events/*.ts` | Event contracts (single source of truth) |
+| `infra/services/*.ts` | Pulumi configs per service |
 
-| Command | Description |
-|---------|-------------|
-| `pf new` | Interactive creation wizard |
-| `pf new workspace <name>` | Scaffold a complete platform monorepo |
-| `pf setup --ai` | Configure AI provider (OpenAI or Anthropic) |
+> **Schema Registry pattern:**
+> All event contracts live in `packages/contracts` as the single source of truth.
+> Services import contracts instead of redefining schemas, ensuring
+> type safety, compatibility, and explicit ownership across service boundaries.
 
-### Service Commands
+### Event-Driven Pattern
 
-| Command | Description |
-|---------|-------------|
-| `pf new hono-micro <path>` | Generate a Hono microservice (lightweight) |
-| `pf new nest-micro <path>` | Generate a NestJS microservice (enterprise-grade) |
-| `pf new hono-micro <path> --ai` | Generate service with AI (requires `pf setup --ai`) |
+**Add events with one command:**
+```bash
+# Creates contract, mock, handler, and wires the stream automatically
+pf event add orders.created --service services/notifications
+```
 
-### Event Testing
+This generates:
+- `packages/contracts/src/events/orders-created.ts` (contract)
+- `packages/contracts/src/events/orders-created.mock.json` (test data)
+- `services/notifications/src/events/orders-created.event.ts` (handler)
+- Adds stream to service `index.ts` if needed
 
-| Command | Description |
-|---------|-------------|
-| `pf event:generate <path>` | Generate event mocks from event handlers |
-| `pf event:list` | List all available event mocks |
-| `pf event:publish <name>` | Publish to NATS JetStream |
-| `pf event:http <name>` | Send via HTTP Pub/Sub endpoint |
+**Test events locally:**
+```bash
+pf event list              # Show available events
+pf event publish orders.created  # Publish mock event to NATS
+```
 
-### Utility Commands
+**Manual pattern (if you prefer):**
 
-| Command | Description |
-|---------|-------------|
-| `pf --version` | Show version information |
-| `pf --help` | Show help for any command |
+**1. Define contract:**
+```typescript
+// packages/contracts/src/events/orders-created.ts
+import { createContract } from '@crossdelta/cloudevents'
+import { z } from 'zod'
 
-</details>
+export const OrdersCreatedContract = createContract({
+  type: 'orders.created',
+  schema: z.object({ orderId: z.string(), total: z.number() }),
+})
+```
 
-<br />
+**2. Publish (Service A):**
+```typescript
+// services/orders/src/use-cases/create-order.use-case.ts
+await publish(OrdersCreatedContract, { orderId: '123', total: 99.99 })
+```
 
----
+**3. Handle (Service B, auto-discovered):**
+```typescript
+// services/notifications/src/events/orders-created.event.ts
+export default handleEvent(OrdersCreatedContract, async (data) => {
+  await sendOrderNotification(data)
+})
+```
 
-## 🔧 Configuration Example
+No manual subscriptions. Convention over configuration.
 
-Define infrastructure in `infra/services/*.ts` using [`@crossdelta/infrastructure`](https://www.npmjs.com/package/@crossdelta/infrastructure):
+---
 
-```ts
-import { ports } from '@crossdelta/infrastructure'
-import type { K8sServiceConfig } from '@crossdelta/infrastructure'
+## ⚡ NATS Message Broker
 
-export const config: K8sServiceConfig = {
-  name: 'orders',
-  ports: ports().http(4001).build(),
-  replicas: 1,
-  healthCheck: { httpPath: '/health' },
-  resources: {
-    requests: { cpu: '50m', memory: '64Mi' },
-    limits: { cpu: '150m', memory: '128Mi' },
-  },
-  env: {
-    DATABASE_URL: databaseUrl,
-    NATS_URL: natsUrl,
-  },
-}
-```
+Every workspace includes pre-configured NATS with JetStream:
 
-**📖 See the [Infrastructure Package Docs](https://www.npmjs.com/package/@crossdelta/infrastructure) for advanced configuration options.**
+- Auto-started with `pf dev`
+- Ports: `4222` (client), `8222` (monitoring)
+- Health check: `curl http://localhost:8222/healthz`
 
-<br />
+See `services/nats/README.md` for details.
 
 ---
 
-## 🚢 Deployment
-
-### Local Deployment
+##  Deployment
 
 ```bash
-pulumi login
-pulumi up --stack dev
+pulumi login && pulumi up --stack dev
 ```
 
-### CI/CD with GitHub Actions
-
-Every workspace includes pre-configured GitHub Actions workflows in `.github/workflows/`:
+### GitHub Actions (pre-configured)
 
 | Workflow | Trigger | Purpose |
 |----------|---------|---------|
-| **`lint-and-tests.yml`** | Pull Requests to `main` | Runs `bun lint` and `bun test` on PRs |
-| **`build-and-deploy.yml`** | Push to `main` | Builds Docker images, pushes to GHCR, deploys via Pulumi |
-| **`publish-packages.yml`** | Changes in `packages/` | Auto-publishes packages to npm with versioning |
-
-### Required GitHub Secrets
-
-Configure these secrets in your repository settings (`Settings` → `Secrets and variables` → `Actions`):
+| `lint-and-tests.yml` | PR to `main` | Lint + test |
+| `build-and-deploy.yml` | Push to `main` | Build, push to GHCR, deploy |
+| `publish-packages.yml` | Changes in `packages/` | Publish to npm |
 
-| Secret | Description | Required For |
-|--------|-------------|--------------|
-| `PULUMI_ACCESS_TOKEN` | Pulumi Cloud access token | All deployments |
-| `DIGITALOCEAN_TOKEN` | DigitalOcean API token | Infrastructure provisioning |
-| `NPM_TOKEN` | npm registry token | Package publishing (optional) |
-| `GHCR_TOKEN` | GitHub Container Registry PAT | Docker image publishing |
+<details>
+<summary>Required secrets</summary>
 
-**Get tokens:**
-- **Pulumi:** [Create access token](https://app.pulumi.com/account/tokens)
-- **DigitalOcean:** [Generate API token](https://cloud.digitalocean.com/account/api/tokens)
-- **npm:** [Create access token](https://www.npmjs.com/settings/~/tokens)
+| Secret | Description |
+|--------|-------------|
+| `PULUMI_ACCESS_TOKEN` | [Pulumi Cloud token](https://app.pulumi.com/account/tokens) |
+| `DIGITALOCEAN_TOKEN` | [DO API token](https://cloud.digitalocean.com/account/api/tokens) |
+| `GHCR_TOKEN` | GitHub Container Registry PAT |
+| `NPM_TOKEN` | [npm access token](https://www.npmjs.com/settings/~/tokens) (only for `publish-packages.yml`) |
 
-<br />
+</details>
 
 ---
 
 ## 📚 Requirements
 
-- **JavaScript runtime** — Bun (recommended) or Node.js ≥ 21 (npm/yarn/pnpm)
-- **[Pulumi CLI](https://www.pulumi.com/docs/install/)** — for infrastructure deployment
-- **[Docker](https://www.docker.com/)** — required for local NATS. Without Docker, you can still scaffold/build
-
+- **Bun** (recommended) or Node.js ≥ 21
+- **[Pulumi CLI](https://www.pulumi.com/docs/install/)** for deployment
+- **[Docker](https://www.docker.com/)** for local NATS
 
 ---