@stacksjs/defaults 0.75.41 → 0.75.43

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 648 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 650 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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. (103 models)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (104 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-chat
-description: Use when implementing chat messaging in Stacks - sending messages to Slack (webhooks, bot tokens, block kit), Discord (webhooks, bot tokens, embeds), Microsoft Teams (adaptive cards, webhooks), the BaseChatDriver abstraction, retry logic, or multi-channel chat routing. Covers @stacksjs/chat.
+description: Use when implementing chat messaging in Stacks - sending messages to Slack (webhooks, bot tokens, block kit), Discord (webhooks, bot tokens, embeds), Microsoft Teams (adaptive cards, webhooks), the BaseChatDriver abstraction, retry logic, multi-channel chat routing, or READING a person's conversations from iMessage, Slack and Discord and archiving them there (the inbox drivers). Covers @stacksjs/chat.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -342,6 +342,56 @@ async function sendCard(webhookUrl: string, card: TeamsAdaptiveCard, summary?: s
 - `driver` -- pre-instantiated singleton
 - `send()`, `sendWebhook()`, `sendCard()`, `configure()` functions
 
+## Inbox drivers (reading and archiving)
+
+`send()` pushes messages out. The inbox drivers go the other way: they list a
+person's conversations, read messages, notice new ones (a per-conversation
+`cursor`), and archive a conversation *in the real app* as far as the provider
+allows. Source: `chat/src/inbox/`. One interface, `InboxDriver`:
+
+```typescript
+import { inbox } from '@stacksjs/chat'
+
+const drivers = [
+  inbox.createInboxDriver('imessage', {}),                                 // chat.db, needs Full Disk Access
+  inbox.createInboxDriver('slack', { token: env.SLACK_USER_TOKEN }),       // xoxp user token
+  inbox.createInboxDriver('discord', { token: env.DISCORD_BOT_TOKEN, userId }), // bot token
+]
+for (const driver of drivers) {
+  if (!(await driver.status()).connected) continue
+  for (const c of await driver.conversations()) {
+    const fresh = await driver.messages(c.id, { after: lastCursor[c.id] })  // oldest first
+    if (wantArchived) await driver.archive(c.id)
+  }
+}
+```
+
+What archiving does is part of every conversation (`conversation.archive`):
+
+| Provider | `mode` | Effect in the real app |
+|---|---|---|
+| iMessage | `confirm` | Opens the conversation in Messages at Delete Conversation; the person confirms. Apple has no API, and editing chat.db is ignored or synced everywhere. |
+| Slack DM / group DM | `native` | `conversations.close`; Slack reopens it when someone writes. `unarchive` reopens. |
+| Slack public channel | `native` | `conversations.leave`; `unarchive` rejoins. |
+| Slack private channel | `unsupported` | Untouched: leaving would need a re-invite. |
+| Discord thread | `native` | Archived in Discord (reopens on a new post). |
+| Discord channel | `unsupported` | Discord cannot hide a channel for one person. |
+
+For iMessage, pass a `controller` (`{ remove(names, url, confirm), recover(names) }`)
+whenever the app can drive Messages by accessibility: it receives every label
+Messages might give the row (contact name, formatted number, handle) and should
+act on the row found by name, never on the current selection - the driver's
+fallback menu script does the latter. With a controller, `unarchive` recovers
+from Recently Deleted, and `confirmDeletes: true` accepts Messages' alert too.
+Attic (`~/Code/Apps/attic`, `app/Desktop/messages-control.swift`) is the reference.
+
+Discord personal DMs are deliberately absent: only a user token reads them, and
+automating a user account breaks Discord's terms. Reactions are separate
+`kind: 'reaction'` messages with `targetId` and an emoji `reaction`; Slack and
+Discord attachments carry a remote `url` that `driver.attachment()` fetches with
+the right credentials. The HTTP drivers take an injectable `fetch`, which is how
+`tests/inbox.test.ts` exercises them against API-shaped fixtures.
+
 ## Retry Logic
 
 All three drivers implement `sendWithRetry()`:

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

@@ -68,6 +68,40 @@ buddy deploy                    # deploy to cloud
    - Tags: Environment, Project, ManagedBy
    - OnFailure: ROLLBACK
 
+## CloudFront origin failover (AWS)
+
+Off unless configured. Two shapes, both under `tsCloud.infrastructure` in `config/cloud.ts`, both
+generated by ts-cloud into a CloudFront origin group (primary + secondary, failover status codes):
+
+```typescript
+storage: {
+  public: {
+    website: true,
+    // Replica of this bucket in another region, replicated with S3 replication.
+    failover: { region: 'us-west-2', connectionAttempts: 1, connectionTimeout: 3 },
+  },
+},
+cdn: {
+  // A standalone distribution: any second origin, string or { domain, originPath, connection* }.
+  frontend: { origin: 'a.s3.us-east-1.amazonaws.com', failoverOrigin: 'b.s3.us-west-2.amazonaws.com' },
+},
+```
+
+- Bucket `failover` needs CloudFront in front of the bucket: a website bucket, `dns.domain`, and SSL
+  (`ssl.certificateArn`, or `ssl.enabled` + `dns.hostedZoneId`). Without them generation throws.
+- Default codes: bucket failover `[403, 404, 500, 502, 503, 504]` (OAC answers a missing object
+  with 403); `cdn` failover `[500, 502, 503, 504]`. CloudFront accepts 400, 403, 404, 416, 429,
+  500, 502, 503, 504 and nothing else.
+- Only GET/HEAD/OPTIONS behaviors may target the group. Compute routes (`/api/*`, which accept
+  writes) stay on their own origin; a group behind a write-capable behavior throws at generation.
+- `connectionAttempts` (1-3) / `connectionTimeout` (1-10 s) on the primary decide how fast an
+  unreachable primary fails over. CloudFront's default is 3 x 10 s.
+- The replica is created by the deploy, not the stack (a stack only makes buckets in its own
+  region). Template metadata `TsCloud::StorageFailover` lists replicas; the deploy runs
+  `ensureFailoverReplicaBuckets` before the stack, `grantFailoverReplicaAccess` and
+  `seedFailoverReplicas` after (all from `@stacksjs/ts-cloud`).
+- Docs: `docs/guide/cloud/origin-failover.md`.
+
 ## Hetzner and SSH targets
 
 Both deploy the same way once a host exists: build each site, package a release tarball, copy it
@@ -256,6 +290,8 @@ Stack naming: `{slugified-app-name}-cloud`
 - 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
+- Origin failover only retries GET, HEAD and OPTIONS on a cache miss; it does not protect writes,
+  and the failover replica outlives `buddy cloud:remove`
 - 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`

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

@@ -92,8 +92,8 @@ transcode is minutes, a vision call is a round trip to a third party. So an
 upload dispatches and the dashboard shows state.
 
 - `storage_item_tasks`, one row per `(disk, path, kind)`, kind being
-  `optimize` (images, via `ts-images`), `transcode` (video, via `ts-videos`) or
-  `tag` (a vision model). They succeed and fail independently, which is why this
+  `optimize` (images, via `ts-images`), `transcode` (video, via `ts-videos`),
+  `tag` (a vision model) or `preview` (the file manager thumbnail, #308). They succeed and fail independently, which is why this
   is not a column on `storage_items` - a video whose transcode finished and
   whose tagging failed is a normal state.
 - `dispatchDashboardFileTasks` decides from the CONTENT TYPE what a file needs.
@@ -107,10 +107,24 @@ upload dispatches and the dashboard shows state.
   and the queue answer different questions - the queue decides whether to retry,
   the row is what somebody looking at the file sees.
 - `POST /files/reprocess` re-runs everything, or the kinds you name.
+- `preview` is decided by `file-preview.ts`, from the type the file CLAIMS
+  (the disk's answer, or the extension when that is `octet-stream`), and the
+  job checks the bytes agree before drawing. Images, WAV waveforms and TrueType
+  specimens become `.variants/<path>/preview.png`; text becomes a
+  `preview.txt` snippet. SVG, video, compressed audio, PDF, CFF/WOFF fonts,
+  HEIC and TIFF are recorded `skipped` with the reason in `error` - no
+  homegrown renderer draws them, and SVG is never rasterized. Never add a
+  renderer that shells out: that is the rule the skips exist to keep.
+- `skipped` is terminal: `runTask` records a thrown `StorageTaskSkipped`
+  without rethrowing, so the queue does not retry it, and `aggregateTaskState`
+  ignores it unless nothing else applied.
 
 Derivatives are written back to the same disk under `.variants/<path>/`. The
 leading dot keeps them out of the listing, which skips hidden components - a
 folder of thirty derivatives beside every photo makes the browser useless.
+A rename or delete through the dashboard moves or removes that folder with the
+file, after the storage operation succeeds and best effort, since the task rows
+already followed and a missing derivative is regenerated by reprocessing.
 
 ### Remote commands (stacksjs/stacks#960)
 

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-database
-description: Use when working with databases in a Stacks application - configuring connections, running queries, migrations, seeding, SQL helpers, or using SQLite/MySQL/PostgreSQL/DynamoDB. Covers @stacksjs/database, bun-query-builder, config/database.ts, and the database/ migrations directory.
+description: Use when working with databases in a Stacks application - configuring connections, running queries, migrations, seeding, SQL helpers, or using SQLite/Turso/MySQL/PostgreSQL/DynamoDB. Covers @stacksjs/database, bun-query-builder, config/database.ts, and the database/ migrations directory.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -12,7 +12,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Database package: `storage/framework/core/database/src/`
 - Configuration: `config/database.ts`
 - QB config: `config/query-builder.ts`
-- Migrations: `database/migrations/` (231 migration files, `.sql` format)
+- Migrations: `database/migrations/` (233 migration files, `.sql` format)
 - QB state: `.qb/`
 - ORM: `storage/framework/orm/`
 
@@ -60,6 +60,7 @@ Database.fromEnv()                  // From env vars (DB_CONNECTION, DB_DATABASE
 ## Factory Functions (database.ts)
 - `createDatabase(options: DatabaseOptions): Database`
 - `createSqliteDatabase(database: string, options?): Database`
+- `createTursoDatabase(url: string, authToken?: string, options?): Database`
 - `createPostgresDatabase(connection: DatabaseConnectionConfig, options?): Database`
 - `createMysqlDatabase(connection: DatabaseConnectionConfig, options?): Database`
 
@@ -154,6 +155,7 @@ interface DatabaseOptions {
 
 ```typescript
 interface SqliteConfig { database: string, prefix?: string }
+interface TursoConfig { url: string, authToken?: string, prefix?: string }
 interface MysqlConfig { name: string, host?: string, port?: number, username?: string, password?: string, prefix?: string, charset?: string, collation?: string }
 interface PostgresConfig { name: string, host?: string, port?: number, username?: string, password?: string, prefix?: string, schema?: string, sslMode?: 'disable' | 'require' | 'verify-ca' | 'verify-full' }
 interface DynamoDbConfig { key: string, secret: string, region?: string, prefix?: string, endpoint?: string, tableName?: string, singleTable?: { enabled?, pkAttribute?, skAttribute?, entityTypeAttribute?, keyDelimiter?, gsiCount? } }
@@ -256,11 +258,30 @@ Entity-centric API for single-table design:
 - `buddy seed` -- seed database
 - `buddy generate:migrations` -- generate migration diffs from models
 
+## Turso / libSQL (`DB_CONNECTION=turso`, alias `libsql`)
+
+SQLite's SQL on a Turso or `sqld` server. Configure `TURSO_DATABASE_URL`
+(`libsql://<db>-<org>.turso.io`, or `http://127.0.0.1:8080` for `turso dev`) and
+`TURSO_AUTH_TOKEN` (a secret, never logged).
+
+- Everything that renders SQL or DDL treats it as `sqlite`: `dialectCapabilities('turso').wire === 'sqlite'`,
+  `getDatabaseDialect()` returns `'sqlite'`, and it shares the SQLite migration corpus and
+  `model-snapshot.sqlite.json`. Switching between `sqlite` and `turso` needs no regeneration.
+- The transport is bun-query-builder's: `setConfig({ dialect: 'sqlite', database: { url, authToken } })`
+  with a libSQL URL selects its dependency-free Hrana-over-HTTP connection (`createLibSQLSQL`).
+- Code that opens the database FILE must ask `isLibsqlDriver(driver)` first - there is none. The SQLite
+  migration preprocessor reads an in-memory replica of the server's schema instead
+  (`loadLibsqlSchemaMirror` in migrations.ts), and the migration lock is a row in
+  `stacks_migration_lock` (`acquireLibsqlMigrationLock`), since migrating hosts share no filesystem.
+- libSQL rejects SQLite's double-quoted-string fallback, so a statement naming a missing column fails
+  instead of storing the column name as text. `tests/corpus-rebuild-sources.test.ts` guards the corpus.
+- Inside `transaction()`, write through the `tx` handle; model writes use their own connection.
+
 ## config/database.ts Shape
 ```typescript
 {
   default: env.DB_CONNECTION || 'mysql',
-  connections: { sqlite, mysql, postgres, dynamodb },
+  connections: { sqlite, turso, mysql, singlestore, vitess, postgres, dynamodb },
   migrations: 'migrations',
   migrationLocks: 'migration_locks',
   queryLogging: {

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

@@ -75,10 +75,14 @@ a versioned `STACKS_DEPLOY_PREVIEW_JSON=` line for API and tool consumers.
 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
+4. **Failover replicas** (only when a bucket sets `failover`): creates each replica bucket in its
+   region before the stack, since the stack cannot and its replication rule needs it
+5. **Deploy**: creates or updates the CloudFormation stack
    - Capabilities: CAPABILITY_IAM, CAPABILITY_NAMED_IAM
    - OnFailure: ROLLBACK
    - Tags: Environment, Project, ManagedBy
+6. **Failover access**: lets the new distribution read each replica, then copies across objects
+   that predate replication
 
 **Hetzner and SSH**
 
@@ -190,4 +194,6 @@ buddy cloud:cleanup           # clean retained resources
   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
+- A failover replica bucket (`infrastructure.storage.<name>.failover`) lives outside the stack, so
+  `buddy cloud:remove` leaves it, and its data, behind on purpose
 - For infrastructure details, see the `stacks-cloud` skill

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

@@ -240,6 +240,15 @@ uses App Store Connect API-key authentication for validation/upload.
 Start with `validate-only: true`. Upload only after the signed artifact passes
 local launch and UI QA.
 
+To package on a developer machine without importing distribution keys into the
+login keychain, generate keys and certificates with `buddy desktop:apple:csr`
+and `buddy desktop:apple:provision --apply`, import the two `.p12` files into a
+throwaway keychain file, and point `--keychain <path>` (or `APPLE_KEYCHAIN`) at
+it. `codesign` and `productbuild` then look for identities in that file only,
+so the search list never changes. The Mac App Distribution identity is named
+`3rd Party Mac Developer Application: ...` and the installer one
+`3rd Party Mac Developer Installer: ...`.
+
 Human-owned prerequisites that Buddy does not pretend to automate:
 
 - Apple Developer Program enrollment and agreement acceptance
@@ -257,6 +266,7 @@ Repository variables:
 - `DESKTOP_URL`
 - `APPLE_APP_SIGNING_IDENTITY`
 - `APPLE_INSTALLER_SIGNING_IDENTITY`
+- `APPLE_KEYCHAIN` (local only, optional): sign from this keychain file instead of the search list
 
 Repository secrets:
 

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

@@ -252,7 +252,7 @@ Default configurations provided at `storage/framework/defaults/ide/`:
 - `vscode/.vscode/extensions.json` -- Recommended extensions
 - `vscode/.vscode/settings.json` -- Editor settings
 - `vscode/.vscode/stacks.code-snippets` -- Code snippets
-- `vscode/package.json` -- VS Code extension manifest
+- `vscode/package.json` -- the Stacks extension (`Stacks.vscode-stacks`). Self-contained: it installs no extension pack and depends on no extension. It builds in `.stx` support from `@stacksjs/stx-vscode` (the stx extension's language support as a library; the standalone stx extension, `Stacks.vscode-stx`, stands down next to it), pickier lint/format/fix-all through the project's own pickier, and env file hover decryption and `buddy env:*` commands. Run `bun run sync:stx` there after updating `@stacksjs/stx-vscode`; never map `*.stx` to `html` in `files.associations`, which takes `.stx` files away from the stx language.
 
 ### JetBrains
 - `.idea/` config (ESLint, modules, VCS, web resources)

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-migrations
-description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 231 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 233 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -119,6 +119,6 @@ The framework includes migrations for all built-in models:
 - Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration
 - If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`
 - `--seed` flag after `migrate:fresh` seeds the database with factory data
-- 231 migration files exist by default for all framework models
+- 233 migration files exist by default for all framework models
 - SQLite >= 3.47.2 is required (system requirement)
 - For the database API (queries, connections), see the `stacks-database` skill

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-models
-description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 103 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
+description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 104 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -88,6 +88,7 @@ generated model types stay precise.
 | `guarded` | Block mass assignment |
 | `hidden` | Exclude from JSON serialization (passwords, tokens) |
 | `foreignKey` | Disable, infer, or configure the FK constraint |
+| `personal` | Personal data: exported by `gdpr:export`, anonymized by erasure and retention. `true`, or `{ anonymize?, export? }`. See "Personal data (GDPR)" below |
 | `factory` | `(faker, attributes) => value`, used by seeders and tests. `attributes` holds what this record's earlier-declared factories produced, so one value can depend on another: `(faker, { discountType }) => ...` |
 | `validation` | `{ rule, message? }` - `rule` from `schema`, `message` keyed by rule name |
 
@@ -107,6 +108,7 @@ generated model types stay precise.
 | `observe` | Emits `{model}:created` / `:updated` / `:deleted` events |
 | `billable` | Stripe methods (`checkout()`, `activeSubscription()`, ...) |
 | `taggable` / `categorizable` / `commentable` / `likeable` | Pivot tables and their relation methods |
+| `gdpr` | Whose data the rows are (`subject`), what erasure does (`erasure`), how long rows live (`retention`), and why (`basis`, `purpose`). See "Personal data (GDPR)" below |
 
 Also at the top level: `indexes: [{ name, columns, unique?, where? }]` for
 composite and partial-unique indexes, and `dashboard: { highlight: true }` to
@@ -212,6 +214,40 @@ scopes: {
 },
 ```
 
+## Personal data (GDPR)
+
+Declared on the model, read by access exports, erasure, retention and the
+processing register (stacksjs/stacks#365). Full guide: `docs/guide/gdpr.md`.
+
+```ts
+belongsTo: ['Customer'],
+traits: {
+  gdpr: {
+    subject: { via: 'Customer' },   // or 'user_id', ['a_id', 'b_id'], { column, where }, { email: 'col' }
+    erasure: 'anonymize',           // default; or 'delete' | 'keep'
+    retention: { days: 3650, action: 'anonymize' }, // optional; column defaults to created_at
+    basis: 'legal_obligation',
+    purpose: 'Order fulfilment, kept for tax and accounting',
+  },
+},
+attributes: {
+  deliveryAddress: { personal: true, validation: { rule: schema.string() } },
+},
+```
+
+- `subject` is derived when left out: `id` on `User`, the `belongsTo: ['User']`
+  foreign key elsewhere. A `via` parent must itself declare a subject.
+- Anonymization writes NULL to nullable columns and a typed placeholder to
+  `NOT NULL` ones (`erased-<id>` when unique). A `NOT NULL` enum or timestamp
+  needs `personal: { anonymize: <value> }`, or every request refuses to run.
+- A model that `belongsTo: ['User']` and declares nothing is **unclassified**:
+  erasure does not reach it and `buddy gdpr:register` lists it. Classify it, even
+  as `erasure: 'keep'`. `core/orm/tests/gdpr.test.ts` fails if a built-in one is.
+- Engine: `exportSubjectData`, `eraseSubject({ dryRun })`, `pruneRetainedData`,
+  `resolveGdprPlan`, `renderProcessingRegister`, all from `@stacksjs/orm`.
+  Commands: `buddy gdpr:export|erase|prune|register|register:check`. Every
+  request writes a `gdpr_requests` row (the `GdprRequest` model).
+
 ## Workflow
 
 ```sh
@@ -265,7 +301,7 @@ pass `--allow-protected` to override.
 ## Built-in models by category
 
 The ones below are worth knowing by name. They are a selection, not the set:
-`storage/framework/defaults/app/Models/` holds 103, and that directory is the
+`storage/framework/defaults/app/Models/` holds 104, and that directory is the
 authority. This section said "All 62 built-in models by category" while
 listing fewer than that against 102 on disk, so an agent reading to the end
 had no way to tell it was short.

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-orm
-description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 103 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
+description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 104 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -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/` (103 models)
+- Model definitions: `storage/framework/defaults/app/Models/` (104 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-security/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-security
-description: Use when implementing security in Stacks - password hashing (bcrypt/argon2), app key generation, AES encryption/decryption, hash verification, rehashing detection, or security configuration (firewall, rate limiting, IP allowlists). Covers @stacksjs/security and config/security.ts.
+description: Use when implementing security in Stacks - password hashing (bcrypt/argon2), app key generation, AES encryption/decryption, hash verification, rehashing detection, security configuration (firewall, rate limiting, IP allowlists), or GDPR data-subject requests (access export, erasure, retention, the processing register). Covers @stacksjs/security, config/security.ts and the GDPR layer in @stacksjs/orm.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -116,6 +116,33 @@ interface HashMakeOptions {
 }
 ```
 
+## Personal data and GDPR
+
+Data-subject requests are driven by model declarations, not by code you write per
+request: `personal: true` on an attribute and `traits.gdpr` on the model (see
+`stacks-models`, "Personal data (GDPR)", and `docs/guide/gdpr.md`).
+
+```bash
+buddy gdpr:export <id|email> --out file.json   # access (Art. 15/20)
+buddy gdpr:erase <id|email> --dry-run          # then without --dry-run, or --yes
+buddy gdpr:prune --dry-run                     # retention; PruneRetainedDataJob runs daily
+buddy gdpr:register && buddy gdpr:register:check
+```
+
+```typescript
+import { eraseSubject, exportSubjectData, pruneRetainedData } from '@stacksjs/orm'
+```
+
+- `GET /me/data-export` (auth bundle, `auth` middleware, 3/hour) is the
+  self-service export; the subject is always the caller.
+- Erasure runs in one transaction with its `gdpr_requests` audit row, writes only
+  rows it matched to the subject, then revokes tokens and destroys sessions.
+- Erasure of the `User` row anonymizes rather than deletes: orders, payments and
+  memberships still point at it. Consent and suppression records are kept by
+  declaration, since honouring an opt-out needs the address.
+- The audit ledger stores counts, never values. Do not log export payloads with
+  `log`, which writes to disk in production.
+
 ## Gotchas
 - Default hashing is bcrypt with 12 rounds — sufficient for most applications
 - `needsRehash()` compares current hash options against provided options — useful after config changes

package/app/Actions/Auth/DataExportAction.test.ts

@@ -0,0 +1,84 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { existsSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import process from 'node:process'
+
+/**
+ * GET /me/data-export, at the action seam, over the framework's own model
+ * declarations and a real SQLite database holding two users.
+ */
+
+const DB_PATH = join(tmpdir(), `stacks-data-export-${process.pid}.sqlite`)
+process.env.DB_CONNECTION = 'sqlite'
+process.env.DB_DATABASE_PATH = DB_PATH
+process.env.APP_ENV = 'test'
+
+const { acquireDbConfigLock, db, ensureDatabaseConfigLoaded, initializeDbConfig } = await import('@stacksjs/database')
+const { default: DataExportAction } = await import('./DataExportAction')
+
+async function forceConfig(): Promise<void> {
+  const release = await acquireDbConfigLock()
+  try {
+    await ensureDatabaseConfigLoaded()
+    initializeDbConfig({
+      app: { env: 'test' },
+      database: { default: 'sqlite', connections: { sqlite: { database: DB_PATH, prefix: '' } } },
+    })
+  }
+  finally {
+    release()
+  }
+}
+
+function requestAs(user: { id: number } | undefined): RequestInstance {
+  return { user: async () => user } as unknown as RequestInstance
+}
+
+beforeAll(async () => {
+  for (const suffix of ['', '-wal', '-shm']) {
+    if (existsSync(`${DB_PATH}${suffix}`))
+      unlinkSync(`${DB_PATH}${suffix}`)
+  }
+  await forceConfig()
+  await db.unsafe(`CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, uuid TEXT, name TEXT, email TEXT, password TEXT, avatar TEXT, created_at TEXT, updated_at TEXT)`).execute()
+  await db.unsafe(`CREATE TABLE gdpr_requests (id INTEGER PRIMARY KEY AUTOINCREMENT, uuid TEXT, type TEXT NOT NULL, subject_id INTEGER, actor TEXT, status TEXT NOT NULL DEFAULT 'completed', summary TEXT, occurred_at TEXT NOT NULL, created_at TEXT, updated_at TEXT)`).execute()
+  await db.unsafe(`INSERT INTO users (name, email, password) VALUES ('Ada Lovelace', 'ada@example.com', 'hash-ada'), ('Bob Byron', 'bob@example.com', 'hash-bob')`).execute()
+})
+
+afterAll(() => {
+  for (const suffix of ['', '-wal', '-shm']) {
+    try {
+      if (existsSync(`${DB_PATH}${suffix}`))
+        unlinkSync(`${DB_PATH}${suffix}`)
+    }
+    catch {
+      // best effort
+    }
+  }
+})
+
+describe('DataExportAction', () => {
+  test('downloads the caller\'s own data, without the password hash, and records the request', async () => {
+    await forceConfig()
+    const res = await DataExportAction.handle(requestAs({ id: 2 })) as Response
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Disposition')).toMatch(/^attachment; filename="personal-data-\d{4}-\d{2}-\d{2}\.json"$/)
+    expect(res.headers.get('Cache-Control')).toBe('private, no-store')
+
+    const body = await res.json() as { subject: { id: number }, data: Record<string, Array<Record<string, unknown>>> }
+    expect(body.subject).toEqual({ id: 2 })
+    expect(body.data.User).toEqual([expect.objectContaining({ id: 2, name: 'Bob Byron', email: 'bob@example.com' })])
+    expect(JSON.stringify(body)).not.toContain('hash-bob')
+    expect(JSON.stringify(body)).not.toContain('ada@example.com')
+
+    const audit = await (db as any).selectFrom('gdpr_requests').selectAll().execute()
+    expect(audit).toEqual([expect.objectContaining({ type: 'access', subject_id: 2, actor: 'api:user:2' })])
+  })
+
+  test('refuses an unauthenticated caller', async () => {
+    const res = await DataExportAction.handle(requestAs(undefined)) as Response
+    expect(res.status).toBe(401)
+  })
+})

package/app/Actions/Auth/DataExportAction.ts

@@ -0,0 +1,40 @@
+import { Action } from '@stacksjs/actions'
+import { log } from '@stacksjs/logging'
+import { exportSubjectData } from '@stacksjs/orm'
+import { response } from '@stacksjs/router'
+
+/**
+ * Self-service data export: the signed-in user downloads their own personal
+ * data (GDPR Articles 15 and 20, stacksjs/stacks#365).
+ *
+ * The subject is always the authenticated caller - there is no id parameter
+ * to tamper with. The export carries only what the models declare personal,
+ * plus ids, timestamps and the purpose/basis/retention each model states.
+ * Each one is recorded in `gdpr_requests` with the caller as actor, and the
+ * route is rate-limited because an export reads every table the user touches.
+ */
+export default new Action({
+  name: 'DataExportAction',
+  description: 'Download the authenticated user\'s personal data',
+  method: 'GET',
+  async handle(request: RequestInstance) {
+    const user = await request.user()
+
+    if (!user?.id)
+      return response.unauthorized('Authentication required')
+
+    const result = await exportSubjectData(user.id, { actor: `api:user:${String(user.id)}` })
+    log.info(`[gdpr] access export served to user ${String(user.id)}`)
+
+    const day = result.generatedAt.slice(0, 10)
+    return new Response(`${JSON.stringify(result, null, 2)}\n`, {
+      status: 200,
+      headers: {
+        'Cache-Control': 'private, no-store',
+        'Content-Disposition': `attachment; filename="personal-data-${day}.json"`,
+        'Content-Type': 'application/json; charset=utf-8',
+        'X-Content-Type-Options': 'nosniff',
+      },
+    })
+  },
+})

package/app/Actions/Dashboard/Content/FileReprocessAction.ts

@@ -5,7 +5,7 @@ import { DashboardFileError, reprocessDashboardFile } from './file-manager'
 
 export default new Action({
   name: 'FileReprocessAction',
-  description: 'Re-runs the background processing for a file: image variants, video renditions, AI tags.',
+  description: 'Re-runs the background processing for a file: image variants, video renditions, AI tags, previews.',
   method: 'POST',
   async handle(request: RequestInstance) {
     try {