@crossdelta/platform-sdk 0.5.5 → 0.5.7

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <strong>Your AI-powered platform engineer.</strong><br />
-  Scaffold complete Turborepo workspaces, generate production-ready microservices<br />
+  Scaffold complete <a href="https://turbo.build/repo">Turborepo</a> workspaces, generate microservice boilerplate<br />
   with natural language, and deploy to the cloud — all from one CLI.
 </p>
 
@@ -29,25 +29,54 @@
 <br />
 
 ---
+## 🚀 Quick Start
 
-## 🎯 Why This Exists
+```bash
+# Create workspace
+bunx @crossdelta/platform-sdk new workspace my-platform -y
+cd my-platform
+
+# Generate service with AI (first time: you'll be prompted to configure an AI provider)
+bunx @crossdelta/platform-sdk new hono-micro services/orders --ai \
+  -d "Handle order creation and payment processing"
+
+# Start all services
+bun dev
+```
+
+**In under a minute you have a running, event-driven microservice platform with infra parity between local and production.**
+
+You get: [Turborepo](https://turbo.build/repo) monorepo + [NATS](https://nats.io) + event-driven microservices + [Pulumi](https://www.pulumi.com) infra + auto-generated `.env.local` + **AI-generated services** — all wired automatically.
+
+<details>
+<summary><strong>💡 Prefer shorter commands? Install globally</strong></summary>
+
+```bash
+# Install once globally
+bun add -g @crossdelta/platform-sdk
+
+# Then use short commands
+pf new workspace my-platform
+pf new hono-micro services/orders --ai -d "..."
+```
+
+Works with npm/yarn/pnpm too: `npm install -g @crossdelta/platform-sdk`
 
-Building microservice platforms is hard. You start with great intentions, but complexity creeps in fast:
+</details>
 
-- **Scattered repositories** with inconsistent conventions across services
-- **No unified DX** — every team member invents their own scripts
-- **Infrastructure drift** — Terraform/Pulumi configs live in separate repos
-- **Environment hell** — `.env` files manually maintained, ports collide, services don't talk
-- **Slow onboarding** — new developers spend days setting up the platform
+<br />
 
-**`pf` is an opinionated CLI for platform engineering.** It helps you:
+---
+
+## 🎯 Why This Exists
 
-- Scaffold monorepos with consistent structure and tooling
-- Generate microservices (manually or AI-assisted) with shared conventions
-- Auto-configure infrastructure, environment variables, and port assignments
-- Run all services locally with a single command
+Platform engineering problems `pf` solves:
 
-Built for teams using **Turborepo + Pulumi + NATS + Bun**.
+- **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.
 
 <br />
 
@@ -58,18 +87,24 @@ Built for teams using **Turborepo + Pulumi + NATS + Bun**.
 ### ✅ `pf` is:
 
 - **Opinionated CLI** for event-driven microservice platforms
-- **Turborepo scaffolder** with Pulumi IaC and NATS messaging built-in
+- **[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 (`bun dev`)
-- **DigitalOcean-first** deployment target (App Platform + DOKS)
+- **[DigitalOcean](https://www.digitalocean.com)-first** deployment target (App Platform + DOKS)
 
 ### ❌ `pf` is not:
 
 - **Generic microservice generator** — makes architectural choices for you
-- **Cloud-agnostic** (yet) — DigitalOcean first, AWS/GCP planned
+- **Multi-cloud** (not yet) — DigitalOcean first, extensible provider architecture
 - **Runtime manager** — scaffolds code, you deploy with Pulumi
 - **Kubernetes replacement** — generates K8s configs via Pulumi
 
+### 🔥 Why `pf` vs other tools?
+
+- **🔗 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
+
 <br />
 
 ---
@@ -140,35 +175,20 @@ These principles guide every decision in `pf`:
 - **🌊 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 />
 
 ---
 
-## 🚀 Quick Start
-
-> 💡 **Get started in under 2 minutes**
-
-### 1. Create a new workspace
+## 👥 Who Is This For?
 
-```bash
-# Install globally
-npm install -g @crossdelta/platform-sdk
-pf new workspace my-platform
+`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.
 
-# Or use directly with bunx (no installation required)
-bunx @crossdelta/platform-sdk new workspace my-platform
-```
-
-**Options:**
+---
 
-| Flag | Description |
-|------|-------------|
-| `-y, --yes` | Skip prompts |
-| `-o, --github-owner <owner>` | GitHub org/user for GHCR registry |
-| `-s, --pulumi-stack <name>` | Pulumi stack base name |
-| `--no-github` | Skip GitHub Actions workflows |
+## 📘 Workflows
 
-### 2. Generate microservices
+### Generate microservices
 
 **Manual scaffolding:**
 ```bash
@@ -192,7 +212,9 @@ pf new hono-micro services/payments --ai \
 - ✅ Test files with validation logic
 - ✅ Complete README documentation
 
-### 3. Start local development
+> **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
 
 ```bash
 cd my-platform
@@ -517,7 +539,6 @@ export default handleEvent(
 | `pf new` | Interactive creation wizard |
 | `pf new workspace <name>` | Scaffold a complete platform monorepo |
 | `pf setup --ai` | Configure AI provider (OpenAI or Anthropic) |
-| `pf dev` | Start development mode with auto-reload |
 
 ### Service Commands
 
@@ -601,9 +622,9 @@ Configure these secrets in your repository settings (`Settings` → `Secrets and
 | `GHCR_TOKEN` | GitHub Container Registry PAT | Docker image publishing |
 
 **Get tokens:**
-- **Pulumi:** https://app.pulumi.com/account/tokens
-- **DigitalOcean:** https://cloud.digitalocean.com/account/api/tokens
-- **npm:** https://www.npmjs.com/settings/~/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)
 
 <br />
 
@@ -611,10 +632,10 @@ Configure these secrets in your repository settings (`Settings` → `Secrets and
 
 ## 📚 Requirements
 
-- Node.js ≥ 21
-- Bun (latest)
-- Pulumi CLI
-- Docker (for local NATS)
+- **[Bun](https://bun.sh)** (latest) — recommended for best performance
+- **Node.js** ≥ 21 — supported as fallback (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
 
 
 ---