@stacksjs/defaults 0.75.109 → 0.75.110

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-middleware
-description: Use when working with middleware in a Stacks application - defining middleware, applying to routes, middleware aliases, parameterized middleware, groups, or the middleware execution pipeline. Covers the Middleware class, app/Middleware.ts alias registry, and all 22 default middleware files.
+description: Use when working with middleware in a Stacks application - defining middleware, applying to routes, middleware aliases, parameterized middleware, groups, or the middleware execution pipeline. Covers the Middleware class, app/Middleware.ts alias registry, and the default middleware files.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -14,7 +14,7 @@ Built into `@stacksjs/router`. Middleware intercepts requests before they reach
 - Middleware class: `storage/framework/core/router/src/middleware.ts`
 - Execution engine: `storage/framework/core/router/src/stacks-router.ts`
 - Alias registry: `app/Middleware.ts`
-- Default middleware: `storage/framework/defaults/app/Middleware/` (22 files)
+- Default middleware: `storage/framework/defaults/app/Middleware/`
 - Auth middleware (standalone): `storage/framework/core/auth/src/middleware.ts`
 - Tests: `storage/framework/core/router/tests/middleware.test.ts`
 
@@ -61,9 +61,9 @@ export default new Middleware({
 ### Short-Circuiting
 
 Middleware can stop request processing by:
-1. **Throwing an Error with `statusCode`** — converted to HTTP error response
-2. **Throwing a Response** — returned directly to client
-3. **Returning void** — continues to next middleware
+1. **Throwing an Error with `statusCode`** - converted to HTTP error response
+2. **Throwing a Response** - returned directly to client
+3. **Returning void** - continues to next middleware
 
 ```typescript
 // Error with status code
@@ -178,7 +178,7 @@ calling `handle`, sorts the combined page chain by priority, writes parameters
 to `request._middlewareParams`, supports exact aliases containing colons and
 `!alias` inversion, and fails closed when an alias is missing.
 
-Group middleware is prepended to all routes inside the callback. Groups can be nested — middleware accumulates.
+Group middleware is prepended to all routes inside the callback. Groups can be nested - middleware accumulates.
 
 ### Parameterized Middleware
 
@@ -198,7 +198,7 @@ Parameters are stored on `request._middlewareParams[middlewareName]` and parsed
 | Alias | Class | Priority | Description |
 |-------|-------|----------|-------------|
 | `maintenance` | Maintenance | 0 | Checks maintenance mode, supports secret bypass URL and IP allowlist |
-| `auth` | Auth | 1 | Validates bearer token, sets authenticated user on request |
+| `auth` | Auth | 1 | Resolves bearer/token cookie/session and stamps the authenticated user |
 | `api` | Api | 1 | Validates request accepts JSON |
 | `guest` | Guest | 1 | Ensures user is NOT authenticated (for login/register pages) |
 | `env` | Env | 1 | Checks current environment |
@@ -209,11 +209,11 @@ Parameters are stored on `request._middlewareParams[middlewareName]` and parsed
 | `permission` | Permission | 3 | Checks user permissions (parameterized: `permission:edit-posts`) |
 | `team` | Team | 3 | Ensures user belongs to a team (parameterized: `team:teamId`) |
 | `verified` | EnsureEmailIsVerified | 4 | Verifies email is confirmed |
-| `throttle` | Throttle | — | Rate limiting (parameterized: `throttle:60,1` or `throttle:100,5m`) |
-| `env:local` | EnvLocal | — | Only allows local environment |
-| `env:development` / `env:dev` | EnvDevelopment | — | Only allows development |
-| `env:staging` | EnvStaging | — | Only allows staging |
-| `env:production` / `env:prod` | EnvProduction | — | Only allows production |
+| `throttle` | Throttle | - | Rate limiting (parameterized: `throttle:60,1` or `throttle:100,5m`) |
+| `env:local` | EnvLocal | - | Only allows local environment |
+| `env:development` / `env:dev` | EnvDevelopment | - | Only allows development |
+| `env:staging` | EnvStaging | - | Only allows staging |
+| `env:production` / `env:prod` | EnvProduction | - | Only allows production |
 
 ### Environment Negation Variants
 
@@ -242,6 +242,12 @@ User middleware in `app/Middleware/` always takes precedence over framework defa
 ## Representative Implementations
 
 ### Auth Middleware
+
+The default `defaults/app/Middleware/Auth.ts` resolves a parsed bearer first,
+then the configured token cookie, then `session_id`. It loads the user, calls
+`Auth.setUser`, stamps `_authenticatedUser`, and stamps `_currentAccessToken`
+for token authentication. The following is only a minimal custom bearer guard:
+
 ```typescript
 export default new Middleware({
   name: 'Auth',
@@ -299,12 +305,22 @@ import { authMiddleware, authMiddlewareHandler } from '@stacksjs/auth'
 ```
 
 ## Gotchas
-- **Priority DOES order the chain** — entries are sorted by `priority` (lower first, default 10) before execution, so CORS can precede auth regardless of the order they were attached in. An earlier version of this file said otherwise. A non-finite or negative value is clamped to the default and warned about once
-- **`terminate()` doesn't exist** — some docs reference it, but it's not in the actual `MiddlewareConfig` interface
-- **Two auth middleware implementations** — defaults version (basic token check) and `@stacksjs/auth` version (full user loading)
-- **EnvNot* files have no aliases** — reachable by class name, or as `'!env:production'` and friends
-- **The alias map merges over the defaults** — an app's `app/Middleware.ts` adds to and overrides them rather than replacing the set
-- **Middleware is cached after first load** — changes require server restart
-- **User overrides take precedence** — `app/Middleware/Auth.ts` replaces the framework default completely
-- **Group middleware accumulates** — nested groups combine all parent middleware
-- **Request body parsed before middleware** — Laravel-style methods (`.input()`, `.query`, `.file()`) are available in middleware
+- **Priority DOES order the chain** - entries are sorted by `priority` (lower first, default 10) before execution, so CORS can precede auth regardless of the order they were attached in. An earlier version of this file said otherwise. A non-finite or negative value is clamped to the default and warned about once
+- **`terminate()` doesn't exist** - some docs reference it, but it's not in the actual `MiddlewareConfig` interface
+- **Auth entrypoints** - default Auth also loads/stamps the user and current token; inspect its cookie/session branches before replacing it
+- **EnvNot* files have no aliases** - reachable by class name, or as `'!env:production'` and friends
+- **The alias map merges over the defaults** - an app's `app/Middleware.ts` adds to and overrides them rather than replacing the set
+- **Middleware is cached after first load** - changes require server restart
+- **User overrides take precedence** - `app/Middleware/Auth.ts` replaces the framework default completely
+- **Group middleware accumulates** - nested groups combine all parent middleware
+- **Request body parsed before middleware** - Laravel-style methods (`.input()`, `.query`, `.file()`) are available in middleware
+
+
+## Source verification
+
+Use `storage/framework/defaults/app/Middleware/Auth.ts` for the complete
+native authentication guard and `core/auth/tests/auth-middleware-entrypoints.test.ts`
+for HTTP entrypoint coverage. Shared page middleware wiring is in
+`core/actions/src/dev/views.ts` and `core/buddy/src/production-server.ts`;
+consult their loadMiddlewareHandlers wiring for page redirects and
+Response handling before assuming an API refusal behaves identically in HTML.

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

@@ -11,7 +11,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 Schema change management via migration files.
 
 ## Key Paths
-- Migration files: `database/migrations/` (96+ files)
+- Migration files: `database/migrations/`
 - Database config: `config/database.ts`
 - Model snapshot: `storage/framework/database/model-snapshot.<dialect>.json`
 
@@ -23,7 +23,6 @@ buddy migrate --diff                # show SQL without running
 buddy migrate --auth                # include auth tables
 buddy migrate:fresh                 # drop ALL tables and re-migrate
 buddy migrate:fresh --seed          # drop, migrate, then seed
-buddy dns:pull                      # live zone as a config/dns.ts block
 buddy make:migration <name>         # create new migration file
 buddy seed                          # seed database
 buddy generate:migrations           # generate migrations from model diffs
@@ -68,7 +67,7 @@ without changing application ignore rules or staging SQL contents. Review and
 stage migrations with their models and snapshot normally; do not add per-file
 `.gitignore` exceptions. Dry-run previews never change the Git index.
 
-## Built-in Migrations (96+)
+## Built-in migration families
 
 The framework includes migrations for all built-in models:
 
@@ -112,12 +111,37 @@ The framework includes migrations for all built-in models:
 
 ## Workflow
 
-1. Define/modify model in `storage/framework/defaults/app/Models/` or `app/Models/`
+1. Define/modify the app model under `app/Models/`; edit defaults only when working on the framework
 2. Run `buddy generate:migrations` to generate SQL diffs
 3. Review generated migration files
 4. Run `buddy generate:migrations` again and confirm there is no remaining diff
 5. Run `buddy migrate` to apply
-6. Commit the generated SQL and `storage/framework/database/model-snapshot.<dialect>.json`
+6. Review models, generated SQL, and `storage/framework/database/model-snapshot.<dialect>.json` together; commit when authorized
+
+## Native migration and schema tooling
+
+Models, named pivot schemas, indexes, foreign-key actions, auth/queue/notification
+support tables, and optional feature selection contribute to schema management.
+The model diff uses the dialect snapshot; live schema inspection is a separate
+drift check. A stable no-op generation is not proof that an independently edited
+production database matches the declaration.
+
+Inspect native schema, FK and unique-index audits through the database package:
+`auditSchemaDrift`, `auditForeignKeys`, `auditUniqueIndexes`, and their associated
+CLI commands. Read `buddy list` and each command's help for the current flags.
+Safe schema helpers include `addColumnSafely`, `renameColumnSafely`, and
+`backfillInBatches`; they have dialect-specific preconditions and are not a
+universal zero-downtime guarantee.
+
+The runner tracks applied migrations, locks concurrent runs, selects the active
+dialect corpus, and preserves application-owned tables when optional bundles
+are excluded. Removing a feature from generation is not permission to drop its
+live data. MySQL/PostgreSQL/Vitess/Turso require their own SQL and evidence
+checks; never run SQLite SQL on a different provider because its filename exists.
+
+Source: `core/database/src/{migrations,model-sources,migration-ledger,
+safe-migrations,schema-drift,fk-audit,unique-audit}.ts`, `config/query-builder.ts`,
+and their retained database tests.
 
 ## Gotchas
 - `migrate:fresh` drops ALL tables — only use in development

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-mobile
-description: Use when building native iOS or Android applications from a Stacks and STX codebase with Craft, including mobile configuration, native capabilities, safe areas, haptics, sharing, and mobile build output.
+description: Use when building native iOS or Android applications from Stacks and STX with Craft, mobile configuration, native capabilities, device search, health, route recording, safe areas, haptics, or mobile build output. Covers @stacksjs/mobile and the mobile build pipeline.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, Xcode for iOS project generation
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -101,7 +101,7 @@ what should differ: `swipeBack` (`'router'`, the stx router's interactive
 swipe, or `'webview'` for WebKit's history swipe), `keyboardAccessory` (off),
 `allowsLinkPreview` (off), `disableZoom` (on), `splashMaxSeconds` (3),
 `requestTimeoutSeconds` (10), `backgroundRefresh: { enabled, identifier?,
-minimumIntervalMinutes? }` and `associatedDomains` (universal links). Leave
+minimumIntervalMinutes? }`and`associatedDomains` (universal links). Leave
 `swipeNavigation` unset: WebKit's swipe alongside the router's fights it, and
 `buddy build:ios` warns. The Liquid Glass chrome needs iOS 26 at run time;
 the default `deploymentTarget` stays, older systems drawing classic bars.
@@ -128,7 +128,7 @@ export default {
 
 `slots` is a budget, not a guess. iOS indexes donated `NSUserActivity` objects
 and hands a tapped one back only for an activity type the build declares in
-`Info.plist`, a list fixed at build time — so a type per record id cannot be
+`Info.plist`, a list fixed at build time - so a type per record id cannot be
 declared at all. Each kind gets that many slots, each slot holds whichever
 record is currently in it, and the oldest donation makes room for the next.
 `buddy build:ios` writes the declarations; an entry the build did not declare
@@ -155,7 +155,7 @@ host predates the bridge, and where the index is turned off (`enabled: false`),
 so a page can donate unconditionally. `spotlight.routeFor(action)` answers a tap
 synchronously for an app that already routes Craft's shortcut events itself.
 
-Index what is the person's — saved, joined, entered — rather than what they
+Index what is the person's - saved, joined, entered - rather than what they
 looked at, wherever the page re-renders on that change: a page that donates on
 every render would put a record straight back the moment they left it. Donating
 the same record twice is free, so an effect over the record is the natural call
@@ -299,6 +299,27 @@ context without exposing `WCSession` to STX templates. Set
 
 ## Validation
 
+### Capability and lifecycle boundaries
+
+Named imports from `@stacksjs/mobile` are browser-safe and tree-shake the
+selected Craft services. Prefer them to reading a module namespace or reaching
+through global bridge internals. A native host can exist before its bridge is
+ready; service wrappers wait where appropriate, while haptics are deliberately
+best-effort so a late response never delays a tap. Check `whenNativeMobile`
+when selecting native-only chrome and preserve cleanup from subscriptions.
+
+Capability configuration generates platform entitlements/privacy descriptions;
+it does not grant the user permission or prove a capability works on every OS.
+Permission denial, revocation, unavailable hardware and web fallback behavior
+are ordinary states. Build evidence and a successful native API call on a real
+device are different validations. Health/watch, StoreKit, Spotlight, background
+refresh and live activity work need their specific device/environment checks.
+
+Route recordings can outlive the web page, so attach to an existing recording
+before starting a second. `indoorVerdict(fixes, elapsedS)` and
+`typedDistanceKm(input)` are small exported helpers for indoor-workout decisions
+and typed distance; they are not an indoor-positioning service.
+
 Before finishing mobile work:
 
 ```bash

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 107 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
+description: Use when defining or extending Stacks models, deriving migrations and CRUD, configuring attributes/relationships/traits/ownership, or preserving model inference. Covers defineModel, extendModel, model types, native data workflows, and the 107 built-in framework models.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -10,15 +10,21 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 ## Key Paths
 - Your models: `app/Models/` (create it; it does not exist in a fresh project)
-- Built-in models: `storage/framework/defaults/app/Models/` (62 files, grouped
+- Built-in models: `storage/framework/defaults/app/Models/` (grouped
   into `commerce/`, `Content/`, `realtime/` and a flat top level)
-- `ModelOptions` / `Attribute` types: `storage/framework/core/types/src/model.ts`
+- Actual `defineModel` contract: `storage/framework/core/orm/src/define-model.ts`
+- Compatibility `ModelOptions` / `Attribute` types: `storage/framework/core/types/src/model.ts`
 - Attribute presets: `storage/framework/types/attributes.ts`
 
 To customize a built-in model, create the same filename under `app/Models/` -
 `app/Models/User.ts` wins over the default. `buddy publish:model User` copies the
 default across as a starting point.
 
+For an additive override, use `extendModel` rather than copying the full built-in
+definition. Read [references/model-capabilities.md](references/model-capabilities.md)
+for merge rules, casts, encryption, ownership, validation, lifecycle, search,
+pagination, sharding, and the native type utilities.
+
 ## Writing a model
 
 Everything - schema, validation, factory, relationships, behavior - is declared
@@ -31,8 +37,8 @@ import { defineModel } from '@stacksjs/orm'
 import { schema } from '@stacksjs/validation'
 
 export default defineModel({
-  name: 'Product',        // defaults to the file name
-  table: 'products',      // defaults to lowercase plural of `name`
+  name: 'Product',        // declare the model identity explicitly
+  table: 'products',      // declare the database table explicitly
   primaryKey: 'id',       // default
   autoIncrement: true,    // default
 
@@ -74,7 +80,11 @@ generated model types stay precise.
 
 ### Attribute fields
 
-`validation.rule` is the only required key on an attribute.
+The modern `defineModel` contract accepts attributes inferred from an explicit
+type, validation rule, factory, or default. A validator is recommended for
+request-facing values, but is not mandatory for every internal attribute.
+An unclassified value can infer `unknown`; declare the intended type instead
+of forcing a cast. See `orm/tests/inference-attributes.test-d.ts`.
 
 | Field | Effect |
 |---|---|
@@ -90,7 +100,8 @@ generated model types stay precise.
 | `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 |
+| `validation` | `{ rule, message? }` - declared rules are enforced on direct ORM writes and generated CRUD |
+| `encrypted` | Encrypt persisted values and decrypt model reads; raw queries still see stored ciphertext |
 
 ### Traits
 
@@ -127,6 +138,13 @@ useApi: {
 }
 ```
 
+`security.api.models` and `STACKS_MODEL_APIS` select which `useApi` definitions
+publish routes. The environment setting wins; `all`, `own`, `none`, or named
+models can narrow the surface. An app override counts as its own model.
+Selection does not add the trait or replace middleware/ownership checks, and
+it is separate from feature bundle and database migration selection. See
+`orm/tests/model-api-selection.test.ts` before configuring a restricted API.
+
 Dashboard-specific endpoints may still use scoped Actions when their transport
 shape, authorization boundary, or aggregation differs from generic CRUD. Do
 not expose a sensitive model through unguarded generated routes just because a
@@ -280,7 +298,7 @@ get: {
   fullName: (model) => `${model.firstName} ${model.lastName}`,
 },
 set: {
-  password: (value) => makeHash(value),
+  password: (attributes) => makeHash(attributes.password),
 },
 scopes: {
   published: (query) => query.where('status', 'published'),
@@ -387,8 +405,9 @@ maintained by hand, drifts the moment anyone adds a bullet, and is the same
 habit that produced the "All 62". The total above is pinned by
 `buddy docs:agent-counts`.
 
-Run `find storage/framework/defaults/app/Models -name '*.ts'` for the full
-list, or `buddy list` for what a given project resolves.
+Run `rg --files storage/framework/defaults/app/Models app/Models` for definitions
+and inspect the model registry for the runtime selection. `buddy list` lists
+commands, not a project's resolved models.
 
 ### Users & Auth
 - **User** — name, email, password | traits: useAuth(passkey), useUuid, useTimestamps, useSocials(github) | hasOne: Subscriber, Driver, Author | hasMany: PersonalAccessToken, Customer
@@ -465,12 +484,13 @@ list, or `buddy list` for what a given project resolves.
   will be overwritten by the next diff.
 - **`commentable`, not `commentables`.** `define-model` only checks the singular
   key. The plural spelling used to type check while leaving the trait inert.
-- **Seeding is model-declared.** `useSeeder` sets the count and fixtures; the
-  per-attribute `factory` functions produce the values. There are no seeder
-  files to write or register.
+- **Seeding can be model-declared.** `useSeeder` sets the count and fixtures;
+  attribute factories produce values. Application `Seeder` classes under
+  `database/seeders` are also supported for ordered bootstrap work.
 - **`hidden` is serialization, `guarded` is mass assignment.** They are different
   protections; a password wants both `hidden` and no `fillable`.
-- **`validation.rule` is mandatory** on every attribute - it drives both request
-  validation and the inferred column type.
+- **Declared validation is enforced on ORM writes**, including quiet writes.
+  Type inference also accepts explicit types, factories, and defaults; absence
+  of a validator is not a promise that an arbitrary request body is safe.
 - Dashboard-highlighted models (`dashboard: { highlight: true }`) appear
   prominently in the admin UI.

package/ai/skills/stacks-models/references/model-capabilities.md

@@ -0,0 +1,104 @@
+# Model capabilities and boundaries
+
+Authority: `core/orm/src/define-model.ts`, `extend-model.ts`, `model-types.ts`,
+`auto-crud.ts`, `ownership.ts`, the trait implementations, and the retained ORM
+tests. Compatibility `ModelOptions` alone does not describe every modern option.
+
+## Additive models and precise types
+
+`extendModel(base, extension)` preserves the built-in definition and adds the
+extension. Attributes merge by attribute name; an override replaces that
+attribute's complete entry. Traits and dashboard options merge one level deep.
+Supported relation lists merge without repeats. Read `mergeModelDefinition`
+when extending named-object relationships, hooks, getters or setters; do not
+assume every nested object deep-merges. Added attributes without an explicit
+order follow the base attributes.
+
+Derive types from the actual definition: `ModelRow<typeof Model>`,
+`ModelCreateData<typeof Model>`, `NewModelData<typeof Model>`,
+`UpdateModelData<typeof Model>`, `InferColumnNames<typeof Model>` and
+`InferNumericColumns<typeof Model>`. Strict create types distinguish fillable
+attributes and belongs-to keys from a loose row shape. Do not invent
+`UserRequest` or a runtime `UserModel` global.
+
+## Write pipeline
+
+Declared validation runs on direct `create`, `createMany`, and update paths,
+before casts and encryption. A partial update validates only supplied fields;
+create checks absent required fields. `ModelValidationError` carries status 422
+and per-field errors. Generated CRUD accepts camelCase and snake_case aliases
+for declared fillable attributes and belongs-to foreign keys.
+
+Mass assignment and serialization differ: `fillable` admits writes, `guarded`
+refuses them, and `hidden` removes values from model serialization. Explicit
+trusted writes can use `forceCreate`, `forceUpdate`, or `forceFill`; they do not
+turn request bodies into trusted data or disable declared validation. Quiet
+operations suppress events, not rules. `withoutValidation` is a deliberate
+scoped escape hatch for an import or backfill, not an endpoint convenience.
+
+Getters see attributes. Setters receive an attribute object, not just the new
+value, and async setters are awaited on the supported write paths. A setter
+must return the transformed attribute value. Tests: `model-validation`,
+`create-many-pipeline`, `mass-assignment`, `force-create-guarded`,
+`instance-mutator`, and `camel-case-accessors`.
+
+## Casts and encrypted attributes
+
+Model `casts` accepts built-in string, number, boolean, integer, float, json,
+array, datetime, and date casts, or a custom object with `get` and `set`.
+Date/datetime persistence uses UTC. Read the caster implementation for exact
+return shapes; JSON parse failures return null and are reported.
+
+An attribute with `encrypted: true` is encrypted on supported model writes and
+decrypted on model reads. Both column spellings are handled. Raw SQL and raw
+query-builder reads bypass the model's plaintext projection. Encrypted values
+are not suitable for ordinary equality/range searching; do not promise searchable
+encryption. Tests: `casting.test.ts` and encrypted utility/write coverage.
+
+## Ownership, roles, and policies
+
+Generated CRUD resolves ownership from the authenticated credential. A
+`team_id` or `user_id` column can supply the native scope; explicit ownership
+can resolve a scalar or permitted set of keys. Helpers include
+`selfOwnership`, `customerOwnership`, `siteOwnership`, `parentOwnership`, and
+`teamMembershipOwnership`.
+
+`ownership: false` explicitly declares an unscoped resource; use only when that
+is the actual resource contract. The default unscoped-write policy can withhold
+store/update/destroy for a model without a scope. Middleware and dashboard roles
+control entry, ownership controls rows, and policies control abilities on rows.
+None substitutes for the others. Do not take an owner identity from a body or
+query field. Tests: `ownership`, `row-scoping-policy`, `model-dashboard-roles`,
+`model-policy-wiring`, and resource-specific security contracts.
+
+## Lifecycle, search, retention, and sharding
+
+`observe` emits native lifecycle events. `withoutEvents` and quiet operations
+can suppress them within their scoped operation. With observation enabled,
+`broadcastOn` plus `broadcastWith` publishes a curated lifecycle projection;
+avoid broadcasting the entire private row. `useActivityLog` writes a readable
+change feed, while `useAudit` records old/new diffs. Hidden/sensitive fields
+remain excluded from the activity projection.
+
+`useSearch` supplies model search helpers and a projected searchable document.
+Related dot-path attributes need their relation data; missing relation data
+does not magically trigger every required query. Hidden fields stay excluded.
+Search-engine pagination has its own hits contract; ORM pagination returns
+native paginator objects. Read `stacks-search-engine` and `stacks-pagination`.
+
+`prunable` declares age/query-based pruning. GDPR ownership, personal attributes,
+access, erasure and retention are distinct declarations, not a global delete
+switch. For Vitess, `sharding` configures derived or explicit VSchema behavior;
+it is not an automatic cluster deployment and is ignored on single-node dialects.
+Use `buddy generate:vschema` and the current dialect evidence before deploying.
+
+## Transaction and row-count gotchas
+
+Model execution is separate from a `transaction` callback's `tx` handle.
+Use `tx` for all statements that must share that transaction. Model calls inside
+the callback do not automatically observe its uncommitted writes.
+
+A driver can report matched rows differently from changed rows. Use native
+`mutationCount` or `matchedRows` only according to the operation's real contract;
+do not interpret an arbitrary `execute()` value as a universal affected-row
+object. Use the service's returned row/not-found contract at an HTTP boundary.