@stacksjs/defaults 0.75.109 → 0.75.110

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

@@ -57,7 +57,7 @@ import { Visibility, createDirectoryListing, normalizeExpiryToMilliseconds, norm
 
 // Low-level file operations
 import { copy, copyFile, copyFolder } from '@stacksjs/storage'
-import { move, rename } from '@stacksjs/storage'
+import { storage } from '@stacksjs/storage' // storage.move, storage.rename
 import { del, deleteFile, deleteFolder, deleteEmptyFolder, deleteEmptyFolders, deleteGlob, isDirectoryEmpty } from '@stacksjs/storage'
 import { readJsonFile, readPackageJson, readTextFile, writeFile, writeJsonFile, writeTextFile, put, get, getFiles, deleteFiles, hasFiles } from '@stacksjs/storage'
 import { isFolder, isDir, doesFolderExist, createFolder, getFolders } from '@stacksjs/storage'
@@ -160,7 +160,7 @@ Storage.reset()
 The facade auto-configures these disks from `config/filesystems.ts`:
 
 - **`local`** -- `driver: 'local'`, root: `<project>/storage/app`, visibility: from config (default `'private'`)
-- **`public`** -- `driver: 'local'`, root: `<project>/public`, url: `<appUrl>/storage`, visibility: `'public'`
+- **`public`** -- `driver: 'local'`, root: `<project>/public`, url: the application origin, visibility: `'public'`
 - **`s3`** -- only added if `s3.bucket` is configured in filesystems config
 
 ## StorageAdapter Interface
@@ -169,7 +169,7 @@ All adapters implement this interface:
 
 ```typescript
 interface StorageAdapter {
-  write(path: string, contents: FileContents): Promise<void>
+  write(path: string, contents: FileContents): Promise<PutResult>
   read(path: string): Promise<FileContents>
   readToString(path: string): Promise<string>
   readToBuffer(path: string): Promise<Buffer>
@@ -208,8 +208,8 @@ const local = createLocalStorage({ root: './storage' })
 - `moveFile()` uses `fs.rename()`; `copyFile()` uses `fs.copyFile()`
 - `checksum()` uses `Bun.CryptoHasher` (default algorithm: `sha256`)
 - `temporaryUrl()` generates HMAC-signed URLs using `APP_KEY` env var
-- `changeVisibility()` is a no-op (Node.js doesn't map to public/private simply)
-- `visibility()` always returns `'private'`
+- `changeVisibility()` changes POSIX modes: public files/directories use 0644/0755, private use 0600/0700
+- `visibility()` reads mode bits; a world-readable entry is public, other modes collapse to private
 - MIME type detection is extension-based (supports txt, html, css, js, json, xml, pdf, zip, jpg, jpeg, png, gif, svg, mp4, mp3, wav)
 - `list()` returns an async iterable; supports `deep: true` for recursive listing
 
@@ -370,17 +370,19 @@ copyFolder('srcDir/', 'destDir/', ['dist'])     // directory with exclusions
 ### Move/Rename
 
 ```typescript
-import { move, rename } from '@stacksjs/storage'
+import { storage } from '@stacksjs/storage'
 
-const result = await move('old.txt', 'new.txt')                    // single file
-const result = await move(['a.txt', 'b.txt'], 'dest/')             // multiple files to directory
-const result = await move('old.txt', 'new.txt', { overwrite: true })
+const result = await storage.move('old.txt', 'new.txt')                    // single file
+const result = await storage.move(['a.txt', 'b.txt'], 'dest/')             // multiple files to directory
+const result = await storage.move('old.txt', 'new.txt', { overwrite: true })
 
-const result = await rename('old.txt', 'new.txt')
+const result = await storage.rename('old.txt', 'new.txt')
 // Returns Result<{ message: string }, Error>
 ```
 
-`move()` creates destination directories if needed. Without `overwrite: true`, throws if destination exists.
+Low-level storage.move/rename returns a Result; inspect an error result instead
+of assuming an awaited call succeeded. The facade Storage.move targets a disk
+and has a different void/error contract.
 
 ### Delete
 
@@ -610,9 +612,9 @@ const config = configFromEnv({ default: 'local' })
 ```
 
 ## Gotchas
-- Default driver is `'bun'` (not `'local'`), but the Storage facade only supports `'local'` and `'s3'` drivers -- the `buildConfig()` in the facade maps the filesystems config to `'local'` as the default disk driver
+- The default is the local disk. filesystems.driver names a configured disk, not an adapter; facade drivers are local, s3 and azure
 - The `local` disk root is `<project>/storage/app`, not the project root
-- The `public` disk root is `<project>/public` with URL prefix `<appUrl>/storage`
+- The public disk root is `<project>/public`, served from the application origin, with no /storage prefix
 - S3 disk is only added if `s3.bucket` is configured
 - `list()` returns an `AsyncIterable` -- use `for await` to iterate
 - `checksum()` defaults to `sha256` in both adapters (not `md5`)
@@ -620,11 +622,28 @@ const config = configFromEnv({ default: 'local' })
 - `temporaryUrl()` on S3 adapter uses pre-signed URLs via `getSignedUrl()`
 - `LocalStorageAdapter` prevents path traversal -- throws if resolved path escapes the root
 - `S3StorageAdapter` requires a bucket name -- throws on construction if missing
-- `changeVisibility()` is a no-op on both local and S3 adapters
-- `visibility()` always returns `'private'` on both adapters
+- Local uses POSIX permissions; S3 uses provider ACL operations. Azure refuses per-object visibility changes because visibility belongs to its container
+- Query visibility through the adapter; a generated publicUrl does not by itself grant public read access
 - The `Storage` singleton is pre-instantiated -- use `Storage.reset()` to clear caches for testing
 - `UploadedFile.storeAs()` rejects filenames containing `..`, `/`, or `\` to prevent path traversal
 - `UploadedFile.hashName()` is cached -- calling it multiple times returns the same hash
 - Low-level operations (`copy`, `move`, `delete*`, etc.) use synchronous `fs` methods, while the Storage facade uses async operations
 - `zip()` and `unzip()` shell out to the `zip`/`unzip` commands -- they require these tools to be installed on the system
 - `STORAGE_DRIVER` env var controls the driver selection in `config/filesystems.ts`
+
+
+## Upload, stream and signed-link workflows
+
+Read [UPLOADS-AND-DISKS.md](UPLOADS-AND-DISKS.md) when implementing uploads,
+direct-to-provider writes, signed downloads, tenant scoping, large file streams
+or cross-disk transfers. It covers the facade/adapter distinction and the limits
+that change application behavior.
+
+## Provider evidence
+
+The capability registry in `core/config/src/capabilities.ts` marks local
+and memory supported; S3, Azure and Bun adapter parity are partial. S3/Azure
+tests prove signing/request construction, not a live provider round-trip.
+`ensureBucket/ensureConfiguredBuckets` provisions S3-compatible buckets;
+Azure containers must exist already. An adapter's optional streaming, signed
+URL and presigned write methods must be checked before a generic call.

package/ai/skills/stacks-storage/UPLOADS-AND-DISKS.md

@@ -0,0 +1,133 @@
+# Uploads and disks
+
+Read this for application upload workflows and topology-dependent behavior.
+Source root: `storage/framework/core/storage/src/`.
+
+## Facade versus adapter
+
+`Storage` is a manager: put/get/delete/url/copy/move and metadata conveniences
+target the configured default disk. `Storage.disk(name)` returns a StorageAdapter,
+whose equivalent names are write/readToString/deleteFile/publicUrl/copyFile/
+moveFile. It does not return a second facade with put/get methods.
+
+```ts
+import { Storage } from '@stacksjs/storage'
+
+const result = await Storage.disk('public').write('exports/report.txt', 'Report')
+const publicUrl = await Storage.disk('public').publicUrl(result.path)
+```
+
+`write` and facade put return PutResult with path/size and optional provider
+metadata. Optional etag/contentType/lastModified values are not synthesized as
+proof of an unavailable provider response. `Storage.stat(path)` provides a full
+metadata read. `filesystems.driver` names a configured disk: local/public/S3
+out of the box, custom names after init/configure. Default is local.
+
+## Server-proxied uploaded files
+
+`Storage.put(file, options?)` accepts UploadedFileLike from a parsed request or
+the native UploadedFile wrapper and returns PutResult plus url. Options are disk,
+dir, filename strategy (uuid/hash/original/custom), preserveExtension, overwrite
+and transform. Default uuid naming avoids leaking client names. overwrite defaults
+true, so set an explicit policy for collision-sensitive uploads.
+
+Use the native request file macro, validate the boundary, then pass the file to
+storage. Client MIME and file extension are hints. `verifyUploadedMime` and
+`detectMimeFromMagicBytes` provide byte checks; read `mime-verify.ts` for supported
+formats and result semantics. fileInfo/fileInfoFromBytes/fileKind/isPreviewable/
+resolveMime provide native metadata. A transform that changes image format must
+also update the output MIME/name policy. The optional image pipeline is under
+`@stacksjs/storage/image`, separate from the lightweight public entry.
+
+Source: `put-file.ts`, `uploaded-file.ts`, `mime-verify.ts`, `file-info.ts`.
+Evidence: `tests/put-file.test.ts`, `mime-verify.test.ts`, `file-info.test.ts`.
+
+## Direct provider uploads
+
+`presignedUploadUrl({ contentType, expiresIn, dir?, filename?, maxSize? })`
+returns a signed PUT destination. `maxSize` is advisory; a browser can ignore it.
+The provider signs the exact Content-Type. Authenticate and authorize the
+presign action, select the server-owned directory, then verify the uploaded object
+before accepting it as the user's record.
+
+For a provider-enforced size cap, use the S3 POST policy API:
+
+```ts
+import { Storage } from '@stacksjs/storage'
+
+const policy = await Storage.disk('s3').presignedUploadPolicy({
+  key: 'avatars/user-7/avatar.jpg',
+  contentType: 'image/jpeg',
+  contentLengthRange: { min: 1, max: 2 * 1024 * 1024 },
+  expiresIn: 300,
+})
+```
+
+Submit every policy.fields entry and the file as multipart form data to policy.url.
+Local/memory adapters do not implement a remote upload URL; generic facade calls
+throw clearly when the optional adapter method is absent. A frontend direct-upload
+composable must be imported from its package when it is absent from the actual
+STX runtime globals. See stacks-composables and stacks-auto-imports.
+
+Source: `facade.ts`, `types.ts`, `s3-presigned-post.ts`, `adapters/s3.ts`.
+Evidence: `tests/s3-presigned-post.test.ts`, `path-sanitize.test.ts`.
+
+## Streams and cross-disk movement
+
+`getStream(path, { signal? })` returns a web ReadableStream; putStream accepts
+that stream and optional contentType/signal plus S3 multipart tuning. Local and
+Azure reads are incremental; S3 reads currently buffer. S3 writes multipart large
+streams; Azure stages blocks and commits the block list. Abort is driver-specific;
+read the adapter when planning memory bounds or retries.
+
+`Storage.copyAcross('sourceDisk:path', 'destinationDisk:path')` uses a native
+copy for the same disk, otherwise reads then writes buffered content.
+moveAcross uses native same-disk movement, or copy then source delete across
+disks. A cross-disk delete failure can leave both copies after a successful
+destination write; it is not an atomic distributed move. Moving a path onto
+itself preserves the file.
+
+Source: `facade.ts`, adapters; evidence: `tests/streaming.test.ts`,
+`readable-stream-guard.test.ts`, `move-onto-itself.test.ts`.
+
+## Provider disks and visibility
+
+Native presets: localDisk/s3Disk/azureDisk/r2Disk/gcsDisk/filebaseDisk/
+backblazeDisk/hetznerDisk. Read `types/filesystem.ts` for their options and
+credentials. S3-compatible providers share the S3 adapter but vary endpoint,
+path style, region and public URL. config/filesystems.s3.usePathStyleEndpoint
+overrides the endpoint default; virtual-hosted providers need the appropriate
+false value. R2's API host is not a public object host.
+
+Local visibility changes POSIX permissions and reads world-readable mode bits;
+S3 uses provider ACL calls. Modern bucket-owner-enforced S3 buckets reject object
+ACL changes, so use provider policies or signed URLs for those buckets. Public URL
+generation is not itself an ACL change. Azure has container-wide visibility and
+rejects changeVisibility for one blob. Azure service-SAS generation needs an
+account key; a configured SAS token cannot be widened into fresh signed grants.
+ensureConfiguredBuckets provisions S3 buckets, not Azure containers.
+
+KnownDisks is an augmentable name registry for completion, not runtime
+configuration. Declare the disk and configure it as well. Provider evidence
+is recorded in `core/config/src/capabilities.ts`; partial live-provider evidence
+is not upgraded by a preset or TypeScript type.
+
+Evidence: `tests/default-disk.test.ts`, `config-path-style.test.ts`,
+`s3-compatible-disks.test.ts`, `visibility.test.ts`, `s3-visibility.test.ts`,
+`azure-adapter.test.ts` and `azure-signing.test.ts`.
+
+## Signed links and tenant scopes
+
+`signedUrl(path, { expiresIn, ... })` grants temporary access; local signed links
+use APP_KEY and the native storage-serving route, while providers use their
+own signed URL mechanism. Verify the actual route/adapter and disk claim rather
+than serving an arbitrary client-supplied path. PublicUrl and signedUrl have
+different access guarantees.
+
+`scoped(Storage.disk(name), { scope: tenantId })` wraps an adapter with a validated
+path prefix and tenant-relative listing/metadata. Derive tenantId from authenticated
+authority. The wrapper protects path scope, not a caller's right to choose the
+tenant. Underlying optional methods still need driver support.
+
+Source: `signed-url.ts`, `static-serve.ts`, `adapters/scoped.ts`; evidence:
+`tests/scoped.test.ts`, `static-serve.test.ts`, `path-sanitize.test.ts`.

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

@@ -16,15 +16,15 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Architecture
 
 The package re-exports from these submodules:
-- `case.ts` — case conversion functions (camelCase, pascalCase, snakeCase, etc.)
-- `pluralize.ts` — English pluralization/singularization with rule engine
-- `slug.ts` — URL slug generation with extensive character map
-- `utils.ts` — random strings, template interpolation, slash, prefix/suffix, truncate, detect-indent, detect-newline
-- `macro.ts` — `Str` and `str` facade objects
-- `validators.ts` — re-exports from `is.ts` (native string validators)
-- `sponge-case.ts` — random upper/lower case
-- `swap-case.ts` — swap upper/lower case
-- `title-case.ts` — intelligent title case with small word handling
+- `case.ts` - case conversion functions (camelCase, pascalCase, snakeCase, etc.)
+- `pluralize.ts` - English pluralization/singularization with rule engine
+- `slug.ts` - URL slug generation with extensive character map
+- `utils.ts` - random strings, template interpolation, slash, prefix/suffix, truncate, detect-indent, detect-newline
+- `macro.ts` - `Str` and `str` facade objects
+- `validators.ts` - re-exports from `is.ts` (native string validators)
+- `sponge-case.ts` - random upper/lower case
+- `swap-case.ts` - swap upper/lower case
+- `title-case.ts` - intelligent title case with small word handling
 
 The top-level `index.ts` does:
 ```typescript
@@ -64,28 +64,28 @@ interface PascalCaseOptions extends CaseOptions {
 ### Functions
 
 ```typescript
-camelCase('hello world')        // 'helloWorld'  — first word lowercase, rest capitalized
-pascalCase('hello world')       // 'HelloWorld'  — all words capitalized
-snakeCase('hello world')        // 'hello_world' — alias for noCase with '_' delimiter
-kebabCase('hello world')        // 'hello-world' — alias for noCase with '-' delimiter
-constantCase('hello world')     // 'HELLO_WORLD' — all uppercase with '_' delimiter
-trainCase('hello world')        // 'Hello-World' — capitalCase with '-' delimiter
-dotCase('hello world')          // 'hello.world' — noCase with '.' delimiter
-pathCase('hello world')         // 'hello/world' — noCase with '/' delimiter
-sentenceCase('hello world')     // 'Hello world' — first word capitalized, rest lowercase
-capitalCase('hello world')      // 'Hello World' — all words capitalized, space delimiter
-noCase('helloWorld')            // 'hello world' — lowercase with space delimiter
-pascalSnakeCase('hello world')  // 'Hello_World' — capitalCase with '_' delimiter
-paramCase('hello world')        // 'hello-world' — alias for kebabCase
+camelCase('hello world')        // 'helloWorld'  - first word lowercase, rest capitalized
+pascalCase('hello world')       // 'HelloWorld'  - all words capitalized
+snakeCase('hello world')        // 'hello_world' - alias for noCase with '_' delimiter
+kebabCase('hello world')        // 'hello-world' - alias for noCase with '-' delimiter
+constantCase('hello world')     // 'HELLO_WORLD' - all uppercase with '_' delimiter
+trainCase('hello world')        // 'Hello-World' - capitalCase with '-' delimiter
+dotCase('hello world')          // 'hello.world' - noCase with '.' delimiter
+pathCase('hello world')         // 'hello/world' - noCase with '/' delimiter
+sentenceCase('hello world')     // 'Hello world' - first word capitalized, rest lowercase
+capitalCase('hello world')      // 'Hello World' - all words capitalized, space delimiter
+noCase('helloWorld')            // 'hello world' - lowercase with space delimiter
+pascalSnakeCase('hello world')  // 'Hello_World' - capitalCase with '_' delimiter
+paramCase('hello world')        // 'hello-world' - alias for kebabCase
 ```
 
 ### Special Case Functions
 
 ```typescript
-spongeCase('hello world')       // 'hElLo wOrLd' — random upper/lower per character
+spongeCase('hello world')       // 'hElLo wOrLd' - random upper/lower per character
 spongeCase('hello', 'en')       // accepts optional locale
 
-swapCase('Hello')               // 'hELLO' — swaps each character's case
+swapCase('Hello')               // 'hELLO' - swaps each character's case
 swapCase('Hello', 'en')         // accepts optional locale
 ```
 
@@ -164,13 +164,13 @@ The pluralization engine preserves the case pattern of the input word:
 
 Two slug functions with different defaults:
 
-### `slug(str, options?)` — Simple slug (strict + lowercase by default)
+### `slug(str, options?)` - Simple slug (strict + lowercase by default)
 ```typescript
 slug('Hello World')              // 'hello-world'
 slug('Hello World', { lower: false })  // 'Hello-World'
 ```
 
-### `slugify(str, options?)` — Full-featured slug
+### `slugify(str, options?)` - Full-featured slug
 ```typescript
 slugify('Hello World!')          // 'Hello-World!'  (not strict/lowercase by default)
 slugify('Hello World!', { lower: true, strict: true })  // 'hello-world'
@@ -201,8 +201,8 @@ Extensive built-in character map covering:
 Locale-specific character mappings for: `bg`, `de`, `es`, `fr`, `pt`, `uk`, `vi`, `da`, `nb`, `it`, `nl`, `sv`.
 
 ```typescript
-slugify('AE', { locale: 'de' })  // 'AE' (German)
-slugify('AE')                     // 'A'  (default)
+slugify('Ä', { locale: 'de' })  // 'AE' (German character map)
+slugify('Ä')                     // 'A'  (default character map)
 ```
 
 ### Extending the Character Map
@@ -213,7 +213,7 @@ extendCharMap({ 'EUR': 'EUR', 'GBP': 'GBP' })
 ## String Utilities
 
 ```typescript
-capitalize('hello world')                  // 'Hello world' — first char upper, rest lower
+capitalize('hello world')                  // 'Hello world' - first char upper, rest lower
 lowercase('HELLO')                         // 'hello'
 slash('path\\to\\file')                    // 'path/to/file'
 ensurePrefix('https://', 'google.com')     // 'https://google.com'
@@ -259,7 +259,7 @@ isJSON('{"key":"value"}')                 // true -- JSON.parse succeeds
 isHSL('hsl(0, 100%, 50%)')               // true
 isMimeType('text/html')                   // true -- /^[a-z]+\/[a-z0-9\-+.]+$/i
 isDataURI('data:text/plain;base64,...')   // true
-isJWT('eyJhbGciOi...')                    // true -- 3 dot-separated base64url segments
+isJWT('eyJhbGciOiJIUzI1NiJ9.e30.c2ln')   // true -- shape check only, not signature verification
 ```
 
 ### Network Validators
@@ -291,14 +291,14 @@ isPostalCode('12345')                     // true -- US, UK, Canada, generic for
 ### Phone, Identity, Date Validators
 ```typescript
 isMobilePhone('+1234567890')              // true -- international format, min 7 digits
-isUUID('550e8400-e29b-41d4-a716...')      // true -- v1-v5
+isUUID('550e8400-e29b-41d4-a716-446655440000') // true -- full value required
 isISO8601('2024-01-01T00:00:00Z')         // true -- with Date validity check
 isIdentityCard('AB123456')                // true -- generic 5-20 alphanumeric
 isISRC('USRC17607839')                    // true
 isISO31661Alpha2('US')                    // true
 isISO31661Alpha3('USA')                   // true
 validateUsername('user123')               // true -- alias for isAlphanumeric
-isHash('abc123...', 'md5')               // true -- supports md5(32), sha1(40), sha256(64), sha384(96), sha512(128)
+isHash('d41d8cd98f00b204e9800998ecf8427e', 'md5') // true -- exact algorithm length required
 isByteLength('hello', { min: 1, max: 10 }) // true
 isFullWidth('\uFF21')                     // true
 isHalfWidth('a')                          // true
@@ -409,8 +409,14 @@ interface PluralizeOptions { count?, inclusive? }
 - `pascalCase` and `camelCase` accept `PascalCaseOptions` with `mergeAmbiguousCharacters` to control number-prefixed word handling
 - All case functions support `prefixCharacters`/`suffixCharacters` to preserve leading/trailing non-word characters
 - `pluralize()` is both a function AND an object with methods -- `pluralize.plural()`, `pluralize.singular()`, etc.
-- The `random()` function uses `Math.random()`, not crypto -- fine for IDs but not for security tokens
-- `isNumeric()` only matches whole numbers (`/^\d+$/`), not floats -- use parseFloat for float checking
+- `random()` uses crypto.getRandomValues and fails if that facility is absent.
+  A caller still owns the alphabet/length and storage/expiry of its token; the
+  helper is not a complete authentication-token workflow.
+- `isNumeric()` only matches unsigned digit strings (`/^\d+$/`), not floats.
+  Use a numeric validator and full input validation for a request; parseFloat
+  accepts a numeric prefix and is not a complete validity check.
 - `isURL()` requires `http:` or `https:` protocol -- rejects other protocols and bare domains
 - The `Str` facade does NOT include validators -- only case, utility, and pluralization methods
-- `helpers.ts` only exports `toString()` which returns `Object.prototype.toString.call(v)`
+- `helpers.ts` exports `toString()` (Object.prototype.toString, not ordinary
+  string coercion) and `mask(value, character, index, length?)`. Mask supports
+  a negative starting index and uses the first character of its mask string.

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

@@ -23,9 +23,10 @@ When the task is how a page should *look* (not just how stx renders), pair this
 - Partials: `resources/partials/`
 - Views: `resources/views/`
 - Package: `@stacksjs/stx`
+- Utility CSS configuration: `config/css.ts` (`@stacksjs/ts-css/engine`)
 
 ## CRITICAL Rules
-1. **ALWAYS use STX** for templating — never write vanilla JS
+1. **ALWAYS use STX** for templating - never write vanilla JS
 2. **NEVER use** `var`, `document.*`, `window.*` in STX templates
 3. STX `<script>` tags should ONLY contain stx-compatible code (signals, composables, directives)
 
@@ -157,42 +158,44 @@ export default {
 } satisfies StxOptions
 ```
 
-### Full StxConfig
-
-```typescript
-interface StxConfig {
-  enabled: boolean
-  debug: boolean
-  componentsDir: string
-  partialsDir: string
-  layoutsDir?: string
-  defaultLayout?: string
-  templatesDir?: string
-  cachePath: string
-  ssr?: boolean
-  cache?: boolean
-  defaultTitle?: string
-  defaultDescription?: string
-
-  // Feature modules
-  i18n?: Partial<I18nConfig>
-  webComponents?: Partial<WebComponentConfig>
-  streaming?: Partial<StreamingConfig>
-  hydration?: Partial<HydrationConfig>
-  a11y?: Partial<A11yConfig>
-  seo?: Partial<SeoFeatureConfig>
-  animation?: Partial<AnimationConfig>
-  markdown?: Partial<MarkdownConfig>
-  forms?: Partial<FormConfig>
-  pwa?: Partial<PwaConfig>
-  components?: Partial<ComponentConfig>
-  media?: Partial<MediaConfig>
-  strict?: boolean | StrictModeConfig
-  customDirectives?: CustomDirective[]
-}
-```
-
-## STX Capabilities (118+ modules)
+### Configuration source
+
+Import `StxOptions` from the installed package and use `satisfies`; the exported
+type and `config/ui.ts` are authoritative. Optional rendering, hydration,
+streaming, SEO, i18n, component/plugin, form, PWA and strict settings vary with
+the installed STX version. Adding a key to a handwritten interface does not
+enable a module. Read the implementation and retained test for the selected
+setting instead of copying an obsolete flattened config shape.
+
+## Request, state and component boundaries
+
+Use `config/ui.ts`'s explicit `root: 'resources'` and relative component,
+layout and partial directories. `stateDir: 'storage/framework/stx'` owns caches,
+client bundles and generated route artifacts. Keep application overrides under
+`resources/`; framework defaults remain the fallback. `defaultViews` controls
+which auth/storefront/error/mail views are served, and its default follows the
+mounted default route bundles. A view existing on disk does not establish that
+its POST endpoint is enabled.
+
+Server scripts run per render; client scripts run in the browser. Serialize
+server data through the supported hydration bridge rather than sharing mutable
+process state. In server templates read the request snapshot (including site)
+through `requestContext`; API AsyncLocalStorage site context does not extend
+through STX's asynchronous render boundary. Pair tenant features with
+`stacks-sites`.
+
+The browser has both eagerly delivered and demand-bundled composables.
+Observers, motion helpers and STX `useForm` are usable client primitives in
+current STX, even when they are not explicit `window.name` aliases. Read
+`stacks-composables/BROWSER.md` before choosing a signature or mixing the
+browser signal API with explicit module Refs.
+
+For account-persisted initial UI use `keptState` or `cachedQuery`, establish
+`setKeptScope` before values are created, and clear the account scope on
+sign-out. Use `clearServerData(key?)` after mutations invalidate hydration
+data. Ordinary localStorage is a different persistence boundary.
+
+## STX capability discovery
 
 ### Core
 - Template parsing and compilation
@@ -224,21 +227,21 @@ function showSearch(): void {
 `nextTick()` runs after the current synchronous signal and effect flush. Prefer it over `querySelector`, manual DOM polling, or `requestAnimationFrame` when the task is waiting for STX to materialize reactive markup.
 
 ### Rendering
-- **SSR** — Server-Side Rendering
-- **Streaming** — Progressive HTML streaming
-- **Hydration** — Progressive and islands-based hydration
-- **Suspense** — Async component loading with fallbacks
-- **Error boundaries** — Graceful error handling in components
+- **SSR** - Server-Side Rendering
+- **Streaming** - Progressive HTML streaming
+- **Hydration** - Progressive and islands-based hydration
+- **Suspense** - Async component loading with fallbacks
+- **Error boundaries** - Graceful error handling in components
 
 ### Features
-- **Router** — Client-side routing
-- **Forms** — Built-in form handling and validation
-- **i18n** — Internationalization support
-- **SEO** — Meta tags, Open Graph, Twitter cards, structured data
-- **PWA** — Progressive Web App support
-- **Animation** — CSS and JS animation system
-- **Markdown** — Markdown rendering with syntax highlighting
-- **A11y** — Accessibility checking and auto-fixing
+- **Router** - Client-side routing
+- **Forms** - Built-in form handling and validation
+- **i18n** - Internationalization support
+- **SEO** - Meta tags, Open Graph, Twitter cards, structured data
+- **PWA** - Progressive Web App support
+- **Animation** - CSS and JS animation system
+- **Markdown** - Markdown rendering with syntax highlighting
+- **A11y** - Accessibility checking and auto-fixing
 
 ### SEO directives
 
@@ -299,21 +302,23 @@ await addLayout('admin', { nav: true, footer: true })
 `default`, `minimal`, `full`, `blog`, `dashboard`, `landing`
 
 ## Gotchas
-- **STX is the ONLY templating system** — do not use other template engines
-- **`bun-plugin-stx` must be loaded** — without it, `.stx` files won't be processed
-- **Auto-imports** — browser auto-imports defined in `storage/framework/browser-auto-imports.json`
+- **STX is the ONLY templating system** - do not use other template engines
+- **`bun-plugin-stx` must be loaded** - without it, `.stx` files won't be processed
+- **Client delivery** - eager runtime/compiler primitives, demand composables
+  and explicit module imports are distinct. The ambient browser manifest
+  does not establish which browser implementation or signature is delivered.
 - **Imported module dependencies** - browser auto-imports are injected into the STX script entry only; imported `.ts` modules must explicitly import every function or store they use
 - **Project-root server imports** - use `~/path` or `@/path` inside `<script server>` when a layout, partial, or page needs a project file. STX resolves both aliases against the application root before executing the server script. Relative imports still resolve against the `.stx` file
 - **Browser package inputs are bundled** - core browser helpers and model auto-import bootstraps are compiler bundle inputs. Rendered HTML must never contain a bare `import '@stacksjs/browser'`, because browsers cannot resolve package specifiers without an import map
 - **Server-to-client values are explicit** - a JSON-serializable top-level value exported by `<script server>` can be referenced by name in `<script client>`. STX serializes only referenced values and never overwrites a client-owned declaration
-- **`storage/framework/stx/`** — stx build cache and the generated route manifest. `config/ui.ts` sets stx's `stateDir` here, so nothing lands in the project root. Gitignored; safe to delete
+- **`storage/framework/stx/`** - stx build cache and the generated route manifest. `config/ui.ts` sets stx's `stateDir` here, so nothing lands in the project root. Gitignored; safe to delete
 - **Reactivity is signal-based** - use callable `state()` and `derived()` signals, not Vue-style `ref()` or `.value`
 - **Client loop conditions** - `@if` chains that read `:for` or `@for` aliases compile into scoped runtime chains; aliases do not leak outside the loop element
 - **Component tag case is semantic** - `<Input v-model:value="query">` is a paired component, while lowercase `<input v-model="query">` is a native void element. Keep component tags PascalCase, including names that collide with native elements
 - **Structural DOM timing** - use `nextTick()` with `useRef()` after opening reactive markup
-- **Crosswind for styling** — use utility classes, not inline styles
-- **Script block restrictions** — only stx-compatible code (signals, composables, directives), no vanilla DOM APIs
+- **Crosswind for styling** - use utility classes, not inline styles
+- **Script block restrictions** - only stx-compatible code (signals, composables, directives), no vanilla DOM APIs
 - **Pre-paint state** - use `@appearanceBootstrap`, never a raw browser script in the template
-- **Components go in `resources/`** — not in `app/` or `storage/`
+- **Components go in `resources/`** - not in `app/` or `storage/`
 - **SEO directives take expressions** - `@seo(seo)`, `@meta('author', post.author)` and `@structuredData(product)` are evaluated; a failure shows up as an inline `<!-- [... Error] -->` comment plus a `[stx]` console warning naming the file, never as silent emptiness. Keep `@seo` inside `<head>`
-- **118+ modules** — STX is a comprehensive framework covering rendering, routing, forms, i18n, SEO, PWA, and more
+- **118+ modules** - STX is a comprehensive framework covering rendering, routing, forms, i18n, SEO, PWA, and more

package/ai/skills/stacks-tdd/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-tdd/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## tdd
+
+Source: [skills/engineering/tdd/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/tdd/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.

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

@@ -13,6 +13,11 @@ produce tests worth keeping: what a good test is, where tests go, the
 anti-patterns, and the rules of the loop. Every section applies on every cycle.
 Consult them before and during, not after.
 
+Use the project's established `CONTEXT.md` or `GLOSSARY.md` vocabulary in test
+names and interfaces, and respect existing ADRs. For each proposed test seam,
+state in one line what it catches and what it misses. Existing agreement on a
+seam carries forward; ask only when that decision remains unsettled.
+
 `stacks-testing` is the *mechanics*: `setupDatabase()`, `refreshDatabase()`,
 DynamoDB Local, `bunfig.toml` preload, the CLI flags. This skill is the
 *discipline*. Read that one for the API and this one for the decisions.
@@ -30,6 +35,8 @@ internal structure.
 
 See [EXAMPLES.md](EXAMPLES.md) for good and bad tests side by side, and for
 where mocking is legitimate.
+The refreshed upstream examples are [tests.md](tests.md) and
+[mocking.md](mocking.md). For fixture assertions, use `stacks-test-fixtures`.
 
 ## Seams: where tests go
 
@@ -121,5 +128,8 @@ environment. See `stacks-new-feature` for the full slice and
 
 ## Downstream
 
+Current upstream provenance is in [NOTICE.md](NOTICE.md); read
+[the Stacks adaptation rules](../stacks-flow/ENGINEERING.md) with this workflow.
+
 > Green? Run `/stacks-review` for the two-axis review, then `/stacks-browse` if
 > the slice has a UI.