@mariachi/core 0.0.1

package/docs/ai-guide.md

@@ -0,0 +1,222 @@
+# Mariachi AI Guide
+
+Concise reference for AI assistants generating code on the Mariachi framework. For quick lookups, see [architecture.md](./architecture.md), [patterns.md](./patterns.md), [conventions.md](./conventions.md), and [packages.md](./packages.md). For step-by-step instructions, see the [recipes](./recipes/).
+
+---
+
+## Architecture
+
+Three-layer request flow:
+
+```
+HTTP → Facade (FastifyAdapter, auth, rate limit)
+     → Controller (Zod validation, communication.call())
+     → Service (business logic, DB, cache, events)
+```
+
+Apps map to layers:
+
+| App | Layer | Purpose |
+|-----|-------|---------|
+| API app | Facade + Controller | HTTP servers, controllers, auth |
+| Services app | Service | Domain logic, handler registration |
+| Worker app | Background | BullMQ job workers, schedules |
+
+---
+
+## Decision Tree: Which Component to Use
+
+**"I need to handle an HTTP request"**
+→ Add a controller extending `BaseController`. Register on a server.
+
+**"I need to run business logic"**
+→ Create a service in your services app. Register a handler via `communication.register()`. Call it from a controller via `communication.call('<domain>.<action>', ctx, input)`.
+
+**"I need to run something in the background"**
+→ Define a job with a Zod schema and retry config. Enqueue via `jobQueue.enqueue(jobName, data)` from a service.
+→ See [recipes/add-background-job.md](./recipes/add-background-job.md).
+
+**"I need to react to something that happened"**
+→ Use the event bus: `eventBus.publish('user.created', payload)` and `eventBus.subscribe('user.created', handler)`. Adapter: Redis pub/sub or NATS.
+
+**"I need to run something on a schedule"**
+→ Add a schedule entry: `{ name, cron, jobName, data }`.
+
+**"I need to cache data"**
+→ Use `cache.getOrSet(key, ttl, fetchFn)` from `@mariachi/cache`. Redis-backed.
+
+**"I need to store files"**
+→ Use `@mariachi/storage` with S3 adapter.
+
+**"I need real-time updates"**
+→ Use `@mariachi/realtime` with `WSAdapter`. Supports channels, broadcast, and per-user messaging.
+
+**"I need to accept webhooks from a third party"**
+→ Create a `WebhookController`. Choose `mode: 'direct'` (sync via communication) or `mode: 'queue'` (async via jobs).
+→ See [recipes/add-webhook-endpoint.md](./recipes/add-webhook-endpoint.md).
+
+**"I need to integrate with an external service"**
+→ Use `defineIntegrationFn()` from `@mariachi/integrations`. See [recipes/add-integration.md](./recipes/add-integration.md).
+
+**"I need to wire up and bootstrap an app from scratch"**
+→ See [recipes/wiring-and-bootstrap.md](./recipes/wiring-and-bootstrap.md). Shows the full initialization sequence from config to running servers.
+
+**"I need to add a new domain entity end-to-end"**
+→ See [recipes/add-domain-entity.md](./recipes/add-domain-entity.md).
+
+---
+
+## Package Cheat Sheet
+
+### bootstrap (lifecycle)
+
+```ts
+import { bootstrap } from '@mariachi/lifecycle';
+const { config, logger, startup, shutdown, health } = bootstrap();
+startup.register({ name: 'my-service', priority: 10, fn: async () => { ... } });
+await startup.runAll(logger);
+```
+
+### communication
+
+```ts
+import { createCommunication } from '@mariachi/communication';
+const communication = createCommunication();
+
+// Register a handler (in services app)
+communication.register('users.create', {
+  schema: { input: CreateUserInput, output: UserOutput },
+  handler: (ctx, input) => UsersService.create(ctx, input),
+});
+
+// Call a handler (in API controller)
+const result = await communication.call('users.create', ctx, input);
+```
+
+### controller (api-facade)
+
+```ts
+import { BaseController, type HttpContext } from '@mariachi/api-facade';
+
+export class OrdersController extends BaseController {
+  readonly prefix = 'orders';
+
+  init() {
+    this.post(this.buildPath(), this.create);
+    this.get(this.buildPath(':id'), this.getById);
+  }
+
+  create = async (ctx: HttpContext, body: unknown) => {
+    const input = CreateOrderInput.parse(body);
+    return communication.call('orders.create', ctx, input);
+  };
+}
+```
+
+### server (api-facade)
+
+```ts
+import { FastifyAdapter } from '@mariachi/api-facade';
+
+const server = new FastifyAdapter({ name: 'public' })
+  .withAuth(['session', 'api-key'])
+  .withRateLimit({ perUser: 1000, perApiKey: 5000, window: '1h' });
+
+server.registerController(new OrdersController());
+await server.listen(3000);
+```
+
+### database schema
+
+```ts
+import { defineTable } from '@mariachi/database';
+import { column } from '@mariachi/database';
+
+export const ordersTable = defineTable('orders', {
+  id:        column.uuid().primaryKey().defaultRandom(),
+  tenantId:  column.text().notNull(),
+  userId:    column.text().notNull(),
+  total:     column.numeric().notNull(),
+  status:    column.text().notNull(),
+  createdAt: column.timestamp().notNull().defaultNow(),
+  updatedAt: column.timestamp().notNull().defaultNow(),
+  deletedAt: column.timestamp(),
+});
+```
+
+### repository (database-postgres)
+
+```ts
+import { DrizzleRepository } from '@mariachi/database-postgres';
+import { orders } from '../compiled-schemas';
+
+export class DrizzleOrdersRepository extends DrizzleRepository<Order> {
+  constructor(db: DrizzleDb) {
+    super(orders, db, { tenantColumn: 'tenantId' });
+  }
+}
+```
+
+Inherited methods: `findById`, `findMany`, `create`, `update`, `softDelete`, `hardDelete`, `paginate`, `count`.
+
+### jobs
+
+```ts
+import { z } from 'zod';
+
+export const ProcessOrderJob = {
+  name: 'orders.process',
+  schema: z.object({ orderId: z.string() }),
+  retry: { attempts: 3, backoff: 'exponential' as const },
+  handler: async (data, ctx) => { ... },
+};
+```
+
+### events
+
+```ts
+const eventBus = createEventBus({ adapter: 'redis', url: process.env.REDIS_URL });
+await eventBus.publish('order.created', { orderId: '123' });
+await eventBus.subscribe('order.created', async (event) => { ... });
+```
+
+### cache
+
+```ts
+const cache = createCache({ adapter: 'redis', url: process.env.REDIS_URL });
+const user = await cache.getOrSet(
+  cache.key('users', userId),
+  3600,
+  () => repo.findById(ctx, userId),
+);
+```
+
+### testing
+
+```ts
+import { createTestHarness, createTestContext, TestRepository } from '@mariachi/testing';
+
+const harness = createTestHarness();
+const ctx = createTestContext();
+const repo = new TestRepository<User>();
+```
+
+---
+
+## Common Gotchas
+
+1. **Communication handlers must be registered before `call()`**. Call your handler registration (e.g. `registerServiceHandlers(communication)`) before starting the API server.
+
+2. **No in-memory job adapter exists**. The worker uses BullMQ. Use `@mariachi/testing`'s `TestJobQueue` in tests.
+
+3. **`createCommunication()` returns an `InProcessAdapter`**. The communication layer is in-process only.
+
+4. **Soft deletes are the default**. `DrizzleRepository.softDelete()` sets `deletedAt`. All queries automatically filter out soft-deleted rows. Use `hardDelete()` only when explicitly needed.
+
+5. **Tenant isolation is automatic in `DrizzleRepository`**. When `tenantColumn` is set and `ctx.tenantId` is present, all queries are scoped to that tenant.
+
+6. **`bootstrap()` registers Config and Logger in the DI container**. Other services pull them via `getContainer().resolve(KEYS.Logger)`.
+
+7. **Controller route handlers receive `(ctx, body, params, query)`**. Use the controller's handler signature, not raw Fastify request.
+
+8. **Some planned adapters are not implemented**. This guide reflects actual code only (Postgres, Redis, BullMQ, etc.).

package/docs/architecture.md

@@ -0,0 +1,110 @@
+# Mariachi Framework Architecture
+
+Mariachi is an LLM-optimized TypeScript backend framework with adapter-based abstractions. It provides a modular structure where external dependencies (databases, caches, message queues, third-party APIs) are hidden behind config-driven adapters, enabling vendor independence and testability.
+
+## Three-Layer Architecture
+
+Requests flow through three layers: **Facade** (HTTP/entry), **Controller** (routing and validation), and **Service** (business logic). Controllers delegate to services via the communication layer.
+
+```mermaid
+flowchart TB
+    subgraph Facade
+        HTTP[HTTP Request]
+        Fastify[FastifyAdapter]
+        Auth[Auth Strategies]
+        RateLimit[Rate Limiting]
+    end
+
+    subgraph Controller
+        Ctrl[Controller]
+        Validation[Input Validation]
+    end
+
+    subgraph Communication
+        Comm[Communication Layer]
+        Middleware[Middleware Pipeline]
+    end
+
+    subgraph Service
+        Svc[Service]
+        BusinessLogic[Business Logic]
+    end
+
+    HTTP --> Fastify
+    Fastify --> Auth
+    Auth --> RateLimit
+    RateLimit --> Ctrl
+    Ctrl --> Validation
+    Validation --> Comm
+    Comm --> Middleware
+    Middleware --> Svc
+    Svc --> BusinessLogic
+```
+
+| Layer | Responsibility |
+|-------|----------------|
+| **Facade** | HTTP server (Fastify), auth strategies, rate limiting, route registration |
+| **Controller** | Parse/validate input, call communication layer, return response |
+| **Service** | Business logic, database access, external integrations |
+
+## Package Overview
+
+| Package | Purpose |
+|---------|---------|
+| `@mariachi/core` | Shared types, errors, context, container |
+| `@mariachi/config` | Typed config, secrets, feature flags |
+| `@mariachi/observability` | Logging (Pino), tracing (OTEL), metrics, error tracking |
+| `@mariachi/lifecycle` | Startup/shutdown, health checks, bootstrap |
+| `@mariachi/communication` | Inter-module communication, middleware pipeline |
+| `@mariachi/database` | Drizzle ORM, PostgreSQL, repositories |
+| `@mariachi/cache` | Redis, in-memory, distributed locks |
+| `@mariachi/events` | Event bus, Redis Pub/Sub |
+| `@mariachi/jobs` | BullMQ job queue, workers, scheduler |
+| `@mariachi/auth` | JWT, API keys, RBAC |
+| `@mariachi/tenancy` | Multi-tenant isolation |
+| `@mariachi/rate-limit` | Redis sliding window rate limiting |
+| `@mariachi/audit` | Append-only audit logging |
+| `@mariachi/api-facade` | Fastify server adapter, auth strategies |
+| `@mariachi/storage` | S3, local file storage |
+| `@mariachi/notifications` | Email (Resend), in-app notifications |
+| `@mariachi/billing` | Stripe billing, webhooks |
+| `@mariachi/search` | Typesense, full-text search |
+| `@mariachi/ai` | AI SDK, sessions, tools, prompts, agent loops |
+| `@mariachi/integrations` | Third-party integration pattern |
+| `@mariachi/testing` | In-memory test doubles, factories |
+| `@mariachi/create` | Scaffolding, validation |
+| `@mariachi/cli` | CLI binary |
+
+## Monolith vs Microservice
+
+Mariachi is designed as a **modular monolith**. All packages can live in one codebase and share the same process. The communication layer (`@mariachi/communication`) uses an in-process adapter by default, routing procedure calls directly to registered handlers.
+
+For future scaling, the communication layer can be swapped for a transport adapter (e.g., message queue, gRPC) without changing controllers or services. The framework does not prescribe microservices; teams can extract services later if needed.
+
+## Adapter Pattern
+
+External dependencies are abstracted behind adapters. Each package exposes a factory (e.g., `createCache`, `createSearch`) that selects the implementation based on config.
+
+```mermaid
+flowchart LR
+    subgraph Config
+        C[Config]
+    end
+
+    subgraph Factory
+        F[createX]
+    end
+
+    subgraph Adapters
+        A1[RedisAdapter]
+        A2[MemoryAdapter]
+    end
+
+    C --> F
+    F -->|adapter: redis| A1
+    F -->|adapter: memory| A2
+```
+
+**Example:** `createSearch(config)` returns `TypesenseSearchAdapter` when `config.adapter === 'typesense'`, or `MemorySearchAdapter` when `config.adapter === 'memory'`. Tests use in-memory adapters; production uses Redis, PostgreSQL, Stripe, etc.
+
+Adapters implement a common interface. The factory is the single place that maps config to implementation, keeping application code vendor-agnostic.

package/docs/conventions.md

@@ -0,0 +1,109 @@
+# Mariachi Conventions
+
+## TypeScript and ESM
+
+- **All packages use ESM** (`"type": "module"` in every `package.json`)
+- **Build tool:** tsup (ESM + CJS dual output, declaration files, sourcemaps)
+- **TypeScript:** strict mode, ES2022 target, `"moduleResolution": "bundler"`
+- **Relative imports are extensionless:** `import { foo } from './bar'` (not `'./bar.js'`). The `"moduleResolution": "bundler"` tsconfig setting and tsup handle resolution.
+- **Cross-package imports use bare specifiers:** `import { Context } from '@mariachi/core'` (no extension)
+- **All packages export from `src/index.ts`** as the single public entry point
+
+### tsup Config (every package)
+
+```ts
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  splitting: false,
+});
+```
+
+### tsconfig (every package)
+
+Extend a shared base or use standard options. No additional compiler options needed unless the package has special requirements.
+
+## File Organization
+
+- One file per concern: `types.ts`, `schema.ts`, `adapter.ts`, `middleware.ts`
+- Adapters go in `src/adapters/` subdirectory
+- Middleware goes in `src/middleware/` subdirectory
+- Schema definitions go in `src/schema/` subdirectory
+- Tests go alongside source in `test/` or `__tests__/` subdirectory
+
+## Dependency Rules
+
+- `@mariachi/core` has zero internal dependencies (only `zod`)
+- Other packages may depend on `@mariachi/core` freely
+- Packages should depend on abstractions, not implementations (e.g., depend on `@mariachi/database`, not `@mariachi/database-postgres`)
+- Apps may depend on any package
+- Circular dependencies between packages are not allowed
+
+## Error Handling
+
+- Always throw typed errors extending `MariachiError` from `@mariachi/core`
+- Each package has its own error class: `DatabaseError`, `AuthError`, `CacheError`, etc.
+- Never throw raw `Error` or string exceptions across package boundaries
+- Errors map to HTTP status codes via `errorToHttpStatus()` in the API facade layer
+
+## Anti-Patterns (Do Not Do These)
+
+**Do not import services from controllers.**
+Controllers must only call `communication.call()`. Never import a service or its handler directly.
+
+```ts
+// WRONG
+import { UsersService } from '../../services/users/users.service';
+const result = await UsersService.create(ctx, input);
+
+// CORRECT
+const result = await communication.call('users.create', ctx, input);
+```
+
+**Do not use `process.env` outside `@mariachi/config`.**
+All configuration flows through `loadConfig()` and `useConfig()`. Direct env access scatters configuration and bypasses validation.
+
+```ts
+// WRONG
+const dbUrl = process.env.DATABASE_URL;
+
+// CORRECT
+const config = useConfig();
+const dbUrl = config.database.url;
+```
+
+Exception: `PORT`, `ADMIN_PORT`, `WEBHOOK_PORT` in app entry points are acceptable since they're startup-only values.
+
+**Do not skip context propagation.**
+Every operation takes a `Context` as its first argument. Never create a new context mid-flow or drop context between layers.
+
+```ts
+// WRONG
+const user = await UsersService.create({ email, name });
+
+// CORRECT
+const user = await UsersService.create(ctx, { email, name });
+```
+
+**Do not expose the Drizzle client directly.**
+All database access goes through repository classes that extend `DrizzleRepository`. The ORM is an implementation detail.
+
+**Do not hardcode adapter choices.**
+Use factory functions (`createCache`, `createSearch`, `createJobQueue`) with config. Never instantiate adapters directly in application code.
+
+```ts
+// WRONG
+const cache = new RedisCacheAdapter({ url: 'redis://localhost' });
+
+// CORRECT
+const cache = createCache({ adapter: 'redis', url: config.redis.url });
+```
+
+**Do not write migration files by hand.**
+Schema changes go through the `defineTable` DSL in `@mariachi/database`. Migrations are generated by `drizzle-kit`.
+
+**Do not register the same procedure name twice.**
+Communication procedure names (`users.create`, `billing.charge`, etc.) must be globally unique. Duplicate registrations will silently overwrite each other.

package/docs/improvements/20260224231420_notifications_realtime_nats.md

@@ -0,0 +1,82 @@
+# Notifications, Realtime, and NATS
+
+> **Date:** 2026-02-24
+> **Status:** Draft
+> **Scope:** `@mariachi/events`, `@mariachi/notifications`, `@mariachi/realtime` (new)
+
+---
+
+## Problem
+
+The current architecture has unclear boundaries between three distinct concerns:
+
+1. **Internal domain events** — service-to-service messaging (`@mariachi/events`, Redis Pub/Sub only)
+2. **Transactional notifications** — user-facing messages (`@mariachi/notifications`, email only, no queue, no multi-channel)
+3. **Realtime delivery** — pushing state to connected clients (does not exist)
+
+There is no way to push updates to a connected browser. Transactional notifications are fire-and-forget with no retry. The event bus has no durable delivery option and no way to expose topics to authenticated clients.
+
+---
+
+## Architecture
+
+```
+                         ┌─────────────────────────────────┐
+                         │        NATS Server               │
+                         │  (subjects, JetStream, auth)     │
+                         └──────────┬──────────┬────────────┘
+                                    │          │
+                    ┌───────────────┘          └───────────────┐
+                    │                                          │
+         ┌──────────▼──────────┐                   ┌───────────▼──────────┐
+         │  @mariachi/events   │                   │  @mariachi/realtime  │
+         │  (internal pub/sub) │                   │  (client-facing)     │
+         │                     │                   │                      │
+         │  Adapters:          │                   │  WebSocket / SSE     │
+         │  - Redis Pub/Sub    │                   │  NATS bridge         │
+         │  - NATS             │◄──────────────────│  Auth via facade     │
+         │  - NATS JetStream   │   subscribes to   │  Presence tracking   │
+         │    (durable)        │   internal events  │  Channel management   │
+         └──────────┬──────────┘                   └──────────────────────┘
+                    │                                          ▲
+                    │  events trigger                           │
+                    │  notifications                            │ pushes to
+                    ▼                                          │ connected clients
+         ┌──────────────────────────────────┐                  │
+         │  @mariachi/notifications          │                  │
+         │  (transactional, multi-channel)   │                  │
+         │                                   │                  │
+         │  1. Receive notification intent   │                  │
+         │  2. Check user preferences (DB)   │                  │
+         │  3. Enqueue via @mariachi/jobs    │                  │
+         │  4. Deliver via channel:          │                  │
+         │     - Email (Resend)              │                  │
+         │     - SMS (Twilio)                │                  │
+         │     - Push (FCM)                  │                  │
+         │     - In-App (DB write) ──────────┼──────────────────┘
+         └──────────────────────────────────┘
+```
+
+---
+
+## Summary of Changes
+
+| Package | Change |
+|---|---|
+| `@mariachi/events` | Add `NATSEventBusAdapter` + `NATSJetStreamAdapter`, update factory, add `nats` dep |
+| `@mariachi/notifications` | Rewrite as multi-channel router. Add `notify()` method, SMS/Push adapters, job-based delivery, delivery tracking DB schema, user preference resolution |
+| `@mariachi/realtime` | **New package.** WebSocket/SSE server, NATS bridge, auth integration, presence, channel management. Redis-backed connection state |
+| `@mariachi/jobs` | Add notification delivery job definition |
+| `@mariachi/auth` | Channel authorization support (can user subscribe to this realtime channel?) |
+
+### Implementation order
+
+1. `@mariachi/events` — add NATS adapter (no breaking changes)
+2. `@mariachi/notifications` — rewrite with multi-channel routing + job queue delivery
+3. `@mariachi/realtime` — new package, depends on events + auth + cache
+4. Wire in-app notifications → realtime push
+5. Add NATS subject naming convention enforcement to `@mariachi/create` validator
+
+---
+
+For full design details (NATS adapter code, notification types, realtime API, client protocol), see the framework repository's `docs/improvements/` or the source ADR.

package/docs/integrations.md

@@ -0,0 +1,70 @@
+# Integrations
+
+How to add and configure third-party integrations in Mariachi.
+
+## How to Add an Integration
+
+1. **Generate the scaffold** (optional, if using `@mariachi/cli`):
+
+   ```bash
+   mariachi generate integration <name>
+   ```
+
+2. **Define credentials** in `integrations/<name>/credentials.ts` using Zod:
+
+   ```ts
+   import { z } from 'zod';
+
+   export const MyCredentials = z.object({
+     apiKey: z.string().min(1),
+     // ... other fields
+   });
+
+   export type MyCredentials = z.infer<typeof MyCredentials>;
+   ```
+
+3. **Define integration functions** in `integrations/<name>/index.ts` using `defineIntegrationFn`:
+
+   ```ts
+   import { defineIntegrationFn } from '@mariachi/integrations';
+   import type { IntegrationContext } from '@mariachi/integrations';
+   import { MyCredentials } from './credentials';
+   import { InputSchema, OutputSchema } from './types';
+
+   export interface MyIntegrationContext extends IntegrationContext {
+     credentials: MyCredentials;
+   }
+
+   export const myAction = defineIntegrationFn({
+     name: 'my.action',
+     input: InputSchema,
+     output: OutputSchema,
+     handler: async (input, ctx) => {
+       const creds = (ctx as MyIntegrationContext).credentials;
+       // Call external API with creds
+       return result;
+     },
+     retry: { attempts: 3, backoff: 'exponential' },
+   });
+   ```
+
+4. **Register in the registry** (optional):
+
+   ```ts
+   registry.register({
+     name: 'my',
+     description: 'My integration',
+     credentialSchema: MyCredentials,
+     functions: ['my.action'],
+   });
+   ```
+
+## Credential Requirements
+
+- Credentials are validated with Zod schemas.
+- Store secrets via `@mariachi/config` (e.g., env adapter); never hardcode.
+- Each integration defines its own credential schema.
+
+## Step-by-step recipe
+
+For a full walkthrough with credentials, client, types, and tests, see [recipes/add-integration.md](./recipes/add-integration.md).

package/docs/packages.md

@@ -0,0 +1,66 @@
+# Mariachi Packages
+
+Quick reference for all 28 packages. Use this to decide which package to reach for.
+
+## Foundation
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/core` | Types, errors, context, DI container, `Result<T,E>` | `getContainer()`, `createContext()`, `KEYS` |
+| `@mariachi/config` | Typed config from env, secrets, feature flags | `loadConfig()`, `useConfig()` |
+| `@mariachi/observability` | Logging, tracing, metrics, error tracking | `createObservability(config)` |
+| `@mariachi/lifecycle` | App bootstrap, startup/shutdown hooks, health checks | `bootstrap()` |
+
+## Communication & API
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/communication` | Inter-module procedure calls with middleware | `createCommunication()` |
+| `@mariachi/api-facade` | HTTP servers with auth, rate limiting, controllers | `new FastifyAdapter()`, `BaseController` |
+| `@mariachi/server` | Low-level Fastify adapter (used by api-facade) | `FastifyServerAdapter` |
+| `@mariachi/webhooks` | Inbound webhook endpoints with auth and logging | `WebhookController`, `WebhookServer` |
+
+## Data & Storage
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/database` | Schema definitions, repository interface, types | `defineTable()`, `column`, `Database` |
+| `@mariachi/database-postgres` | PostgreSQL + Drizzle ORM implementation | `createPostgresDatabase()`, `DrizzleRepository` |
+| `@mariachi/cache` | Redis caching, distributed locks, memoization | `createCache()`, `createLock()` |
+| `@mariachi/storage` | File/object storage (S3, local) | `Storage`, `DefaultStorage` |
+
+## Async & Events
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/events` | Pub/sub event bus (Redis or NATS) | `createEventBus()` |
+| `@mariachi/jobs` | Background job queue and scheduling (BullMQ) | `createJobQueue()`, `defineJob` |
+| `@mariachi/realtime` | WebSocket connections, channels, broadcasting | `Realtime`, `WSAdapter` |
+
+## Security & Access
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/auth` | JWT, API keys, OAuth, RBAC | `createAuth()`, `createAuthorization()` |
+| `@mariachi/auth-clerk` | Clerk authentication, webhook verification (Svix) | `createClerkAuth()`, `ClerkWebhookController` |
+| `@mariachi/tenancy` | Multi-tenant isolation (subdomain, header, JWT) | `createTenantResolver()`, `createTenancyMiddleware()` |
+| `@mariachi/rate-limit` | Redis sliding-window rate limiting | `createRateLimiter()` |
+
+## Domain Features
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/billing` | Stripe payments, subscriptions, credits, webhooks | `createBilling()`, `StripeAdapter` |
+| `@mariachi/notifications` | Email (Resend), SMS, push, in-app notifications | `Notifications`, `createEmailAdapter()` |
+| `@mariachi/search` | Full-text search (Typesense) | `createSearch()` |
+| `@mariachi/ai` | AI/LLM sessions, tools, prompts, agent loops | `createAI()`, `runAgent()` |
+| `@mariachi/audit` | Append-only audit logging | `createAuditLogger()` |
+| `@mariachi/integrations` | Third-party integration pattern | `defineIntegrationFn()` |
+
+## Tooling
+
+| Package | Use when you need... | Factory / Entry |
+|---------|---------------------|-----------------|
+| `@mariachi/testing` | In-memory test doubles, factories | `createTestHarness()`, `TestRepository` |
+| `@mariachi/create` | Code scaffolding and validation rules | `mariachi generate` |
+| `@mariachi/cli` | CLI binary | `mariachi init/generate/validate` |