@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,228 @@
+---
+name: stacks-events
+description: Use when working with the event system in a Stacks application — dispatching events, listening for events, model events, wildcard listeners, the event emitter, or event-driven architecture. Covers @stacksjs/events, app/Events.ts, app/Listener.ts, and app/Listeners/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Events
+
+Tiny (~200b) functional event emitter based on mitt, with Stacks-specific model events and action-based listener resolution.
+
+## Key Paths
+- Core package: `storage/framework/core/events/src/index.ts` (single file -- entire implementation)
+- Application events: `app/Events.ts`
+- Listener setup: `app/Listener.ts`
+- Listeners: `app/Listeners/`
+- Event types: `storage/framework/types/events.ts`
+
+## Core mitt Implementation (index.ts)
+
+The entire event system is a single `mitt()` factory function that returns an `Emitter<Events>` object:
+
+```typescript
+export default function mitt<Events>(all?: EventHandlerMap<Events>): Emitter<Events>
+```
+
+### Emitter Interface
+```typescript
+interface Emitter<Events> {
+  all: EventHandlerMap<Events>  // Map<keyof Events | '*', Handler[]>
+
+  on<Key>(type: Key, handler: Handler<Events[Key]>): void
+  on(type: '*', handler: WildcardHandler<Events>): void
+
+  off<Key>(type: Key, handler?: Handler<Events[Key]>): void
+  off(type: '*', handler?: WildcardHandler<Events>): void
+
+  emit<Key>(type: Key, event?: Events[Key]): void
+}
+```
+
+### How emit() Works
+1. Gets handlers array from `all.get(type)` -- calls each with `handler(event)`
+2. Gets wildcard handlers from `all.get('*')` -- calls each with `handler(type, event)`
+3. Handlers are called via `.slice()` copy to avoid mutation during iteration
+4. Each handler is wrapped in try-catch with `console.error` logging
+5. Error in one handler does NOT prevent other handlers from executing
+6. Both type-matched AND wildcard handlers run (wildcards run second)
+7. If `event` is `undefined`, handlers are NOT called
+
+### on() / off() Behavior
+- `on(type, handler)`: pushes to handlers array (creates array if first handler)
+- `off(type, handler)`: splices handler from array by index
+- `off(type)` (no handler): replaces handlers array with empty `[]`
+- Handler maps use `Map<string, Array<Handler>>` internally
+
+## Stacks Event System Exports
+
+The package creates a single `mitt<StacksEvents>()` instance and exports multiple aliases:
+
+```typescript
+import { dispatch, listen, off, emitter, events, useEvent, useListen, useEvents, all } from '@stacksjs/events'
+
+// Dispatch an event
+dispatch('user:registered', { id: 1, email: 'user@example.com' })
+
+// Listen for an event
+listen('user:registered', (data) => {
+  console.log('New user:', data.email)
+})
+
+// Wildcard listener (catches ALL events)
+listen('*', (type, data) => {
+  console.log(`Event ${type}:`, data)
+})
+
+// Remove a specific listener
+off('user:registered', handler)
+
+// Direct emitter access
+emitter.on('event', handler)
+emitter.off('event', handler)
+emitter.emit('event', data)
+emitter.all  // Map of all handlers
+```
+
+### Export Aliases
+| Export | Maps To |
+|--------|---------|
+| `dispatch` | `emitter.emit` |
+| `useEvent` | `emitter.emit` (alias for `dispatch`) |
+| `listen` | `emitter.on` |
+| `useListen` | `emitter.on` (alias for `listen`) |
+| `off` | `emitter.off` |
+| `emitter` | the mitt instance |
+| `events` | the mitt instance (alias for `emitter`) |
+| `useEvents` | the mitt instance (alias for `emitter`) |
+| `all` | `emitter.all` (the handler Map) |
+| `mitt` | the factory function itself |
+
+### Type Aliases
+```typescript
+type Dispatch = <Key extends keyof StacksEvents>(type: Key, event: StacksEvents[Key]) => void
+type Listen = <Key extends keyof StacksEvents>(type: Key, handler: Handler<StacksEvents[Key]>) => void
+type Off = <Key extends keyof StacksEvents>(type: Key, handler?: Handler<StacksEvents[Key]>) => void
+```
+
+## Built-in Event Types (StacksEvents)
+
+```typescript
+interface StacksEvents extends ModelEvents, Record<EventType, unknown> {
+  'user:registered': Record<string, any>
+  'user:logged-in': Record<string, any>
+  'user:logged-out': Record<string, any>
+  'user:password-reset': Record<string, any>
+  'user:password-changed': Record<string, any>
+}
+```
+
+The `Record<EventType, unknown>` intersection allows arbitrary event names beyond the declared ones.
+
+## Model Events
+
+Every model with `observe: true` trait (in defineModel) emits via `afterCreate`/`afterUpdate`/`afterDelete` hooks:
+- `'{model}:created'` -- after insert
+- `'{model}:updated'` -- after update
+- `'{model}:deleted'` -- after delete
+
+Model name is lowercased: `'user:created'`, `'post:updated'`, `'order:deleted'`
+
+Events are dispatched via lazy `import('@stacksjs/events').then(({ dispatch }) => dispatch(...))` to avoid circular dependencies. If the import fails (e.g., browser context), errors are silently caught.
+
+The `observe` trait can be:
+- `true` -- emits all three events (create, update, delete)
+- `['create', 'update']` -- emits only specified events
+- `false` / undefined -- no events
+
+Full model list (45+ with events defined in `storage/framework/types/events.ts`):
+Author, Page, Post, User, Activity, Campaign, Cart, CartItem, Category, Comment, Coupon, Customer, DeliveryRoute, DigitalDelivery, Driver, EmailList, GiftCard, LicenseKey, LoyaltyPoint, LoyaltyReward, Manufacturer, Notification, Order, OrderItem, Payment, PrintDevice, Product, ProductUnit, ProductVariant, Receipt, Review, ShippingMethod, ShippingRate, ShippingZone, SocialPost, Subscription, Tag, TaxRate, Transaction, WaitlistProduct, WaitlistRestaurant, Websocket
+
+## Event-to-Listener Mapping (app/Events.ts)
+
+```typescript
+import type { Events } from '@stacksjs/types'
+
+export default {
+  'user:registered': ['SendWelcomeEmail'],
+  'user:created': ['NotifyUser'],
+} satisfies Events
+```
+
+Keys are event names (must match StacksEvents keys). Values are arrays of **Action names** -- these correspond to files in `app/Actions/`.
+
+## Listener Resolution (app/Listener.ts)
+
+The `handleEvents()` function sets up the entire event-to-action pipeline:
+
+### Setup
+```typescript
+export async function handleEvents() {
+  emitter.on('*', listenEvents as WildcardHandler<StacksEvents>)
+}
+```
+Subscribes a single wildcard handler that intercepts ALL events.
+
+### Event Processing Flow
+1. **Fast path**: `eventTypes` Set (pre-computed from `Object.keys(events)`) provides O(1) lookup. Events not in the map are skipped immediately.
+2. **Listener resolution**: For each listener name in the array, `resolveAction(listener)` is called:
+   - Checks `actionCache` Map (in-memory module cache)
+   - Checks `pendingImports` Map (deduplicates concurrent imports of the same action)
+   - Dynamically imports `app/Actions/{listener}.ts`
+   - Validates the module exports a `handle(event)` method
+   - Caches the resolved module in `actionCache`
+3. **Execution**: `processListeners()` iterates listeners sequentially (`for...of`), awaiting each action's `handle(event)` method
+4. **Error handling**: Errors are caught per-listener via `handleError()` from `@stacksjs/error-handling` -- one listener failure does not prevent others
+
+### Caching Details
+```typescript
+const actionCache = new Map<string, { handle: (event: any) => Promise<any> | any }>()
+const pendingImports = new Map<string, Promise<...>>()
+const eventTypes = new Set(Object.keys(events))  // pre-computed at module load
+```
+
+- `actionCache`: stores resolved action modules permanently
+- `pendingImports`: prevents double-importing when multiple events fire simultaneously for the same listener
+- `eventTypes`: O(1) lookup to skip events with no registered listeners
+
+### Listener Type Support
+The listener can also be a function (not just a string):
+```typescript
+if (typeof listener === 'function') {
+  await listener(event)
+  continue
+}
+```
+
+## Implementation Details
+
+### Thread Safety
+- mitt handlers are stored in arrays -- `emit()` calls `.slice()` before iterating to safely handle additions/removals during iteration
+- Wildcard handler registration happens once in `handleEvents()` -- the single handler routes all events
+
+### Synchronous vs Asynchronous
+- **mitt itself is synchronous**: `emit()` calls handlers directly, does not await them
+- **Listener resolution is asynchronous**: `processListeners()` uses `async/await` for dynamic imports and action execution
+- The wildcard handler in `app/Listener.ts` calls `processListeners()` as fire-and-forget (no await) since mitt doesn't support async wildcard handlers
+
+### Memory
+- The emitter is a module-level singleton -- created once at import time
+- Action modules are cached permanently in `actionCache` -- hot-reloading new actions requires server restart
+- The `pendingImports` Map entries are cleaned up in the `finally` block of each import
+
+## Gotchas
+- Events are functional, not class-based -- no need to create event classes
+- The emitter is a **singleton** -- shared across the entire application process
+- Wildcard `'*'` listeners receive `(type, event)` -- regular handlers receive just `(event)`
+- Listeners in `app/Events.ts` are **Action names** (strings), not file paths or handler functions
+- The action module must export a default with a `handle(event)` method
+- Event dispatch via mitt is **synchronous** but listener action resolution (dynamic import) is **asynchronous**
+- Model events only fire when the model has `observe: true` (or array) trait set
+- The event system is ~200 bytes total -- it is intentionally minimal
+- Listener caching means hot-reloading new actions requires server restart
+- If `evt` is `undefined`, handlers are NOT called (mitt checks `if (evt !== undefined)`)
+- The `'*'` event type cannot be manually emitted -- it only receives forwarded events
+- `off(type)` without a handler argument clears ALL handlers for that type (sets to empty array, not delete)
+- The `StacksEvents` interface extends `Record<EventType, unknown>` allowing any string as an event name
+- Error logging in mitt uses `console.error` (not `@stacksjs/logging`) to avoid circular dependencies

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

@@ -0,0 +1,158 @@
+---
+name: stacks-faker
+description: Use when working with fake data generation in a Stacks application — seeding databases, generating test data, model factories, or using faker utilities. Covers @stacksjs/faker (wrapper around ts-mocker) and its integration with the database seeder.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Faker
+
+`@stacksjs/faker` wraps `ts-mocker` with a `@faker-js/faker`-compatible API plus enhanced modules for vehicle, company, lorem, location, datatype, and helpers.
+
+## Key Paths
+- Core package: `storage/framework/core/faker/src/`
+- Source: `storage/framework/core/faker/src/index.ts` (265 lines)
+- Tests: `storage/framework/core/faker/tests/faker.test.ts`
+- Seeder integration: `storage/framework/core/database/src/seeder.ts`
+
+## Usage
+
+```typescript
+import { faker } from '@stacksjs/faker'
+
+faker.person.fullName()        // 'John Smith'
+faker.internet.email()         // 'john.smith@example.com'
+faker.lorem.sentence()         // 'Lorem ipsum dolor sit amet.'
+faker.number.int({ min: 1, max: 100 })  // 42
+faker.datatype.uuid()          // 'a1b2c3d4-...'
+faker.vehicle.vrm()            // 'AB12 CDE'
+```
+
+## Modules
+
+### datatype (Compatibility Layer)
+```typescript
+faker.datatype.boolean(): boolean
+faker.datatype.number(options?: { min?: number, max?: number }): number
+faker.datatype.float(options?: { min?: number, max?: number, precision?: number }): number
+faker.datatype.uuid(): string
+faker.datatype.string(length?: number): string           // default: 10
+faker.datatype.array<T>(generator: () => T, length?: number): T[]
+```
+
+### location
+```typescript
+faker.location.street(): string
+faker.location.streetAddress(useFullAddress?: boolean): string
+faker.location.city(): string
+faker.location.state(): string
+faker.location.stateAbbr(): string
+faker.location.country(): string
+faker.location.countryCode(): string
+faker.location.zipCode(): string
+faker.location.latitude(options?: { min?, max?, precision? }): number
+faker.location.longitude(options?: { min?, max?, precision? }): number
+faker.location.direction(): string
+faker.location.buildingNumber(): string
+```
+
+### company
+```typescript
+faker.company.name(): string
+faker.company.catchPhrase(): string
+faker.company.buzzPhrase(): string
+```
+
+### vehicle (Fully Custom)
+```typescript
+faker.vehicle.vrm(): string             // UK Registration: 'AB12 CDE'
+faker.vehicle.vehicle(): string          // 'Toyota Camry'
+faker.vehicle.type(): string             // Sedan, SUV, Truck, Van, Coupe, etc.
+faker.vehicle.manufacturer(): string     // Toyota, Honda, Ford, BMW, Tesla, etc.
+faker.vehicle.model(): string            // Camry, Accord, F-150, Model 3, etc.
+faker.vehicle.fuel(): string             // Gasoline, Diesel, Electric, Hybrid
+faker.vehicle.vin(): string              // 17-character VIN
+faker.vehicle.color(): string            // Black, White, Silver, Red, Blue, etc.
+```
+
+### helpers
+```typescript
+faker.helpers.arrayElement<T>(array: T[]): T
+faker.helpers.arrayElements<T>(array: T[], count?: number): T[]
+faker.helpers.shuffle<T>(array: T[]): T[]
+faker.helpers.maybe<T>(cb: () => T, options?: { probability?: number }): T | undefined
+faker.helpers.objectKey<T>(obj: T): keyof T
+faker.helpers.objectValue<T>(obj: T): T[keyof T]
+```
+
+### lorem
+```typescript
+faker.lorem.word(): string
+faker.lorem.words(count?: number): string              // default: 3
+faker.lorem.sentence(maxWords?: number): string        // default: 3-10 words
+faker.lorem.sentences(count?, separator?): string      // default: 3, sep: ' '
+faker.lorem.paragraph(sentenceCount?): string
+faker.lorem.paragraphs(count?, separator?): string     // default: 3, sep: '\n\n'
+faker.lorem.text(length?: number): string              // default: 200 chars
+faker.lorem.slug(wordCount?: number): string           // URL-safe, default: 3
+faker.lorem.lines(count?: number): string              // default: 3
+```
+
+### Inherited from ts-mocker
+```typescript
+faker.commerce.department() / .price() / .productName() / .productDescription()
+faker.date.past() / .future() / .recent() / .soon()
+faker.finance.creditCardNumber()
+faker.image.avatar() / .url()
+faker.internet.email() / .ip() / .mac() / .url() / .userAgent()
+faker.number.int() / .float()
+faker.person.fullName()
+faker.phone.number()
+faker.string.alpha() / .alphanumeric() / .numeric() / .uuid()
+faker.system.fileName() / .filePath() / .fileType()
+faker.word.adjective() / .noun()
+```
+
+## Seeder Integration
+
+Model attributes declare a `factory` function receiving `faker`:
+
+```typescript
+{
+  name: {
+    validator: { rule: 'string', min: 3, max: 255 },
+    factory: faker => faker.company.name(),
+  },
+  status: {
+    validator: { rule: 'enum', options: ['active', 'inactive'] },
+    factory: faker => faker.helpers.arrayElement(['active', 'inactive']),
+  },
+}
+```
+
+### How Seeding Works
+1. Model needs `traits: { useSeeder: { count: N } }`
+2. `generateRecord()` calls `attr.factory(faker)` for each attribute
+3. Falls back to `attr.default` if factory fails
+4. Converts camelCase → snake_case for DB columns
+5. Auto-hashes password fields (bcrypt)
+6. Inserts in batches of 100
+7. Order: User (0), Team (1), Project (2), everything else (10)
+
+### Smart Default Inference (no factory defined)
+- `is*`, `has*`, `*able` → `false`
+- `*count`, `*amount`, `*quantity` → `0`
+- `*url`, `*link` → `'https://example.com'`
+- `*email` → `faker.internet.email()`
+- `*name` → `faker.person.fullName()`
+- Unknown → `null`
+
+## Gotchas
+- **Not @faker-js/faker** — wrapper around `ts-mocker`. Most APIs compatible but not all
+- **Custom modules override base** — lorem, datatype, location, company, vehicle, helpers are custom
+- **Vehicle module is fully custom** — hardcoded manufacturer/model lists, not from ts-mocker
+- **Factory receives faker** — signature is `(faker: Faker) => value`, not `() => value`
+- **Password detection is heuristic** — by name pattern or `hidden: true` attribute
+- **Seeder batch size is 100** — records inserted in chunks
+- **Model seeding order matters** — User first, then Team, Project, everything else

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

@@ -0,0 +1,158 @@
+---
+name: stacks-git
+description: Use when working with git in a Stacks application — commit conventions, git hooks, changelog generation, commit scopes/types, or GitHub API types. Covers @stacksjs/git, config/git.ts, config/commit.ts, and the git hooks system.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Git
+
+## Key Paths
+- Core package: `storage/framework/core/git/`
+- Git config: `config/git.ts`
+- Commit config: `config/commit.ts`
+- Git hooks config: `storage/framework/core/git-hooks.config.ts`
+- Git utilities: `storage/framework/core/utils/src/git.ts`
+- Commit action: `storage/framework/core/actions/src/commit.ts`
+- Buddy commands: `storage/framework/core/buddy/src/commands/commit.ts`, `changelog.ts`
+- GitHub API types: `storage/framework/types/git.ts`
+- Core types: `storage/framework/core/types/src/git.ts`
+
+## Git Configuration (config/git.ts)
+
+```typescript
+interface GitOptions {
+  hooks: GitHooks
+  scopes: string[]
+  types: { value: string, name: string, emoji: string }[]
+  messages: {
+    type: string, scope: string, customScope: string, subject: string
+    body: string, breaking: string, footer: string, confirmCommit: string
+  }
+}
+```
+
+### Hooks
+```typescript
+hooks: {
+  'pre-commit': 'lint-staged'
+}
+```
+
+### Commit Types
+
+| Value | Emoji | Description |
+|-------|-------|-------------|
+| feat | ✨ | A new feature |
+| fix | 🐛 | A bug fix |
+| docs | 📝 | Documentation only changes |
+| style | 💄 | Changes that don't affect meaning |
+| refactor | ♻️ | Code change without fix or feature |
+| perf | ⚡️ | Performance improvement |
+| test | ✅ | Adding/adjusting tests |
+| build | 📦️ | Build system or dependencies |
+| ci | 🎡 | CI configuration changes |
+| chore | 🔨 | Other changes not affecting src/test |
+| revert | ⏪️ | Reverts previous commit |
+
+### Commit Scopes
+
+`ci`, `deps`, `dx`, `release`, `docs`, `test`, `core`, `actions`, `arrays`, `auth`, `build`, `cache`, `cli`, `cloud`, `collections`, `config`, `database`, `datetime`, `errors`, `git`, `lint`, `modules`, `notifications`, `objects`, `path`, `realtime`, `router`, `buddy`, `security`, `server`, `storage`, `strings`, `tests`, `types`, `ui`, `utils`
+
+## Commit Configuration (config/commit.ts)
+
+Based on `cz-git` UserConfig:
+
+```typescript
+{
+  rules: { 'scope-enum': [2, 'always', [...scopes]] },
+  prompt: {
+    useEmoji: false,
+    allowCustomScopes: true,
+    allowEmptyScopes: true,
+    allowBreakingChanges: ['feat', 'fix'],
+    breaklineNumber: 100,
+    breaklineChar: '|',
+    issuePrefixs: [{ value: 'closed', name: 'closed: ISSUES has been processed' }],
+    maxHeaderLength: Infinity,
+    maxSubjectLength: Infinity,
+  }
+}
+```
+
+## Git Utilities
+
+```typescript
+import { isGitClean } from '@stacksjs/utils'
+
+function isGitClean(): boolean
+// Uses: git diff-index --quiet HEAD --
+// Returns true if clean, false if dirty
+```
+
+## CLI Commands
+
+```bash
+buddy commit                    # Interactive conventional commit
+buddy commit --verbose
+buddy commit -p [project]       # Target specific project
+
+buddy changelog                 # Generate changelog
+buddy changelog --quiet
+buddy changelog --dry-run       # Preview without writing
+buddy changelog -p [project]
+```
+
+## GitHub API Types
+
+### GitHubCommit
+```typescript
+interface GitHubCommit {
+  sha: string
+  commit: {
+    author: { name: string, email: string, date: string }
+    committer: { name: string, email: string, date: string }
+    message: string
+    verification: { verified: boolean, reason: string }
+  }
+  url: string, html_url: string
+  author: { login: string, id: number, avatar_url: string }
+}
+```
+
+### WorkflowRun
+```typescript
+interface WorkflowRun {
+  id: number, name: string, head_branch: string, head_sha: string
+  run_number: number, event: string, status: string, conclusion: string
+  workflow_id: number, created_at: string, updated_at: string
+  actor: { login: string, id: number }
+  run_attempt: number, run_started_at: string
+  jobs_url: string, logs_url: string, artifacts_url: string
+  head_commit: { id: string, message: string, timestamp: string }
+}
+```
+
+## Package Dependencies
+
+```json
+{
+  "name": "@stacksjs/git",
+  "devDependencies": {
+    "@stacksjs/gitlint": "^0.1.5",
+    "@stacksjs/gitit": "^0.2.5",
+    "bun-git-hooks": "^0.3.1"
+  }
+}
+```
+
+## Gotchas
+- **`@stacksjs/git` is mostly re-exports** — actual functionality in `@stacksjs/gitlint`, `@stacksjs/gitit`, `bun-git-hooks`
+- **Pre-commit runs lint-staged** — the only default hook
+- **Emoji disabled by default** — `useEmoji: false` but emoji mappings exist for each type
+- **`buddy commit` runs `npm run commit`** — delegates to commitizen/cz-git flow
+- **Scopes dynamically extended** — component and function names merged into scopes at runtime
+- **Breaking changes only for feat/fix** — `allowBreakingChanges: ['feat', 'fix']`
+- **No max header length** — `maxHeaderLength: Infinity`
+- **Git hooks config re-exports** — `git-hooks.config.ts` just re-exports from `config/git.ts`

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

@@ -0,0 +1,98 @@
+---
+name: stacks-guard
+description: Use for safety rails — warns on destructive commands (rm -rf, DROP TABLE, force-push, git reset --hard) and provides freeze mode for focused debugging. Invoke with /stacks-guard.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-guard — Safety Rails
+
+Prevent destructive actions and enforce focus during debugging sessions.
+
+## Destructive Command Detection
+
+### 🔴 CRITICAL — Block and require confirmation
+
+| Pattern | Risk |
+|---------|------|
+| `rm -rf /`, `rm -rf ~`, `rm -rf .` | Catastrophic file deletion |
+| `DROP TABLE`, `DROP DATABASE`, `TRUNCATE` | Irreversible data loss |
+| `git push --force` to `main`/`master` | Overwrites shared history |
+| `git reset --hard` with uncommitted changes | Loses uncommitted work |
+| `git clean -fd` | Deletes untracked files permanently |
+| `buddy migrate:fresh` on production | Drops ALL tables |
+| `buddy seed --fresh` on production | Truncates all data |
+
+Response:
+```
+🔴 GUARD: Destructive command detected
+Command: [command]
+Risk: [what will be destroyed]
+Reversible: [yes/no]
+```
+
+### 🟡 WARNING — Warn but allow
+
+| Pattern | Risk |
+|---------|------|
+| `git push --force` (non-main) | Overwrites remote branch |
+| `rm -rf [specific dir]` | Deletes directory tree |
+| `bun remove [core dep]` | May break build |
+| `git checkout -- .` | Discards all unstaged changes |
+| Bulk file moves/renames | May break imports/aliases |
+| Modifying `config/services.ts` | Contains API keys |
+| Modifying `storage/framework/core/*/src/index.ts` | Public package API |
+
+### 🟢 INFORMATIONAL — Note but don't block
+
+| Pattern | Note |
+|---------|------|
+| `git rebase` | History rewrite — ensure not shared |
+| `bun update` (major versions) | May introduce breaking changes |
+| Modifying CI/CD config | Affects deployment pipeline |
+| Changing auth/permissions code | Security-sensitive |
+| Modifying migration files | Database schema change |
+
+## Freeze Mode
+
+Restrict edits during focused debugging.
+
+### Activate
+```
+/stacks-guard freeze [file or directory pattern]
+```
+
+When active:
+1. **Block edits outside the freeze scope**
+2. **Track all changes** made during the session
+3. **Warn if changes grow large** (>5 files or >50 lines)
+
+### Deactivate
+```
+/stacks-guard thaw
+```
+
+Produces a summary of all changes.
+
+## Pre-Commit Safety
+
+Before commits, scan for:
+1. **Secrets**: API keys, tokens, passwords in staged files
+2. **Debug artifacts**: `console.log`, `debugger`, `TODO: remove`
+3. **Large files**: >1MB being committed
+4. **Lockfile consistency**: `package.json` changed → `bun.lock` should too
+
+## Stacks-Specific Guards
+
+- **Don't edit `storage/framework/types/*.d.ts`** — these are auto-generated
+- **Don't edit `storage/framework/defaults/app/Models/`** without also generating migrations
+- **Don't modify `config/services.ts` in commits** — contains API keys
+- **Check `storage/framework/core/*/package.json` versions** — workspace packages should stay in sync
+
+## Rules
+
+- **Never silently allow destructive commands.**
+- **Don't be annoying.** `rm file.txt` doesn't need a warning. `rm -rf node_modules` is fine — it's regenerable.
+- **Respect user intent.** After warning once, if confirmed, proceed.
+- **Context matters.** Force-push to personal branch ≠ force-push to main.