@stacksjs/defaults 0.72.103 → 0.73.0

package/ai/skills/stacks-codebase-design/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: stacks-codebase-design
+description: Use when designing or restructuring code in a Stacks project - shaping an action or package interface, deciding where a seam goes, choosing between a trait and a helper, making code testable or navigable, or when another skill needs the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality).
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Codebase design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a
+clean seam, testable through that interface. Use this language and these
+principles wherever Stacks code is being designed or restructured. The aim is
+leverage for callers, locality for maintainers, and testability for everyone.
+
+Stacks is already built this way, which is why the vocabulary is worth sharing:
+`defineModel()` puts a schema, validation, factories, relationships and a REST
+surface behind one call. The driver packages (`cache`, `queue`, `storage`,
+`email`, `ai`, `chat`, `search-engine`, `dns`) are ports with two or more
+adapters each. Use the words below rather than inventing new ones per package.
+
+Credit: the deep-module model here is adapted from Matt Pocock's
+`codebase-design` skill (MIT), <https://github.com/mattpocock/skills>, itself
+building on Ousterhout and Feathers.
+
+## Glossary
+
+Use these terms exactly. Do not substitute "component", "service", "API" or
+"boundary". Consistent language is the whole point.
+
+**Module**: anything with an interface and an implementation. Deliberately
+scale-agnostic: a function, an action, a model, a `@stacksjs/*` package, a
+tier-spanning slice. *Avoid*: unit, component, service.
+
+**Interface**: everything a caller must know to use the module correctly. The
+type signature, but also invariants, ordering constraints, error modes, required
+config, and performance characteristics. For a Stacks action the interface
+includes its route, its middleware and its request shape, not just its `handle`
+signature. *Avoid*: API, signature (too narrow, they name only the type surface).
+
+**Implementation**: what is inside a module. Distinct from **adapter**: a thing
+can be a small adapter over a large implementation (the S3 storage driver) or a
+large adapter over a small one (an in-memory fake). Reach for "adapter" when the
+seam is the topic, "implementation" otherwise.
+
+**Depth**: leverage at the interface. How much behaviour a caller or a test can
+exercise per unit of interface they have to learn. A module is **deep** when a
+lot of behaviour sits behind a small interface, **shallow** when the interface is
+nearly as complex as the implementation.
+
+**Seam** (Michael Feathers): a place where you can alter behaviour without
+editing in that place. The *location* at which a module's interface lives. Where
+to put the seam is its own design decision, distinct from what goes behind it. In
+Stacks the `app/` override model is a seam the framework hands you for free:
+`app/Actions/Cms/PostIndexAction.ts` replaces the default without editing it.
+*Avoid*: boundary (overloaded with DDD's bounded context).
+
+**Adapter**: a concrete thing that satisfies an interface at a seam. Describes
+*role* (which slot it fills), not substance (what is inside). `config/cache.ts`
+picking `memory` or `redis` is adapter selection.
+
+**Leverage**: what callers get from depth. More capability per unit of interface
+learned. One implementation pays back across N call sites and M tests.
+
+**Locality**: what maintainers get from depth. Change, bugs, knowledge and
+verification concentrate in one place rather than spreading across callers. Fix
+once, fixed everywhere.
+
+## Deep versus shallow
+
+**Deep** = small interface, lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small interface   │  ← few entry points, simple params
+├─────────────────────┤
+│                     │
+│  Deep implementation│  ← complexity hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow** = large interface, little implementation. Avoid:
+
+```
+┌─────────────────────────────────┐
+│       Large interface           │  ← many methods, complex params
+├─────────────────────────────────┤
+│  Thin implementation            │  ← mostly passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask: can I reduce the number of entry points? Can I
+simplify the params? Can I hide more complexity inside?
+
+The `useApi` trait is the canonical deep interface in this framework: one config
+object, and the model gains five actions, five routes, an OpenAPI entry and a
+dashboard view. `useSearch`, `useAuth` and `useSoftDeletes` are the same trade.
+When you find yourself writing the fifth near-identical action, the question is
+whether a trait wants to be born.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module
+  can be internally composed of small, swappable parts. They just are not part of
+  the interface. A module can have **internal seams** (private, used by its own
+  tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it
+  was a pass-through. If complexity reappears across N callers, it was earning
+  its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam.
+  If you want to test *past* the interface, the module is probably the wrong
+  shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Do
+  not introduce a seam unless something actually varies across it. Production
+  plus test counts as two.
+
+## Designing for testability
+
+1. **Accept dependencies, do not create them.**
+
+   ```typescript
+   // testable
+   export async function processOrder(order: Order, gateway: PaymentGateway) {}
+
+   // hard to test
+   export async function processOrder(order: Order) {
+     const gateway = new StripeGateway()
+   }
+   ```
+
+2. **Return results, do not produce side effects.**
+
+   ```typescript
+   // testable
+   function calculateDiscount(cart: Cart): Discount {}
+
+   // hard to test
+   function applyDiscount(cart: Cart): void { cart.total -= discount }
+   ```
+
+3. **Small surface area.** Fewer entry points means fewer tests. Fewer params
+   means simpler setup.
+
+In a Stacks app the third dependency is almost always the database, and it does
+not need injecting: `refreshDatabase()` plus model factories give you a real one
+per suite. See `stacks-tdd` for where that line sits.
+
+## Relationships
+
+- A **module** has exactly one **interface**, the surface it presents to callers
+  and tests.
+- **Depth** is a property of a **module**, measured against its **interface**.
+- A **seam** is where a **module**'s **interface** lives.
+- An **adapter** sits at a **seam** and satisfies the **interface**.
+- **Depth** produces **leverage** for callers and **locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as a ratio of implementation lines to interface lines** (Ousterhout):
+  rewards padding the implementation. Use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public
+  methods**: too narrow. Interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or
+  **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies**: [DEEPENING.md](DEEPENING.md)
+  covers the dependency categories, seam discipline, and replace-do-not-layer
+  testing.
+- **Exploring alternative interfaces**: [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)
+  runs parallel sub-agents to design one interface several radically different
+  ways, then compares on depth, locality and seam placement.
+
+## Downstream
+
+> Reach for `stacks-tdd` to write the tests at the seam you chose, and
+> `stacks-domain-modeling` when the module needs a name the project does not
+> have yet.

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-collections
-description: Use when working with collection data structures in Stacks — chaining array operations, Laravel-style collection methods, mapping, filtering, reducing, or grouping. Covers @stacksjs/collections which wraps ts-collect.
+description: Use when working with collection data structures in Stacks - chaining array operations, Laravel-style collection methods, mapping, filtering, reducing, or grouping. Covers @stacksjs/collections which wraps ts-collect.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-commerce
-description: Use when building e-commerce features in Stacks — the commerce namespace with 13 sub-modules (products, orders, customers, coupons, payments, shipping, tax, gift cards, waitlists, devices, receipts, restaurant), 20+ commerce models, default commerce functions, or the commerce configuration. Covers @stacksjs/commerce.
+description: Use when building e-commerce features in Stacks - the commerce namespace with 15 sub-modules (products, carts, orders, customers, coupons, payments, gift cards, auctions, shipping, tax, waitlists, restaurant, devices, receipts, errors), 20+ commerce models, checkout and redemption logic, or the commerce configuration. Covers @stacksjs/commerce.
 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 Commerce
 
-Comprehensive e-commerce module with 13 sub-modules and 20+ models.
+Comprehensive e-commerce module with 15 sub-modules and 20+ models.
 
 ## Key Paths
 - Core package: `storage/framework/core/commerce/src/`
@@ -20,30 +20,37 @@ Comprehensive e-commerce module with 13 sub-modules and 20+ models.
 ```typescript
 import { commerce } from '@stacksjs/commerce'
 
-// 13 sub-modules
-commerce.products      // Product CRUD
-commerce.coupons       // Coupon management
-commerce.customers     // Customer management
-commerce.errors        // Error tracking
-commerce.giftCards     // Gift card management
-commerce.orders        // Order management
-commerce.payments      // Payment processing
-commerce.restaurant    // Restaurant features
-commerce.shippings     // Shipping management
-commerce.tax           // Tax rate management
-commerce.waitlists     // Waitlist management
+// 15 sub-modules
+commerce.products      // Products, variants, units, manufacturers, reviews, categories
+commerce.carts         // The pre-checkout basket
+commerce.orders        // Orders, order items, export, checkout guards
+commerce.customers     // Customer records
+commerce.coupons       // Coupons, including atomic redemption
+commerce.payments      // Payment records, refunds
+commerce.giftCards     // Gift cards, balance, redemption and reload
+commerce.auctions      // Benefit auctions: lots, bids, proxy bidding, pledges
+commerce.shippings     // Methods, rates, zones, routes, couriers, live tracking
+commerce.tax           // Tax rates and breakdown
+commerce.waitlists     // Waitlists
+commerce.restaurant    // Restaurant features (lives at waitlists/restaurant)
 commerce.devices       // Print device management
-commerce.receipts      // Receipt management
+commerce.receipts      // Receipt records
+commerce.errors        // Error tracking
 ```
 
+`restaurant` is re-exported from `waitlists/restaurant` rather than having a
+directory of its own, which is why the source tree shows one fewer directory
+than the namespace has keys. `tests/commerce.test.ts` asserts the exact key set,
+so adding a sub-module means updating that count.
+
 ## Sub-Module Operations
 
 Each sub-module typically provides:
-- `index()` — list all
-- `fetch(id)` — get one
-- `store(data)` — create
-- `update(id, data)` — update
-- `destroy(id)` — delete
+- `fetchAll()` - list all
+- `fetchById(id)` - get one
+- `store(data)` - create, plus `bulkStore`
+- `update(id, data)` - update, plus `bulkUpdate`
+- `destroy(id)` - delete, plus `bulkDestroy`
 
 ### Products Sub-Module
 - Products: items, variants, units
@@ -62,7 +69,7 @@ Each sub-module typically provides:
 - Shipping rates (weight-based)
 - Shipping zones
 - Delivery routes and their stops
-- Drivers
+- Couriers
 - Digital deliveries
 - License keys
 - **Live tracking** (`commerce.shippings.tracking`) - see below
@@ -85,16 +92,77 @@ Each sub-module typically provides:
 | Manufacturer | manufacturer info | hasMany: Product |
 | Review | rating(1-5), content, isVerifiedPurchase, helpfulVotes | belongsTo: Product, Customer |
 | ShippingRate | weightFrom, weightTo, rate | belongsTo: ShippingMethod, ShippingZone |
-| DeliveryRoute | stops, totalDistance, status(planned/active/completed), startedAt | belongsTo: Driver; hasMany: DeliveryStop, DriverPing |
+| DeliveryRoute | stops, totalDistance, status(planned/active/completed), startedAt | belongsTo: Courier; hasMany: DeliveryStop, CourierPing |
 | DeliveryStop | sequence, status, address, latitude, longitude, etaAt, arrivedAt | belongsTo: DeliveryRoute, Order |
-| Driver | name, phone, vehicleNumber, status, latitude, longitude, heading, lastPingAt | hasMany: DeliveryRoute, DriverPing |
-| DriverPing | latitude, longitude, heading, speed, accuracy, recordedAt | belongsTo: Driver, DeliveryRoute |
+| Courier | name, phone, vehicleNumber, status, latitude, longitude, heading, lastPingAt | hasMany: DeliveryRoute, CourierPing |
+| CourierPing | latitude, longitude, heading, speed, accuracy, recordedAt | belongsTo: Courier, DeliveryRoute |
 | TaxRate | name, rate(0-100), type(VAT/GST/Sales Tax) | |
 | LicenseKey | key(XXXX-XXXX-XXXX-XXXX-XXXX), template, status | belongsTo: Customer, Product, Order |
 | DigitalDelivery | downloadLimit, expiryDays, automaticDelivery | |
 | WaitlistProduct | product waitlist tracking | |
 | Receipt | receipt records | |
 
+## Money paths
+
+Three operations move money, and all three are written as a **single conditional
+UPDATE** rather than read-check-write. Concurrency here is not theoretical: two
+parallel requests against a read-then-write redemption both see the pre-state
+and both succeed, which is a coupon redeemed past its limit or a gift card spent
+twice.
+
+### Redeeming a coupon
+
+```ts
+const result = await commerce.coupons.redeem(couponId)
+
+if (!result.ok) {
+  // 'not-found' | 'inactive' | 'expired' | 'limit-reached'
+  throw new HttpError(400, `Coupon cannot be redeemed: ${result.reason}`)
+}
+// result.coupon reflects the post-redemption state.
+```
+
+`redeem` bumps `usage_count` and enforces `max_uses`, `is_active` and the
+start/end dates in the WHERE clause, so the database decides the race. A
+`max_uses` of `NULL` means unlimited. Do not fetch, check and then call
+`update()` to increment: that is the exact pattern this replaced.
+
+### Spending or reloading a gift card
+
+```ts
+await commerce.giftCards.updateBalance(cardId, -25)  // redeem 25
+await commerce.giftCards.updateBalance(cardId, 50)   // reload 50
+```
+
+One entry point for both directions, and they are deliberately asymmetric:
+
+| | Redemption (`amount < 0`) | Reload (`amount > 0`) |
+|---|---|---|
+| Allowed status | `ACTIVE` | `ACTIVE`, or `USED` when the card is `isReloadable` |
+| `lastUsedDate` | stamped | left alone |
+| Balance floor | cannot go below 0 | n/a |
+| Expiry | refused past `expiryDate` | refused past `expiryDate` |
+
+The balance lands on 0 and the status flips to `USED` in the same statement. A
+reloadable card can be revived from `USED`; a non-reloadable one cannot, and
+throws `Gift card is not reloadable`. `deactivate(id)` is the terminal state and
+reports whether a row actually changed.
+
+### Recording a refund
+
+`commerce.payments.recordRefund(id, amount)` takes **integer minor units** and
+enforces `refund_amount + amount <= amount` in the WHERE clause, so operators
+cannot over-refund a payment by racing each other. It flips the status to
+`refunded` or `partiallyRefunded` depending on where the total lands.
+
+## Carts
+
+`commerce.carts` is the pre-checkout basket, with the same CRUD shape as every
+other sub-module plus bulk variants. `commerce.orders` owns what happens after
+checkout, and `orders/guards.ts` holds the pre-flight checks that run between
+the two, including `cleanupAbandonedCarts({ olderThanDays, limit })` for the
+sweeper you schedule daily.
+
 ## Live Delivery Tracking
 
 `commerce.shippings.tracking` is the moving part of shipping: position ingest,
@@ -116,22 +184,22 @@ const stop = await tracking.assignStop({
 await tracking.startRoute(route.id)
 await tracking.startStop(stop.id)      // order -> OUT_FOR_DELIVERY
 
-// One call per position fix from the driver's device.
-await tracking.recordDriverPing({
-  driverId, latitude, longitude, speed, accuracy,
+// One call per position fix from the courier's device.
+await tracking.recordCourierPing({
+  courierId, latitude, longitude, speed, accuracy,
 })
 
 await tracking.completeStop(stop.id)   // order -> DELIVERED, route closes itself
 ```
 
-### What `recordDriverPing` does
+### What `recordCourierPing` does
 
 One entry point, so a tracking page never shows a position its ETA disagrees
-with. Per fix it: appends to `driver_pings`, updates the driver's denormalised
+with. Per fix it: appends to `courier_pings`, updates the courier's denormalised
 present position, recomputes the served stop's ETA, broadcasts the position,
 and latches `delivery:nearby` / `delivery:arrived` so each fires exactly once.
 
-A fix reporting worse than 250m accuracy is stored but does not move the driver
+A fix reporting worse than 250m accuracy is stored but does not move the courier
 or trip a threshold.
 
 ### Two fan-outs, on purpose
@@ -159,7 +227,7 @@ back to `SHIPPED` when a drop fails and the parcel returns to the depot.
 `distanceInMeters`, `bearingInDegrees`, `estimateSecondsRemaining`, `isWithin`
 and `hasCoordinates` are exported for building dispatch views. The ETA pads
 straight-line distance by a detour factor and returns `null` for a stationary
-driver rather than `Infinity`.
+courier rather than `Infinity`.
 
 ## Integration with Payments
 Commerce works with `@stacksjs/payments` for Stripe integration:
@@ -172,13 +240,51 @@ await Payment.charge(customer, order.totalAmount, paymentMethodId)
 All commerce models have dashboard views at `/dashboard/commerce/*`.
 
 ## Gotchas
-- Commerce models are auto-generated — edit definitions, not generated files
-- Use `buddy make:migration` when changing commerce schemas
+
+### Writing raw SQL here
+
+Two dialect traps have each shipped a broken money path, so both are now guarded
+by `src/tests/sql-dialect-portability.test.ts`:
+
+- **Placeholders.** Postgres numbers them (`$1`); a literal `?` is a syntax
+  error. Render them with `sqlHelpers(env.DB_CONNECTION || 'sqlite').param(n)`.
+- **Booleans.** A `schema.boolean()` attribute becomes a real `BOOLEAN` on
+  Postgres, so `is_active = 1` is `operator does not exist: boolean = integer`.
+  Use `sqlHelpers(...).boolTrue` / `.boolFalse`.
+
+Both pass on SQLite, which is what the tests run against, so neither shows up
+locally. That is the whole reason the source-level test exists.
+
+### Reading back a row you just inserted
+
+Use `insertedId(result)` from `utils/inserted-id`. Couriers disagree: SQLite
+reports `lastInsertRowid`, MySQL reports `insertId`, and Postgres reports
+neither without a `RETURNING` clause (fall back to the `uuid` the row was
+written with).
+
+**Never read a row count as an id.** `numInsertedOrUpdatedRows` says how many
+rows changed, not which one, so a successful single-row insert reports `1` and
+the caller fetches row 1 of the table instead of the new record. `mutationCount`
+is the helper for when the count is genuinely what you want.
+
+### Everything else
+
+- Commerce models are auto-generated - edit definitions, not generated files
+- Run `buddy generate:migrations` after changing a commerce model, and read the
+  SQL before applying it
 - Order `observe: true` emits events on create/update/delete
 - Products have JSON fields for allergens and nutritionalInfo
-- Cart expiry is tracked via `expiresAt` field
+- Cart expiry is tracked via `expiresAt`; `cleanupAbandonedCarts` is the sweeper
 - Coupon types: `fixed_amount` or `percentage`
 - Gift card codes are unique and auto-generated
 - License keys follow XXXX-XXXX-XXXX-XXXX-XXXX format
 - Product dashboard is highlighted (`dashboard: { highlight: true }`)
-- Default seeder counts: Product(10), Order(20), Review(50), Payment(50)
+- Default seeder counts: Product(10), Order(20), Review(50), Payment(50),
+  GiftCard(20), Customer(20), Coupon(15)
+- `fetchById` in most sub-modules returns the raw row, so columns arrive
+  snake_cased even though the declared type is camelCase
+
+## Downstream
+
+> Touching a money path? `/stacks-tdd` for the seam to test it at, and
+> `/stacks-review` before it merges. `/stacks-payments` covers the Stripe side.

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 - 90+ 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-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-config
-description: Use when working with Stacks configuration — the 44 config files, config helper functions, default values, environment-specific overrides, or the defineApp/defineDatabase/etc builder functions. Covers @stacksjs/config and the config/ directory.
+description: Use when working with Stacks configuration - the 44 config files, config helper functions, default values, environment-specific overrides, or the defineApp/defineDatabase/etc builder functions. Covers @stacksjs/config and the config/ directory.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-configuration
-description: Use when setting up or modifying Stacks project-level configuration — bunfig.toml preload order, the tsconfig chain and TypeScript 7 / tsgo type checking, workspace configuration, .env setup, package.json scripts, system requirements (Bun >= 1.3.0, SQLite >= 3.47.2), or the project bootstrap process. For individual feature configs (database, email, auth, etc.), see the specific package skills instead.
+description: Use when setting up or modifying Stacks project-level configuration - bunfig.toml preload order, the tsconfig chain and TypeScript 7 / tsgo type checking, workspace configuration, .env setup, package.json scripts, system requirements (Bun >= 1.3.0, SQLite >= 3.47.2), or the project bootstrap process. For individual feature configs (database, email, auth, etc.), see the specific package skills instead.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-cron
-description: Use when working with cron expressions in a Stacks application — parsing cron syntax, registering OS-level cron jobs, or low-level scheduling. Covers @stacksjs/cron. For higher-level scheduling, see stacks-scheduler.
+description: Use when working with cron expressions in a Stacks application - parsing cron syntax, registering OS-level cron jobs, or low-level scheduling. Covers @stacksjs/cron. For higher-level scheduling, see stacks-scheduler.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-crosswind
-description: Use when styling components in a Stacks application — utility-first CSS classes, theming, responsive design, variants, custom rules, or CSS generation. Crosswind is the CSS utility engine powering Stacks' Crosswind config.
+description: Use when styling components in a Stacks application - utility-first CSS classes, theming, responsive design, variants, custom rules, or CSS generation. Crosswind is the CSS utility engine powering Stacks' Crosswind config.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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/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

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-datetime
-description: Use when working with dates and times in Stacks — the DateTime class with Carbon-like API (add/sub, comparison, formatting, start/end of day/month/year), date parsing, format tokens, or timezone handling. Covers @stacksjs/datetime.
+description: Use when working with dates and times in Stacks - the DateTime class with Carbon-like API (add/sub, comparison, formatting, start/end of day/month/year), date parsing, format tokens, or timezone handling. Covers @stacksjs/datetime.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-dependencies
-description: Use when managing dependencies in a Stacks project — system dependencies via Pantry, Bun workspaces, buddy-bot updates, better-dx tooling, or dependency configuration. Covers config/deps.ts, Pantry, and workspace management.
+description: Use when managing dependencies in a Stacks project - system dependencies via Pantry, Bun workspaces, buddy-bot updates, better-dx tooling, or dependency configuration. Covers config/deps.ts, Pantry, and workspace management.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 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 - 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.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, AWS
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-desktop
-description: Use when building or publishing desktop applications with Stacks — Craft native windows, system tray, desktop packaging, or Mac App Store delivery.
+description: Use when building or publishing desktop applications with Stacks - Craft native windows, system tray, desktop packaging, or Mac App Store delivery.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-development
-description: Use when setting up or configuring the Stacks development environment — dev server, hot reload, development utilities, or IDE configuration. Covers the @stacksjs/development package, the dev server, CLI commands, reverse proxy, SSL, and dev workflow.
+description: Use when setting up or configuring the Stacks development environment - dev server, hot reload, development utilities, or IDE configuration. Covers the @stacksjs/development package, the dev server, CLI commands, reverse proxy, SSL, and dev workflow.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-dns
-description: Use when managing DNS in a Stacks application — Route53 hosted zones, domain records, nameserver management, or DNS configuration. Covers @stacksjs/dns (AWS Route53 driver), @stacksjs/dnsx, and config/dns.ts.
+description: Use when managing DNS in a Stacks application - Route53 hosted zones, domain records, nameserver management, or DNS configuration. Covers @stacksjs/dns (AWS Route53 driver), @stacksjs/dnsx, and config/dns.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-docs
-description: Use when building or configuring documentation for a Stacks project — BunPress setup, doc generation, navigation, sidebar structure, or documentation meta/SEO. Covers @stacksjs/docs and config/docs.ts.
+description: Use when building or configuring documentation for a Stacks project - BunPress setup, doc generation, navigation, sidebar structure, or documentation meta/SEO. Covers @stacksjs/docs and config/docs.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob