@geekmidas/cli 10.0.0-alpha.1 → 10.0.0-alpha.100

package/README.md

@@ -7,7 +7,7 @@ A powerful CLI tool for building and managing TypeScript-based backend APIs with
 - **Project Scaffolding**: Interactive `init` command to bootstrap new projects with templates
 - **Multi-Provider Support**: Generate handlers for AWS Lambda (API Gateway v1/v2) and server applications
 - **Development Server**: Hot-reload development server with file watching
-- **Telescope Integration**: Laravel-style debugging dashboard for inspecting requests, logs, and exceptions
+- **Telescope Integration**: Laravel-style recording of requests, logs and exceptions, served as JSON
 - **OpenAPI Generation**: Auto-generate OpenAPI 3.0 specifications from your endpoints
 - **Docker Support**: Generate optimized Dockerfiles with multi-stage builds, turbo prune for monorepos
 - **Secrets Management**: Secure credential generation, encryption, and stage-based secrets storage
@@ -54,6 +54,7 @@ Create a `gkm.config.ts` file in your project root:
 import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   // Glob pattern to find endpoint files
   routes: 'src/routes/**/*.ts',
 
@@ -72,7 +73,7 @@ export default defineConfig({
   // Logger configuration
   logger: './src/logger.ts#logger',
 
-  // Optional: Telescope debugging dashboard (enabled by default in dev)
+  // Optional: Telescope request recording (enabled by default in dev)
   telescope: {
     enabled: true,
     path: '/__telescope',
@@ -142,36 +143,32 @@ export const createUser = api
 
 ### 5. Create Subscribers (Optional)
 
-Create event subscribers in `src/subscribers/`:
+Declare the topic once, and a worker to run what has no port; a subscriber is
+built from the worker and binds to the topic:
 
 ```typescript
+// src/constructs/topics.ts
+import { Topic } from '@geekmidas/constructs/topic';
+import { z } from 'zod';
+
+export const users = new Topic('Users', {
+  events: {
+    'user.created': z.object({ userId: z.string(), email: z.email() }),
+    'user.updated': z.object({ userId: z.string() }),
+  },
+});
+
+// src/constructs/worker.ts
+import { Worker } from '@geekmidas/constructs/worker';
+
+export const worker = new Worker('Jobs', { logger });
+
 // src/subscribers/userSubscriber.ts
-import { SubscriberBuilder } from '@geekmidas/constructs/subscribers';
-import type { Service } from '@geekmidas/services';
-import type { EventPublisher, PublishableMessage } from '@geekmidas/events';
-import type { EnvironmentParser } from '@geekmidas/envkit';
-
-// Define event types
-type UserEvents =
-  | PublishableMessage<'user.created', { userId: string; email: string }>
-  | PublishableMessage<'user.updated', { userId: string }>;
-
-// Create event publisher service
-const userEventPublisher = {
-  serviceName: 'userEventPublisher' as const,
-  async register(envParser: EnvironmentParser<{}>) {
-    const config = envParser.create((get) => ({
-      publisherUrl: get('EVENT_PUBLISHER_URL').string()
-    })).parse();
-
-    const { Publisher } = await import('@geekmidas/events');
-    return Publisher.fromConnectionString<UserEvents>(config.publisherUrl);
-  }
-} satisfies Service<'userEventPublisher', EventPublisher<UserEvents>>;
+import { users } from '../constructs/topics';
+import { worker } from '../constructs/worker';
 
-// Create subscriber
-export const userCreatedSubscriber = new SubscriberBuilder()
-  .publisher(userEventPublisher)
+export const userCreatedSubscriber = worker
+  .topic(users)
   .subscribe(['user.created'])
   .handle(async ({ events, logger }) => {
     for (const event of events) {
@@ -181,11 +178,16 @@ export const userCreatedSubscriber = new SubscriberBuilder()
   });
 ```
 
+An endpoint publishes to the topic with `.event(users, { type: 'user.created',
+payload: (user) => ({ userId: user.id, email: user.email }) })`. Declaring the
+topic is what puts a broker in the local plan and resolves
+`USERS_PUBLISHER_CONNECTION_STRING` for whatever publishes to it.
+
 ### 6. Build Handlers
 
 ```bash
-# Generate AWS Lambda handlers
-npx gkm build --provider aws-apigatewayv1
+# Build for where gkm.config.ts deploys (AWS for `deploy: { default: 'sst' }`)
+npx gkm build
 
 # Generate server application
 npx gkm build --provider server
@@ -224,7 +226,7 @@ When run without `--yes`, the command will ask:
    - `api` - Full API with auth, database, services
    - `serverless` - AWS Lambda handlers
    - `worker` - Background job processing
-3. **Telescope** - Include debugging dashboard (default: yes)
+3. **Telescope** - Include request, exception and log recording (default: yes)
 4. **Database** - Include Kysely database support (default: yes)
 5. **Logger** - Choose logger implementation:
    - `pino` - Fast JSON logger for production (recommended)
@@ -309,17 +311,20 @@ Generate handlers from your endpoints.
 gkm build [options]
 ```
 
+By default it builds for where the project deploys: `deploy: { default: 'sst' }`
+builds for AWS, one Lambda per construct; `dokploy` (the default when nothing
+is declared) builds a server.
+
 **Options:**
-- `--provider <provider>`: Target provider (default: `aws-apigatewayv1`)
-  - `aws-apigatewayv1`: AWS API Gateway v1 Lambda handlers
-  - `aws-apigatewayv2`: AWS API Gateway v2 Lambda handlers
+- `--provider <provider>`: Override the deploy target
+  - `aws`: One Lambda handler per construct (API Gateway v2 for endpoints)
   - `server`: Server application with Hono
 - `--production`: Generate production-optimized bundle (server provider only)
 
 **Example:**
 ```bash
-# Generate AWS Lambda handlers
-gkm build --provider aws-apigatewayv1
+# Build for where gkm.config.ts deploys
+gkm build
 
 # Generate server application
 gkm build --provider server
@@ -333,7 +338,7 @@ gkm build --provider server --production
 When using `--production` with the server provider, the CLI generates an optimized bundle at `.gkm/server/dist/server.mjs`. This bundle:
 - Is minified and tree-shaken for smaller size
 - Includes all dependencies (single-file deployment)
-- Can be used with `gkm docker --slim` for minimal Docker images
+- Is what `gkm docker`'s images run — built inside the image, never copied in from the host
 
 ### `gkm openapi`
 
@@ -433,54 +438,44 @@ gkm docker [options]
 ```
 
 **Options:**
-- `--build`: Build Docker image after generating files
-- `--push`: Push image to registry after building
+- `--build`: Build each app's image after generating files
+- `--push`: Push the images to the registry after building
 - `--tag <tag>`: Image tag (default: `latest`)
 - `--registry <url>`: Container registry URL
-- `--slim`: Use slim Dockerfile (requires pre-built bundle from `gkm build --production`)
-- `--turbo`: Enable turbo prune for monorepo optimization
-- `--turbo-package <name>`: Package name for turbo prune (defaults to package.json name)
 
 **Generated Files:**
-- `.gkm/docker/Dockerfile` - Multi-stage or slim Dockerfile
-- `.gkm/docker/docker-compose.yml` - Docker Compose configuration
-- `.gkm/docker/docker-entrypoint.sh` - Entrypoint script
-- `.dockerignore` - Docker ignore file (project root)
+- `.gkm/docker/Dockerfile.<app>` - one per app (`Dockerfile` for an app at the root)
+- `docker-compose.constructs.yml` - the containers the constructs imply, and the apps (project root)
+- `.dockerignore` - at the build root, created or completed
 
-**Dockerfile Types:**
+**How an image is built:**
 
-| Type | Flag | Description |
-|------|------|-------------|
-| Multi-stage | (default) | Builds from source inside Docker, most reproducible |
-| Turbo | `--turbo` | Optimized for monorepos with turbo prune |
-| Slim | `--slim` | Uses pre-built bundle, requires prior `gkm build --production` |
+Every image is built inside Docker — `docker build` on a clean checkout is all
+it takes. The context is the build root (the directory holding the lockfile or
+`pnpm-workspace.yaml`, at or above the workspace); `turbo prune` cuts the app's
+slice of it; the image installs it, builds the workspace packages the app
+depends on, and builds the app (`gkm build --provider server --production` for
+a backend, the framework's build for a site). The runner holds `server.mjs`, a
+Next.js standalone server, or a Vite site's files served by Caddy.
 
 **Example:**
 ```bash
-# Generate multi-stage Dockerfile (default, recommended)
+# Generate the Dockerfiles
 gkm docker
 
-# Generate and build image
+# Generate and build the images
 gkm docker --build --tag v1.0.0
 
 # Build and push to registry
 gkm docker --build --push --registry ghcr.io/myorg --tag v1.0.0
-
-# Use turbo prune for monorepo
-gkm docker --turbo --turbo-package my-api
-
-# Use slim Dockerfile (after running gkm build --production)
-gkm build --provider server --production
-gkm docker --slim
 ```
 
 **Package Manager Support:**
 
-The CLI auto-detects your package manager from lockfiles and generates optimized Dockerfiles:
-- **pnpm**: Uses `pnpm fetch` for better layer caching
-- **npm**: Uses `npm ci` with cache mounts
-- **yarn**: Uses `yarn install --frozen-lockfile`
-- **bun**: Uses `bun install --frozen-lockfile`
+The package manager is detected from the lockfile and pinned to the build
+root's `packageManager` field; turbo is pinned to the version the build root
+resolves. Dependencies install with a BuildKit cache mount for the package
+manager's store.
 
 **Configuration:**
 
@@ -490,6 +485,7 @@ Configure Docker settings in `gkm.config.ts`:
 import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   routes: 'src/routes/**/*.ts',
   envParser: './src/env.ts',
   logger: './src/logger.ts',
@@ -503,38 +499,20 @@ export default defineConfig({
     baseImage: 'node:22-alpine',
     // Port to expose (default: 3000)
     port: 3000,
-    // Docker Compose services
-    compose: {
-      services: {
-        postgres: { image: 'postgis/postgis:16-3.4-alpine' },  // Custom image
-        redis: true,                                            // Default version
-        rabbitmq: { version: '3.12-management-alpine' },        // Custom version
-      },
-    },
   },
 });
 ```
 
-**Docker Compose Services:**
+**Compose:** there is no `compose` option. `gkm docker` writes
+`docker-compose.constructs.yml` at the project root from the declared
+constructs; an image pin or an extra service goes in your own
+`docker-compose.yml`, which is merged over it:
 
-Services can be configured with custom versions, custom images, or use defaults:
-
-```typescript
-// Object format (recommended)
-services: {
-  postgres: { version: '15-alpine' },              // Custom version
-  redis: true,                                      // Default: redis:7-alpine
-  rabbitmq: { version: '3.12-management-alpine' },
-}
-
-// Custom images (e.g., PostGIS, Redis Stack)
-services: {
-  postgres: { image: 'postgis/postgis:16-3.4-alpine' },  // Full image reference
-  redis: { image: 'redis/redis-stack:latest' },
-}
-
-// Legacy array format - uses default versions
-services: ['postgres', 'redis', 'rabbitmq']
+```yaml
+# docker-compose.yml
+services:
+  postgres:
+    image: postgis/postgis:16-3.4-alpine
 ```
 
 **Service Configuration Options:**
@@ -557,7 +535,7 @@ services: ['postgres', 'redis', 'rabbitmq']
 
 ### `gkm dev`
 
-Start a development server with hot-reload and optional Telescope debugging dashboard.
+Start a development server with hot-reload and optional Telescope recording.
 
 ```bash
 gkm dev [options]
@@ -569,7 +547,8 @@ gkm dev [options]
 **Features:**
 - Hot-reload on file changes (endpoints, functions, crons, subscribers)
 - Automatic port switching if requested port is in use
-- Telescope debugging dashboard (enabled by default)
+- Telescope JSON API at `/__telescope/api` (enabled by default)
+- The declared database, read-only, as JSON at `/__gkm/db`
 - Real-time WebSocket updates in Telescope
 
 **Example:**
@@ -682,8 +661,8 @@ gkm secrets:init --stage production --force
 ```
 
 **Generated:**
-- Secure passwords for postgres, redis, rabbitmq (based on `docker.compose.services` config)
-- Connection URLs (`DATABASE_URL`, `REDIS_URL`, `RABBITMQ_URL`)
+- Custom secrets for the stage; the containers' credentials are provisioned by
+  reconcile from the declared constructs, not stored here
 - Stored in `.gkm/secrets/<stage>.json` (gitignored)
 
 ### `gkm secrets:set`
@@ -797,7 +776,7 @@ Store credentials locally to avoid setting environment variables for every comma
 
 ### `gkm login`
 
-Authenticate with a deployment service. Credentials are stored in `~/.gkm/credentials.json`.
+Authenticate with a deployment service. Credentials are stored in `~/.gkm/credentials.json` (`$GKM_HOME/credentials.json` when `GKM_HOME` is set).
 
 ```bash
 gkm login [options]
@@ -825,7 +804,7 @@ gkm login --endpoint https://dokploy.example.com
 # These commands no longer need DOKPLOY_API_TOKEN
 gkm deploy:list
 gkm deploy:init --project my-project --app api
-gkm deploy --provider dokploy --stage production
+gkm deploy --stage production
 ```
 
 ### `gkm logout`
@@ -871,91 +850,99 @@ gkm whoami
 
 ### `gkm deploy`
 
-Deploy application to a provider. Builds for production, injects encrypted secrets, and deploys.
+Deploy a stage through its **target**: `deploy.default` in `gkm.config.ts`
+(`dokploy` when unset), or `--target` for one run. `dokploy`, `compose` and
+`sst` ship with the CLI; any other target is a package the project installs and
+names in `deploy.targets`.
 
 ```bash
-gkm deploy --provider <provider> --stage <stage> [options]
+gkm deploy --stage <stage> [options]
 ```
 
 **Options:**
-- `--provider <provider>`: Deploy provider (`docker`, `dokploy`, `aws-lambda`)
-- `--stage <stage>`: Deployment stage
-- `--tag <tag>`: Image tag (default: `stage-timestamp`)
-- `--skip-push`: Skip pushing image to registry
-- `--skip-build`: Skip build step (use existing build)
+- `--stage <stage>`: Deployment stage (required): one of `stages.deployed`, or the local stage through `compose`
+- `--target <name>`: `dokploy`, `compose`, `sst`, or a name in `deploy.targets` (default: `deploy.default`)
+- `--tag <tag>`: Image tag (default: `<stage>-<timestamp>`; compose: the commit). Through compose, a given tag is pulled
+- `--json`: Write the deploy's events as JSON lines on stdout instead of progress; never prompts
+- `--dry-run`: Show what would be created or reused, and change, build and push nothing
+- `--atomic`: If the release fails, roll back every app it released, not only the ones that failed
+- `--provider <provider>`: Deprecated. `dokploy` means `--target dokploy`; `docker` and `aws-lambda` fail with `ProviderRemoved`
+- `--skip-push`, `--skip-build`: Deprecated and ignored
 
 **Examples:**
 ```bash
-# Docker: build and push image
-gkm deploy --provider docker --stage production
+# deploy.default (dokploy unless configured otherwise)
+DOKPLOY_API_TOKEN=xxx gkm deploy --stage production
 
-# Dokploy: build, push, and trigger deployment
-DOKPLOY_API_TOKEN=xxx gkm deploy --provider dokploy --stage production
+# Plan only
+gkm deploy --stage production --dry-run
 
-# Custom tag
-gkm deploy --provider docker --stage production --tag v1.0.0
-```
+# One Docker Compose stack behind Caddy, on this machine, from images CI pushed
+gkm deploy --target compose --stage production --tag v1.4.0
 
-**Workflow:**
-1. **Sniffs environment variables** - Automatically detects which env vars each app needs
-2. Builds production bundle with `gkm build --provider server --production --stage <stage>`
-3. Encrypts secrets from `.gkm/secrets/<stage>.json` into the bundle
-4. Generates Docker files with `gkm docker`
-5. Builds and pushes Docker image
-6. (Dokploy) Triggers deployment via API with `GKM_MASTER_KEY`
+# AWS, with deploy: { default: 'sst' }: gkm build --provider aws, then sst deploy
+AWS_PROFILE=acme-prod gkm deploy --stage production
 
-**Environment Variable Detection:**
-
-The deploy command automatically detects required environment variables for each app using different strategies based on app configuration:
+# Events for another program
+gkm deploy --stage production --json | jq -c 'select(.type == "app.deployed")'
+```
 
-| App Type | Detection Strategy |
-|----------|-------------------|
-| Frontend apps | Returns empty (no server secrets) |
-| Apps with `requiredEnv` | Uses explicit list from config |
-| Entry-based apps | Imports entry file in subprocess to capture `config.parse()` calls |
-| Route-based apps | Loads routes and calls `getEnvironment()` on each construct |
-| Apps with `envParser` only | Runs SnifferEnvironmentParser to detect usage |
+**What every deploy does:** loads the config and discovers the constructs in a
+sandbox, takes the stage's lock (a second run gets `StateLocked`; a crashed
+run's lock is released with `gkm state:unlock`), checks every credential and
+secret before anything changes, then runs the target's phases
+(`provision`, `build`, `release`, `verify`) and reports each as events.
 
-For route-based apps, the sniffer loads each endpoint/function/cron/subscriber and collects environment variables from:
-- All services attached to the construct (via `service.register()`)
-- Publisher service (if any)
-- Auditor storage service (if any)
-- Database service (if any)
+**Verified, or rolled back (Dokploy).** An app counts as released once Dokploy's deployment has finished and the app has answered its health route 2xx three times in a row (`/health` for a backend, `/` for a site; an app without a domain gets the deployment check only). Backends are released and checked before any site is released, and a failed backend stops the run. Whatever fails is pointed back at the image it ran before. Pending migrations are applied before any app is switched, in the deploy's sandbox, with each database URL handed over as a secret file. Tune the checks with `deploy.dokploy.verify: { deploymentTimeoutMs, healthCheckPath, healthyAfter, intervalMs, healthTimeoutMs }`.
 
-This allows the CLI to validate that all required secrets are configured before deployment, preventing runtime errors from missing environment variables.
+At a terminal a missing Dokploy or registry login is asked for (and the Dokploy one stored). With `--json` or without a terminal nothing is asked: the deploy stops with `MissingCredential` and exits 1.
 
-**Configuration:**
+**From a program:** the same deploy is `deploy()` from `@geekmidas/cli/deploy` — explicit `cwd`, an injected `CredentialProvider`, a logger and an `AbortSignal`; it returns a run you iterate for JSON events, plus a `result` promise. It never prompts, prints or exits.
 
 ```typescript
-// gkm.config.ts
-export default defineConfig({
-  routes: 'src/endpoints/**/*.ts',
-  envParser: './src/env.ts',
-  logger: './src/logger.ts',
+import { deploy } from '@geekmidas/cli/deploy';
 
-  docker: {
-    registry: 'ghcr.io/myorg',
-    imageName: 'my-api',
-  },
-
-  // For Dokploy deployments
-  providers: {
-    dokploy: {
-      endpoint: 'https://dokploy.example.com',
-      projectId: 'proj_xxx',
-      applicationId: 'app_xxx',
-    },
-  },
-});
+const run = deploy({ cwd: '/srv/shop', stage: 'production', signal });
+for await (const event of run) console.log(event.type);
+const result = await run.result;
 ```
 
+The project's own code — loading `gkm.config.ts`, discovering constructs, sniffing each app's environment, running migrations — runs in a `Sandbox`, never in the host process and never with the deploy's credentials. The default `LocalSandbox` is a child process with an allowlisted environment and a timeout per step; a host building repositories it does not trust passes its own isolating one (`sandbox`), and a config holding live objects then fails with `ConfigObjectNotSerializable`.
+
+**Writing a target:** `defineTarget` from `@geekmidas/cli/target`, with the package's runtime declared in its `package.json` (`"gkm": { "runtime": "server" }`).
+
 **Environment Variables:**
 - `DOKPLOY_API_TOKEN`: API token for Dokploy (not needed if logged in via `gkm login`)
-- `GKM_MASTER_KEY`: Automatically set by Dokploy, or manually for Docker deployments
+- `DOKPLOY_ENDPOINT`: Dokploy URL, if neither the stored login nor `deploy.dokploy.endpoint` gives one
+- `DOCKER_REGISTRY_USERNAME` / `DOCKER_REGISTRY_PASSWORD`: a registry login, used only when Dokploy has no registry for `deploy.registry` and one has to be created
+- `AWS_PROFILE`, or `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`: the `sst` target's AWS credentials, handed to `sst deploy` only (the profile wins when both are set)
+- `GKM_HOME`: where stage keys and stored logins live (default `~/.gkm`)
+- `GKM_MASTER_KEY`: set in each container's runtime environment by the deploy; for an image you run yourself, from `.gkm/server/master.key`, which `gkm build --stage` writes (the key is never printed; output shows its fingerprint)
+
+**Guides:**
+[Deploy targets](https://geekmidas.github.io/toolbox/next/guide/deploy-targets) ·
+[Writing a target](https://geekmidas.github.io/toolbox/next/guide/writing-a-target) ·
+[Deploying from a program](https://geekmidas.github.io/toolbox/next/guide/deploy-api) ·
+[The sandbox](https://geekmidas.github.io/toolbox/next/guide/sandbox) ·
+[Deploy state](https://geekmidas.github.io/toolbox/next/guide/state) ·
+[Running in production](https://geekmidas.github.io/toolbox/next/guide/production) ·
+[Upgrading to 10.0.0-alpha](https://geekmidas.github.io/toolbox/next/guide/upgrading) ·
+[Deprecated deploy APIs](https://geekmidas.github.io/toolbox/next/guide/deploy-deprecations)
+
+### `gkm deploy:rollback`
+
+Put a stage's app back on the release before the one it runs (Dokploy). One app by default; `--atomic` rolls back every app that has an earlier release, for apps that only work together. It restores images only: migrations are forward-only.
+
+```bash
+gkm deploy:rollback --stage production --app api
+gkm deploy:rollback --stage production --atomic
+```
+
+From a program: `rollbackStage({ cwd, stage, app })` from `@geekmidas/cli/deploy`.
 
 ### `gkm deploy:init`
 
-Initialize a new Dokploy deployment by creating a project and application via the Dokploy API. Automatically updates `gkm.config.ts` with the configuration.
+Initialize a new Dokploy deployment by creating a project and application via the Dokploy API. Nothing is written to `gkm.config.ts`: the ids are rediscovered by name on each run and kept in the deploy state file.
 
 ```bash
 gkm deploy:init --project <name> --app <name> [options]
@@ -990,8 +977,7 @@ gkm deploy:init \
 1. Searches for existing project by name, or creates a new one
 2. Creates a new application in the project
 3. Configures registry if `--registry-id` is provided
-4. Updates `gkm.config.ts` with the Dokploy configuration
-5. Shows next steps for secrets and deployment
+4. Shows next steps for secrets and deployment
 
 ### `gkm deploy:list`
 
@@ -1017,6 +1003,24 @@ gkm deploy:list --registries
 gkm deploy:list --endpoint https://dokploy.example.com
 ```
 
+### `gkm state:*`
+
+Deploy state records what a stage's deploys created, so the next deploy finds
+it again. It lives where `state` in `gkm.config.ts` says: `.gkm/deploy-<stage>.json`
+by default, or SSM (`{ provider: 'ssm', region }`) or S3
+(`{ provider: 's3', bucket, region }`) for teams and CI. Every deploy holds the
+stage's lock and writes conditionally.
+
+```bash
+gkm state:show   --stage production [--json]  # ids, releases, pending resources; secrets masked
+gkm state:pull   --stage production           # remote → .gkm/
+gkm state:push   --stage production           # .gkm/ → remote, under the remote lock
+gkm state:diff   --stage production
+gkm state:unlock --stage production           # release a crashed deploy's lock
+```
+
+See [Deploy state](https://geekmidas.github.io/toolbox/next/guide/state).
+
 ### Using Encrypted Credentials
 
 After deploying with secrets, your application decrypts credentials at runtime:
@@ -1040,7 +1044,7 @@ export const envParser = new EnvironmentParser({...process.env, ...Credentials})
 
 **How it works:**
 - At build time, secrets are encrypted with AES-256-GCM and embedded in the bundle
-- An ephemeral master key is generated per build
+- An ephemeral master key is generated per build and written to `.gkm/server/master.key` (mode `0600`); the build prints its path and fingerprint, never the key
 - At runtime, `Credentials` decrypts using `GKM_MASTER_KEY` environment variable
 - In development (no embedded secrets), `Credentials` returns `{}`
 
@@ -1059,28 +1063,23 @@ The following commands are planned for future releases:
 The `gkm.config.ts` file defines how the CLI discovers and processes your endpoints:
 
 ```typescript
-// Construct types accept a string, string[], or partitioned config
-type Routes = string | string[] | PartitionedRoutes;
-
-interface PartitionedRoutes {
-  paths: string | string[];
-  partition: (filepath: string) => string;
-}
+// Construct types accept a glob string or an array of them
+type Routes = string | string[];
 
 interface GkmConfig {
-  routes: Routes;                // Glob patterns or partitioned config
+  routes: Routes;                // Glob patterns
   envParser: string;             // Path to environment parser
   logger: string;                // Path to logger configuration
-  functions?: Routes;            // Glob patterns or partitioned config
-  crons?: Routes;                // Glob patterns or partitioned config
-  subscribers?: Routes;          // Glob patterns or partitioned config
+  functions?: Routes;            // Glob patterns
+  crons?: Routes;                // Glob patterns
+  subscribers?: Routes;          // Glob patterns
   runtime?: 'node' | 'bun';     // Runtime environment (default: 'node')
   telescope?: boolean | TelescopeConfig; // Telescope debugging config
 }
 
 interface TelescopeConfig {
   enabled?: boolean;       // Enable/disable (default: true in dev)
-  path?: string;           // Dashboard path (default: '/__telescope')
+  path?: string;           // Where the JSON API is mounted (default: '/__telescope')
   ignore?: string[];       // URL patterns to ignore
   recordBody?: boolean;    // Record request/response bodies (default: true)
   maxEntries?: number;     // Max entries to keep (default: 1000)
@@ -1092,7 +1091,7 @@ interface TelescopeConfig {
 
 #### `routes`
 
-Glob pattern(s) to discover endpoint files. Can be a single pattern, array of patterns, or a partitioned config:
+Glob pattern(s) to discover endpoint files. Can be a single pattern or an array of patterns:
 
 ```typescript
 // Single pattern
@@ -1104,19 +1103,8 @@ routes: [
   'src/api/**/*.ts',
   'src/handlers/**/*.ts'
 ]
-
-// Partitioned — groups constructs in the generated manifest
-routes: {
-  paths: './src/endpoints/**/*.ts',
-  partition: (filepath) => {
-    const match = filepath.match(/endpoints\/([^/]+)\//);
-    return match?.[1] ?? 'default';
-  },
-}
 ```
 
-The same partitioned format works for `functions`, `crons`, and `subscribers`. When a `partition` callback is provided, the generated manifest groups constructs by partition name (e.g., `manifest.routes.admin`). Without it, manifest fields remain flat arrays.
-
 #### `envParser`
 
 Path to your environment parser configuration. Supports both default and named exports.
@@ -1149,7 +1137,7 @@ logger: './src/utils.ts#appLogger'
 
 #### `telescope`
 
-Configuration for the Telescope debugging dashboard. Telescope is enabled by default when using `gkm dev`.
+Configuration for Telescope, which records requests, logs and exceptions and serves them as JSON. Telescope is enabled by default when using `gkm dev`.
 
 ```typescript
 // Disable telescope
@@ -1174,7 +1162,7 @@ telescope: {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `enabled` | `boolean` | `true` | Enable/disable Telescope |
-| `path` | `string` | `/__telescope` | Dashboard URL path |
+| `path` | `string` | `/__telescope` | Where the JSON API is mounted |
 | `ignore` | `string[]` | `[]` | URL patterns to exclude from recording |
 | `recordBody` | `boolean` | `true` | Record request/response bodies |
 | `maxEntries` | `number` | `1000` | Maximum entries per type to keep |
@@ -1216,6 +1204,7 @@ import { defineWorkspace } from '@geekmidas/cli/config';
 
 export default defineWorkspace({
   name: 'my-project',
+  stages: { local: 'dev', deployed: ['prod'] },
   constructs: './constructs/**/*.ts',
   shared: {
     packages: ['packages/*'],
@@ -1239,7 +1228,7 @@ them out of the manifest; none of them is listed in config.
 
 ```typescript
 // constructs/api.ts
-export const api = new RestApi('Api', { defaultAuthorizer: 'none', logger });
+export const api = new RestApi('Api', { path: 'apps/api', defaultAuthorizer: 'none', logger });
 ```
 
 `gkm build --provider server` generates a Hono server from the endpoints built
@@ -1253,6 +1242,7 @@ An auth server mounts a wildcard, so there is nothing for a glob to find:
 ```typescript
 // constructs/auth.ts
 export const auth = new BetterAuth('Auth', {
+  path: 'apps/auth',
   database: authDb,
   basePath: '/api/auth',
 });
@@ -1271,8 +1261,8 @@ from being read by it.
 
 ```typescript
 // constructs/site.ts
-export const web = new StaticSite('Web').dependsOn([api, auth]);
-export const admin = new StaticSite('Admin', { variant: 'next' }).dependsOn([api]);
+export const web = new StaticSite('Web', { path: 'apps/web' }).dependsOn([api, auth]);
+export const admin = new StaticSite('Admin', { path: 'apps/admin', variant: 'next' }).dependsOn([api]);
 ```
 
 `.dependsOn()` is the single fact behind four things that are hand-maintained
@@ -1291,7 +1281,7 @@ gkm docker
 - `.gkm/docker/Dockerfile.api` - Routes-based backend (uses `gkm build`)
 - `.gkm/docker/Dockerfile.auth` - Entry-based backend (uses esbuild bundling)
 - `.gkm/docker/Dockerfile.web` - Next.js standalone output
-- `.gkm/docker/docker-compose.yml` - Full stack with all apps and services
+- `docker-compose.constructs.yml` - every container the constructs imply, and each app behind the `apps` profile (project root)
 - `.dockerignore` - Optimized ignore patterns
 
 **Dockerfile types by app:**
@@ -1358,12 +1348,10 @@ interface WorkspaceConfig {
 What an app is comes from the declaration, not from here:
 
 ```typescript
-/** Overrides, all optional. A surface normally has none. */
+/** How a site is built and run. A surface declares only its `path`. */
 interface AppSpec {
-  /** Default: `apps/<kebab-id>` if present, else the project root. */
-  path?: string;
-  /** Default: the conventional directories under `path`. */
-  code?: string;
+  /** Required: where the app lives, relative to the workspace root. */
+  path: string;
   /** Default: assigned in a stable order, so adding an app renumbers nothing. */
   port?: number;
   entry?: string;
@@ -1371,42 +1359,24 @@ interface AppSpec {
 }
 ```
 
-## Providers
-
-### AWS API Gateway v1
-
-Generates Lambda handlers compatible with AWS API Gateway v1 (REST API).
-
-```bash
-gkm build --provider aws-apigatewayv1
-```
-
-**Generated Handler:**
-```typescript
-import { AmazonApiGatewayV1Endpoint } from '@geekmidas/constructs/aws';
-import { myEndpoint } from '../src/routes/example.js';
-import { envParser } from '../src/env.js';
+## Build Targets
 
-const adapter = new AmazonApiGatewayV1Endpoint(envParser, myEndpoint);
+### AWS
 
-export const handler = adapter.handler;
-```
-
-### AWS API Gateway v2
-
-Generates Lambda handlers compatible with AWS API Gateway v2 (HTTP API).
+Generates one Lambda handler per construct. Endpoints get an API Gateway v2
+(HTTP API) adapter.
 
 ```bash
-gkm build --provider aws-apigatewayv2
+gkm build                  # with deploy: { default: 'sst' }
+gkm build --provider aws   # whatever the deploy target
 ```
 
 **Generated Handler:**
 ```typescript
 import { AmazonApiGatewayV2Endpoint } from '@geekmidas/constructs/aws';
-import { myEndpoint } from '../src/routes/example.js';
-import { envParser } from '../src/env.js';
+import { myEndpoint } from '../../../src/routes/example.js';
 
-const adapter = new AmazonApiGatewayV2Endpoint(envParser, myEndpoint);
+const adapter = new AmazonApiGatewayV2Endpoint(myEndpoint);
 
 export const handler = adapter.handler;
 ```
@@ -1448,139 +1418,141 @@ export default createApp;
 
 ## Output Structure
 
-The CLI generates files in the `.gkm/<provider>` directory:
+Handlers are generated beside the app, in `<app>/.gkm/<target>`; the manifest
+at the workspace root, where `sst.config.ts` runs:
 
 ```
-.gkm/
-├── aws-apigatewayv1/
-│   ├── getUsers.ts          # Individual Lambda handler
-│   ├── createUser.ts        # Individual Lambda handler
-├── server/
-│   ├── app.ts               # Server application
-│   ├── endpoints.ts         # Endpoint exports
-├── manifest/
-│   ├── aws.ts               # AWS manifest with types
-│   └── server.ts            # Server manifest with types
-└── openapi.json             # OpenAPI specification
+<root>/
+├── .gkm/manifest/
+│   ├── aws.ts                   # AWS manifest with types
+│   └── server.ts                # Server manifest with types
+└── apps/api/.gkm/
+    ├── aws/
+    │   ├── routes/getUsers.ts   # One Lambda handler per endpoint
+    │   ├── functions/
+    │   ├── crons/
+    │   ├── queues/
+    │   └── subscribers/
+    └── server/
+        ├── app.ts               # Server application
+        └── endpoints.ts         # Endpoint exports
 ```
 
 ### Build Manifest
 
-The CLI generates TypeScript manifests with full type information in the `.gkm/manifest/` directory. These manifests export both the data and derived types for type-safe usage.
+The manifest is the application's, not an app's: the root `gkm build` builds
+every backend and writes it once, to `.gkm/manifest/aws.ts` or
+`.gkm/manifest/server.ts` at the workspace root. An app's own build writes no
+manifest. Every handler path in it is relative to the workspace root. `gkm init`
+adds a root tsconfig alias for the manifest, `@<project>/manifest`.
 
-#### AWS Manifest (`.gkm/manifest/aws.ts`)
+It exports two values — every declared construct keyed by id, and the backends
+the build resolved — and the types derived from them:
 
 ```typescript
-export const manifest = {
-  routes: [
-    {
-      path: '/users',
-      method: 'GET',
-      handler: '.gkm/aws-apigatewayv1/getUsers.handler',
-      authorizer: 'jwt',
-    },
-    {
-      path: '/users',
-      method: 'POST',
-      handler: '.gkm/aws-apigatewayv1/createUser.handler',
-      authorizer: 'jwt',
-    },
-  ],
-  functions: [
-    {
-      name: 'processData',
-      handler: '.gkm/aws-lambda/functions/processData.handler',
-      timeout: 60,
-      memorySize: 256,
-    },
-  ],
-  crons: [
-    {
-      name: 'dailyCleanup',
-      handler: '.gkm/aws-lambda/crons/dailyCleanup.handler',
-      schedule: 'rate(1 day)',
-      timeout: 300,
-      memorySize: 512,
+export const constructs = {
+  Database: { id: 'Database', kind: 'database' },
+  Api: {
+    id: 'Api',
+    kind: 'rest-api',
+    path: 'apps/api',
+    endpoints: [
+      {
+        id: 'ApiGET/users',
+        method: 'GET',
+        path: '/users',
+        handler: 'apps/api/.gkm/aws/routes/getUsers.handler',
+        dependencies: [{ target: 'Database', kind: 'database' }],
+        authorizer: 'iam',
+      },
+    ],
+  },
+  ProcessData: {
+    id: 'ProcessData',
+    kind: 'function',
+    handler: 'apps/api/.gkm/aws/functions/processData.handler',
+    dependencies: [],
+  },
+  DailyCleanup: {
+    id: 'DailyCleanup',
+    kind: 'cron',
+    handler: 'apps/api/.gkm/aws/crons/dailyCleanup.handler',
+    schedule: 'rate(1 day)',
+    dependencies: [{ target: 'Database', kind: 'database' }],
+  },
+  Emails: {
+    id: 'Emails',
+    kind: 'queue',
+    // The queue's consumer is nested in it
+    worker: {
+      id: 'emails',
+      handler: 'apps/api/.gkm/aws/queues/emails.handler',
+      dependencies: [],
     },
-  ],
-  subscribers: [],
-} as const;
+  },
+  Users: {
+    id: 'Users',
+    kind: 'topic',
+    events: ['user.created'],
+    // As are a topic's subscribers
+    subscribers: [
+      {
+        id: 'onUser',
+        handler: 'apps/api/.gkm/aws/subscribers/onUser.handler',
+        events: ['user.created'],
+        dependencies: [],
+      },
+    ],
+  },
+} as const satisfies ConstructManifest;
+
+export const backends = { cache: 'upstash', email: 'ses' } as const;
 
 // Derived types
-export type Route = (typeof manifest.routes)[number];
-export type Function = (typeof manifest.functions)[number];
-export type Cron = (typeof manifest.crons)[number];
-export type Subscriber = (typeof manifest.subscribers)[number];
+export type Ids = IdsOf<typeof constructs>;
+export type Construct<Id extends Ids> = DeclarationOf<typeof constructs, Id>;
+export type Kind = Construct<Ids>['kind'];
 
 // Useful union types
-export type Authorizer = Route['authorizer'];
-export type HttpMethod = Route['method'];
-export type RoutePath = Route['path'];
+export type ProvidedKeys = AllProvidedKeys<typeof constructs>;
+export type Surfaces = IdsOfKind<typeof constructs, 'rest-api'>;
+export type CacheBackend = (typeof backends)['cache'];
+export type EmailBackend = (typeof backends)['email'];
 ```
 
-When routes are partitioned, the manifest groups them by partition name and generates partition-aware types:
-
-```typescript
-export const manifest = {
-  routes: {
-    "admin": [{ path: '/admin/users', method: 'GET', handler: '...', authorizer: 'jwt' }],
-    "default": [{ path: '/users', method: 'GET', handler: '...', authorizer: 'jwt' }],
-  },
-  functions: [...], // flat if not partitioned
-} as const;
+A `RestApi` carries its endpoints, each with its method, path, handler, the
+dependencies it declared and its authorizer. On AWS the handler is the
+endpoint's own Lambda (`apps/api/.gkm/aws/routes/<export>.handler`); in the
+server manifest every endpoint's handler is the app entry
+(`apps/api/.gkm/server/app.ts`). Functions and crons are top-level
+declarations; a queue's worker and a topic's subscribers are nested in the
+queue or topic.
 
-// Partition-aware derived types
-export type RoutePartition = keyof typeof manifest.routes;
-export type Route<P extends RoutePartition = RoutePartition> =
-  (typeof manifest.routes)[P][number];
-```
+#### Using the Manifest
 
-#### Server Manifest (`.gkm/manifest/server.ts`)
+On AWS, `fromManifest` from `@geekmidas/cloud/sst` provisions all of it —
+resources, each API's endpoints, queue consumers, functions and crons:
 
 ```typescript
-export const manifest = {
-  app: {
-    handler: '.gkm/server/app.ts',
-    endpoints: '.gkm/server/endpoints.ts',
-  },
-  routes: [
-    { path: '/users', method: 'GET', authorizer: 'jwt' },
-    { path: '/users', method: 'POST', authorizer: 'jwt' },
-  ],
-  subscribers: [
-    { name: 'orderHandler', subscribedEvents: ['order.created'] },
-  ],
-} as const;
+// sst.config.ts
+const { App, fromManifest, Stack } = await import('@geekmidas/cloud/sst');
+const { backends, constructs } = await import('./.gkm/manifest/aws.js');
 
-// Derived types
-export type Route = (typeof manifest.routes)[number];
-export type Subscriber = (typeof manifest.subscribers)[number];
-
-// Useful union types
-export type Authorizer = Route['authorizer'];
-export type HttpMethod = Route['method'];
-export type RoutePath = Route['path'];
+fromManifest(new Stack(app, 'Shop'), constructs, { Database: { vpc } }, backends);
 ```
 
-#### Using Manifest Types
-
-Import the manifest types for type-safe infrastructure configuration:
+The types narrow to what was declared:
 
 ```typescript
-import { manifest, type Route, type Authorizer } from './.gkm/manifest/aws';
+import { constructs, type Construct, type Surfaces } from './.gkm/manifest/aws';
 
-// Type-safe route iteration
-for (const route of manifest.routes) {
-  console.log(`${route.method} ${route.path} -> ${route.handler}`);
-}
+const api: Construct<'Api'> = constructs.Api;
 
-// Use union types for validation
-function isValidMethod(method: string): method is HttpMethod {
-  return manifest.routes.some((r) => r.method === method);
+for (const endpoint of api.endpoints) {
+  console.log(`${endpoint.method} ${endpoint.path} -> ${endpoint.handler}`);
 }
 
-// Access authorizer names
-const authorizers = new Set(manifest.routes.map((r) => r.authorizer));
+const surface: Surfaces = 'Api'; // any other id is a type error
 ```
 
 ## OpenAPI Generation
@@ -1663,62 +1635,25 @@ gkm openapi --output api-docs.json --json
 
 ## Deployment Examples
 
-### AWS Lambda with Serverless Framework
+Deploying goes through `gkm deploy` and a target, rather than through a
+hand-written server file or framework config:
 
-```yaml
-# serverless.yml
-service: my-api
-
-provider:
-  name: aws
-  runtime: nodejs18.x
-
-functions:
-  getUsers:
-    handler: .gkm/aws-apigatewayv1/getUsers.handler
-    events:
-      - http:
-          path: users
-          method: get
-  
-  createUser:
-    handler: .gkm/aws-apigatewayv1/createUser.handler
-    events:
-      - http:
-          path: users
-          method: post
-```
-
-### Server Deployment
+```bash
+# Dokploy (the default target)
+gkm deploy --stage production
 
-```typescript
-// server.ts
-import { createApp } from './.gkm/server/app.js';
+# One Docker Compose stack behind Caddy, on this machine
+gkm compose --stage production --tag v1.4.0
 
-const app = createApp();
+# AWS through SST, with deploy: { default: 'sst' }
+gkm deploy --stage production
 
-const port = process.env.PORT || 3000;
-app.listen(port, () => {
-  console.log(`Server running on port ${port}`);
-});
+# Only the Docker files, to build and run images yourself
+gkm docker --build --tag v1.4.0
 ```
 
-### Docker Deployment
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-
-COPY . .
-RUN npm run build
-
-EXPOSE 3000
-
-CMD ["node", "server.js"]
-```
+See [Deploy targets](https://geekmidas.github.io/toolbox/next/guide/deploy-targets) and the
+[deployment guide](https://geekmidas.github.io/toolbox/next/guide/deployment).
 
 ## Advanced Usage
 
@@ -1883,6 +1818,7 @@ Configure multiple patterns for complex project structures:
 import { defineConfig } from '@geekmidas/cli/config';
 
 export default defineConfig({
+  stages: { local: 'dev', deployed: ['prod'] },
   routes: [
     'src/routes/**/*.ts',
     'src/api/v1/**/*.ts',
@@ -1914,8 +1850,8 @@ Error: Failed to load gkm.config.ts: Invalid configuration
 # No endpoints found
 No endpoints found to process
 
-# Invalid provider
-Error: Unsupported provider: invalid-provider
+# Unknown deploy target
+Unknown deploy target "fly". Use one of dokploy, compose, sst, or name the package that provides it in gkm.config.ts: deploy: { targets: { "fly": '<package>' } }.
 ```
 
 ### OpenAPI Errors
@@ -1935,44 +1871,22 @@ Error: OpenAPI generation failed: Invalid endpoint schema
     "dev": "gkm dev",
     "dev:port": "gkm dev --port 8080",
     "build": "gkm build",
-    "build:lambda": "gkm build --provider aws-apigatewayv1",
+    "build:lambda": "gkm build --provider aws",
     "build:server": "gkm build --provider server",
-    "docs": "gkm openapi --output src/api.ts"
+    "client": "gkm openapi"
   }
 }
 ```
 
 ### CI/CD Pipeline
 
-```yaml
-# .github/workflows/deploy.yml
-name: Deploy API
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-          
-      - name: Install dependencies
-        run: npm ci
-        
-      - name: Build handlers
-        run: npm run build:lambda
-        
-      - name: Deploy to AWS
-        run: npx serverless deploy
-```
+`gkm init` writes a GitHub Actions deploy workflow that runs
+`gkm deploy --stage "$STAGE"` for each stage. Its credentials come from the
+stage's GitHub environment: `AWS_ROLE_ARN` for SST (set by
+`gkm deploy:github --stage <stage>`), or `DOKPLOY_API_TOKEN` and
+`DOKPLOY_ENDPOINT` for Dokploy. In any CI job, `gkm deploy --json` writes the
+deploy's events as JSON lines and never prompts. See
+[Deploying from GitHub Actions](https://geekmidas.github.io/toolbox/next/guide/deployment#deploying-from-github-actions).
 
 ## Troubleshooting
 
@@ -2029,8 +1943,8 @@ DEBUG=gkm:* npx gkm build
 ### Types
 
 ```typescript
-// Provider options
-type Provider = 'server' | 'aws-apigatewayv1' | 'aws-apigatewayv2';
+// Build targets
+type Provider = 'aws' | 'server';
 
 // Runtime options
 type Runtime = 'node' | 'bun';
@@ -2054,17 +1968,8 @@ interface DockerConfig {
   imageName?: string;       // Image name (defaults to package.json name)
   baseImage?: string;       // Base image (default: node:22-alpine)
   port?: number;            // Port to expose (default: 3000)
-  compose?: {
-    services?: ComposeServicesConfig | ComposeServiceName[];
-  };
 }
 
-// Service configuration for docker-compose
-type ComposeServiceName = 'postgres' | 'redis' | 'rabbitmq';
-type ComposeServicesConfig = {
-  [K in ComposeServiceName]?: boolean | { version?: string };
-};
-
 // Telescope configuration
 interface TelescopeConfig {
   enabled?: boolean;
@@ -2077,7 +1982,7 @@ interface TelescopeConfig {
 
 // Build options
 interface BuildOptions {
-  provider: Provider;
+  provider?: Provider; // default: where gkm.config.ts deploys
 }
 
 // Dev options