chore(dev): bootstrap script wires docker + drizzle push + turbo dev

README.md

@@ -2,45 +2,96 @@
 
 > Describe your tool. We host the server. AI uses it.
 
-Prompt-to-production MCP servers with OAuth 2.1 and Streamable HTTP.
+Prompt-to-production MCP servers with OAuth 2.1 and Streamable HTTP. Production-grade
+infrastructure for hosting Model Context Protocol servers your AI clients (Claude
+Desktop, Cursor, ChatGPT) can install with a copy-paste snippet.
 
-## Run locally
+## Quick start
 
 ```bash
-# 1. Install deps
+# 1. Install
 pnpm install
 
-# 2. Copy env and fill ANTHROPIC_API_KEY if you want real generation
+# 2. Copy env. Defaults work for local dev. Set ANTHROPIC_API_KEY if you want real generation.
 cp .env.example .env
 
-# 3. Boot everything (postgres, redis, web, api, generator)
+# 3. Boot everything
 pnpm dev
 ```
 
+`pnpm dev` will:
+1. Load `.env`.
+2. `docker compose up -d --wait` postgres + redis.
+3. Push the Drizzle schema (`drizzle-kit push --force`).
+4. Start the full stack in parallel: web (Next.js, :3000), api (Fastify, :4000),
+   generator (BullMQ worker).
+
 Then open:
 
 - Dashboard: <http://localhost:3000>
-- API: <http://localhost:4000>
+- API: <http://localhost:4000/health>
 
-Sign in with the magic link printed to the API stdout, click **New Server**, paste a
-prompt, watch the build stream live over WebSocket.
+Click **Start building**, enter your email, copy the magic-link URL printed to the
+**api** terminal output, paste it in your browser. You land on `/dashboard`. Click
+**New server**, paste a prompt, and watch the build stream live over WebSocket.
+
+If `ANTHROPIC_API_KEY` is unset, the generator returns a deterministic mock spec
+(an `echo` and a `now` tool) so the full end-to-end flow stays demoable.
+
+If Docker is unavailable, the build will fail at the deploy step with a clear error.
+Otherwise: a fresh container is launched on a host port from
+`RUNNER_PORT_RANGE_START…RUNNER_PORT_RANGE_END`, the server is marked `live`, and the
+dashboard renders install snippets for Claude Desktop, Cursor and ChatGPT.
 
 ## Architecture
 
-See `BuildMyMCPServer_MASTER_PROMPT.md` for the full spec and `CHOICES.md` for the
-decisions made during Sprints 1–3.
-
-## Workspace layout
+See `BuildMyMCPServer_MASTER_PROMPT.md` for the full specification and `CHOICES.md`
+for decisions made during this Sprints 1–3 build.
 
 ```
 apps/
-  web/              Next.js 15 dashboard + marketing
-  api/              Fastify control plane
-  generator/        BullMQ worker — Claude → build → deploy
-  runner-template/  Hosted MCP server template
+  web/              Next.js 15 dashboard + marketing landing
+  api/              Fastify control plane (auth, server CRUD, OAuth 2.1 AS, JWKS, WS stream)
+  generator/        BullMQ worker — Claude → spec → render → docker build → local deploy
+  runner-template/  Hosted MCP server template (Streamable HTTP + OAuth 2.1 RS)
 packages/
   db/               Drizzle schema + client
-  auth/             Better-Auth wrapper
-  types/            Shared Zod types
-  ui/               Shared React primitives
+  auth/             Magic-link + session
+  types/            Shared Zod contracts
 ```
+
+## Scripts
+
+| Command            | Effect                                                        |
+| ------------------ | ------------------------------------------------------------- |
+| `pnpm dev`         | Bootstrap + parallel dev for web, api, generator              |
+| `pnpm dev:no-docker` | Skip docker-compose (assumes postgres + redis already up)   |
+| `pnpm build`       | Turbo build all apps                                          |
+| `pnpm typecheck`   | Turbo typecheck all apps                                      |
+| `pnpm lint`        | Biome check                                                   |
+| `pnpm lint:fix`    | Biome check --write                                           |
+| `pnpm db:push`     | Push schema to postgres (drizzle-kit)                         |
+| `pnpm db:generate` | Generate SQL migration files                                  |
+| `pnpm db:migrate`  | Apply pending migrations                                      |
+| `pnpm stop`        | docker compose down                                           |
+
+## Acceptance check
+
+After `pnpm dev` is up:
+
+- [x] `http://localhost:3000` renders the landing page.
+- [x] `http://localhost:4000/health` returns `{ "ok": true }`.
+- [x] Sign in via magic link (URL printed in the api terminal).
+- [x] New Server → paste prompt → live WebSocket stream `queued → generating → building → deploying → live`.
+- [x] If Docker is running, a container is launched and `http://localhost:<port>/mcp`
+      responds **401 + WWW-Authenticate** without a token, **200** with a valid token
+      issued by `/oauth/token`.
+- [x] Install snippets render with copy buttons for Claude Desktop, Cursor, ChatGPT.
+
+## Repo conventions
+
+- TypeScript strict, zero `any` (Biome lints `noExplicitAny` as error).
+- ESM-only, Node 20 LTS.
+- Conventional commits.
+- Tailwind v4 (`@import 'tailwindcss'`).
+- Geist + Geist Mono.