@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/AGENTS.md

@@ -63,9 +63,22 @@ same path under `app/` and it wins.
 
 ## Skills
 
-The framework ships two kinds of skill under
+The framework ships task-specific skills under
 `storage/framework/defaults/ai/skills`.
 
+Start with `stacks-native` when implementing a feature or checking what Stacks
+already provides. Its catalog maps every core package to the appropriate skill,
+its recipes connect model definitions to migrations and protected CRUD, and its
+driver reference records supported, partial, and experimental capabilities.
+
+Describe schema once in `app/Models/` with `defineModel()`; use `extendModel()`
+for additive changes to a built-in model. Run `./buddy generate:migrations`,
+review the generated SQL and snapshot, then apply with `./buddy migrate`.
+`useApi` registers CRUD at runtime. Read `stacks-models`, `stacks-migrations`,
+and `stacks-router` for selection, authentication, ownership, and mount behavior.
+Use `stacks-auto-imports` to distinguish browser bindings from declarations
+and explicit module imports.
+
 **Subsystem reference**, one per area (`stacks-orm`, `stacks-router`,
 `stacks-queue`, ...), each documenting it authoritatively. Read the relevant
 `SKILL.md` before doing non-trivial work rather than guessing at an API.
@@ -85,6 +98,24 @@ The framework ships two kinds of skill under
 | A step only a human can take | `stacks-wizard` |
 | Improve the environment for next time | `stacks-retro` |
 | Write a skill or any doc an agent reads | `stacks-writing-for-agents` |
+| Humanize prose with a broad editorial rewrite | `stacks-humanizer` |
+| Audit AI-sounding prose, suggest minimal edits, or learn and match a voice | `stacks-unslop` |
+| Persist design decisions, write a spec, and create linked tickets | `stacks-grill-with-docs`, `stacks-to-spec`, `stacks-to-tickets` |
+| Implement a ticket or a spec's task graph | `stacks-implement`, `stacks-implement-spec` |
+| Triage reports or resolve a large decision map | `stacks-triage`, `stacks-wayfinder` |
+| Research, architecture improvements, or PR descriptions | `stacks-research`, `stacks-improve-codebase-architecture`, `stacks-pr` |
+| Learn, collect writing material, or shape an article | `stacks-teach`, `stacks-writing-fragments`, `stacks-writing-shape`, `stacks-writing-beats` |
+| Specify a recurring workflow or coordinate a long-running effort | `stacks-loop`, `stacks-chief-of-staff` |
+
+**Marketing**: read `stacks-marketing`, then choose the task-specific skill from
+its `CATALOG.md`. The framework bundles all 50 reviewed marketing playbooks,
+including copywriting, SEO, acquisition, conversion, retention, and measurement.
+They complement framework skills such as `stacks-analytics` and `stacks-email`.
+Use stx and Crosswind for implementation. A draft does not authorize sending,
+spending, publishing, or scheduling; existing explicit authorization carries forward.
+
+Source revisions, hashes, native substitutes, and all 38 reviewed Matt Pocock
+skill mappings live in `stacks-flow/upstream-skills.json` beside its entrypoint.
 
 Add your own with `app/Skills/<name>/SKILL.md`, then re-run `buddy setup:ai`.
 A project skill shadows a bundled one of the same name. Read
@@ -95,6 +126,10 @@ enforces and how to write a description that actually fires.
 
 ## Before finishing
 
+Generated user-visible copy uses regular hyphens and ordinary sentence
+punctuation. Never emit em-dashes or separator en-dashes. Preserve verbatim
+source quotations; flag a punctuation conflict rather than altering a quote.
+
 - Lint: `./buddy lint` (fix with `./buddy lint:fix`)
 - Type check: `./buddy typecheck`
 - Test: `./buddy test`

package/ai/README.md

@@ -38,7 +38,14 @@ reference for a task instead of guessing at an API.
 symlinks by default so skills stay in sync when you upgrade the framework. Pass
 `--copy` if you would rather edit them per project.
 
-### Two kinds
+### Collections
+
+`stacks-native` is the starting point for native implementation. Its catalog
+maps every core package to a subsystem skill and source entrypoint. Its recipes
+cover model-driven migrations and protected CRUD; its capability reference
+records current driver evidence and limitations. The framework repository
+regenerates these references with `buddy docs:native-skills` and verifies them
+in CI with `buddy docs:native-skills:check`.
 
 Most bundled skills are **subsystem reference**: one per part of the framework,
 model-invoked, found by the agent from the task at hand. A smaller set are
@@ -50,6 +57,37 @@ package it touches: `stacks-flow` routes between them, and `stacks-grilling`,
 [mattpocock/skills](https://github.com/mattpocock/skills) (MIT), with credit in
 each `SKILL.md`.
 
+The current Matt Pocock refresh includes specs, dependency-linked tickets,
+implementation graphs, triage, wayfinding, research, PR writing, and optional
+productivity workflows. All 38 upstream skills have a recorded destination or
+Stacks-native substitute. Hooks stay on pickier and bun-git-hooks; imported
+workflows do not commit, publish, or start schedules without authorization.
+
+**Marketing** is a third collection: `stacks-marketing` routes over all 50
+playbooks from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills).
+Each keeps its supporting references, templates, and original MIT notice.
+Names are distinct from runtime package skills. The shared workflow explains
+product context, verified claims, Stacks implementation, and optional connectors.
+
+`skills/stacks-flow/upstream-skills.json` records both source revisions and
+every source-to-Stacks mapping. Shared engineering rules, marketing guidance,
+and source manifests live inside skill directories so both symlink and `--copy`
+agent setups retain them. The docs site has matching marketing, engineering,
+and productivity pages plus an upstream-porting report.
+
+The prose skills are `stacks-humanizer` for broad editorial rewrites and
+`stacks-unslop` for contextual audits, minimal edits, and voice matching. They
+adapt [blader/humanizer](https://github.com/blader/humanizer) and
+[theclaymethod/unslop](https://github.com/theclaymethod/unslop), with attribution
+and revision details in each skill's `NOTICE.md`. They require no runtime
+scripts or extra dependencies.
+
+The `@stacksjs/defaults` build includes this entire `ai/` directory. New
+package-based apps and framework upgrades receive the skills through the
+managed defaults sync; vendored apps carry them directly. `buddy setup:ai`
+then exposes them through the existing agent setup mechanism. No remote skill
+installation is needed.
+
 Each skill also has a page in the documentation site, under `docs/skills/`, one
 per skill with a landing page per section. `tests/unit/skills-docs-contract.test.ts`
 fails when a skill gains or loses a page, so the two cannot drift apart.

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

@@ -30,12 +30,12 @@ export default new Action({
   method: 'POST',
   model: Widget,
 
-  async handle(request: RequestInstance) {
+  async handle(request) {
     await request.validate()
 
     const widget = await Widget.create(toSnakeCaseKeys(request.all()))
 
-    return response.json(widget, 201)
+    return response.created(widget)
   },
 })
 ```
@@ -44,6 +44,59 @@ Use the `Action` class, an explicit HTTP method, and `response` helpers. Store a
 update actions should set `model` and call `request.validate()` before persisting
 input. Import framework helpers explicitly, following the default actions.
 
+Let `handle(request)` infer its request type. An explicit broad annotation loses
+the model or validation field types that `Action` can derive. The typed Action
+contract lives in `core/actions/src/action.ts`; the execution pipeline lives in
+`core/router/src/stacks-router.ts`.
+
+## Validation, lifecycle, and typed clients
+
+An explicit `validations` object is inferred from its validators and runs
+automatically before `authorize`, `before`, and `handle`. A `model` supplies
+the rules used by an explicit `request.validate()` call; do not assume attaching
+a model means every custom handler has already validated all its input.
+
+```ts
+import { Action } from '@stacksjs/actions'
+import { schema } from '@stacksjs/validation'
+
+export default new Action({
+  method: 'POST',
+  validations: {
+    title: { rule: schema.string().min(1).max(120) },
+  },
+  async handle(request) {
+    return { title: request.get('title') }
+  },
+})
+```
+
+`authorize` can return true, false, or an exact Response; false short-circuits
+with 403. `before` can prepare context or return a Response early. Both run
+after declared validation. Directly registered actions and action strings use
+the same `wrapAction` pipeline. Register an imported action with
+`createTypedRouter` when its inferred request/response types should reach a
+`createTypedClient`; lazy strings do not carry that response inference.
+
+`responses`, `responseHeaders`, and `requestHeaders` enrich OpenAPI documentation.
+They describe the contract and do not validate the actual response at runtime.
+Test the endpoint's wire shape. `apiResponse` controls JSON formatting;
+returning a raw Response owns the wire format and yields unknown client output.
+
+`dependencies` lazily creates per-action dependencies exposed through
+`this.deps`. `overrideDependencies` and `resetDependencies` let a test replace
+external boundaries without module-wide mocking. They do not justify mocking
+every internal collaborator or replacing a real database test with a fake.
+
+`Precognition: true` or `?_validate=1` requests a validation-only probe.
+`Precognition-Validate-Only` narrows explicit validation fields. Probes stop
+before authorization/hooks/handler side effects, and do not magically run
+custom `request.validate()` calls inside `handle`.
+
+For event actions, declare `invocation: 'event'` and infer the payload from
+`validations` when supplied. Event discovery calls `handle(payload, event)`;
+it does not hand an HTTP Request to an event handler.
+
 ## Resource Action Contract
 
 Show, update, and destroy actions must distinguish malformed identifiers,
@@ -51,8 +104,9 @@ missing records, invalid input, and operational failures:
 
 1. Read resource identifiers from `request.getParam('id')`, never from the
    request body.
-2. Convert the value to a number and require a safe positive integer. Return
-   `422` when it is malformed.
+2. Validate its actual identifier contract. Numeric resource IDs require a safe
+   positive integer; UUIDs or string keys need their own validation. The built-in
+   Commerce contract returns `422` for malformed numeric IDs.
 3. Validate update input with the action model, then normalize persisted keys
    with `toSnakeCaseKeys(request.all())` when the service expects database
    column names.
@@ -71,7 +125,9 @@ copying the contract across every resource. The built-in Commerce actions use
 
 ## Auto-Generated API Actions (useApi Trait)
 
-When a model defines `useApi`, the framework auto-generates REST actions:
+When a model defines `useApi`, the runtime registers native CRUD routes and
+handlers from the merged model registry. It does not require generated action
+files or a separate model-class generation step:
 
 ```typescript
 defineModel({
@@ -92,7 +148,7 @@ This generates:
 - `PUT /api/products/{id}` → Update action
 - `DELETE /api/products/{id}` → Destroy action
 
-## Default Framework Actions (80+)
+## Default framework action families
 
 ### Authentication Actions
 - `LoginAction` — POST /login (validates email + password, returns token + user)
@@ -158,6 +214,8 @@ route.post('/users', 'Actions/CreateUser')
 - The `handle()` method is required — it receives the request object
 - Actions used as event listeners also have a `handle(event)` method
 - The `useApi` model trait auto-generates CRUD actions + routes
+- Custom actions retain their own domain contract; generic CRUD also applies
+  model middleware, ownership, dashboard roles and per-row policy checks.
 - Actions are resolved dynamically at runtime via string names
 - The HealthAction at `/health` is useful for container health checks
 - Login action returns `{ token: string, user: { id, email, name } }`

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

@@ -18,9 +18,9 @@ Comprehensive AI/LLM integration with 4 provider drivers, image generation, visi
 ```
 ai/src/
 ├── drivers/
-│   ├── anthropic.ts      # Claude driver
-│   ├── openai.ts         # GPT + DALL-E + Whisper + TTS
-│   ├── ollama.ts         # Local LLM driver
+│   ├── anthropic/index.ts # Claude driver
+│   ├── openai/index.ts    # GPT + image + transcription + TTS
+│   ├── ollama/index.ts    # Local LLM driver
 │   └── bedrock/          # Amazon Bedrock, through the Converse API
 ├── image.ts              # Image generation & vision
 ├── speech.ts             # Provider-neutral text-to-speech & speech-to-text
@@ -210,7 +210,7 @@ const index = await indexText(text, { chunkSize: 500 })
 const answer = await rag('What is X?', index, { model: 'claude-sonnet-4-20250514', maxTokens: 1000 })
 
 // VectorIndex class
-const idx = new VectorIndex({ dimensions: 1536 })
+const idx = new VectorIndex({ provider: 'openai', model: 'text-embedding-3-small' })
 await idx.add([{ id: '1', content: 'Hello', metadata: {} }])
 const results = await idx.search('greeting', 5)
 const results2 = await idx.searchByVector(queryEmbedding, 5)
@@ -239,9 +239,9 @@ const openaiTools = client.toOpenAITools()
 
 // Multiple servers
 const manager = new MCPManager()
-manager.addServer({ name: 'server1', transport: 'stdio', command: '...' })
-manager.addServer({ name: 'server2', transport: 'streamable-http', url: '...' })
-const allTools = await manager.getAllTools()
+await manager.addServer({ name: 'server1', transport: 'stdio', command: '...' })
+await manager.addServer({ name: 'server2', transport: 'streamable-http', url: '...' })
+const allTools = manager.getAllTools() // cached tools from connected servers
 await manager.callTool('server1/tool-name', args)
 await manager.disconnectAll()
 
@@ -356,14 +356,40 @@ await driver.resumeSession(sessionId, 'Add validation')
 ```
 
 ## Gotchas
-- API keys should be in `.env` — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`
+- API keys should be in `.env` - `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`
 - Ollama requires a local server running on port 11434
 - Image generation uses OpenAI DALL-E by default
 - Vision supports both GPT-4V and Claude models
-- VectorIndex is in-memory — not persisted between restarts
+- VectorIndex is in-memory - not persisted between restarts
 - RAG combines chunking + embedding + vector search + LLM generation
 - MCP supports stdio (subprocess), SSE, and HTTP transports
 - The buddy assistant has git integration (commit, push, apply changes)
 - Claude Agent SDK wraps the Claude Code CLI for agentic workflows
 - A Bedrock id as `default` selects the Bedrock driver; it never reaches api.anthropic.com
-- Sentiment/classification use AI models — they're not rule-based
+- Sentiment/classification use AI models - they're not rule-based
+
+
+## Usage, retries and multimodal messages
+
+The public package also exposes `onUsage/recordUsage/listUsageReporters`
+(and clearUsageReporters for teardown), `estimateTokens/estimateMessageTokens`,
+`sanitizePrompt`, `fetchWithRetry`, and
+`buildMessageWithImages/normalizeMessagesForProvider`. Use the exported
+types and their `utils/` implementations before composing a provider-neutral
+message or reporting costs. Token estimates are heuristic, usage callback data
+comes from provider results, and sanitizing a prompt is not authorization for
+executing a suggested tool.
+
+Provider capabilities differ: embeddings currently use OpenAI/Ollama; RAG supports
+Anthropic/OpenAI/Ollama; speech uses OpenAI only. The shared chat client and
+tool-turn helpers support the four chat providers but do not imply those other
+features are implemented by Bedrock. VectorIndex is memory-only; its constructor
+accepts EmbeddingOptions (provider/model), not an arbitrary vector dimensions
+setting. Runtime credentials come from env/provider configuration, never a
+browser-exported config response.
+
+Tests: `storage/framework/core/ai/tests/usage-and-tokens.test.ts`,
+`vision.test.ts`, `retry.test.ts`, `driver-retry.test.ts`,
+`tool-calls.test.ts` and `client.test.ts`. Verify chosen model/provider
+capabilities from config and registry rather than assuming a marketing model name
+is usable for every API.

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-alias
-description: Use when working with path aliases in a Stacks project - import resolution, module aliasing, or debugging import paths. Covers @stacksjs/alias which defines 260+ path mappings for the entire framework.
+description: Use when debugging source aliases, package/subpath resolution, or the boundary between checkout and published imports. Covers @stacksjs/alias and its active resolver consumers.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,87 +8,42 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Path Aliases
 
-## Key Paths
-- Core package: `storage/framework/core/alias/src/`
-- Source: `storage/framework/core/alias/src/index.ts`
-- Package: `@stacksjs/alias`
-
-## API
-
-```typescript
-import { alias } from '@stacksjs/alias'
-
-const alias: Record<string, string>  // 260+ entries
-```
-
-## Alias Categories
-
-### Framework Module Aliases
-Maps `@stacksjs/*` and `stacks/*` imports to their source files:
-
-```typescript
-'@stacksjs/ai':          'storage/framework/core/ai/src/index.ts'
-'@stacksjs/auth':        'storage/framework/core/auth/src/index.ts'
-'@stacksjs/database':    'storage/framework/core/database/src/index.ts'
-'@stacksjs/router':      'storage/framework/core/router/src/index.ts'
-'@stacksjs/cache':       'storage/framework/core/cache/src/index.ts'
-'@stacksjs/cli':         'storage/framework/core/buddy/src/index.ts'
-'@stacksjs/config':      'storage/framework/core/config/src/index.ts'
-// ... all core packages
-```
-
-Both `@stacksjs/` and `stacks/` prefixes are supported:
-
-```typescript
-'stacks/auth':            'storage/framework/core/auth/src/index.ts'
-'stacks/database':        'storage/framework/core/database/src/index.ts'
-```
-
-### Config Aliases
-Maps `~/config/*` to config files:
-
-```typescript
-'~/config/database':      'config/database.ts'
-'~/config/dns':           'config/dns.ts'
-'~/config/docs':          'config/docs.ts'
-'~/config/email':         'config/email.ts'
-// ... all 44 config files
-```
-
-### Resource Aliases
-Maps `~/` paths to project directories:
-
-```typescript
-'~/app/*':                'app/*'
-'~/components/*':         'resources/components/*'
-'~/functions/*':          'resources/functions/*'
-'~/views/*':              'resources/views/*'
-'~/lang/*':               'locales/*'
-'~/*':                    '*'
-```
-
-### Framework Aliases
-```typescript
-'framework/*':            'storage/framework/*'
-'@/*':                    '*'
-```
-
-## Usage
-
-Aliases are automatically resolved by Bun at runtime and by the build system for production:
-
-```typescript
-// These all work because of aliases
-import { db } from '@stacksjs/database'
-import { route } from '@stacksjs/router'
-import { auth } from 'stacks/auth'
-import dbConfig from '~/config/database'
-```
-
-## Gotchas
-- **260+ entries** — covers every core package, config file, and resource directory
-- **Dual prefixes** — both `@stacksjs/` and `stacks/` resolve to the same source files
-- **Runtime resolution** — Bun resolves these at runtime via `bunfig.toml` preloading
-- **Build-time resolution** — the build system resolves aliases to actual paths for production
-- **Always use aliases** — never use relative paths between packages in the monorepo
-- **Adding new packages** — requires adding alias entries for both `@stacksjs/` and `stacks/` prefixes
+Use `@stacksjs/alias` to inspect the framework's source alias map and debug a
+configured build resolver. The exported alias object is metadata; importing it
+does not install a universal module resolver.
+
+## Actual mappings
+
+The map in `storage/framework/core/alias/src/index.ts` uses @stacksjs/path to
+resolve project-relative resources to concrete paths. Many packages have
+@stacksjs/name and stacks/name aliases plus wildcard subpaths, but only entries
+actually in the map are promised. Cli maps to core/cli, Buddy to core/buddy;
+they are separate packages.
+
+Configuration/resource aliases cover declared config paths and resources. Read
+that source and the active tsconfig/bun/build configuration for exact spellings;
+a fixed count or schematic wildcard table cannot establish runtime resolution.
+An application override changes the source root resolved by @stacksjs/path.
+
+## Source versus published consumers
+
+Public @stacksjs package names and declared subpaths are the portable imports.
+Source aliases help the framework checkout and configured Stacks app build.
+A published consumer must resolve package exports without reaching outside its
+installed package. Do not invent a subpath merely because a matching source
+file exists behind a wildcard alias. Declaration and runtime export validation
+are separate checks.
+
+When adding a source alias, update the actual map and the consuming resolver;
+check its package's exports/build entries as well. Relative imports within a
+package are ordinary implementation imports; using a relative path that escapes
+into another package's unpublished types is the problem. Avoid the former rule
+that all relative imports are forbidden, since framework code itself uses them
+to keep internal modules and cycle boundaries explicit.
+
+## Verification
+
+Source: `core/alias/src/index.ts`, active tsconfig.json and the build/runtime
+consumer reading the map. Retained coverage: `core/alias/tests/alias.test.ts`.
+For missing globals, read stacks-auto-imports; aliases solve module resolution,
+not injection of ambient names into a browser or server request.

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

@@ -8,8 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Analytics
 
-Privacy-friendly analytics with four drivers: Fathom, Plausible, Google Analytics
-and self-hosted.
+Analytics drivers: AnalyticsHQ, Fathom, Plausible, Google Analytics and self-hosted.
 
 ## Key Paths
 - Core package: `storage/framework/core/analytics/src/`
@@ -46,7 +45,7 @@ that should carry it.
 ## Drivers
 
 ### Fathom
-Hosted, cookie-free, GDPR-compliant. Requires a Fathom account.
+Hosted tracker script. Requires a Fathom account; compliance depends on the complete application and provider setup.
 `scriptUrl` points the tag at your own origin so a content blocker does not drop it.
 
 ```typescript
@@ -178,3 +177,24 @@ Analytics dashboard at `/dashboard/analytics` displays:
 - `trackOutboundLinks` adds click handlers to external `<a>` tags
 - `capturePageviews` is server-side and independent of `driver`
 - AnalyticsHQ custom events need no script: `data-analyticshq-event="Ticket click"` on any element, with other `data-analyticshq-*` attributes as properties
+
+
+## Environment and capture boundaries
+
+enabled:false returns no tags. When environments is explicitly supplied,
+getAnalyticsHead runs the shared integration gate and forwards the resolved label
+to AnalyticsHQ. If environments is absent, the current registry preserves its
+older ungated behavior; the shipped config explicitly lists production/staging.
+Do not assume every caller gets that allowlist when constructing config itself.
+
+First-party capturePageviews is separate from script injection and the remote
+driver gate. recordPageview(req) writes qualifying GET page requests to
+analytics_events; isPageviewRequest filters assets/API/internal paths and obvious
+bots/monitors. classifyAgent/referrerHost are coarse helpers, not unique visitor
+identification. Capture failures are swallowed so a statistic cannot break a
+page. Apply the table/model migration before relying on the dashboard data.
+
+Source: `storage/framework/core/analytics/src/registry.ts`, capture.ts and
+drivers/. Tests: environment-gate.test.ts, capture.test.ts and drivers.test.ts.
+A configured script does not certify analytics consent/privacy compliance or
+prove a provider received an event. Read stacks-env for the shared gate.

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

@@ -21,10 +21,11 @@ export * as arr from './arr'
 export * from './macro'
 ```
 
-The `arr.ts` re-exports from three submodules:
-- `contains.ts` — containment check functions
-- `helpers.ts` — array manipulation (toArray, flatten, partition, unique, shuffle, etc.)
-- `math.ts` — statistical functions (average, median, mode, variance, etc.)
+The `arr.ts` re-exports these submodules:
+- `contains.ts` - containment check functions
+- `helpers.ts` - array manipulation (toArray, flatten, partition, unique, shuffle, etc.)
+- `math.ts` - statistical functions (average, median, mode, variance, etc.)
+- `transform.ts` - typed grouping, selectors, ordering, sets and zip helpers
 
 The `macro.ts` provides the `Arr` and `arr` facade objects.
 
@@ -140,10 +141,10 @@ All containment functions work with `string[]`. The `contains` function checks i
 contains('foobar', ['foo', 'baz'])              // true  -- 'foobar'.includes('foo')
 contains('hello', ['foo', 'bar'])               // false
 
-containsAll(['foo', 'bar'], ['foobar', 'barx']) // true  -- all needles found
+containsAll(['foobar', 'barx'], ['foo', 'bar']) // true  -- each needle contains a haystack substring
 containsAll(['foo', 'qux'], ['foobar'])         // false -- 'qux' not found
 
-containsAny(['foo', 'qux'], ['foobar'])         // true  -- at least one found
+containsAny(['foobar', 'qux'], ['foo'])         // true  -- at least one needle contains a haystack substring
 containsAny(['baz', 'qux'], ['foobar'])         // false
 
 containsNone(['baz', 'qux'], ['foobar'])        // true  -- none found
@@ -153,7 +154,7 @@ containsOnly(['foo', 'bar'], ['foobar', 'barx']) // checks if haystack items onl
 // Implemented as: containsAll(haystack, needles) -- reversed args
 
 doesNotContain('qux', ['foo', 'bar'])           // true
-doesNotContain('foo', ['foobar'])               // false
+doesNotContain('foo', ['foobar'])               // true -- 'foo' does not contain 'foobar'
 ```
 
 **Important**: `contains` uses `needle.includes(hay)`, NOT `haystack.includes(needle)`. It checks if the needle string contains any of the haystack substrings. This is substring matching, not array membership.
@@ -211,7 +212,10 @@ covariance([1, 2, 3, 4], [4, 3, 2, 1])     // -1.25 -- negative correlation
 
 ## Arr Facade (`macro.ts`)
 
-Both `Arr` and `arr` are exported as equivalent facade objects.
+Use `Arr` for the facade. The root's lowercase `arr` is the namespace exported
+from `arr.ts`, with all standalone functions. It is not the same object as
+`Arr` and does not include the facade-only `random` method. A lowercase alias
+also exists in `macro.ts`, but the root namespace export wins.
 
 ```typescript
 import { Arr, arr } from '@stacksjs/arrays'
@@ -256,7 +260,29 @@ The facade adds one extra method not in the standalone functions:
 Arr.random(arr, count)   // like sample but filters null/undefined from results
 ```
 
-## Exported Types
+## Typed transformations
+
+These standalone functions are also available through the root `arr` namespace:
+
+- `groupBy`, `keyBy`, `countBy` use selector functions and return typed records.
+  Repeated keyBy keys overwrite earlier entries; groupBy accumulates them.
+- `sortBy(array, ...selectors)` copies before sorting, supports multiple keys,
+  and accepts `{ by, order: 'desc' }` selectors.
+- `sumBy`, `meanBy`, `minBy`, `maxBy` aggregate selected values. `meanBy` returns
+  undefined on an empty input; extrema return the selected element, not its value.
+- `zip`, `zipWith` stop at the shorter input; `unzip` splits pairs.
+- `difference` keeps first-input duplicates that are not excluded;
+  `intersection` and `union` deduplicate by Set identity.
+- `chunk` validates a positive integer size; `compact` removes only null and
+  undefined, preserving false, zero and empty strings.
+- `splitAt` supports negative indexes; `splitWhen` starts the second half at
+  the first match; `times` requires a non-negative integer count.
+
+Read `core/arrays/src/transform.ts` and `tests/transform.test.ts` for precise
+empty-input and selector behavior. These pure helpers are preferable to a new
+utility dependency for common native transformations.
+
+## Type example
 
 ```typescript
 type PartitionFilter<T> = (item: T, index: number, array: readonly T[]) => any

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

@@ -0,0 +1,34 @@
+---
+name: stacks-audio
+description: Use when planning native audio derivatives, processing supported audio formats, generating waveforms/transcripts, or signing audio delivery. Covers @stacksjs/audio and runtime encoder capability checks.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Native audio planning and delivery
+
+audio(source) builds a profile-driven delivery plan. Supply an inspected
+AudioProfile and actual runtime encoder/codec capabilities. A declared output
+does not prove that an encoder is available.
+
+## Plan versus process
+
+generate() returns the plan, including copy/transcode actions and availability.
+assertAudioPlanExecutable rejects an unavailable encoding path. process() or
+processAudioPlan delegates executable work to the installed native-transcode
+implementation. Do not report a generated plan as finished media bytes.
+
+Content type, format and source characteristics determine bitrate/output
+selection. negotiateAudioOutput handles accept preferences. createWaveform and
+normalizeTranscript build waveform data and transcript/VTT output from supplied
+samples/segments; they do not infer spoken text from an audio file themselves.
+
+audioResponseHeaders supports delivery caching; signAudioAsset/verifyAudioAsset
+and createProtectedAudioPlaylist support protected delivery. Preserve expiration,
+path and key handling; a protected playlist still needs an authorized key route.
+
+Tests prove planning, capability rejection, helpers and delegated processing.
+The processing test mocks the transcoder, so it is not evidence that every codec
+works on every host. Verify the real target runtime when producing assets.
+Source: core/audio/src/index.ts. Evidence: audio.test.ts and process.test.ts.