@stacksjs/defaults 0.74.3 → 0.74.5

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -66,7 +66,7 @@ globalThis.toggleDark = toggleDark
 - **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
 
 ### Server Auto-Imports (100+)
-- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (60+ models)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (97 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

package/ai/skills/stacks-buddy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-buddy
-description: Use when working with the Stacks CLI (buddy/bud/stacks/stx) - understanding all 50+ commands with their flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files.
+description: Use when working with the Stacks CLI (buddy/bud/stacks/stx) - understanding every command with its flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Buddy CLI
 
-The complete CLI runtime for the Stacks framework with 50+ commands, lazy-loaded for fast cold starts.
+The complete CLI runtime for the Stacks framework, lazy-loaded for fast cold starts. `docs/guide/buddy/commands.md` lists every command and is generated from the runtime registry, so it is the count as well as the reference.
 
 ## Key Paths
 - Core package: `storage/framework/core/buddy/src/`
@@ -367,7 +367,57 @@ buddy env:check                  # validate environment configuration
 ## Cloud & Deployment
 
 ### `buddy deploy` - Deploy to cloud
-Handles full deployment workflow: prerequisites check, pantry install, env setup, APP_KEY, AWS credentials (from .env.{env} or ~/.aws/credentials), domain setup, email DNS records (DKIM, MX, SPF, DMARC), mail user creation.
+Handles full deployment workflow: prerequisites check, pantry install, env setup, APP_KEY, provider credentials, domain setup, email DNS records (DKIM, MX, SPF, DMARC), mail user creation.
+
+```bash
+buddy deploy [env]             # env is production | staging | development
+  --domain <domain>            # override the domain this deploy publishes
+  -p/--project [project]       # target a specific project
+  --prod                       # deploy to production
+  --staging                    # deploy to staging
+  --dev                        # deploy to development
+  --site <name>                # deploy only this one site to the existing server
+  --docker                     # also build an OCI image with pantry and push it
+  --dry-run                    # preview the plan, change nothing
+  --yes                        # skip confirmation (required from a non-TTY)
+  -J/--json                    # machine-readable deployment preview
+  --verbose                    # verbose output
+
+buddy deploy:rollback [site]   # activate a preserved release (hetzner/ssh targets)
+  --env <environment>          # environment to roll back (default: production)
+  --to <release>               # preserved release id to activate
+  --dry-run                    # preview without changing the active release
+  --verbose                    # verbose output
+```
+
+Where it deploys is `cloud.provider` in `config/cloud.ts`: `'aws'` (default, CloudFormation),
+`'hetzner'` (provision a server, then deploy over SSH), or `'ssh'` (a host you already own).
+`CLOUD_PROVIDER` overrides the config value.
+
+### `buddy server:*` - An SSH deploy target
+For `cloud.provider: 'ssh'`, a Linux box you already own. The `raspberry-pi` profile tunes the
+bootstrap for a small single-board computer.
+
+```bash
+buddy server:flash        # write an OS image to an SD card or USB disk
+  --os <name>             # raspberry-pi-os-lite (default), raspberry-pi-os, ubuntu-24.04, ubuntu-26.04
+  --device <path>         # the whole disk to write to, e.g. /dev/disk4
+  --list                  # list writable disks and exit
+  --dry-run               # say what would happen without writing
+  --yes                   # skip the confirmation
+buddy server:first-boot   # write cloud-init user-data to the mounted boot partition
+  --hostname <name>       # the board's hostname
+  --user <name>           # the login user cloud-init creates
+buddy server:doctor       # preflight over SSH: arch, OS, memory, disk, sudo, clock, HTTPS
+buddy server:setup        # adopt and bootstrap the host (bun, rpx, systemd units)
+buddy server:trust        # install the box's local CA here, or emit a .mobileconfig
+```
+
+Then `buddy deploy --prod` behaves exactly as it does for Hetzner. Connection details come from
+`ssh.hosts` in `config/cloud.ts`, or from `TS_CLOUD_SSH_HOST`, `TS_CLOUD_SSH_USER`,
+`TS_CLOUD_SSH_PORT` and `TS_CLOUD_SSH_KEY`, which win over the config. A host on a private address
+publishes no DNS and requests no certificate; `TS_CLOUD_SSH_PUBLISH_DNS=1` forces publishing on
+and `0` forces it off.
 
 ### `buddy cloud` - Cloud management
 ```bash

package/ai/skills/stacks-cloud/SKILL.md

@@ -1,14 +1,29 @@
 ---
 name: stacks-cloud
-description: Use when deploying or managing cloud infrastructure for Stacks - AWS deployment via CloudFormation/CDK, server mode (EC2, ALB, VPC), serverless mode (Lambda, API Gateway, CloudFront), jump boxes, domain management (Route53), S3 storage, SES email, edge computing, security groups, IAM, or the cloud configuration. Covers @stacksjs/cloud, @stacksjs/deploy, storage/framework/cloud/, and cloud/.
+description: Use when deploying or managing cloud infrastructure for Stacks - choosing between the AWS, Hetzner and SSH targets, AWS deployment via CloudFormation/CDK, server mode (EC2, ALB, VPC), serverless mode (Lambda, API Gateway, CloudFront), jump boxes, domain management (Route53), S3 storage, SES email, edge computing, security groups, IAM, the rpx gateway and systemd units on an SSH box, or the cloud configuration. Covers @stacksjs/cloud, @stacksjs/deploy, storage/framework/cloud/, and cloud/.
 license: MIT
-compatibility: Bun >= 1.3.0, TypeScript, AWS
+compatibility: Bun >= 1.3.0, TypeScript, AWS / Hetzner / any 64-bit Debian or Ubuntu host over SSH
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
 # Stacks Cloud & Deployment
 
-AWS-focused cloud deployment using CloudFormation via `@stacksjs/ts-cloud`.
+Cloud infrastructure for Stacks, across three deploy targets, all driven through
+`@stacksjs/ts-cloud`.
+
+## Targets
+
+`cloud.provider` in `config/cloud.ts` decides which one runs. `CLOUD_PROVIDER` in the environment
+overrides it. With neither set, the provider is `aws`.
+
+| `cloud.provider` | Infrastructure | Pipeline |
+|---|---|---|
+| `'aws'` (default) | CloudFormation stack: EC2/ALB/VPC or Lambda/API Gateway/CloudFront | Template generated and applied |
+| `'hetzner'` | One Hetzner Cloud server, firewall, SSH key, managed services | Tarball over SSH, systemd units, rpx gateway |
+| `'ssh'` | A host you already own; nothing is provisioned | Same tarball pipeline, after an in-place bootstrap |
+
+Read `config/cloud.ts` before advising anything provider-specific. This repo uses `'hetzner'`.
+Most of this page is the AWS target; the Hetzner and SSH sections are marked as such.
 
 ## Key Paths
 - Cloud package: `storage/framework/core/cloud/src/`
@@ -18,7 +33,7 @@ AWS-focused cloud deployment using CloudFormation via `@stacksjs/ts-cloud`.
 - Cloud driver state: `storage/cloud/` (ts-cloud's `stateDir`, set in `config/cloud.ts`)
 - Configuration: `config/cloud.ts`
 
-## Deployment Modes
+## Deployment Modes (AWS)
 
 ### Server Mode (EC2)
 - EC2 instances with configurable types (t3.micro, t4g.nano, etc.)
@@ -37,7 +52,7 @@ AWS-focused cloud deployment using CloudFormation via `@stacksjs/ts-cloud`.
 - SQS queues for background jobs
 - DynamoDB (optional)
 
-## Deployment Flow
+## Deployment Flow (AWS)
 
 ```bash
 buddy deploy                    # deploy to cloud
@@ -53,6 +68,51 @@ buddy deploy                    # deploy to cloud
    - Tags: Environment, Project, ManagedBy
    - OnFailure: ROLLBACK
 
+## Hetzner and SSH targets
+
+Both deploy the same way once a host exists: build each site, package a release tarball, copy it
+over SSH, install and restart systemd units, preserve the prior release, and write this project's
+rpx gateway fragment.
+
+```typescript
+// config/cloud.ts
+cloud: { provider: 'hetzner' },        // HCLOUD_TOKEN or hetzner.apiToken
+```
+
+```typescript
+cloud: { provider: 'ssh' },
+ssh: {
+  profile: 'raspberry-pi',             // or 'generic'
+  hosts: [{ host: 'pi-stacks.local', user: 'pi', port: 22, privateKeyPath: '~/.ssh/id_ed25519', role: 'app' }],
+  hostKey: 'pin',                      // 'pin' | 'accept-new' | 'insecure'
+  sudo: true,
+  publicIp: 'auto',                    // omit to stay LAN-only
+  lan: { hostname: 'pi-stacks.local', tls: 'local-ca' },
+},
+```
+
+Env beats config for the SSH target: `TS_CLOUD_SSH_HOST`, `TS_CLOUD_SSH_USER`,
+`TS_CLOUD_SSH_PORT`, `TS_CLOUD_SSH_KEY`. The first host with no `role`, or `role: 'app'`, is the
+one deployed to. Multi-host fleets are not supported.
+
+**The LAN rule.** An SSH host on a private address publishes no DNS, requests no Let's Encrypt
+certificate, skips the CDN and skips mail reconciliation, and prints the LAN URLs instead. Private
+means RFC1918, `100.64/10` CGNAT, loopback, link-local, IPv6 unique-local or link-local, a
+`.local` / `.internal` / `.lan` / `.intranet` / `.home.arpa` name, or a bare single-label
+hostname. LAN HTTPS comes from a certificate authority on the box itself (rpx `localCa`), not from
+Let's Encrypt. To publish: routable address, ports 80 and 443 forwarded, a site with a domain, and
+`ssh.publicIp` set. `TS_CLOUD_SSH_PUBLISH_DNS=1` forces publishing on, `0` forces it off.
+
+**Shared boxes.** Both targets support `cloud.attachTo: '<owner slug>'`. An attached project skips
+provisioning and deploys only its own sites. Each project owns `/etc/rpx/sites.d/<slug>.json` and
+replaces it wholesale, so `project.slug` must be unique on the box, and the config must declare
+every domain that fragment currently serves or the deploy stops.
+
+**State.** `storage/cloud/state/<stack>.json` records the host, SSH user and port, key path, host
+key fingerprint, LAN address, profile and staging path. `buddy cloud` builds an `ssh` project's
+fleet from the config plus those pins, since there is no provider API to enumerate; status reads
+`unknown` because nothing polls the host. `buddy server:doctor` is what asks.
+
 ## Cloud Helper Functions
 
 ```typescript
@@ -136,7 +196,10 @@ export default {
 
 ```bash
 buddy deploy                          # deploy application
-buddy cloud --diff                    # show infrastructure changes
+buddy deploy:rollback [site]           # activate a preserved release (hetzner/ssh)
+buddy server:doctor                   # preflight an ssh host
+buddy server:setup                    # adopt and bootstrap an ssh host
+buddy cloud --diff                    # show infrastructure changes (aws)
 buddy cloud --ssh                     # SSH into cloud
 buddy cloud --invalidate-cache        # invalidate CDN
 buddy cloud:add --jump-box            # add jump box instance
@@ -173,19 +236,28 @@ buddy domains:remove <domain>         # remove domain
 
 ## Infrastructure Stack (storage/framework/cloud/)
 
-- `deploy.ts` — Main deployment script (CDK app entry)
-- `cdk.json` — CDK configuration with 54 AWS context settings
-- `package.json` — Cloud package dependencies
+- `deploy.ts`: Main deployment script (CDK app entry)
+- `cdk.json`: CDK configuration with 54 AWS context settings
+- `package.json`: Cloud package dependencies
 
 Stack naming: `{slugified-app-name}-cloud`
 
 ## Gotchas
+- Check `cloud.provider` first. AWS advice is wrong for a Hetzner or SSH box, and vice versa
+- On Hetzner and SSH there is no CloudFormation, no CDK, no stack, and `buddy cloud --diff` has
+  nothing to diff
+- An SSH host is adopted, never created. `buddy server:doctor` checks it and `buddy server:setup`
+  bootstraps it before the first deploy
+- A key named in `ssh.hosts[].privateKeyPath` that is not on disk is caught up front now; it used
+  to surface much later as a bare `Permission denied (publickey)`
+- A Raspberry Pi has no real-time clock, so apt and ACME can both fail in the first minute after
+  boot until NTP corrects it
 - AWS credentials MUST be configured (`buddy configure:aws` or env vars)
 - Default region is `us-east-1` (from AWS_DEFAULT_REGION env)
 - APP_KEY must be colon-separated format (validated during deployment)
 - Server mode uses EC2 + ALB; serverless uses Lambda + API Gateway + CloudFront
-- Jump boxes are optional — used for SSH access to private instances
-- `cloud:remove` with `--force` skips confirmation — destructive operation
+- Jump boxes are optional, used for SSH access to private instances
+- `cloud:remove` with `--force` skips confirmation and is destructive
 - CDK toolkit stack is named `stacks-toolkit`
 - Environment mapping: `local` → `development`, others preserved
 - Deploy hooks run before/after deployment for custom logic

package/ai/skills/stacks-commerce/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Commerce
 
-Comprehensive e-commerce module with 15 sub-modules and 20+ models.
+Comprehensive e-commerce module with 15 sub-modules and 36 models.
 
 ## Key Paths
 - Core package: `storage/framework/core/commerce/src/`

package/ai/skills/stacks-composables/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-composables
-description: Use when creating or using reactive composables in STX templates - 90+ composables for state management, DOM interaction, sensors, animation, browser APIs, async operations, or the complete list of auto-imported composables. Covers @stacksjs/composables.
+description: Use when creating or using reactive composables in STX templates - 153 composables for state management, DOM interaction, sensors, animation, browser APIs, async operations, or the complete list of auto-imported composables. Covers @stacksjs/composables.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-dashboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 250+ built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 399 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 250+ components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 399 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

package/ai/skills/stacks-deploy/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: stacks-deploy
-description: Use when deploying a Stacks application - the deployment workflow (build → deploy), pre/post deploy hooks, server vs serverless mode selection, first-time deployment setup, deployment troubleshooting, or the buddy deploy command. For cloud infrastructure details (EC2, Lambda, CloudFormation, Route53, IAM), see stacks-cloud.
+description: Use when deploying a Stacks application - picking a deploy target (AWS, Hetzner, or a host you own over SSH), the deployment workflow (build → deploy), pre/post deploy hooks, server vs serverless mode selection, first-time deployment setup, rollback, deployment troubleshooting, or the buddy deploy command. For cloud infrastructure details (EC2, Lambda, CloudFormation, Route53, IAM, rpx, systemd), see stacks-cloud.
 license: MIT
-compatibility: Bun >= 1.3.0, TypeScript, AWS
+compatibility: Bun >= 1.3.0, TypeScript, AWS / Hetzner / any 64-bit Debian or Ubuntu host over SSH
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
@@ -10,6 +10,23 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 The deployment workflow for Stacks applications.
 
+## Deploy Targets
+
+`cloud.provider` in `config/cloud.ts` decides where `buddy deploy` ships. `CLOUD_PROVIDER` in the
+environment overrides it. With neither set, the provider is `aws`.
+
+| `cloud.provider` | Target | What the deploy does |
+|---|---|---|
+| `'aws'` (default) | AWS | Generates infrastructure, creates or updates a CloudFormation stack |
+| `'hetzner'` | Hetzner Cloud | Provisions the server through the Hetzner API, then deploys over SSH |
+| `'ssh'` | A host you already own | Adopts and bootstraps the host over SSH, then deploys to it |
+
+Read the repo's own `config/cloud.ts` before assuming a target. This repo uses `'hetzner'`.
+
+Hetzner and `ssh` share one pipeline: a release tarball copied over SSH, systemd units per site,
+and the rpx gateway in front. They differ in whether a server is created for you. AWS is a
+different pipeline entirely.
+
 ## Quick Deploy
 
 ```bash
@@ -20,36 +37,73 @@ Preview the complete environment-aware plan before changing anything:
 
 ```bash
 buddy deploy --dry-run
-buddy deploy --dry-run --env staging
+buddy deploy staging --dry-run
 buddy deploy --dry-run --site docs
 buddy deploy --dry-run --json
 ```
 
-The preview uses the same environment transformation and ts-cloud site
-classification as a real deploy. It reports the ordered validation,
-infrastructure, build, package, release, runtime, gateway, DNS, TLS, and
-optional container operations. It exits before prerequisite setup, builds,
-packaging, hooks, provider calls, persistence, DNS, TLS, or service restarts.
-The JSON form emits a versioned `STACKS_DEPLOY_PREVIEW_JSON=` line for API and
-tool consumers.
+The preview uses the same environment transformation and ts-cloud site classification as a real
+deploy. It reports the ordered validation, infrastructure, build, package, release, runtime,
+gateway, DNS, TLS, and optional container operations. It exits before prerequisite setup, builds,
+packaging, hooks, provider calls, persistence, DNS, TLS, or service restarts. The JSON form emits
+a versioned `STACKS_DEPLOY_PREVIEW_JSON=` line for API and tool consumers.
 
 ## Deployment Prerequisites
 
+**AWS** (`provider: 'aws'`)
+
 1. **AWS credentials configured**: `buddy configure:aws`
 2. **APP_KEY generated**: `buddy key:generate` (must be colon-separated format)
 3. **APP_URL set** in `.env`
 4. **Team configured** in `config/team.ts`
 
+**Hetzner** (`provider: 'hetzner'`)
+
+1. `HCLOUD_TOKEN` in the environment, or `hetzner.apiToken` in `config/cloud.ts`
+2. `~/.ssh/id_ed25519.pub` on the machine deploying: the driver registers it on the server
+
+**SSH** (`provider: 'ssh'`)
+
+1. A host in `ssh.hosts`, or `TS_CLOUD_SSH_HOST` in the environment
+2. A key that reaches it, and passwordless sudo when the user is not root
+3. `buddy server:doctor` clean
+
 ## Deployment Flow
 
-1. **Validation** — checks APP_KEY format, AWS region, app URL, team config
-2. **Build** — compiles application for production
-3. **Infrastructure** — generates CloudFormation template via ts-cloud
-4. **Deploy** — creates or updates the CloudFormation stack
+**AWS**
+
+1. **Validation**: checks APP_KEY format, AWS region, app URL, team config
+2. **Build**: compiles application for production
+3. **Infrastructure**: generates CloudFormation template via ts-cloud
+4. **Deploy**: creates or updates the CloudFormation stack
    - Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM
    - OnFailure: ROLLBACK
    - Tags: Environment, Project, ManagedBy
 
+**Hetzner and SSH**
+
+1. **Validation**: same prerequisite checks, plus the ts-cloud persistent-state capability check
+2. **Infrastructure**: Hetzner creates or reuses the server; SSH checks and bootstraps the host
+3. **Build and package**: builds each site, packages a release tarball
+4. **Release**: copies over SSH, installs systemd units, restarts, preserves the prior release
+5. **Gateway**: writes `/etc/rpx/sites.d/<slug>.json`
+6. **DNS and TLS**: reconciles A records and issues certificates, when publishing is allowed
+
+## The LAN rule (`provider: 'ssh'` only)
+
+An SSH host on a private address publishes no DNS, requests no Let's Encrypt certificate, skips
+the CDN and skips mail reconciliation. It prints the LAN URLs instead.
+
+Private means RFC1918, `100.64/10` CGNAT, loopback, link-local, IPv6 unique-local or link-local,
+a `.local` / `.internal` / `.lan` / `.intranet` / `.home.arpa` name, or a bare single-label
+hostname. Publishing an A record for `192.168.1.42` would point every visitor's browser at
+whatever occupies that address on their own network, and an ACME challenge cannot reach a host
+the internet cannot route to.
+
+To publish: give the host a routable address, forward 80 and 443 to it, declare a domain on a
+site, and set `ssh.publicIp` (`'auto'` discovers it at deploy time). `TS_CLOUD_SSH_PUBLISH_DNS=1`
+forces publishing on for a host behind a port forward the deploy cannot see; `0` forces it off.
+
 ## Deploy Hooks (cloud/deploy-script.ts)
 
 ```typescript
@@ -70,6 +124,8 @@ export default {
 
 ## Deployment Modes
 
+Modes apply to the AWS target.
+
 ### Server Mode (default)
 - EC2 instances with ALB
 - Best for: full-stack apps, WebSocket support, persistent connections
@@ -83,8 +139,10 @@ export default {
 ## First Deployment Checklist
 
 ```bash
-# 1. Configure AWS
-buddy configure:aws
+# 1. Configure the provider
+buddy configure:aws          # aws
+# hetzner: set HCLOUD_TOKEN
+# ssh:     buddy server:doctor, then buddy server:setup
 
 # 2. Generate app key
 buddy key:generate
@@ -96,25 +154,40 @@ buddy env:set APP_ENV production
 # 4. Review cloud config
 # Edit config/cloud.ts
 
-# 5. Deploy
+# 5. Preview, then deploy
+buddy deploy --dry-run
 buddy deploy
 ```
 
 ## CLI Commands
 
 ```bash
-buddy deploy                  # deploy to cloud
+buddy deploy [env]            # deploy; env is production | staging | development
+buddy deploy --prod           # same, by flag (--staging, --dev)
 buddy deploy --dry-run        # preview without changing anything
+buddy deploy --site <name>    # deploy one site to the existing server
+buddy deploy --domain <d>     # override the domain this deploy publishes
+buddy deploy --yes            # skip confirmation (required in CI)
+buddy deploy:rollback [site]  # activate a preserved release (--env, --to, --dry-run)
+buddy server:doctor           # preflight an ssh host
+buddy server:setup            # adopt and bootstrap an ssh host
 buddy cloud --diff            # preview infrastructure changes before deploying
 buddy cloud --ssh             # SSH into deployed server
-buddy cloud:remove            # tear down infrastructure
+buddy cloud:remove            # tear down infrastructure (alias: undeploy)
 buddy cloud:cleanup           # clean retained resources
 ```
 
 ## Gotchas
-- First deployment creates the CloudFormation stack — subsequent deploys update it
+- Check `cloud.provider` before advising anything provider-specific. Half the AWS advice is wrong
+  for a Hetzner or SSH box, and vice versa.
+- `buddy deploy --prod` from a non-interactive shell refuses without `--yes`, rather than hanging
+  on the confirmation prompt.
 - APP_KEY must be colon-separated format (validated during deployment)
-- Default region is `us-east-1` (from AWS_DEFAULT_REGION env)
-- `buddy cloud --diff` shows changes BEFORE deploying — always review first
-- Deploy hooks run in the deployment process, not on the target server
-- For infrastructure details (EC2, Lambda, VPC, etc.), see the `stacks-cloud` skill
+- `buddy cloud --diff` shows changes BEFORE deploying, and only for AWS
+- Deploy hooks run in the deployment process on your machine, not on the target server
+- On Hetzner and SSH, a project's `/etc/rpx/sites.d/<slug>.json` is replaced wholesale, so
+  `project.slug` must be unique on a shared box and the config must declare every domain that
+  fragment serves
+- `.env.<environment>` is decrypted at deploy time and shipped as every site's `.env`, so declare
+  `tenants` in `config/cloud.ts` on a shared box to strip other tenants' keys
+- For infrastructure details, see the `stacks-cloud` skill

package/ai/skills/stacks-orm/SKILL.md

@@ -11,7 +11,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Key Paths
 - Core ORM package: `storage/framework/core/orm/src/`
 - ORM implementation: `storage/framework/orm/`
-- Model definitions: `storage/framework/defaults/app/Models/` (50+ models)
+- Model definitions: `storage/framework/defaults/app/Models/` (97 models)
 - Application models: `app/Models/`
 - Default model templates: `storage/framework/defaults/app/Models/`
 - ORM type globals: `storage/framework/types/orm-globals.d.ts`

package/ai/skills/stacks-types/SKILL.md

@@ -86,7 +86,7 @@ All model CRUD events: `model:created`, `model:updated`, `model:deleted`
 
 - **Content**: author, post, page
 - **Core**: user, activity, campaign, comment, email-list, notification, social-post, subscription, tag
-- **Commerce (30+ models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more
+- **Commerce (36 models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more
 
 All payloads are `Record<string, any>`.
 

package/ai/skills/stacks-writing-for-agents/SKILL.md

@@ -13,7 +13,7 @@ project `AGENTS.md`, a doc reached by a pointer. The packaging differs, the
 writing does not. The same levers make each one predictable, because the agent
 takes the same *process* every run rather than producing the same output.
 
-Stacks ships 100+ skills and expects projects to add their own under
+Stacks ships 115 skills and expects projects to add their own under
 `app/Skills/`, so this is the skill that keeps that set from turning to sludge.
 The Stacks-specific mechanics (frontmatter, invocation, the override model,
 what `buddy setup:ai` does with the result) are in

package/app/Actions/Dashboard/Analytics/WebAnalyticsAction.ts

@@ -1,14 +1,12 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
-import { Request } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
 import { dashboardOperationalError } from '../dashboard-response'
 import {
-  buildWebAnalytics,
   normalizeAnalyticsRange,
   normalizeAnalyticsScope,
-  requestAnalyticsRow,
 } from './request-analytics'
+import { readDashboardWebAnalytics } from './web-analytics-provider'
 
 export default new Action({
   name: 'WebAnalyticsAction',
@@ -29,10 +27,7 @@ export default new Action({
       }, 422)
     }
     try {
-      const records = await Request.orderByDesc('id').limit(10_000).get()
-      const rows = records.map(requestAnalyticsRow)
-
-      return buildWebAnalytics(rows, range, new Date(), scope)
+      return await readDashboardWebAnalytics({ range, scope })
     }
     catch (error) {
       return dashboardOperationalError(error, 'Web analytics records could not be read.', 'WebAnalyticsAction')

package/app/Actions/Dashboard/Analytics/web-analytics-provider.ts

@@ -0,0 +1,103 @@
+import type { DashboardProviderUnavailable } from '../dashboard-provider'
+import type { AnalyticsRange, AnalyticsScope } from './request-analytics'
+import { Request } from '@stacksjs/orm'
+import { HQ_READ_UNAVAILABLE, readThroughProvider, resolveDashboardDriver } from '../dashboard-provider'
+import { buildWebAnalytics, requestAnalyticsRow } from './request-analytics'
+
+/**
+ * Where the web Analytics section reads from.
+ *
+ * The local provider aggregates this application's own recorded requests, and
+ * it keeps the read exactly as `WebAnalyticsAction` performed it, including the
+ * ten thousand row ceiling. That ceiling is applied by id before the range
+ * filter runs, so a busy application reports on its ten thousand most recent
+ * requests rather than on the window that was asked for. That is existing
+ * behaviour, it is load bearing for the current numbers, and changing it here
+ * would make this refactor impossible to verify as behaviour preserving. It is
+ * worth fixing on its own, against its own tests.
+ *
+ * Only web analytics is seamed. Sales and marketing analytics aggregate orders
+ * and campaigns from this application's own tables, which no hosted analytics
+ * product has any view of.
+ */
+
+const ROW_CEILING = 10_000
+
+/**
+ * The exact shape `buildWebAnalytics` returns, taken from the function itself.
+ *
+ * Deliberately derived rather than declared. Writing this shape out by hand and
+ * annotating the builder with it would narrow `source` from the literal
+ * `'requests'` to `string` and would re-type the two empty arrays it returns,
+ * which is a visible type change in a refactor that is supposed to have none.
+ */
+export type DashboardWebAnalyticsPayload
+  = ReturnType<typeof buildWebAnalytics> & Partial<DashboardProviderUnavailable>
+
+export interface DashboardWebAnalyticsQuery {
+  range: AnalyticsRange
+  scope: AnalyticsScope
+}
+
+export interface DashboardWebAnalyticsProvider {
+  webAnalytics: (query: DashboardWebAnalyticsQuery) => Promise<DashboardWebAnalyticsPayload>
+}
+
+/**
+ * An empty analytics payload, carrying the reason there is nothing to show.
+ *
+ * Built by running the real aggregation over no rows, so every key, every
+ * zero and every placeholder string is whatever the section already renders
+ * for an application that has served no traffic. A hand written empty object
+ * would drift from that the first time the builder gains a field.
+ */
+export function emptyWebAnalyticsPayload(
+  reason: string,
+  query: DashboardWebAnalyticsQuery,
+): DashboardWebAnalyticsPayload {
+  return {
+    ...buildWebAnalytics([], query.range, new Date(), query.scope),
+    unavailable: reason,
+  }
+}
+
+function isWebAnalyticsPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object')
+    return false
+  const candidate = payload as Partial<DashboardWebAnalyticsPayload>
+  return Boolean(candidate.overview)
+    && Array.isArray(candidate.traffic)
+    && Array.isArray(candidate.pages)
+}
+
+/**
+ * This application's own recorded requests.
+ *
+ * Not wrapped in a catch, so a local read failure still reaches the action's
+ * operational error exactly as it did before the seam existed.
+ */
+export const localWebAnalyticsProvider: DashboardWebAnalyticsProvider = {
+  async webAnalytics(query: DashboardWebAnalyticsQuery): Promise<DashboardWebAnalyticsPayload> {
+    const records = await Request.orderByDesc('id').limit(ROW_CEILING).get()
+    const rows = records.map(requestAnalyticsRow)
+
+    return buildWebAnalytics(rows, query.range, new Date(), query.scope)
+  },
+}
+
+/** Reads the web Analytics section through whichever provider config selects. */
+export async function readDashboardWebAnalytics(
+  query: DashboardWebAnalyticsQuery,
+): Promise<DashboardWebAnalyticsPayload> {
+  const driver = await resolveDashboardDriver('analytics')
+
+  if (driver.name === 'local')
+    return localWebAnalyticsProvider.webAnalytics(query)
+
+  return readThroughProvider(
+    'analytics',
+    reason => emptyWebAnalyticsPayload(reason, query),
+    async () => emptyWebAnalyticsPayload(HQ_READ_UNAVAILABLE, query),
+    isWebAnalyticsPayload,
+  )
+}