create-qpq-app 0.1.6 → 0.1.7

package/lib/commonjs/steps/013_printNextSteps.js

@@ -23,7 +23,7 @@ deploys as a single docker image.
 Next steps:
 
   cd ${answers.appName}
-${install}  npm run go:dev     # local dev server on http://localhost:8080
+${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080
   npm run go         # build the docker image (then run the printed docker command)
 
 Deploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).

package/lib/commonjs/steps/013_printNextSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEa,QAAA,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAoB,EAAE,4CAAf,EAAE,OAAO,EAAE;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC,CAAA;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run go:dev     # local dev server on http://localhost:8080\n  npm run go         # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}
+{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEa,QAAA,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAoB,EAAE,4CAAf,EAAE,OAAO,EAAE;QACrB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC,CAAA;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080\n  npm run go         # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}

package/lib/esm/steps/013_printNextSteps.js

@@ -11,7 +11,7 @@ deploys as a single docker image.
 Next steps:
 
   cd ${answers.appName}
-${install}  npm run go:dev     # local dev server on http://localhost:8080
+${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080
   npm run go         # build the docker image (then run the printed docker command)
 
 Deploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).

package/lib/esm/steps/013_printNextSteps.js.map

@@ -1 +1 @@
-{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run go:dev     # local dev server on http://localhost:8080\n  npm run go         # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}
+{"version":3,"file":"013_printNextSteps.js","sourceRoot":"","sources":["../../../src/steps/013_printNextSteps.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,MAAM;IAEZ,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kCAAkC,CAAC;QAEtF,OAAO,CAAC,GAAG,CAAC;UACN,OAAO,CAAC,OAAO;;;;;;;OAOlB,OAAO,CAAC,OAAO;EACpB,OAAO;;;8BAGqB,OAAO,CAAC,OAAO,gCAAgC,OAAO,CAAC,MAAM;CAC1F,CAAC,CAAC;IACD,CAAC;CACF,CAAC","sourcesContent":["import { CreateQpqAppStep } from '../types';\n\nexport const printNextSteps: CreateQpqAppStep = {\n  name: 'Done',\n\n  run: async ({ answers }) => {\n    const install = answers.installDependencies ? '' : '  npm install\\n  npm run build\\n';\n\n    console.log(`\nCreated ${answers.appName}!\n\nYour app has five services — admin, auth, design, shell and todo — and\ndeploys as a single docker image.\n\nNext steps:\n\n  cd ${answers.appName}\n${install}  npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080\n  npm run go         # build the docker image (then run the printed docker command)\n\nDeploy config lives in apps/${answers.appName}/deploy.config.json (domain: ${answers.domain}).\n`);\n  },\n};\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Scaffold a new quidproquo app — npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.6"
+    "quidproquo-tsconfig": "0.1.7"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/README.md

@@ -21,8 +21,7 @@ always runs against the in-repo HEAD. Build the framework first
 nvm use              # ALWAYS FIRST — switches to the Node version in .nvmrc
 npm install          # installs deps + symlinks the sibling quidproquo-* packages (file: refs)
 npm run build        # build every workspace (libs -> tsc -b to dist; services -> type-check)
-npm run go:dev       # backend dev server on :8080 (all services of the selected app)
-npm run go:dev:web   # views dev servers (host + one Rspack server per remote)
+npm run go:dev       # full local dev stack: api dev server (:8080) + all views dev servers
 ```
 
 Smoke test once `go:dev` is up:
@@ -74,7 +73,7 @@ generic CDK app in `quidproquo-deploy-awscdk`.
   `defineDevServerOptions({ port })` in its `infrastructure.ts`). The
   only generated artifact is `apps/<app>/tsconfig.federated.json` — regenerate
   with `npm run prep` after adding or removing a marker.
-- **The dev server** (`qpq go:dev`, powered by `quidproquo-dev-server`) loads each service's
+- **The dev server** (`qpq go:dev:api`, powered by `quidproquo-dev-server`) loads each service's
   `infrastructure.ts` directly — no synth needed, just built libs. Its bundle
   externalizes `node_modules` (an externals function in its rspack config) so native modules like
   `sqlite3` load at runtime from their install location.
@@ -90,7 +89,8 @@ generic CDK app in `quidproquo-deploy-awscdk`.
 npm run build        # build only the libs (services/views are bundled, not built); scope with --workspace=@qpqjs/constants
 npm run validate-ts  # TS check: build libs, then tsc-typecheck every service + views
 npm run prep         # regenerate tsconfig.federated.json from // federated.export markers
-npm run go:dev       # backend dev server on :8080, every service at /api/<svc>
+npm run go:dev       # api + web dev servers in one process (one ctrl+c stops the lot)
+npm run go:dev:api   # backend dev server only, on :8080, every service at /api/<svc>
 npm run go:dev:web   # boot ALL views Rspack dev servers (host shell :3080 + remotes on their
                      # ports); remotes resolve dynamically at runtime via mf-manifest.json.
                      # Subset: npm run go:dev:web -- --only host,shell,design
@@ -99,7 +99,7 @@ npm run go:dev:web   # boot ALL views Rspack dev servers (host shell :3080 + rem
 ### App selection (multi-app)
 
 Every app-facing script (`prep`, `synth`, `go`, `go:docker`, `go:dev`,
-`go:dev:web`) resolves its target app the same way:
+`go:dev:api`, `go:dev:web`) resolves its target app the same way:
 
 1. `--app <name>` — **must come after `--`**: `npm run go:dev -- --app qpqjs`
    (this npm silently swallows flags before `--`)

package/template/apps/qpqjs/services/design/views/src/components/LandingPage/components/Footer.tsx

@@ -18,8 +18,9 @@ export function Footer() {
             <span className="hero__title-glow">your first story?</span>
           </h2>
           <p className="footer__cta-sub">
-            Install the core, yield an action, and let the runtime handle the
-            rest.
+            One command scaffolds a full app — five services, a local dev
+            server, a one-image docker deploy. Yield an action; the runtime
+            handles the rest.
           </p>
           <div className="footer__cta-actions">
             <InstallChip />

package/template/apps/qpqjs/services/design/views/src/components/LandingPage/components/InstallChip.tsx

@@ -1,6 +1,6 @@
 import { useState } from 'react';
 
-const INSTALL_COMMAND = 'npm install quidproquo-core';
+const INSTALL_COMMAND = 'npx create-qpq-app myapp';
 
 export function InstallChip() {
   const [copied, setCopied] = useState(false);

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt-stream.md

@@ -42,7 +42,7 @@ The parameters are identical to [askAiPrompt](./ask-ai-prompt.md) — see there
 | --- | --- | --- |
 | `model` | `AiModel` | Which model to prompt. |
 | `prompt` | `string` | The user prompt. Ignored when `options.messages` is set. |
-| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
+| `options` | `AskAiPromptStreamOptions` | `{ system?, aiName?, messages?, reasoning?, caching? }` — same shape and meaning as [`AskAiPromptOptions`](./ask-ai-prompt.md#askaipromptoptions). |
 
 ## Returns
 

package/template/docusaurus/docs/actions/core/ai/ask-ai-prompt.md

@@ -49,6 +49,7 @@ function* askAiPrompt(
 | `aiName` | `string` | – | Name of a [defineAi](../../../config/core/ai.md) config to bind. This is what wires up tool definitions (and their executors) for the model to call. Omit for a plain, tool-less prompt. |
 | `messages` | [`AiMessage[]`](#aimessage) | – | A full conversation history. When present, this is sent instead of `prompt`, letting you carry a multi-turn dialogue (including prior assistant turns and tool results). |
 | `reasoning` | [`AiReasoningConfig`](#aireasoningconfig) | – | Enables extended thinking. Its presence turns reasoning on; `budgetTokens` caps how many tokens the model may spend thinking before it answers (defaults to `4096` on AWS). |
+| `caching` | `boolean` | – | Marks the system prompt and the last message (or the last `messages` entry) with a Bedrock cache point, so a following call in the same conversation can read everything up to there from cache instead of reprocessing it. |
 
 ### `AiModel`
 

package/template/docusaurus/docs/getting-started.md

@@ -4,803 +4,142 @@ sidebar_position: 1
 
 # Getting Started
 
-Get up and running with Quidproquo in minutes. This guide will walk you through installation, creating your first story, building an API, and deploying your application.
-
-## Prerequisites
-
-Before you begin, ensure you have:
-- Node.js 18+ installed
-- npm or yarn package manager
-- Basic knowledge of JavaScript/TypeScript
-- Familiarity with generator functions (we'll explain the basics)
-
-## Installation
-
-### Create a New Project
+The fastest way to a running quidproquo app is one command:
 
 ```bash
-# Create a new directory
-mkdir my-qpq-app
-cd my-qpq-app
-
-# Initialize package.json
-npm init -y
-
-# Install TypeScript (recommended)
-npm install --save-dev typescript @types/node
+npx create-qpq-app myapp
 ```
 
-### Install Quidproquo Packages
+That scaffolds a complete, working application — five services, a local dev
+server, and a one-image docker deploy — then installs its dependencies,
+builds it, and makes the first git commit for you.
 
 ```bash
-# Core package (required)
-npm install quidproquo-core
-
-# Web server package (for APIs)
-npm install quidproquo-webserver
-
-# Development server (for local development)
-npm install --save-dev quidproquo-dev-server
-
-# Platform-specific processors (choose based on deployment target)
-npm install quidproquo-actionprocessor-node  # For Node.js
-# OR
-npm install quidproquo-actionprocessor-awslambda  # For AWS
-```
-
-### TypeScript Configuration
-
-Create a `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": ["ES2020"],
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true,
-    "declarationMap": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
-```
-
-## Your First Story
-
-Let's create a simple "Hello World" story to understand the basics.
-
-### Understanding Generator Functions
-
-Generator functions (marked with `*`) can pause and resume execution:
-
-```typescript
-// src/stories/hello.ts
-import { askDateNow, askLogCreate } from 'quidproquo-core';
-
-export function* helloWorldStory(name: string) {
-  // Log the start
-  yield* askLogCreate('INFO', `Starting hello for ${name}`);
-  
-  // Get current time
-  const currentTime = yield* askDateNow();
-  
-  // Return greeting
-  return `Hello ${name}! The time is ${currentTime}`;
-}
-```
-
-**Key concepts:**
-- `function*` declares a generator function
-- `yield*` pauses execution and delegates to another generator
-- Each `ask*` function returns a generator that yields an action
-- The runtime processes each action and returns the result
-
-### Creating Actions
-
-Actions describe what you want to do:
-
-```typescript
-// src/stories/user.ts
-import { 
-  askKeyValueStoreGet,
-  askKeyValueStoreUpsert,
-  askGuidNew,
-  askDateNow,
-  askThrowError
-} from 'quidproquo-core';
-
-export function* createUserStory(email: string, name: string) {
-  // Check if user exists
-  const existingUser = yield* askKeyValueStoreGet('users', email);
-  
-  if (existingUser) {
-    // Throw an error if user exists
-    yield* askThrowError('USER_EXISTS', `User with email ${email} already exists`);
-  }
-  
-  // Generate a new ID
-  const userId = yield* askGuidNew();
-  
-  // Get current timestamp
-  const createdAt = yield* askDateNow();
-  
-  // Create user object
-  const user = {
-    id: userId,
-    email,
-    name,
-    createdAt
-  };
-  
-  // Store the user
-  yield* askKeyValueStoreUpsert('users', user);
-  
-  return user;
-}
+cd myapp
+npm run go:dev     # api on http://localhost:8080, web on http://localhost:3080
 ```
 
-## Building Your First API
-
-Now let's create a REST API using Quidproquo.
-
-### Define Routes
+One command, one ctrl+c: `go:dev` runs the backend dev server and every views
+dev server in a single process. Want just one side? `npm run go:dev:api` and
+`npm run go:dev:web` run them separately.
 
-```typescript
-// src/api/index.ts
-import { HTTPMethod, HTTPResponse } from 'quidproquo-webserver';
-import { createUserStory } from '../stories/user';
-import { askCatch } from 'quidproquo-core';
+Check it's alive:
 
-export function* handleCreateUser(request: any): Generator<any, HTTPResponse, any> {
-  const { email, name } = JSON.parse(request.body);
-  
-  // Validate input
-  if (!email || !name) {
-    return {
-      statusCode: 400,
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ error: 'Email and name are required' })
-    };
-  }
-  
-  // Try to create user
-  const result = yield* askCatch(createUserStory(email, name));
-  
-  if (result.success) {
-    return {
-      statusCode: 201,
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(result.result)
-    };
-  } else {
-    return {
-      statusCode: 400,
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ error: result.error.errorText })
-    };
-  }
-}
-```
-
-### Configure the API
-
-```typescript
-// src/config.ts
-import { defineRoute, defineApi, defineService } from 'quidproquo-webserver';
-import { defineKeyValueStore } from 'quidproquo-core';
-import { handleCreateUser } from './api';
-
-export default [
-  // Define a key-value store for users
-  defineKeyValueStore('users', {
-    partitionKey: 'email',
-    indexes: []
-  }),
-  
-  // Define API routes
-  defineApi('main', {
-    routes: [
-      defineRoute(HTTPMethod.POST, '/users', handleCreateUser),
-      defineRoute(HTTPMethod.GET, '/health', function* () {
-        return {
-          statusCode: 200,
-          body: JSON.stringify({ status: 'healthy' })
-        };
-      })
-    ]
-  }),
-  
-  // Define the service
-  defineService('my-app', {
-    apis: ['main']
-  })
-];
+```bash
+curl http://localhost:8080/api/shell/v1/health
+# {"status":"healthy","service":"shell","checkedAt":"..."}
 ```
 
-## Running Locally
-
-The development server simulates cloud services locally.
+## Prerequisites
 
-### Create Dev Server Entry
+- **Node.js 24 or newer** — the scaffolder checks and refuses politely on
+  older versions
+- **Docker** — only needed when you deploy (`npm run go`); local dev doesn't
+  use it
 
-```typescript
-// src/dev.ts
-import { createDevServer } from 'quidproquo-dev-server';
-import config from './config';
+## What you get
 
-const server = createDevServer({
-  config,
-  port: 3000,
-  watch: true
-});
+`create-qpq-app` generates an npm-workspaces monorepo:
 
-server.start().then(() => {
-  console.log('Dev server running on http://localhost:3000');
-});
 ```
-
-### Add Scripts to package.json
-
-```json
-{
-  "scripts": {
-    "dev": "ts-node src/dev.ts",
-    "build": "tsc",
-    "start": "node dist/dev.js"
-  }
-}
+myapp/
+├── package.json              # workspace root — run all commands from here
+└── apps/myapp/
+    ├── deploy.config.json    # environments: development + production (docker)
+    ├── packages/
+    │   ├── constants/        # domain, service enum, user directory name
+    │   ├── config/
+    │   └── service-utils/    # the shared config every service starts from
+    └── services/
+        ├── shell/            # module-federation host — the root website
+        ├── design/           # shared UI — federated views other services import
+        ├── auth/             # authentication service
+        ├── admin/            # the qpq admin console
+        └── todo/             # the example feature: an api service + TodoList view
 ```
 
-### Start the Dev Server
+Every service follows the same layout: a `service/` package holding its
+infrastructure config and controllers, an optional `views/` microfrontend,
+and small lib packages (`models`, `shared-logic`, `service-utils`, …) for
+code you'll share between them.
 
-```bash
-npm run dev
-```
-
-Your API is now running! Test it:
+## Your first story
 
-```bash
-# Create a user
-curl -X POST http://localhost:3000/users \
-  -H "Content-Type: application/json" \
-  -d '{"email": "alice@example.com", "name": "Alice"}'
+Business logic in quidproquo is a **story** — a generator function that
+yields typed actions. The scaffolded shell service ships one: the health
+route you just curled.
 
-# Check health
-curl http://localhost:3000/health
-```
-
-## Complete Example: Todo API
-
-Let's build a more complete example - a Todo API with CRUD operations.
-
-### Define Todo Stories
-
-```typescript
-// src/stories/todo.ts
+```typescript title="apps/myapp/services/shell/service/src/entry/controller/health/health.ts"
 import {
-  askKeyValueStoreGet,
-  askKeyValueStoreUpsert,
-  askKeyValueStoreDelete,
-  askKeyValueStoreQuery,
-  askGuidNew,
   askDateNow,
-  askThrowError
-} from 'quidproquo-core';
-
-interface Todo {
-  id: string;
-  userId: string;
-  title: string;
-  completed: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export function* createTodoStory(userId: string, title: string) {
-  const todoId = yield* askGuidNew();
-  const now = yield* askDateNow();
-  
-  const todo: Todo = {
-    id: todoId,
-    userId,
-    title,
-    completed: false,
-    createdAt: now,
-    updatedAt: now
-  };
-  
-  yield* askKeyValueStoreUpsert('todos', todo);
-  return todo;
-}
-
-export function* getTodoStory(todoId: string, userId: string) {
-  const todo = yield* askKeyValueStoreGet('todos', todoId);
-  
-  if (!todo) {
-    yield* askThrowError('NOT_FOUND', 'Todo not found');
-  }
-  
-  if (todo.userId !== userId) {
-    yield* askThrowError('FORBIDDEN', 'Access denied');
-  }
-  
-  return todo;
-}
-
-export function* updateTodoStory(
-  todoId: string, 
-  userId: string, 
-  updates: Partial<Pick<Todo, 'title' | 'completed'>>
-) {
-  // Get existing todo
-  const todo = yield* getTodoStory(todoId, userId);
-  
-  // Update fields
-  const updatedTodo = {
-    ...todo,
-    ...updates,
-    updatedAt: yield* askDateNow()
-  };
-  
-  yield* askKeyValueStoreUpsert('todos', updatedTodo);
-  return updatedTodo;
-}
-
-export function* deleteTodoStory(todoId: string, userId: string) {
-  // Verify ownership
-  yield* getTodoStory(todoId, userId);
-  
-  // Delete
-  yield* askKeyValueStoreDelete('todos', todoId);
-  return { success: true };
-}
-
-export function* listTodosStory(userId: string) {
-  const todos = yield* askKeyValueStoreQuery('todos', {
-    index: 'byUser',
-    keyCondition: {
-      userId: { '=': userId }
-    }
-  });
-  
-  return todos;
-}
-```
-
-### Create API Handlers
-
-```typescript
-// src/api/todos.ts
-import { HTTPRequest, HTTPResponse } from 'quidproquo-webserver';
-import { askCatch } from 'quidproquo-core';
-import * as todoStories from '../stories/todo';
-
-export function* createTodo(request: HTTPRequest): Generator<any, HTTPResponse, any> {
-  const { title } = JSON.parse(request.body);
-  const userId = request.headers['x-user-id']; // Simplified auth
-  
-  if (!title) {
-    return { statusCode: 400, body: JSON.stringify({ error: 'Title required' }) };
-  }
-  
-  const todo = yield* todoStories.createTodoStory(userId, title);
-  return { statusCode: 201, body: JSON.stringify(todo) };
-}
-
-export function* getTodo(request: HTTPRequest): Generator<any, HTTPResponse, any> {
-  const todoId = request.pathParameters.id;
-  const userId = request.headers['x-user-id'];
-  
-  const result = yield* askCatch(todoStories.getTodoStory(todoId, userId));
-  
-  if (!result.success) {
-    const statusCode = result.error.errorType === 'NOT_FOUND' ? 404 : 403;
-    return { statusCode, body: JSON.stringify({ error: result.error.errorText }) };
-  }
-  
-  return { statusCode: 200, body: JSON.stringify(result.result) };
-}
-
-export function* updateTodo(request: HTTPRequest): Generator<any, HTTPResponse, any> {
-  const todoId = request.pathParameters.id;
-  const userId = request.headers['x-user-id'];
-  const updates = JSON.parse(request.body);
-  
-  const result = yield* askCatch(
-    todoStories.updateTodoStory(todoId, userId, updates)
-  );
-  
-  if (!result.success) {
-    return { statusCode: 400, body: JSON.stringify({ error: result.error.errorText }) };
-  }
-  
-  return { statusCode: 200, body: JSON.stringify(result.result) };
-}
-
-export function* deleteTodo(request: HTTPRequest): Generator<any, HTTPResponse, any> {
-  const todoId = request.pathParameters.id;
-  const userId = request.headers['x-user-id'];
-  
-  const result = yield* askCatch(todoStories.deleteTodoStory(todoId, userId));
-  
-  if (!result.success) {
-    return { statusCode: 400, body: JSON.stringify({ error: result.error.errorText }) };
+  AskResponse,
+  HTTPEvent,
+  HTTPEventResponse,
+  qpqWebServerUtils,
+} from 'quidproquo';
+import { dynamicRoute } from 'quidproquo-features';
+
+export const health = dynamicRoute(
+  ['GET', '/health'],
+  function* healthCheck(event: HTTPEvent): AskResponse<HTTPEventResponse> {
+    const checkedAt = yield* askDateNow();
+
+    return qpqWebServerUtils.toJsonEventResponse({
+      status: 'healthy',
+      service: 'shell',
+      checkedAt,
+    });
   }
-  
-  return { statusCode: 204, body: '' };
-}
-
-export function* listTodos(request: HTTPRequest): Generator<any, HTTPResponse, any> {
-  const userId = request.headers['x-user-id'];
-  const todos = yield* todoStories.listTodosStory(userId);
-  return { statusCode: 200, body: JSON.stringify(todos) };
-}
+);
 ```
 
-### Configure Complete API
-
-```typescript
-// src/config/todos.ts
-import { defineRoute, defineApi, HTTPMethod } from 'quidproquo-webserver';
-import { defineKeyValueStore } from 'quidproquo-core';
-import * as todoHandlers from '../api/todos';
-
-export default [
-  // Define storage
-  defineKeyValueStore('todos', {
-    partitionKey: 'id',
-    indexes: [
-      {
-        name: 'byUser',
-        partitionKey: 'userId',
-        sortKey: 'createdAt'
-      }
-    ]
-  }),
-  
-  // Define API
-  defineApi('todos', {
-    routes: [
-      defineRoute(HTTPMethod.POST, '/todos', todoHandlers.createTodo),
-      defineRoute(HTTPMethod.GET, '/todos', todoHandlers.listTodos),
-      defineRoute(HTTPMethod.GET, '/todos/:id', todoHandlers.getTodo),
-      defineRoute(HTTPMethod.PUT, '/todos/:id', todoHandlers.updateTodo),
-      defineRoute(HTTPMethod.DELETE, '/todos/:id', todoHandlers.deleteTodo),
-    ]
-  })
-];
-```
+The story never reads the clock itself — it *asks* for the time by yielding
+an action, and the runtime answers. On your machine that's the dev server;
+in production it's whatever platform the app is deployed to. Same story,
+zero changes.
 
-## Deployment Options
+Add your own route by dropping a file next to `health.ts`, exporting it from
+the controller `index.ts`, and saving — the dev server rebuilds and restarts
+itself.
 
-Quidproquo supports multiple deployment targets. Here's how to deploy to common platforms.
+## Deploy it
 
-### Deploy to AWS Lambda
+Both scaffolded environments deploy as a single docker image — the whole
+app, one container:
 
 ```bash
-# Install AWS CDK and QPQ deploy package
-npm install --save-dev aws-cdk quidproquo-deploy-awscdk
-npm install quidproquo-actionprocessor-awslambda
-
-# Create CDK app
-mkdir cdk
-cd cdk
-cdk init app --language typescript
-```
-
-Create CDK stack:
-
-```typescript
-// cdk/lib/my-app-stack.ts
-import * as cdk from 'aws-cdk-lib';
-import { QPQApp } from 'quidproquo-deploy-awscdk';
-import config from '../../src/config';
-
-export class MyAppStack extends cdk.Stack {
-  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
-    super(scope, id, props);
-    
-    new QPQApp(this, 'MyQPQApp', {
-      qpqConfig: config,
-      environment: 'production'
-    });
-  }
-}
+npm run go
 ```
 
-Deploy:
+Pick an environment when prompted (or pass `--env development`), and the
+build prints the `docker run` command when the image is ready:
 
 ```bash
-cdk deploy
+docker run --rm -p 80:8080 -p 8080:8080 -p 8888:8888 -p 3001:3001 \
+  -v qpq-myapp-data:/app/.qpq-runtime \
+  qpq-myapp:development
 ```
 
-### Deploy to Node.js Server
-
-```typescript
-// src/server.ts
-import express from 'express';
-import { createNodeRuntime } from 'quidproquo-actionprocessor-node';
-import config from './config';
-
-const app = express();
-const runtime = createNodeRuntime(config);
-
-app.use(express.json());
-app.all('*', async (req, res) => {
-  const result = await runtime.handleHTTPRequest({
-    method: req.method,
-    path: req.path,
-    headers: req.headers,
-    body: JSON.stringify(req.body),
-    query: req.query
-  });
-  
-  res.status(result.statusCode).json(JSON.parse(result.body));
-});
-
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
-```
-
-### Deploy to Docker
-
-Create a Dockerfile:
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --production
-
-COPY dist ./dist
-COPY config ./config
+Then open [http://localhost](http://localhost). Environments live in
+`apps/myapp/deploy.config.json` — an app can move platforms (docker → AWS)
+with a config change, not a rewrite.
 
-CMD ["node", "dist/server.js"]
-```
-
-Build and run:
+## Options
 
 ```bash
-npm run build
-docker build -t my-qpq-app .
-docker run -p 3000:3000 my-qpq-app
-```
-
-## Testing Your Application
-
-Quidproquo's architecture makes testing straightforward.
-
-### Unit Testing Stories
-
-```typescript
-// src/stories/todo.test.ts
-import { createTodoStory } from './todo';
-
-test('creates todo with correct fields', () => {
-  const story = createTodoStory('user-123', 'Buy milk');
-  
-  // First yield: Generate ID
-  const { value: guidAction } = story.next();
-  expect(guidAction.type).toBe('Guid::New');
-  
-  // Provide mock ID
-  const { value: dateAction } = story.next('todo-456');
-  expect(dateAction.type).toBe('Date::Now');
-  
-  // Provide mock date
-  const { value: storeAction } = story.next('2024-01-01T00:00:00Z');
-  expect(storeAction.type).toBe('KeyValueStore::Upsert');
-  expect(storeAction.payload.item).toEqual({
-    id: 'todo-456',
-    userId: 'user-123',
-    title: 'Buy milk',
-    completed: false,
-    createdAt: '2024-01-01T00:00:00Z',
-    updatedAt: '2024-01-01T00:00:00Z'
-  });
-  
-  // Complete story
-  const { value: result } = story.next();
-  expect(result.id).toBe('todo-456');
-});
-```
-
-### Integration Testing
-
-```typescript
-// src/api/todos.test.ts
-import { createTestRuntime } from 'quidproquo-testing';
-import { createTodo } from './todos';
-
-test('creates todo via API', async () => {
-  const runtime = createTestRuntime({
-    stores: {
-      todos: new Map()
-    }
-  });
-  
-  const request = {
-    body: JSON.stringify({ title: 'Test todo' }),
-    headers: { 'x-user-id': 'user-123' }
-  };
-  
-  const response = await runtime.execute(createTodo, request);
-  
-  expect(response.statusCode).toBe(201);
-  const todo = JSON.parse(response.body);
-  expect(todo.title).toBe('Test todo');
-  expect(todo.userId).toBe('user-123');
-});
-```
+npx create-qpq-app <app-name> [options]
 
-## Debugging
-
-Quidproquo provides excellent debugging capabilities.
-
-### Enable Debug Logging
-
-```typescript
-// Set environment variable
-process.env.QPQ_LOG_LEVEL = 'DEBUG';
-
-// Or in config
-import { defineLogging } from 'quidproquo-core';
-
-export default [
-  defineLogging({
-    level: 'DEBUG',
-    pretty: true
-  }),
-  // ... other config
-];
+--language <typescript|javascript>   skip the language prompt
+--domain <domain>                    app domain (default: <app-name>.example.com)
+--no-git                             skip git init
+--no-install                         skip npm install (and the initial build)
 ```
 
-### View Execution Logs
-
-```typescript
-// src/debug.ts
-import { createDevServer } from 'quidproquo-dev-server';
-
-const server = createDevServer({
-  config,
-  port: 3000,
-  debug: {
-    logActions: true,        // Log all actions
-    logResults: true,        // Log action results
-    logDuration: true,       // Log execution time
-    slowThreshold: 100,      // Warn if action takes > 100ms
-  }
-});
-```
-
-### Replay Executions
-
-```typescript
-// Capture execution
-const execution = await runtime.execute(myStory, args, {
-  capture: true
-});
-
-// Save for debugging
-fs.writeFileSync('execution.json', JSON.stringify(execution));
-
-// Replay later
-const executionLog = JSON.parse(fs.readFileSync('execution.json'));
-const result = await qpqExecuteLog(executionLog, myStory);
-```
-
-## Best Practices
-
-### 1. Keep Stories Pure
-
-```typescript
-// Good: Pure story with no side effects
-function* calculatePrice(items: Item[]) {
-  const subtotal = items.reduce((sum, item) => sum + item.price, 0);
-  const tax = subtotal * 0.1;
-  return subtotal + tax;
-}
-
-// Bad: Side effects in story
-function* calculatePrice(items: Item[]) {
-  console.log('Calculating...');  // Side effect!
-  const subtotal = items.reduce((sum, item) => sum + item.price, 0);
-  fs.writeFileSync('log.txt', `Subtotal: ${subtotal}`);  // Side effect!
-  return subtotal * 1.1;
-}
-```
-
-### 2. Use Composition
-
-```typescript
-// Compose smaller stories
-function* validateEmail(email: string) {
-  if (!email.includes('@')) {
-    yield* askThrowError('INVALID_EMAIL', 'Invalid email format');
-  }
-}
-
-function* createUser(email: string, name: string) {
-  yield* validateEmail(email);  // Reuse validation
-  // ... rest of creation logic
-}
-```
-
-### 3. Handle Errors Gracefully
-
-```typescript
-function* safeOperation() {
-  const result = yield* askCatch(riskyOperation());
-  
-  if (!result.success) {
-    // Log error
-    yield* askLogCreate('ERROR', result.error.errorText);
-    // Return default
-    return defaultValue;
-  }
-  
-  return result.result;
-}
-```
-
-### 4. Use TypeScript
-
-```typescript
-// Define types for your domain
-interface User {
-  id: string;
-  email: string;
-  name: string;
-}
-
-// Type your stories
-function* getUser(userId: string): Generator<any, User, any> {
-  const user = yield* askKeyValueStoreGet<User>('users', userId);
-  if (!user) {
-    yield* askThrowError('NOT_FOUND', 'User not found');
-  }
-  return user;
-}
-```
-
-## Next Steps
-
-Now that you have the basics, explore:
-
-- [Core Concepts](./core-concepts.md) - Deep dive into the architecture
-- [API Reference](./api/index.md) - Complete action reference
-- [Use Cases](./use-cases.md) - Real-world examples
-- [Architecture Overview](./architecture-overview.md) - Understanding the internals
-
-## Getting Help
-
-- **Documentation**: This site contains comprehensive documentation
-- **GitHub Issues**: Report bugs or request features
-- **Examples**: Check the examples directory in the repository
-- **Community**: Join our Discord server (coming soon)
-
-## Summary
-
-You've learned how to:
-- ✅ Install Quidproquo
-- ✅ Create your first story
-- ✅ Build a REST API
-- ✅ Run locally with the dev server
-- ✅ Deploy to various platforms
-- ✅ Test your application
-- ✅ Debug issues
+Prefer plain JavaScript? `--language javascript` generates the same app with
+type annotations stripped and JSX preserved — it runs on the same toolchain.
 
-Quidproquo provides a powerful, flexible foundation for building modern web applications. Its unique architecture enables you to write business logic once and deploy anywhere, with complete observability and testing capabilities built in.
+## Next steps
 
-Start building with Quidproquo today and experience the benefits of true platform independence!
+- [Core Concepts](./core-concepts.md) — stories, actions and processors in depth
+- [Architecture Overview](./architecture-overview.md) — how the runtime executes a story
+- [API Reference](./api/index.md) — the full action catalogue

package/template/docusaurus/docs/index.md

@@ -179,7 +179,12 @@ Dive deep into the architecture that powers Quidproquo's platform independence a
 
 ## Next Steps
 
-Ready to get started with Quidproquo?
+Ready to get started with Quidproquo? One command scaffolds a complete,
+running app:
+
+```bash
+npx create-qpq-app myapp
+```
 
 <div className="row">
   <div className="col col--6">
@@ -188,7 +193,7 @@ Ready to get started with Quidproquo?
         <h3>🚀 Quick Start</h3>
       </div>
       <div className="card__body">
-        <p>Get up and running in 5 minutes with our quick start guide.</p>
+        <p>Scaffold a five-service app that runs locally and deploys as a single docker image.</p>
       </div>
       <div className="card__footer">
         <a href="/getting-started" className="button button--primary button--block">Get Started</a>

package/template/package.json

@@ -25,8 +25,9 @@
     "lint:fix": "eslint . --fix",
     "synth": "qpq synth",
     "go:dev": "qpq go:dev",
-    "prep": "qpq prep",
+    "go:dev:api": "qpq go:dev:api",
     "go:dev:web": "qpq go:dev:web",
+    "prep": "qpq prep",
     "postinstall": "qpq hooks postinstall || true",
     "go": "qpq go",
     "publish": "qpq publish",