@stacksjs/defaults 0.75.109 → 0.75.110

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, asynchronous overrides, driver capability evidence, framework feature gates, package resource discovery, or request context. Covers @stacksjs/config and the config/ directory.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,164 +8,110 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Configuration
 
-## Key Paths
-- Core package: `storage/framework/core/config/src/`
-- Configuration directory: `config/`
-- Defaults: `storage/framework/core/config/src/defaults.ts`
-- Overrides: `storage/framework/core/config/src/overrides.ts`
-
-## Config API
-
-```typescript
-import { config, getConfig } from '@stacksjs/config'
-
-config.app.name       // 'Stacks'
-config.database       // full database config
-config.auth           // auth config
-getConfig()           // returns full StacksOptions
-```
-
-## Individual Config Exports
-
-```typescript
-import { ai, analytics, app, auth, cache, cloud, cli, database, dns, docs, email, errors, git, hashing, library, logging, notification, payment, ports, queue, realtime, security, saas, searchEngine, services, filesystems, team, ui } from '@stacksjs/config'
-```
-
-## Config Builder Functions
-
-```typescript
-import { defineApp, defineDatabase, defineCache, defineEmail } from '@stacksjs/config'
-
-// Used in config files:
-export default defineApp({
-  name: 'My App',
-  env: 'production',
-  url: 'https://myapp.com'
-}) satisfies AppConfig
-```
-
-All builders: `defineApp`, `defineCache`, `defineCdn`, `defineChat`, `defineCli`, `defineDatabase`, `defineDependencies`, `defineDns`, `defineEmailConfig`, `defineEmail`, `defineGit`, `defineHashing`, `defineLibrary`, `defineNotification`, `definePayment`, `defineQueue`, `defineSearchEngine`, `defineSecurity`, `defineServices`, `defineSms`, `defineFilesystems`, `defineUi`, `defineEvents`
-
-`defineModel` is NOT among them: it comes from `@stacksjs/orm`, and it builds a
-model rather than returning a config object. `@stacksjs/config` used to export a
-second one typed `(config: Model) => Model`, which widened every literal a model
-declared - its table name, its attribute names - so a model that imported the
-wrong one silently lost the typing the ORM version exists to provide.
-
-The app-level registries have their own helpers, in the packages that own what
-they name: `defineEvents` and `defineListener` from `@stacksjs/events`,
-`defineMiddleware` from `@stacksjs/router`, `defineGates` from `@stacksjs/auth`.
-
-## Helper Functions
-- `determineAppEnv(): 'dev' | 'stage' | 'prod' | string`
-- `localUrl(): string` — local development URL
-
-## Feature Flags
-`feature(name)` from `@stacksjs/config` reads `enabled` on `config/<name>.ts`.
-It accepts the installable bundles (`dashboard`, `commerce`, `cms`, `forms`,
-`marketing`, `monitoring`, `realtime`, `queue`) plus two config gates: `auth`
-(whether the ORM loads Team, Referral, Subscriber, Site and the other account
-models; it does not mount the auth routes, `STACKS_DEFAULT_ROUTES` does) and
-`email` (the email webhook route bundle). `./buddy features` lists both groups.
-
-Any other name is a compile error, so a typo cannot silently read `false`. An
-app's own flags are declared first:
-
-```ts
-declare module '@stacksjs/config' {
-  interface AppFeatureFlags { 'new-checkout': true }
-}
-```
-
-## All 44 Config Files
-
-### Core App
-| File | Type | Key Settings |
-|------|------|-------------|
-| `app.ts` | AppConfig | name, env, url, debug, key, timezone, locale, seo (sitemap.xml / robots.txt) |
-| `auth.ts` | AuthConfig | guards, providers, token and browser-session lifetimes, passwordReset |
-| `database.ts` | DatabaseConfig | default driver, connections (sqlite/mysql/postgres/dynamodb), queryLogging |
-| `cache.ts` | CacheConfig | driver('memory'), ttl(3600), maxKeys(-1), redis config |
-| `env.ts` | EnvConfig | validation schemas for env vars |
-| `stacks.ts` | StackExtensionRegistry | extension definitions |
-
-### Services
-| File | Type | Key Settings |
-|------|------|-------------|
-| `email.ts` | EmailConfig | from, domain, mailboxes, server config, ports, categorization, default('ses') |
-| `sms.ts` | SmsConfig | enabled(false), provider('twilio'), drivers (twilio/vonage/pinpoint) |
-| `notification.ts` | NotificationConfig | default('email') |
-| `payment.ts` | PaymentConfig | driver('stripe'), stripe keys |
-| `ai.ts` | AiConfig | default model, AWS Bedrock models |
-| `analytics.ts` | AnalyticsConfig | driver('fathom'), tracking settings |
-
-### Infrastructure
-| File | Type | Key Settings |
-|------|------|-------------|
-| `cloud.ts` | CloudConfig | project, mode(server/serverless), environments, infrastructure |
-| `dns.ts` | DnsConfig | a, aaaa, cname, mx, txt records, nameservers |
-| `queue.ts` | QueueConfig | default('sync'), connections (sync/database/redis/sqs/memory) |
-| `realtime.ts` | RealtimeConfig | enabled(true), mode, driver, channels, WebSocket config |
-| `search-engine.ts` | SearchEngineConfig | driver('opensearch') |
-
-### Development
-| File | Type | Key Settings |
-|------|------|-------------|
-| `ports.ts` | Ports | frontend:3000, backend:3001, admin:3002, ... api:3008 |
-| `lint.ts` | PickierOptions | format rules, indent, quotes, semi |
-| `git.ts` | GitConfig | hooks, scopes, commit types |
-| `commit.ts` | UserConfig | cz-git conventional commit config |
-| `logging.ts` | LoggingConfig | logsPath, deploymentsPath |
-| `docs.ts` | BunPressOptions | docsDir, outDir, nav, sitemap |
-
-### Security
-| File | Type | Key Settings |
-|------|------|-------------|
-| `security.ts` | SecurityConfig | api.rowScoping('deny'), api.models('all' / 'own' / 'none' / names; `STACKS_MODEL_APIS` overrides), firewall (enabled, countryCodes, rateLimitPerMinute) |
-| `hashing.ts` | HashingConfig | driver('bcrypt'), bcrypt.rounds(12), argon2 config |
-
-### Features
-| File | Type | Key Settings |
-|------|------|-------------|
-| `blog.ts` | BlogConfig | subdomain, postsPerPage, enableRss/enableSitemap (enableComments and enableSearch are declared but not yet honoured) |
-| `cms.ts` | CmsConfig | content management settings |
-| `saas.ts` | SaasConfig | plans (Hobby/Pro/Lifetime with pricing), webhook, currencies |
-| `ui.ts` | HeadwindOptions | content, output, minify |
-| `stx.ts` | StxOptions | componentsDir, layoutsDir, partialsDir |
-
-### Data & Storage
-| File | Type | Key Settings |
-|------|------|-------------|
-| `filesystems.ts` | FilesystemsConfig | driver('bun'), root, s3 config, defaultVisibility('private') |
-| `file-systems.ts` | — | re-exports from filesystems.ts |
-| `query-builder.ts` | — | re-exports from qb.ts |
-| `qb.ts` | QueryBuilderConfig | dialect, timestamps, pagination, softDeletes, transactions |
-
-### Other
-| File | Type | Key Settings |
-|------|------|-------------|
-| `buddy-bot.ts` | BuddyConfig (`@buddysh/buddy`) | repository, dashboard, workflows |
-| `cli.ts` | BinaryConfig | name, command, description |
-| `deps.ts` | PantryConfig | system dependencies (bun, sqlite, redis, etc.) |
-| `errors.ts` | ErrorConfig | comprehensive validation error messages |
-| `library.ts` | LibraryConfig | name, owner, webComponents, functions |
-| `phone.ts` | PhoneConfig | enabled, provider, businessHours |
-| `services.ts` | ServicesConfig | API keys for 20+ services |
-| `team.ts` | Team | name, members |
-
-## Default Values (from defaults.ts)
-- App name: `'Stacks'`
-- Cache driver: `'memory'`
-- Database: SQLite at `database/stacks.sqlite`
-- Hashing: bcrypt, 12 rounds
-- Auth token expiry: 30 days
-- Ports: frontend 3000, backend 3001, admin 3002, api 3008
-
-## Gotchas
-- Config files are TypeScript with `satisfies` for type checking
-- All configs support environment variable overrides via `env.*`
-- Framework provides defaults — user overrides in `~/config/*.ts`
-- Two duplicate file pairs: `file-systems.ts`/`filesystems.ts` and `query-builder.ts`/`qb.ts`
-- Config changes may require dev server restart
-- The `services.ts` file contains API keys for AWS, Stripe, Slack, Discord, OpenAI, Anthropic, etc.
-- Lazy loading is used in config to avoid circular dependencies
+Read the application's `config/*.ts` and exported types before proposing a
+setting. Config is typed executable code; a copied options inventory can drift.
+
+## Loading and readiness
+
+~~~ts
+import { config, overridesReady } from '@stacksjs/config'
+
+await overridesReady
+const applicationName = config.app.name
+~~~
+
+The config proxy merges framework defaults with asynchronous application
+overrides. Read it after overridesReady when initializing a driver or caching a
+scalar setting. Destructuring before readiness can capture a default forever.
+The readiness promise and override storage are shared across installed copies.
+Compiled server builds have a separate minimal env config and may deliberately
+set `SKIP_CONFIG_LOADING=true`; see `stacks-server`.
+
+Individual exports (app, auth, database, queue, filesystems and others) are also
+available. Use the matching `satisfies ...Config` type or define helper.
+`defineModel` belongs to `@stacksjs/orm`. App registries are owned by their
+packages: defineEvents/defineListener by events, defineMiddleware by router,
+defineGates by auth and defineCommand by cli.
+
+## Driver capability evidence
+
+`capabilityRegistry`, `capabilityDrivers(category)`,
+`findCapability(category, name)` and `assertCapabilityAvailable` are
+exported by `@stacksjs/config`. Read status, topology, prerequisites,
+limitations and testEvidence before promising provider support.
+
+- Supported local drivers have retained local tests. Supported remote drivers
+  name a version and CI workflow in liveServiceContract.
+- Partial drivers have an implementation with narrower retained evidence.
+  For S3/Azure and external mail this includes request/signature/config checks,
+  without a live object round-trip or delivery assertion.
+- Experimental drivers are usable within their documented limitations, without
+  the supported conformance claim.
+- Unsupported and unknown drivers throw through assertCapabilityAvailable.
+  A config-shaped entry alone is not an implemented runtime driver.
+
+`validateConfig(snapshot)` returns path/message issues; `reportConfigIssues`
+prints them. Boot validation checks important known fields, not every possible
+option. Read `validators.ts` before treating it as a complete schema validator.
+
+## Framework feature gates
+
+`feature(name)` reads a bundle's `config/<name>.ts`. Explicit runtime
+enableFeature/disableFeature overrides win, then config enabled and its optional
+env allowlist, then framework fallback (dashboard is on when config is absent).
+resetFeature removes a runtime override; listFeatures snapshots the known set.
+
+Use `buddy features` and the bundle's install/uninstall commands to inspect
+and change installed feature resources. Runtime config gates and installation
+are related but not interchangeable. The `auth` gate controls account-family
+model loading; default auth routes are selected by STACKS_DEFAULT_ROUTES.
+The `email` gate controls the implicit email webhook route bundle.
+
+Application config flags augment AppFeatureFlags. Runtime targeting,
+experiments and persisted user flags belong to the separate native
+`@stacksjs/feature-flags` package. Read its exports/config before using it;
+`feature()` is not an A/B allocation API.
+
+## Native resource discovery
+
+Discovered packages can contribute routes, models, jobs, migrations, views and
+explicitly opted-in components through their package Stacks metadata.
+`packageModelRoots/packageJobRoots/packageMigrationRoots/packageViewRoots/
+packageComponentRoots`read`storage/framework/discovered-packages.json`.
+Missing manifests mean no package resources. Component directories are opt-in
+because bare tag names enter a global template namespace. Package migration
+sources are copied before any preprocessing; installed package files are read
+as resources, not rewritten in place. See `stacks-plugins`.
+
+Default view selection uses `resolveViewPatterns` and the exported bundle
+metadata. Request-local configuration context lives in `request-context.ts`:
+`useRequestEvent()` reads the scoped request snapshot, while entrypoints
+install scopes. Request context must be established per request; globals or
+cached snapshots cannot represent concurrent users.
+
+## Configuration paths
+
+| Concern | Read |
+|---|---|
+| application, SEO, launch | app.ts |
+| model connection and SQL behavior | database.ts, query-builder.ts |
+| credentials, sessions, cookies, OAuth, magic links | auth.ts, hashing.ts |
+| model API exposure and row ownership | security.ts |
+| background work and cache | queue.ts, cache.ts |
+| uploads and disks | filesystems.ts, default local disk |
+| mail, SMS and notifications | email.ts, sms.ts, notification.ts, services.ts |
+| deployment | cloud.ts, its named tsCloud export and default wrapper |
+| frontend | stx.ts, crosswind.ts, ui.ts |
+| agent installation | app/Skills/, defaults/ai/, stacks-skills package |
+
+Use `stacks-env` for validated/coerced environment variables, encrypted files
+and shared-box tenant isolation. Config files hold expressions referencing env;
+editing a nested live object is not the same as persisting that source file.
+
+## Sources and verification
+
+Public contract: `storage/framework/core/config/src/index.ts`,
+`config.ts`, `overrides.ts`, `capabilities.ts`,
+`features.ts`, `discovered-resources.ts` and `request-context.ts`.
+Retained tests are under `core/config/tests/`; driver readiness also has
+`core/search-engine/tests/early-proxy.test.ts`.

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

@@ -30,10 +30,12 @@ cron/src/
 ```typescript
 import { parse } from '@stacksjs/cron'
 
-function parse(expression: string, relativeDate?: Date | number): Date | null
+function parse(expression: string, relativeDate?: Date | number, options?: { tz?: string }): Date | null
 ```
 
-Parses a cron expression and returns the next matching UTC date. Falls back to native `Bun.cron.parse()` if available.
+Parses a cron expression and returns the next matching Date as a UTC instant.
+Without tz it uses Bun.cron.parse when available, otherwise the built-in parser.
+With tz it always uses the built-in parser so the IANA timezone is honored.
 
 ```typescript
 parse('0 0 * * *')                   // Next midnight UTC
@@ -47,7 +49,7 @@ parse('0 0 1 * *', new Date())       // Next 1st of month from now
 ```typescript
 import { parseCron } from '@stacksjs/cron'
 
-function parseCron(expression: string, relativeDate?: Date | number): Date | null
+function parseCron(expression: string, relativeDate?: Date | number, options?: { tz?: string }): Date | null
 ```
 
 Full 5-field cron parser supporting:
@@ -80,9 +82,9 @@ async function register(path: string, schedule: string, title: string): Promise<
 
 Registers an OS-level cron job. Requires Bun.cron support.
 
-- `path` — path to the script (must export `scheduled(controller)` handler)
-- `schedule` — cron expression
-- `title` — job identifier (alphanumeric, hyphens, underscores only)
+- `path` - path to the script (must export `scheduled(controller)` handler)
+- `schedule` - cron expression
+- `title` - job identifier (alphanumeric, hyphens, underscores only)
 
 ### remove
 
@@ -114,10 +116,22 @@ parse('30 4 * * SUN')         // Sundays at 4:30 AM
 ```
 
 ## Gotchas
-- **Low-level primitive** — for most use cases, prefer `@stacksjs/scheduler` which provides `.daily()`, `.hourly()`, etc.
-- **UTC dates** — `parse()` returns UTC dates, not local time
-- **POSIX OR logic** — when both dayOfMonth and dayOfWeek are specified (not `*`), matches if EITHER matches
-- **Named values** — supports JAN-DEC and SUN-SAT (case-insensitive)
-- **Searches up to ~4 years** — parser iterates forward to find the next match, stops after ~4 years
-- **OS-level registration** — `register()` requires Bun.cron support (not available in all environments)
-- **`register()` scripts must export `scheduled()`** — the target file must have a `scheduled(controller)` handler
+- **Low-level primitive** - for most use cases, prefer `@stacksjs/scheduler` which provides `.daily()`, `.hourly()`, etc.
+- **UTC dates** - `parse()` returns UTC dates, not local time
+- **POSIX OR logic** - when both dayOfMonth and dayOfWeek are specified (not `*`), matches if EITHER matches
+- **Named values** - supports JAN-DEC and SUN-SAT (case-insensitive)
+- **Searches up to ~4 years** - parser iterates forward to find the next match, stops after ~4 years
+- **OS-level registration** - `register()` requires Bun.cron support (not available in all environments)
+- **`register()` scripts must export `scheduled()`** - the target file must have a `scheduled(controller)` handler
+
+## Timezone and verification
+
+Use `parse('0 9 * * *', new Date(), { tz: 'America/New_York' })` for a local
+9 AM schedule. DST transition hours can be skipped or repeated; the parser
+does not promise one business effect across that window. The high-level
+scheduler adds task policies and `.cron()` support for selected seconds forms;
+the low-level parser still accepts five fields only.
+
+Source: `storage/framework/core/cron/src/index.ts` and `parser.ts`.
+Retained parser tests are under `core/cron/tests/`; scheduler timezone and
+cron-expression coverage is under `core/scheduler/tests/`.

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

@@ -1,190 +1,85 @@
 ---
 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 Stacks templates with Crosswind utilities, configuring the ts-css engine, responsive or dark variants, theme tokens, shortcuts, safelists, or debugging generated CSS. Covers config/css.ts and @stacksjs/ts-css/engine.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
-# Crosswind CSS Framework
+# Stacks utility CSS
 
-Crosswind (`@cwcss/crosswind`) is the utility-first CSS engine for Stacks — similar to Tailwind CSS but built for Bun.
+Use Crosswind utility classes in STX. The current framework implements this
+through `@stacksjs/ts-css/engine`, the successor package used by STX and
+`@stacksjs/ui`; do not copy an old `@cwcss/crosswind` import into this checkout.
+Pair visually important work with `stacks-design-taste`.
 
-## Design & anti-slop skills
+## Configuration and delivery
 
-For taste-level guidance on *which* utilities to reach for (layout variance, spacing rhythm, color calibration, motion), see the design-taste family: `stacks-design-taste` (flagship), the presets `stacks-design-soft` / `stacks-design-minimalist` / `stacks-design-brutalist`, `stacks-redesign`, `stacks-design-output`, and the image-first `stacks-image-to-code` / `stacks-imagegen-web` / `stacks-imagegen-mobile` / `stacks-brandkit`.
+`config/css.ts` is the authoritative application config, typed as
+`CssOptions` from `@stacksjs/ts-css/engine`. `config/ui.ts` instead configures
+STX, including its root and stateDir. STX's loader accepts a legacy crosswind
+config as a deprecated fallback; prefer the css name for new projects.
 
-## Key Paths
-- Package: `node_modules/@cwcss/crosswind/`
-- UI config: `config/ui.ts` (Crosswind options referencing Crosswind)
-- Default styles: `storage/framework/defaults/styles/`
-- Output: `storage/framework/stx/cache/cw-<hash>.css`, one file per page (stx's `stateDir`, set in `config/ui.ts`)
+```ts
+import type { CssOptions } from '@stacksjs/ts-css/engine'
 
-## Core API
-
-### CSSGenerator
-
-```typescript
-import { CSSGenerator } from '@cwcss/crosswind'
-
-const generator = new CSSGenerator(config: CrosswindConfig)
-generator.generate(className: string): void    // Process a single class
-generator.toCSS(includePreflight?, minify?): string  // Output CSS
-generator.reset(): void                        // Clear generated CSS
-```
-
-### Parser
-
-```typescript
-import { parseClass, expandBracketSyntax, extractClasses, extractAttributifyClasses } from '@cwcss/crosswind'
-
-parseClass('hover:bg-blue-500'): ParsedClass
-// { raw: 'hover:bg-blue-500', variants: ['hover'], utility: 'bg-blue-500', important: false, arbitrary: false }
-
-extractClasses(htmlContent: string, options?): Set<string>
-expandBracketSyntax('text-[#1a1a1a]', config?): string[]
-extractAttributifyClasses(content, config?): Set<string>
+export default {
+  content: ['./resources/**/*.{stx,html}'],
+  minify: false,
+} satisfies CssOptions
 ```
 
-### Scanner
+The default config also includes framework component/view roots. Preserve those
+when replacing application content globs. The STX server generates CSS for
+the page's extracted classes and caches it under
+`storage/framework/stx/cache/cw-<hash>.css`. The historical cw prefix does not
+mean that the old package is loaded. Cache output is runtime state, not source.
 
-```typescript
-import { Scanner } from '@cwcss/crosswind'
+For engine-level work, inspect the installed `CssOptions` and exports rather
+than copying a handwritten interface. The engine exposes `CSSGenerator`:
 
-const scanner = new Scanner(patterns: string[], transformer?, extractOptions?)
-await scanner.scan(): Promise<ScanResult>
-await scanner.scanFile(filePath: string): Promise<Set<string>>
-scanner.scanContent(content: string): Set<string>
-```
-
-### Build Functions
-
-```typescript
-import { build, writeCSS, buildAndWrite } from '@cwcss/crosswind'
-
-const result = await build(config: CrosswindConfig): Promise<BuildResult>
-await writeCSS(css: string, outputPath: string): Promise<void>
-await buildAndWrite(config: CrosswindConfig): Promise<BuildResult>
+```ts
+import { CSSGenerator, defaultConfig } from '@stacksjs/ts-css/engine'
 
-interface BuildResult {
-  css: string
-  classes: Set<string>
-  duration: number
-  compiledClasses?: Map<string, { className: string, utilities: string[] }>
-  transformedFiles?: Map<string, string>
-}
+const generator = new CSSGenerator(defaultConfig)
+generator.generate('hover:bg-blue-600')
+const css = generator.toCSS()
 ```
 
-### Bun Plugin
+## Template authoring
 
-```typescript
-import { plugin } from '@cwcss/crosswind'
+Use static complete class names so extraction can find the selected utilities.
+For stateful classes use literal branches, for example
+`:class="active() ? 'bg-blue-600' : 'bg-gray-200'"`, rather than assembling
+`'bg-' + color`. If a class only exists in runtime data, deliberately safelist
+it in the engine config after checking the config's actual type.
 
-const bunPlugin = plugin(options?: CrosswindPluginOptions): BunPlugin
-```
-
-## Configuration
-
-```typescript
-interface CrosswindConfig {
-  content: string[]                    // Glob patterns for source files
-  output: string                       // Output CSS file path
-  minify: boolean
-  watch: boolean
-  verbose?: boolean
-  theme: Theme
-  shortcuts: Record<string, string | string[]>
-  rules: CustomRule[]
-  variants: VariantConfig
-  safelist: string[]                   // Always include these classes
-  blocklist: string[]                  // Never include these classes
-  preflights: Preflight[]
-  presets: Preset[]
-  compileClass?: CompileClassConfig
-  attributify?: AttributifyConfig
-  bracketSyntax?: BracketSyntaxConfig
-  cssVariables?: boolean
-}
-```
-
-### Theme
-
-```typescript
-interface Theme {
-  colors: Record<string, string | Record<string, string>>
-  spacing: Record<string, string>
-  fontSize: Record<string, [string, { lineHeight: string }]>
-  fontFamily: Record<string, string[]>
-  screens: Record<string, string>
-  borderRadius: Record<string, string>
-  boxShadow: Record<string, string>
-  extend?: Partial<Omit<Theme, 'extend'>>
-}
-```
-
-### Variants (40+ built-in)
-
-```
-responsive, hover, focus, active, disabled, dark, group, peer,
-before, after, marker, first, last, odd, even, first-of-type,
-last-of-type, visited, checked, focus-within, focus-visible,
-placeholder, selection, file, required, valid, invalid, read-only,
-autofill, open, closed, empty, enabled, only, target, indeterminate,
-default, optional, print, rtl, ltr, motion-safe, motion-reduce,
-contrast-more, contrast-less
-```
-
-### Parsed Class Structure
-
-```typescript
-interface ParsedClass {
-  raw: string              // Original class string
-  variants: string[]       // Applied variants (hover, focus, etc.)
-  utility: string          // Core utility name
-  value?: string           // Arbitrary value if present
-  important: boolean       // Has ! prefix
-  arbitrary: boolean       // Uses [] brackets
-  typeHint?: string        // Type hint for arbitrary values
-}
-```
-
-## Usage in Templates
-
-```html
-<div class="flex items-center justify-between p-4 bg-white rounded-lg shadow">
-  <h1 class="font-bold text-2xl text-gray-900">Title</h1>
-  <button class="px-4 py-2 text-white bg-blue-500 hover:bg-blue-600 rounded">
-    Click me
-  </button>
-</div>
-
-<!-- Arbitrary values -->
-<div class="grid-cols-[1fr_2fr] w-[calc(100%-2rem)] text-[#1a1a1a]">
-
-<!-- Dark mode -->
-<div class="text-black dark:text-white bg-white dark:bg-gray-900">
-
-<!-- Responsive -->
-<div class="w-full md:w-1/2 lg:w-1/3">
-```
-
-## Built-in Utility Categories
-- Display (flex, grid, block, hidden, container)
-- Flexbox (direction, wrap, justify, align, gap)
-- Spacing (margin, padding)
-- Sizing (width, height, min/max)
-- Typography (font-size, font-weight, line-height, text-align, text-color)
-- Colors (background, text, border, ring)
-- Borders (width, radius, style)
-- Effects (shadow, opacity)
-- Transitions & animations
+Responsive variants (`md:`, `lg:`), state variants (`hover:`, `focus-visible:`),
+`dark:`, arbitrary values and `motion-reduce:` are ordinary utilities. Theme,
+shortcut and custom-rule support belongs in css config. Validate an uncommon
+utility by checking emitted CSS in the installed engine; familiar Tailwind
+syntax alone does not establish support.
 
 ## Gotchas
-- **Not Tailwind** — Crosswind is a separate implementation with Tailwind-compatible syntax
-- **Stacks uses Crosswind config** — `config/ui.ts` defines Crosswind options which feed Crosswind
-- **Output is per-page, content-hashed** — `storage/framework/stx/cache/cw-<hash>.css`, generated on demand rather than one bundled stylesheet. The directory is gitignored and safe to delete; the next request regenerates it
-- **Bun plugin available** — can be used as a Bun build plugin for automatic CSS generation
-- **Attributify mode** — optional mode where utilities can be written as HTML attributes instead of classes
-- **Bracket syntax** — `text-[#custom]` for arbitrary values, same as Tailwind JIT
-- **Custom rules** — defined as `[RegExp, (match) => Record<string, string>]` tuples
-- **Presets** — extensible via presets for shared configurations
+
+- Preflight configuration uses `preflights` objects. A top-level boolean
+  `preflight` is not the engine option; the base reset already ships.
+- Dark utilities require the appropriate root appearance state. Use
+  `useColorMode()` and STX `@appearanceBootstrap` for persisted pre-paint setup.
+- Keep fonts and colors in application tokens/config; a utility does not
+  download a font or introduce an icon dependency.
+- Use CSS transitions/keyframes and scroll-driven CSS for motion. Browser
+  observation and reduced-motion helpers are documented in
+  `stacks-composables`, including cleanup and client-delivery boundaries.
+- Content hashes include config/class inputs. A cache file should never be
+  hand-edited to fix a source class or token.
+
+## Source and evidence
+
+`config/css.ts`, `config/ui.ts`, `core/ui/src/index.ts` and
+`core/ui/package.json` establish the framework boundary. The installed STX
+`dev-server/ts-css` module establishes loader precedence, class extraction
+and cache behavior. Relevant upstream tests include
+`test/dev-server/ts-css-extraction.test.ts` and
+`test/ts-css-shortcut-precedence.test.ts`. Core paths are relative to
+`storage/framework/`.

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

@@ -21,6 +21,14 @@ The Stacks admin dashboard provides a full-featured admin panel with 100+ route
 
 ## Dashboard Sections
 
+Enable/install the dashboard feature before expecting its default route bundle
+and owned application scaffolds. Keep custom page/component overrides under
+`resources/` and custom Actions under `app/` at their matching relative paths.
+The sidebar registry determines navigation; a page existing on disk does not
+add a sidebar entry or authorize its data Action. Feature sections can be
+disabled independently in configuration. Pair new model views with
+`stacks-models`, `stacks-actions`, and the route registry actually mounted.
+
 Dashboard route views are mounted at the dashboard server root. Do not prefix
 page links with `/dashboard`. The `/api/dashboard/*` prefix is reserved for
 dashboard data Actions.