@maestro-js/agent-skills 1.0.0-alpha.0

package/dist/choosing-an-npm-package/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: choosing-an-npm-package
+description:  Consult before installing any npm package, running npm install, pnpm add, or adding a new dependency to package.json. Provides the user's preferred packages for common use cases including UI components, drag and drop, rich text editing, date/time utilities, animations, styling, pattern matching, PDF generation, email templates, routing, testing, maps, and databases. Check this skill to use the preferred package instead of alternatives.
+---
+
+# Choosing an NPM Package
+
+Before installing any dependency, check this list for the user's preferred package. Use the preferred package unless it genuinely cannot solve the problem.
+
+## Preferred Packages
+
+- **Headless UI:** `react-aria-components` — accessible, unstyled primitives
+- **Drag & Drop:** `@dnd-kit/core` — + `@dnd-kit/sortable`, `@dnd-kit/utilities`
+- **Rich Text:** `tiptap` — + `@tiptap/react`, `@tiptap/starter-kit`
+- **Date/Time:** `iso-fns@alpha` — ISO 8601 type-safe date/time utilities (Instant, ZonedDateTime, Duration). Use this instead of moment or date-fns.
+- **Advanced Animations:** `motion` — layout animations, gestures
+- **Loading Delay:** `spin-delay` — prevents flash of spinner
+- **Styling:** `tailwindcss` — utility-first CSS framework; prefer over custom CSS or other styling solutions
+- **Class Merging:** `tailwind-merge` — Tailwind conflict resolution
+- **Pattern Matching:** `ts-pattern` — exhaustive matching with type narrowing
+- **PDF Generation:** `@react-pdf/renderer` — React components to PDF
+- **PDF Display:** `react-pdf` — display PDFs in browser
+- **Email Templates:** `react-email` — React-based email building
+- **Frontend Router:** `react-router` — nested routes, data loading
+- **CLI Prompts:** `prompts` — lightweight interactive prompts for CLI questions
+- **CLI Framework:** `sade` — smooth, fast CLI tool builder
+- **SVG Icons:** `vite-plugin-icons-spritesheet` — generates SVG sprite sheets from icon files
+- **Maps:** `mapbox-gl` — + `react-map-gl` for React
+- **Unit/Integration Tests:** `beartest-js` — project test framework
+- **E2E Tests:** `playwright` — cross-browser with auto-waiting
+- **Database:** Prefer the MySQL driver for @maestro-js/db
+- **@maestro-js/agent-container** — Docker-based isolated agent execution environment with patch-based sync. Use when you need to create sandboxed containers for AI agents, run code in isolated Docker environments, pull container changes back to the host working tree as patches, or manage container lifecycles. Provides create, list, kill, shell, open (VS Code), and pull operations. Containers include Node.js 22, pnpm, Claude CLI, Playwright, git, and zsh.
+- **@maestro-js/auth** — 
+- **@maestro-js/broadcast** — "Pattern-based event routing across channels and processes using @maestro-js/broadcast. Use when working with @maestro-js/broadcast, channel patterns, broadcast listeners, event name generation, or wildcard/dynamic-segment routing. Key capabilities: define typed channels with URL-like patterns (:id, optional segments, wildcards), emit and listen for events through a pluggable driver (e.g. Events/Redis), extract params from matched patterns, generate concrete event names from patterns, and manage listener lifecycles."
+- **@maestro-js/cache** — Key-value caching with TTL, stale-while-revalidate, distributed locking, cache-aside pattern, atomic increment/decrement, and set-if-not-exists (add) for @maestro-js/cache. Use when working with @maestro-js/cache, adding caching to services, implementing distributed locks, using the remember/SWR pattern, incrementing or decrementing counters, adding values only if absent, configuring Redis or MockRedis drivers, or following the canonical Provider pattern from service-registry.
+- **@maestro-js/cache-control** — HTTP Cache-Control-inspired caching for async functions with caller/callee directives. Use when working with @maestro-js/cache-control. Key capabilities: wrap async functions with cacheFn to add cache-control semantics, set response directives (maxAge, staleWhileRevalidate, noStore) from the callee, set request directives (maxAge, noStore) from the caller, automatic background revalidation of stale data, in-flight request deduplication, built-in LRU cache or custom cache backends, human-readable duration strings (e.g. '5 minutes'), structured logging of all cache lifecycle events, and optional tracing integration for observability.
+- **@maestro-js/components** — 
+- **@maestro-js/config** — Configuration loader for .env files and TypeScript/JavaScript config modules with AES-256-GCM encryption support. Use when working with @maestro-js/config, including loading config into process.env, reading/writing encrypted .env files, creating config modules, deriving computed env values, and generating encryption keys. Key capabilities: load config files, parse .env files (plaintext or encrypted), encrypt/decrypt env files, generate encryption keys, resolve config modules (named exports, default exports, sync/async functions), type-safe process.env via Config.Resolve utility type, and auto-load via node --import @maestro-js/config/load.
+- **@maestro-js/context** — Guide for working with @maestro-js/context, a request-scoped key-value storage package backed by Node.js AsyncLocalStorage. Use when working with @maestro-js/context, adding per-request state, storing visible or hidden context values, propagating context across async boundaries, integrating context with logging or tracing, creating typed context item handles, or transferring context stores between execution scopes. Covers the Provider pattern, visible/hidden buckets, run/runWith lifecycle, createItem typed handles, getStore for context propagation, and testing patterns.
+- **@maestro-js/crypt** — AES-256-GCM encryption and decryption with automatic key rotation for the maestro-js framework. Use when working with @maestro-js/crypt, encrypting or decrypting strings, rotating encryption keys, checking key IDs on encrypted data, or setting up field-level encryption. Key capabilities include AES-256-GCM authenticated encryption, dot-delimited cipher format with embedded key IDs, zero-downtime key rotation via previousKeys, per-call random IV generation, Provider pattern with deferred resolution, and key identification without decryption.
+- **@maestro-js/custom-errors** — 
+- **@maestro-js/db** — Use when working with @maestro-js/db, the database access package for Maestro. Covers MySQL driver setup, parameterized SQL queries (select, insert, update, delete, scalar, statement), transactions with automatic commit/rollback, streaming results via selectIterable, connection pooling, query formatting, and the provider pattern for multiple database instances. Maestro uses raw parameterized SQL with no ORM. Depends on service-registry and log. Used by queue for message storage. Works with the sql package for query builders.
+- **@maestro-js/events** — Guide for @maestro-js/events — a pub/sub messaging package with pluggable drivers (Redis, WebSocket, Local). Use when working with @maestro-js/events, adding event-driven communication, creating typed event handles, configuring Redis pub/sub, setting up IPC via WebSocket, using in-process local events, or integrating with the Broadcast package. Covers the Provider pattern, driver configuration, typed Event handles, listener lifecycle, and cross-package usage with service-registry and broadcast.
+- **@maestro-js/exceptions** — Centralized exception reporting with automatic severity mapping and structured context, backed by @maestro-js/log. Use when working with @maestro-js/exceptions — reporting errors, silencing expected exceptions, attaching tags/extra metadata to error reports, or integrating exception handling into application services. Key capabilities: report exceptions with auto-detected severity (Error maps to 'error', non-Error maps to 'warn'), override log level via context, ignore/unignore specific exception instances, attach structured tags and extra data to reports. Follows the Provider pattern from @maestro-js/service-registry.
+- **@maestro-js/file-storage** — 
+- **@maestro-js/form** — Headless React form primitives with client and server validation, hidden inputs for custom components, controlled/uncontrolled state management, and Standard Schema (Zod) FormData parsing with automatic type coercion. Use when building custom form components that need native constraint validation, server error integration, file upload handling, or type-safe FormData parsing. Provides HeadlessForm root component, useValidation/useWarningState/useControlledState/useReset hooks, HiddenInput/HiddenFileInput/HiddenSelect components, parseFormData/parseFormDataClientSide utilities, and composeValidators.
+- **@maestro-js/hash** — Pluggable hashing and verification with driver-based backends for @maestro-js/hash. Use when working with @maestro-js/hash, hashing values, verifying hashes, detecting when a rehash is needed, or rotating signing keys. Built-in drivers: SHA256 (HMAC-SHA256 with key rotation and timing-safe comparison).
+- **@maestro-js/helpers** — Standalone utility functions for async control flow and file handling in the @maestro-js/helpers package. Use when working with @maestro-js/helpers. Key capabilities: retry with configurable attempts/delay/backoff, sleep, withMaxConcurrency for limiting parallel executions, withRateLimit with fixed or sliding window, raceWithFallback for promise racing with default values, AsyncIterableCollection for lazy async iteration (map, filter, reduce, forEach, toArray), sanitizeFilename for safe cross-platform filenames, and withRetry for wrapping functions with retry behavior.
+- **@maestro-js/log** — Structured logging with pluggable transports and channel-based routing for the Maestro framework. Use when working with @maestro-js/log, adding or modifying log transports, configuring log channels, filtering log messages by level or channel, integrating logging into other packages, or writing tests that capture log output. Key capabilities: create loggers with pluggable transports (console, file, Sentry, stub), route messages through named channels, filter by level and channel, override Node.js console, custom formatters, and the silence transport for suppressing output.
+- **@maestro-js/mail** — Driver-based email sending with queued delivery, scheduled sending, and mailable templates for the @maestro-js/mail package. Use when working with @maestro-js/mail. Covers creating mail services with SendGrid/SES/MailTrap/Stub drivers, sending emails immediately or via queue, scheduling future delivery, building reusable mailable templates, processing webhook events, generating ICS calendar attachments, and testing with the stub driver.
+- **@maestro-js/metrics** — Use when working with @maestro-js/metrics. Unified metrics collection piped through the Log transport system. Covers four metric types (counters, distributions, sets, gauges), provider setup, logger integration, Sentry transport, and custom transport authoring. Trigger on metrics emission, observability instrumentation, Sentry metrics integration, or application telemetry tasks.
+- **@maestro-js/password** — 
+- **@maestro-js/queue** — Database-backed job queue for deferring work beyond the current request with scheduled execution, concurrency control, and distributed tracing. Use when working with @maestro-js/queue, including dispatching jobs, processing queues, configuring the db driver, writing queue consumers, handling retries/stuck jobs, integrating with mail or recurring-jobs, and understanding the queue database schema.
+- **@maestro-js/queue2** — Database-backed job queue for deferring work beyond the current request with scheduled execution, concurrency control, and distributed tracing. Use when working with @maestro-js/queue, including dispatching jobs, processing queues, configuring the db driver, writing queue consumers, handling retries/stuck jobs, integrating with mail or recurring-jobs, and understanding the queue database schema.
+- **@maestro-js/rate-limiting** — Per-key rate limiting with configurable decay windows. Use when enforcing attempt limits on login, API endpoints, or any action that needs throttling. Provides increment/check/clear workflow, guarded callback execution via attempt(), and ISO 8601 duration reporting. Requires a cache driver (e.g. from @maestro-js/cache).
+- **@maestro-js/react-router-file-routes** — 
+- **@maestro-js/recurring-jobs** — Use when working with @maestro-js/recurring-jobs. Cron-based job scheduling backed by the Queue package. Covers creating recurring jobs, managing schedules, start/stop processing, rescheduling, listing jobs, and inspecting upcoming runs. Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, deduplication across process restarts, per-job dedicated queues, structured log events, and paginated execution history.
+- **@maestro-js/session** — 
+- **@maestro-js/signed-url** — URL signing and verification with pluggable hash drivers for @maestro-js/signed-url. Use when generating tamper-proof signed URLs with expiration (e.g. file download links, email verification) or validating signed URL parameters. Accepts any hash driver compatible with @maestro-js/hash.
+- **@maestro-js/sql** — Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions (CTEs). Use when working with @maestro-js/sql, building dynamic SQL filters, constructing parameterized WHERE clauses, wrapping Db services with CTEs, or generating safe parameterized SQL fragments. Key capabilities: WhereClauseBuilder for incremental AND/OR conditions with nested sub-groups, CommonTableExpressionBuilder for wrapping a Db service so all queries auto-prepend WITH clauses, cloning builders, recursive CTEs, and dynamic parameter resolution.
+- **@maestro-js/tracing** — Distributed tracing package built on OpenTelemetry with pluggable providers (Sentry, Maestro). Use when working with @maestro-js/tracing. Key capabilities: wrap functions for automatic span tracking, create active spans with duration measurement, proxy entire objects for tracing, serialize/deserialize trace context across process boundaries (dehydrate/hydrate), add custom log transports for span events, integrate Sentry as a tracing provider.
+
+## General Guidance
+
+1. **Always check the list first.** If the use case matches a category above, use that package.
+2. **Check `@maestro-js/*` packages before external deps.** The monorepo may already provide what you need (caching, logging, queuing, mail, etc.).
+3. **Don't install packages that overlap existing dependencies.** Check `package.json` for what's already available before adding anything new.
+4. **When no preference is listed** for a use case, ask the user which package they prefer before installing.
+5. **When the preferred package doesn't fit** the specific requirement, explain the gap, propose an alternative, and wait for the user's approval before installing.
+
+
+{{MAESTRO_PACKAGES}}

package/dist/maestro-cli/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: maestro-cli
+description: "Skill for the @maestro-js/cli package, the command-line interface for the Maestro framework. Use when working with @maestro-js/cli or the maestro-cli package directory. Key capabilities: database migrations (create, run, rollback, status), environment encryption/decryption, Docker database container creation, and AWS WireGuard VPN client provisioning. Trigger when adding CLI commands, modifying migration workflows, working with env encryption, or integrating new Maestro packages into the CLI."
+---
+
+# @maestro-js/cli
+
+CLI tool for the Maestro framework, built with [sade](https://github.com/lukeed/sade). Provides commands for database migrations, environment file encryption, Docker container creation, and AWS WireGuard client provisioning.
+
+Binary name: `maestro`. Installed via the `bin` field in package.json as `./dist/bin.js`.
+
+## Package Location
+
+- Source: `packages/maestro-cli/src/`
+- Entry point: `packages/maestro-cli/src/bin.ts`
+- Commands: `packages/maestro-cli/src/commands/`
+- Utilities: `packages/maestro-cli/src/utils/`
+- No tests directory exists for this package.
+
+## Available Commands
+
+| Command | Description |
+|---|---|
+| `maestro db:make-migration <name>` | Create a new database migration |
+| `maestro db:migrate` | Run pending database migrations |
+| `maestro db:rollback` | Rollback database migrations |
+| `maestro db:status` | Show database migration status |
+| `maestro db:make-container` | Create a Docker database container |
+| `maestro env:generate-key` | Generate an encryption key |
+| `maestro env:encrypt` | Encrypt a .env file |
+| `maestro env:decrypt` | Decrypt a .env.encrypted file |
+| `maestro aws:make-wireguard-client [id]` | Add a WireGuard client peer to a VPN server |
+
+## Command Details
+
+### db:make-migration
+
+Create a new migration in `infrastructure/db-migrations/` relative to cwd. Delegates to `DbMigrations.scaffold()` from `@maestro-js/db-migrate`.
+
+```
+maestro db:make-migration <name>
+```
+
+Generates three files: a `.ts` migration file, an `.up.sql` file, and a `.down.sql` file.
+
+### db:migrate
+
+Run pending database migrations. Connects to the database using resolved config (CLI flags > env vars > config file).
+
+```
+maestro db:migrate [options]
+  --host        Database host (env: DB_HOST)
+  --port        Database port (env: DB_PORT)
+  --user        Database user (env: DB_USER)
+  --password    Database password (env: DB_PASSWORD)
+  --database    Database name (env: DB_DATABASE)
+  --dry-run     Preview migrations without executing
+  --count       Number of migrations to run
+```
+
+### db:rollback
+
+Rollback database migrations. Default count is 1.
+
+```
+maestro db:rollback [options]
+  --host        Database host (env: DB_HOST)
+  --port        Database port (env: DB_PORT)
+  --user        Database user (env: DB_USER)
+  --password    Database password (env: DB_PASSWORD)
+  --database    Database name (env: DB_DATABASE)
+  --dry-run     Preview rollback without executing
+  --count       Number of migrations to rollback (default: 1)
+```
+
+### db:status
+
+Show which migrations have been applied and which are pending.
+
+```
+maestro db:status [options]
+  --host        Database host (env: DB_HOST)
+  --port        Database port (env: DB_PORT)
+  --user        Database user (env: DB_USER)
+  --password    Database password (env: DB_PASSWORD)
+  --database    Database name (env: DB_DATABASE)
+```
+
+### db:make-container
+
+Interactive command that prompts for database type (MySQL, PostgreSQL, Redis), container name, port, database name, and password. Pulls the Docker image and runs the container.
+
+```
+maestro db:make-container
+```
+
+Supported database images: `mysql:8`, `postgres:17`, `redis:7`.
+
+### env:generate-key
+
+Generate an encryption key via `Config.generateEncryptionKey()` from `@maestro-js/config`. Prints the key to stdout.
+
+```
+maestro env:generate-key
+```
+
+### env:encrypt
+
+Encrypt a `.env` file to `.env.encrypted`. Requires an encryption key via `--key` flag or `MAESTRO_ENV_ENCRYPTION_KEY` env var.
+
+```
+maestro env:encrypt [options]
+  --env    Environment name (e.g. production, creates .env.production.encrypted)
+  --key    Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)
+```
+
+### env:decrypt
+
+Decrypt a `.env.encrypted` file back to `.env`. Requires an encryption key via `--key` flag or `MAESTRO_ENV_ENCRYPTION_KEY` env var.
+
+```
+maestro env:decrypt [options]
+  --env      Environment name (e.g. production)
+  --key      Encryption key (env: MAESTRO_ENV_ENCRYPTION_KEY)
+  --force    Overwrite existing .env file
+```
+
+### aws:make-wireguard-client
+
+Add a WireGuard client peer to an existing VPN server managed via AWS SSM Parameter Store. If no `[id]` argument is provided, lists available WireGuard configurations from SSM and prompts for selection.
+
+```
+maestro aws:make-wireguard-client [id] [options]
+  --region        AWS region (env: AWS_REGION)
+  --name          Label for the peer
+  --endpoint      Override auto-detected server IP
+  --dns           DNS for client config
+  --allowed-ips   Client AllowedIPs (default: "10.0.0.0/16, 10.100.0.0/24")
+```
+
+Generates a WireGuard client configuration, stores the peer in SSM, and applies it on the server via SSM Run Command.
+
+## Adding New Commands
+
+### 1. Create the command file
+
+Add a new file in `packages/maestro-cli/src/commands/`. Follow the existing pattern: export a single async function that receives parsed options.
+
+```ts
+// packages/maestro-cli/src/commands/my-command.ts
+interface Options {
+  flag?: string
+}
+
+export async function myCommand(opts: Options) {
+  // Implementation
+  console.log('Done.')
+}
+```
+
+### 2. Register in bin.ts
+
+Import the command function and register it with sade in `packages/maestro-cli/src/bin.ts`:
+
+```ts
+import { myCommand } from './commands/my-command.ts'
+
+prog
+  .command('namespace:my-command')
+  .describe('Short description of what it does')
+  .option('--flag', 'Description of the flag')
+  .action(myCommand)
+```
+
+### 3. Command naming convention
+
+Use colon-separated namespaces matching existing groups:
+- `db:*` for database-related commands
+- `env:*` for environment/config commands
+- `aws:*` for AWS infrastructure commands
+
+### 4. For database commands
+
+Use the shared utilities in `packages/maestro-cli/src/utils/db.ts`:
+
+```ts
+import { createDb, resolveDbConfig, type DbConnectionConfig } from '../utils/db.ts'
+
+export async function myDbCommand(opts: Partial<DbConnectionConfig>) {
+  const config = await resolveDbConfig(opts)
+  const db = await createDb(config)
+  try {
+    // Use db...
+  } finally {
+    await db.destroy()
+  }
+}
+```
+
+The `resolveDbConfig` function resolves database connection settings with this precedence: CLI flags > environment variables > config file (loaded via `@maestro-js/config` with config name `db-migrate`).
+
+## Common Patterns
+
+### Database config resolution
+
+All `db:*` commands (except `db:make-migration` and `db:make-container`) share the same connection options and resolution logic from `utils/db.ts`. The `resolveDbConfig` function reads from:
+1. CLI flags (`--host`, `--port`, `--user`, `--password`, `--database`)
+2. Environment variables (`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_DATABASE`)
+3. Config file via `@maestro-js/config` with config name `db-migrate`
+
+### Migration directory
+
+All migration commands expect migrations in `infrastructure/db-migrations/` relative to the current working directory.
+
+### Interactive prompts
+
+The `prompts` library is used for interactive input in `db:make-container` and `aws:make-wireguard-client`. All prompt flows call `process.exit(0)` on cancellation.
+
+### Error handling
+
+Commands print errors to stderr via `console.error()` and call `process.exit(1)` on failure. Database commands use `try/finally` to ensure `db.destroy()` is always called.
+
+## Cross-Package Integration
+
+| Dependency | Usage |
+|---|---|
+| `@maestro-js/config` | Env encryption/decryption (`Config.generateEncryptedEnvFile`, `Config.generateDecryptedEnvFile`, `Config.generateEncryptionKey`), config file loading for DB credentials |
+| `@maestro-js/db` | Database connection creation via `Db.Provider.create` with `Db.drivers.mysql` driver |
+| `@maestro-js/db-migrate` | Migration operations: `DbMigrations.scaffold`, `DbMigrations.migrate`, `DbMigrations.rollback`, `DbMigrations.status` |
+| `sade` | CLI argument parsing and command registration |
+| `prompts` | Interactive terminal prompts for `db:make-container` and `aws:make-wireguard-client` |
+| `@aws-sdk/client-ssm` | SSM parameter read/write and Run Command for WireGuard provisioning |
+| `@aws-sdk/client-sts` | Caller identity resolution for default peer naming |
+
+## Utility Modules
+
+### utils/db.ts
+
+Exports `resolveDbConfig`, `createDb`, and the `DbConnectionConfig` / `CliDb` interfaces. Central place for database connection setup across all db commands.
+
+### utils/migrations.ts
+
+Re-exports `DbMigrations` from `@maestro-js/db-migrate`.
+
+### utils/scaffolding.ts
+
+General-purpose file scaffolding utility (`Scaffolding.scaffold`, `Scaffolding.previewScaffold`, `Scaffolding.fromDirectory`). Supports token replacement with `{{token}}` syntax, skip-existing behavior, and reading directory trees into scaffolding objects. Not currently used by any CLI command but available for future scaffolding needs.
+
+## Build and Development
+
+```bash
+pnpm --filter @maestro-js/cli build        # Build with tsup
+pnpm --filter @maestro-js/cli typecheck     # Typecheck
+pnpm --filter @maestro-js/cli watch         # Watch mode
+```
+
+No tests exist for this package. When adding tests, use `beartest-js` with `expect` assertions consistent with the rest of the monorepo.

package/dist/maestro-packages/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: maestro-packages
+description: "Reference for the @maestro-js backend framework. Use when working with any @maestro-js package — caching, database, queuing, mail, logging, events, encryption, config, tracing, and more. Covers package APIs and how packages compose together."
+---
+
+# Maestro Packages
+
+Maestro is a modular Node.js backend framework. Each package below handles a single concern (caching, logging, database, queuing, etc.) and composes with others.
+
+Use this skill when you need to:
+
+- **Understand a package's API** — find the right package below and open its detail page for full documentation
+- **Choose between packages** — decide which package solves a given problem (e.g. Cache vs CacheControl, Queue vs RecurringJobs)
+- **Wire packages together** — understand how packages relate (e.g. Queue powers Mail delivery, Log is used by most packages, Context provides request-scoped state)
+
+## How to use this skill
+
+Each package has a linked detail page with its full API, driver options, and usage examples. Start by scanning the list below to find the relevant package, then open its detail page.
+
+## Packages
+
+- **broadcast** — "Pattern-based event routing across channels and processes using @maestro-js/broadcast. Use when working with @maestro-js/broadcast, channel patterns, broadcast listeners, event name generation, or wildcard/dynamic-segment routing. Key capabilities: define typed channels with URL-like patterns (:id, optional segments, wildcards), emit and listen for events through a pluggable driver (e.g. Events/Redis), extract params from matched patterns, generate concrete event names from patterns, and manage listener lifecycles." [View details](./broadcast.md)
+- **cache** — Key-value caching with TTL, stale-while-revalidate, distributed locking, cache-aside pattern, atomic increment/decrement, and set-if-not-exists (add) for @maestro-js/cache. Use when working with @maestro-js/cache, adding caching to services, implementing distributed locks, using the remember/SWR pattern, incrementing or decrementing counters, adding values only if absent, configuring Redis or MockRedis drivers, or following the canonical Provider pattern from service-registry. [View details](./cache.md)
+- **cache-control** — HTTP Cache-Control-inspired caching for async functions with caller/callee directives. Use when working with @maestro-js/cache-control. Key capabilities: wrap async functions with cacheFn to add cache-control semantics, set response directives (maxAge, staleWhileRevalidate, noStore) from the callee, set request directives (maxAge, noStore) from the caller, automatic background revalidation of stale data, in-flight request deduplication, built-in LRU cache or custom cache backends, human-readable duration strings (e.g. '5 minutes'), structured logging of all cache lifecycle events, and optional tracing integration for observability. [View details](./cache-control.md)
+- **config** — Configuration loader for .env files and TypeScript/JavaScript config modules with AES-256-GCM encryption support. Use when working with @maestro-js/config, including loading config into process.env, reading/writing encrypted .env files, creating config modules, deriving computed env values, and generating encryption keys. Key capabilities: load config files, parse .env files (plaintext or encrypted), encrypt/decrypt env files, generate encryption keys, resolve config modules (named exports, default exports, sync/async functions), type-safe process.env via Config.Resolve utility type, and auto-load via node --import @maestro-js/config/load. [View details](./config.md)
+- **context** — Guide for working with @maestro-js/context, a request-scoped key-value storage package backed by Node.js AsyncLocalStorage. Use when working with @maestro-js/context, adding per-request state, storing visible or hidden context values, propagating context across async boundaries, integrating context with logging or tracing, creating typed context item handles, or transferring context stores between execution scopes. Covers the Provider pattern, visible/hidden buckets, run/runWith lifecycle, createItem typed handles, getStore for context propagation, and testing patterns. [View details](./context.md)
+- **crypt** — AES-256-GCM encryption and decryption with automatic key rotation for the maestro-js framework. Use when working with @maestro-js/crypt, encrypting or decrypting strings, rotating encryption keys, checking key IDs on encrypted data, or setting up field-level encryption. Key capabilities include AES-256-GCM authenticated encryption, dot-delimited cipher format with embedded key IDs, zero-downtime key rotation via previousKeys, per-call random IV generation, Provider pattern with deferred resolution, and key identification without decryption. [View details](./crypt.md)
+- **db** — Use when working with @maestro-js/db, the database access package for Maestro. Covers MySQL driver setup, parameterized SQL queries (select, insert, update, delete, scalar, statement), transactions with automatic commit/rollback, streaming results via selectIterable, connection pooling, query formatting, and the provider pattern for multiple database instances. Maestro uses raw parameterized SQL with no ORM. Depends on service-registry and log. Used by queue for message storage. Works with the sql package for query builders. [View details](./db.md)
+- **events** — Guide for @maestro-js/events — a pub/sub messaging package with pluggable drivers (Redis, WebSocket, Local). Use when working with @maestro-js/events, adding event-driven communication, creating typed event handles, configuring Redis pub/sub, setting up IPC via WebSocket, using in-process local events, or integrating with the Broadcast package. Covers the Provider pattern, driver configuration, typed Event handles, listener lifecycle, and cross-package usage with service-registry and broadcast. [View details](./events.md)
+- **exceptions** — Centralized exception reporting with automatic severity mapping and structured context, backed by @maestro-js/log. Use when working with @maestro-js/exceptions — reporting errors, silencing expected exceptions, attaching tags/extra metadata to error reports, or integrating exception handling into application services. Key capabilities: report exceptions with auto-detected severity (Error maps to 'error', non-Error maps to 'warn'), override log level via context, ignore/unignore specific exception instances, attach structured tags and extra data to reports. Follows the Provider pattern from @maestro-js/service-registry. [View details](./exceptions.md)
+- **form** — Headless React form primitives with client and server validation, hidden inputs for custom components, controlled/uncontrolled state management, and Standard Schema (Zod) FormData parsing with automatic type coercion. Use when building custom form components that need native constraint validation, server error integration, file upload handling, or type-safe FormData parsing. Provides HeadlessForm root component, useValidation/useWarningState/useControlledState/useReset hooks, HiddenInput/HiddenFileInput/HiddenSelect components, parseFormData/parseFormDataClientSide utilities, and composeValidators. [View details](./form.md)
+- **hash** — Pluggable hashing and verification with driver-based backends for @maestro-js/hash. Use when working with @maestro-js/hash, hashing values, verifying hashes, detecting when a rehash is needed, or rotating signing keys. Built-in drivers: SHA256 (HMAC-SHA256 with key rotation and timing-safe comparison). [View details](./hash.md)
+- **helpers** — Standalone utility functions for async control flow and file handling in the @maestro-js/helpers package. Use when working with @maestro-js/helpers. Key capabilities: retry with configurable attempts/delay/backoff, sleep, withMaxConcurrency for limiting parallel executions, withRateLimit with fixed or sliding window, raceWithFallback for promise racing with default values, AsyncIterableCollection for lazy async iteration (map, filter, reduce, forEach, toArray), sanitizeFilename for safe cross-platform filenames, and withRetry for wrapping functions with retry behavior. [View details](./helpers.md)
+- **log** — Structured logging with pluggable transports and channel-based routing for the Maestro framework. Use when working with @maestro-js/log, adding or modifying log transports, configuring log channels, filtering log messages by level or channel, integrating logging into other packages, or writing tests that capture log output. Key capabilities: create loggers with pluggable transports (console, file, Sentry, stub), route messages through named channels, filter by level and channel, override Node.js console, custom formatters, and the silence transport for suppressing output. [View details](./log.md)
+- **mail** — Driver-based email sending with queued delivery, scheduled sending, and mailable templates for the @maestro-js/mail package. Use when working with @maestro-js/mail. Covers creating mail services with SendGrid/SES/MailTrap/Stub drivers, sending emails immediately or via queue, scheduling future delivery, building reusable mailable templates, processing webhook events, generating ICS calendar attachments, and testing with the stub driver. [View details](./mail.md)
+- **metrics** — Use when working with @maestro-js/metrics. Unified metrics collection piped through the Log transport system. Covers four metric types (counters, distributions, sets, gauges), provider setup, logger integration, Sentry transport, and custom transport authoring. Trigger on metrics emission, observability instrumentation, Sentry metrics integration, or application telemetry tasks. [View details](./metrics.md)
+- **queue** — Database-backed job queue for deferring work beyond the current request with scheduled execution, concurrency control, and distributed tracing. Use when working with @maestro-js/queue, including dispatching jobs, processing queues, configuring the db driver, writing queue consumers, handling retries/stuck jobs, integrating with mail or recurring-jobs, and understanding the queue database schema. [View details](./queue.md)
+- **rate-limiting** — Per-key rate limiting with configurable decay windows. Use when enforcing attempt limits on login, API endpoints, or any action that needs throttling. Provides increment/check/clear workflow, guarded callback execution via attempt(), and ISO 8601 duration reporting. Requires a cache driver (e.g. from @maestro-js/cache). [View details](./rate-limiting.md)
+- **react-router-file-routes** —  [View details](./react-router-file-routes.md)
+- **recurring-jobs** — Use when working with @maestro-js/recurring-jobs. Cron-based job scheduling backed by the Queue package. Covers creating recurring jobs, managing schedules, start/stop processing, rescheduling, listing jobs, and inspecting upcoming runs. Follows the Provider pattern with ServiceRegistry. Key capabilities include cron expression parsing, deduplication across process restarts, per-job dedicated queues, structured log events, and paginated execution history. [View details](./recurring-jobs.md)
+- **sql** — Composable SQL query builders for dynamic WHERE clauses and Common Table Expressions (CTEs). Use when working with @maestro-js/sql, building dynamic SQL filters, constructing parameterized WHERE clauses, wrapping Db services with CTEs, or generating safe parameterized SQL fragments. Key capabilities: WhereClauseBuilder for incremental AND/OR conditions with nested sub-groups, CommonTableExpressionBuilder for wrapping a Db service so all queries auto-prepend WITH clauses, cloning builders, recursive CTEs, and dynamic parameter resolution. [View details](./sql.md)
+- **tracing** — Distributed tracing package built on OpenTelemetry with pluggable providers (Sentry, Maestro). Use when working with @maestro-js/tracing. Key capabilities: wrap functions for automatic span tracking, create active spans with duration measurement, proxy entire objects for tracing, serialize/deserialize trace context across process boundaries (dehydrate/hydrate), add custom log transports for span events, integrate Sentry as a tracing provider. [View details](./tracing.md)