@classytic/arc 2.3.0 → 2.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.3.0",
+  "version": "2.4.2",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -108,6 +108,10 @@
       "types": "./dist/events/transports/redis-stream-entry.d.mts",
       "default": "./dist/events/transports/redis-stream-entry.mjs"
     },
+    "./dynamic": {
+      "types": "./dist/dynamic/index.d.mts",
+      "default": "./dist/dynamic/index.mjs"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.mts",
       "default": "./dist/testing/index.mjs"
@@ -144,6 +148,10 @@
       "types": "./dist/integrations/websocket.d.mts",
       "default": "./dist/integrations/websocket.mjs"
     },
+    "./integrations/websocket-redis": {
+      "types": "./dist/integrations/websocket-redis.d.mts",
+      "default": "./dist/integrations/websocket-redis.mjs"
+    },
     "./integrations/jobs": {
       "types": "./dist/integrations/jobs.d.mts",
       "default": "./dist/integrations/jobs.mjs"
@@ -152,6 +160,10 @@
       "types": "./dist/integrations/event-gateway.d.mts",
       "default": "./dist/integrations/event-gateway.mjs"
     },
+    "./integrations/webhooks": {
+      "types": "./dist/integrations/webhooks.d.mts",
+      "default": "./dist/integrations/webhooks.mjs"
+    },
     "./auth/redis": {
       "types": "./dist/auth/redis-session.d.mts",
       "default": "./dist/auth/redis-session.mjs"
@@ -163,6 +175,18 @@
     "./scope": {
       "types": "./dist/scope/index.d.mts",
       "default": "./dist/scope/index.mjs"
+    },
+    "./rpc": {
+      "types": "./dist/rpc/index.d.mts",
+      "default": "./dist/rpc/index.mjs"
+    },
+    "./mcp": {
+      "types": "./dist/integrations/mcp/index.d.mts",
+      "default": "./dist/integrations/mcp/index.mjs"
+    },
+    "./mcp/testing": {
+      "types": "./dist/integrations/mcp/testing.d.mts",
+      "default": "./dist/integrations/mcp/testing.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -173,26 +197,31 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "skills"
   ],
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --fix src/",
+    "lint:all": "biome check src/ tests/",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run tests/e2e",
     "test:unit": "vitest run tests/core tests/hooks tests/utils tests/plugins",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+    "smoke": "node scripts/smoke-test.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run smoke"
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.3.2",
-    "@classytic/streamline": ">=1.0.0",
+    "@classytic/mongokit": ">=3.4.3",
+    "@classytic/streamline": ">=2.0.0",
     "@fastify/cors": "^11.0.0",
     "@fastify/helmet": "^13.0.0",
     "@fastify/jwt": "^10.0.0",
@@ -202,14 +231,14 @@
     "@fastify/type-provider-typebox": "^6.0.0",
     "@fastify/under-pressure": "^9.0.0",
     "@fastify/websocket": "^11.0.0",
-    "@opentelemetry/api": "^1.0.0",
+    "@modelcontextprotocol/sdk": ">=1.28.0",
     "@opentelemetry/auto-instrumentations-node": ">=0.40.0",
     "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
     "@opentelemetry/instrumentation-http": ">=0.50.0",
     "@opentelemetry/instrumentation-mongodb": ">=0.40.0",
     "@opentelemetry/sdk-node": ">=0.50.0",
     "@sinclair/typebox": "^0.34.0",
-    "better-auth": ">=1.0.0",
+    "better-auth": ">=1.5.5",
     "bullmq": "^5.0.0",
     "fastify": "^5.7.4",
     "fastify-raw-body": "^5.0.0",
@@ -297,6 +326,9 @@
     },
     "zod": {
       "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -304,11 +336,13 @@
     "qs": "^6.14.1"
   },
   "devDependencies": {
-    "@classytic/mongokit": "^3.3.2",
+    "@biomejs/biome": "^2.4.10",
+    "@classytic/mongokit": "^3.4.3",
     "@fastify/jwt": "^10.0.0",
     "@fastify/multipart": "^9.0.0",
     "@fastify/type-provider-typebox": "^6.0.0",
     "@fastify/websocket": "^11.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@sinclair/typebox": "^0.34.0",
     "@types/node": "^22.10.0",
     "@types/qs": "^6.14.0",
@@ -317,8 +351,8 @@
     "jsonwebtoken": "^9.0.0",
     "mongodb": "^7.1.0",
     "mongodb-memory-server": "^11.0.1",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.7.2",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
     "vitest": "^3.0.0",
     "ws": "^8.0.0",
     "zod": "^4.3.6"

package/skills/arc/SKILL.md

@@ -0,0 +1,518 @@
+---
+name: arc
+description: |
+  @classytic/arc — Resource-oriented backend framework for Fastify.
+  Use when building REST APIs with Fastify, resource CRUD, defineResource, createApp,
+  permissions, presets, database adapters, hooks, events, QueryCache, authentication,
+  multi-tenant SaaS, OpenAPI, job queues, WebSocket, MCP tools, or production deployment.
+  Triggers: arc, fastify resource, defineResource, createApp, BaseController, arc preset,
+  arc auth, arc events, arc jobs, arc websocket, arc mcp, arc plugin, arc testing, arc cli,
+  arc permissions, arc hooks, arc pipeline, arc factory, arc cache, arc QueryCache.
+version: 2.4.2
+license: MIT
+metadata:
+  author: Classytic
+  version: "2.4.1"
+tags:
+  - fastify
+  - rest-api
+  - resource-framework
+  - crud
+  - permissions
+  - multi-tenant
+  - presets
+  - typescript
+  - cache
+  - events
+  - openapi
+progressive_disclosure:
+  entry_point:
+    summary: "Resource-oriented Fastify framework: defineResource(), presets, permissions, QueryCache, events, multi-tenant, OpenAPI"
+    when_to_use: "Building REST APIs with Fastify, resource CRUD, authentication, presets, caching, events, or production deployment"
+    quick_start: "1. npm install @classytic/arc fastify 2. createApp({ preset: 'production', auth: { type: 'jwt', jwt: { secret } } }) 3. defineResource({ name, adapter, presets, permissions })"
+  context_limit: 700
+---
+
+# @classytic/arc
+
+Resource-oriented backend framework for Fastify. Database-agnostic, tree-shakable, production-ready.
+
+**Requires:** Fastify `^5.7.4` | Node.js `>=22` | ESM only
+
+## Install
+
+```bash
+# Install the Arc agent skill (Claude Code / AI agents)
+npx skills add classytic/arc
+
+# Install the npm package
+npm install @classytic/arc fastify
+npm install @classytic/mongokit mongoose    # MongoDB adapter
+```
+
+## Quick Start
+
+```typescript
+import { createApp } from '@classytic/arc/factory';
+import mongoose from 'mongoose';
+
+await mongoose.connect(process.env.DB_URI);
+
+const app = await createApp({
+  preset: 'production',
+  auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+  cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') },
+});
+
+await app.register(productResource.toPlugin());
+await app.listen({ port: 8040, host: '0.0.0.0' });
+```
+
+## defineResource()
+
+Single API to define a full REST resource:
+
+```typescript
+import { defineResource, createMongooseAdapter, allowPublic, requireRoles } from '@classytic/arc';
+
+const productResource = defineResource({
+  name: 'product',
+  adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
+  controller: productController,  // optional — auto-created if omitted
+  presets: ['softDelete', 'slugLookup', { name: 'multiTenant', tenantField: 'orgId' }],
+  permissions: {
+    list: allowPublic(),
+    get: allowPublic(),
+    create: requireRoles(['admin']),
+    update: requireRoles(['admin']),
+    delete: requireRoles(['admin']),
+  },
+  cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
+  additionalRoutes: [
+    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic(), wrapHandler: true },
+  ],
+});
+
+await fastify.register(productResource.toPlugin());
+// Auto-generates: GET /, GET /:id, POST /, PATCH /:id, DELETE /:id
+```
+
+## Authentication
+
+Auth uses a **discriminated union** with `type` field:
+
+```typescript
+// Arc JWT (with optional token extraction and revocation)
+auth: {
+  type: 'jwt',
+  jwt: { secret, expiresIn: '15m', refreshSecret, refreshExpiresIn: '7d' },
+  tokenExtractor: (req) => req.cookies?.['auth-token'] ?? null,  // optional
+  isRevoked: async (decoded) => redis.sismember('revoked', decoded.jti),  // optional
+}
+
+// Better Auth (recommended for SaaS with orgs)
+import { createBetterAuthAdapter } from '@classytic/arc/auth';
+auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth, orgContext: true }) }
+
+// Custom Fastify plugin (must decorate fastify.authenticate)
+auth: { type: 'custom', plugin: myAuthPlugin }
+
+// Custom function (decorates fastify.authenticate directly)
+auth: { type: 'authenticator', authenticate: async (req, reply) => { ... } }
+
+// Disabled
+auth: false
+```
+
+**Decorates:** `app.authenticate`, `app.optionalAuthenticate`, `app.authorize`
+
+## Permissions
+
+Function-based. A `PermissionCheck` returns `boolean | { granted, reason?, filters? }`:
+
+```typescript
+import {
+  allowPublic, requireAuth, requireRoles, requireOwnership,
+  requireOrgMembership, requireOrgRole, requireTeamMembership,
+  allOf, anyOf, when, denyAll,
+  createDynamicPermissionMatrix,
+} from '@classytic/arc';
+
+permissions: {
+  list: allowPublic(),
+  get: requireAuth(),
+  create: requireRoles(['admin', 'editor']),
+  update: anyOf(requireOwnership('userId'), requireRoles(['admin'])),
+  delete: allOf(requireAuth(), requireRoles(['admin'])),
+}
+```
+
+**Custom permission:**
+
+```typescript
+const requirePro = (): PermissionCheck => async (ctx) => {
+  if (!ctx.user) return { granted: false, reason: 'Auth required' };
+  return { granted: ctx.user.plan === 'pro' };
+};
+```
+
+**Field-level permissions:**
+
+```typescript
+import { fields } from '@classytic/arc';
+
+fields: {
+  password: fields.hidden(),
+  salary: fields.visibleTo(['admin', 'hr']),
+  role: fields.writableBy(['admin']),
+  email: fields.redactFor(['viewer'], '***'),
+}
+```
+
+**Dynamic ACL (DB-managed):**
+
+```typescript
+const acl = createDynamicPermissionMatrix({
+  resolveRolePermissions: async (ctx) => aclService.getRoleMatrix(orgId),
+  cacheStore: new RedisCacheStore({ client: redis, prefix: 'acl:' }),
+});
+permissions: { list: acl.canAction('product', 'read') }
+```
+
+## Presets
+
+| Preset | Routes Added | Controller Interface | Config |
+|--------|-------------|---------------------|--------|
+| `softDelete` | GET /deleted, POST /:id/restore | `ISoftDeleteController` | `{ deletedField }` |
+| `slugLookup` | GET /slug/:slug | `ISlugLookupController` | `{ slugField }` |
+| `tree` | GET /tree, GET /:parent/children | `ITreeController` | `{ parentField }` |
+| `ownedByUser` | none (middleware) | — | `{ ownerField }` |
+| `multiTenant` | none (middleware) | — | `{ tenantField }` |
+| `audited` | none (middleware) | — | — |
+| `bulk` | POST/PATCH/DELETE /bulk | — | `{ operations?, maxCreateItems? }` |
+
+```typescript
+presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
+// Bulk: presets: ['bulk'] or bulkPreset({ operations: ['createMany', 'updateMany'] })
+```
+
+## QueryCache
+
+TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
+
+```typescript
+// Enable globally
+const app = await createApp({ arcPlugins: { queryCache: true } });
+
+// Per-resource config
+defineResource({
+  name: 'product',
+  cache: {
+    staleTime: 30,      // seconds fresh (no revalidation)
+    gcTime: 300,         // seconds stale data kept (SWR window)
+    tags: ['catalog'],   // cross-resource grouping
+    invalidateOn: { 'category.*': ['catalog'] },  // event pattern → tag targets
+    list: { staleTime: 60 },  // per-operation override
+    byId: { staleTime: 10 },
+  },
+});
+```
+
+**Auto-invalidation:** POST/PATCH/DELETE bumps resource version. Old cached queries expire naturally via TTL.
+
+**Runtime modes:** `memory` (default, zero-config) | `distributed` (requires `stores.queryCache: RedisCacheStore`)
+
+**Response header:** `x-cache: HIT | STALE | MISS`
+
+## BaseController
+
+```typescript
+import { BaseController } from '@classytic/arc';
+import type { IRequestContext, IControllerResponse } from '@classytic/arc';
+
+class ProductController extends BaseController<Product> {
+  constructor() { super(productRepo); }
+
+  async getFeatured(req: IRequestContext): Promise<IControllerResponse> {
+    const products = await this.repository.getAll({ filters: { isFeatured: true } });
+    return { success: true, data: products };
+  }
+}
+```
+
+**IRequestContext:** `{ params, query, body, user, headers, context, metadata, server }` — `user` is `Record<string, unknown> | undefined` (guard with `if (req.user)` on public routes)
+
+**IControllerResponse:** `{ success, data?, error?, status?, meta?, headers? }`
+
+## Adapters (Database-Agnostic)
+
+```typescript
+// Mongoose
+import { createMongooseAdapter } from '@classytic/arc';
+const adapter = createMongooseAdapter({ model: ProductModel, repository: productRepo });
+
+// Custom adapter — implement CrudRepository interface:
+interface CrudRepository<TDoc> {
+  getAll(params?): Promise<TDoc[] | PaginatedResult<TDoc>>;
+  getById(id: string): Promise<TDoc | null>;
+  create(data): Promise<TDoc>;
+  update(id: string, data): Promise<TDoc | null>;
+  delete(id: string): Promise<boolean>;
+}
+```
+
+## Events
+
+The factory auto-registers `eventPlugin` — no manual setup needed:
+
+```typescript
+// createApp() registers eventPlugin automatically (default: MemoryEventTransport)
+const app = await createApp({
+  stores: { events: new RedisEventTransport(redis) },  // optional, defaults to memory
+  arcPlugins: {
+    events: {                     // event plugin config (default: true, false to disable)
+      logEvents: true,
+      retry: { maxRetries: 3, backoffMs: 1000 },
+    },
+  },
+});
+
+await app.events.publish('order.created', { orderId: '123' });
+await app.events.subscribe('order.*', async (event) => { ... });
+```
+
+CRUD events auto-emit: `{resource}.created`, `{resource}.updated`, `{resource}.deleted`.
+
+**Transports:** Memory (default) | Redis Pub/Sub (fire-and-forget) | Redis Streams (durable, at-least-once, consumer groups, DLQ)
+
+**Event Outbox** — at-least-once delivery via transactional outbox pattern. Arc ships `OutboxStore` interface + `MemoryOutboxStore` (dev). You implement the store for your DB (Mongoose, Drizzle, Knex, etc.). Cleanup via optional `purge()` contract or native DB tools (TTL index, pg_cron, key expiry).
+
+## Factory — createApp()
+
+```typescript
+const app = await createApp({
+  preset: 'production',            // production | development | testing | edge
+  runtime: 'memory',              // memory (default) | distributed
+  auth: { type: 'jwt', jwt: { secret } },
+  cors: { origin: ['https://myapp.com'] },
+  helmet: true,                    // false to disable
+  rateLimit: { max: 100 },         // false to disable
+  ajv: { keywords: ['x-internal'] }, // custom AJV keywords for schema validation
+  arcPlugins: {
+    events: true,                  // event plugin (default: true, false to disable)
+    emitEvents: true,              // CRUD event emission (default: true)
+    queryCache: true,              // server cache (default: false)
+    sse: true,                     // SSE streaming (default: false)
+    caching: true,                 // ETag + Cache-Control (default: false)
+  },
+  stores: {                        // required when runtime: 'distributed'
+    events: new RedisEventTransport({ client: redis }),
+    queryCache: new RedisCacheStore({ client: redis }),
+  },
+});
+```
+
+## Hooks
+
+```typescript
+import { createHookSystem, beforeCreate, afterUpdate } from '@classytic/arc/hooks';
+
+const hooks = createHookSystem();
+beforeCreate(hooks, 'product', async (ctx) => { ctx.data.slug = slugify(ctx.data.name); });
+afterUpdate(hooks, 'product', async (ctx) => { await invalidateCache(ctx.result._id); });
+```
+
+## Pipeline
+
+```typescript
+import { guard, transform, intercept } from '@classytic/arc';
+
+defineResource({
+  pipe: {
+    create: [
+      guard('verified', async (ctx) => ctx.user?.verified === true),
+      transform('inject', async (ctx) => { ctx.body.createdBy = ctx.user._id; }),
+    ],
+  },
+});
+```
+
+## Query Parsing
+
+Arc's default parser handles filters, sort, select, populate, and pagination. Swap in MongoKit's `QueryParser` for $lookup joins.
+
+```
+GET /products?page=2&limit=20&sort=-createdAt&select=name,price
+GET /products?price[gte]=100&status[in]=active,featured&search=keyword
+GET /products?after=<cursor_id>&limit=20                     # keyset pagination
+GET /products?populate=category                               # ref-based populate
+GET /products?populate[category][select]=name,slug            # populate with field select
+GET /products?populate[category][select]=-internal            # exclude fields
+GET /products?populate[category][match][isActive]=true        # populate with filter
+```
+
+**Lookup/join (no refs — $lookup via MongoKit QueryParser):**
+
+```
+GET /products?lookup[cat][from]=categories&lookup[cat][localField]=categorySlug&lookup[cat][foreignField]=slug&lookup[cat][single]=true
+GET /products?lookup[cat][from]=categories&...&lookup[cat][select]=name,slug
+```
+
+Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `like`, `regex`, `exists`
+
+**Custom query parser (e.g., MongoKit for $lookup support):**
+
+```typescript
+import { QueryParser } from '@classytic/mongokit';
+
+defineResource({
+  name: 'product',
+  adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
+  queryParser: new QueryParser(),  // enables lookup, advanced populate, keyset pagination
+  schemaOptions: {
+    query: {
+      allowedPopulate: ['category', 'brand'],     // whitelist populate paths
+      allowedLookups: ['categories', 'brands'],   // whitelist lookup collections
+    },
+  },
+});
+```
+
+## Error Classes
+
+```typescript
+import { ArcError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError } from '@classytic/arc';
+throw new NotFoundError('Product not found');  // 404
+```
+
+## Compensating Transaction
+
+In-process rollback for multi-step operations. Not a distributed saga — use Temporal/Streamline for that.
+
+```typescript
+import { withCompensation } from '@classytic/arc/utils';
+
+const result = await withCompensation('checkout', [
+  { name: 'reserve', execute: reserveStock, compensate: releaseStock },
+  { name: 'charge', execute: chargeCard, compensate: refundCard },
+  { name: 'notify', execute: sendEmail, fireAndForget: true },  // non-blocking
+], { orderId }, {
+  onStepComplete: (name, res) => fastify.events.publish(`checkout.${name}.done`, res),
+});
+// result: { success, completedSteps, results, failedStep?, error?, compensationErrors? }
+```
+
+## CLI
+
+```bash
+arc init my-api --mongokit --better-auth --ts
+arc generate resource product              # standard resource
+arc generate resource product --mcp        # resource + MCP tools file
+arc generate mcp analytics                 # standalone MCP tools file
+arc docs ./openapi.json --entry ./dist/index.js
+arc introspect --entry ./dist/index.js
+arc doctor
+```
+
+Set `"mcp": true` in `.arcrc` to always generate `.mcp.ts` files with resources.
+
+## MCP (AI Agent Tools)
+
+Expose Arc resources as MCP tools for AI agents. Stateless by default — fresh server per request, zero session overhead.
+
+See [mcp reference](references/mcp.md) for full details.
+
+```typescript
+import { mcpPlugin } from '@classytic/arc/mcp';
+
+// Stateless (default) — production-ready, scalable
+await app.register(mcpPlugin, {
+  resources: [productResource, orderResource],
+  auth: false,                              // or: getAuth() | custom function
+  exclude: ['credential'],
+  overrides: { product: { operations: ['list', 'get'] } },
+});
+
+// Stateful — when you need server-initiated messages
+await app.register(mcpPlugin, { resources, stateful: true, sessionTtlMs: 600000 });
+```
+
+Connect Claude CLI: `claude mcp add --transport http my-api http://localhost:3000/mcp`
+
+**Auth** — three modes, user chooses: `false` | `getAuth()` (Better Auth OAuth 2.1) | custom function:
+
+```typescript
+auth: async (headers) => {
+  if (headers['x-api-key'] !== process.env.MCP_KEY) return null;
+  return { userId: 'bot', organizationId: 'org-1', roles: ['admin'] };
+},
+```
+
+**Guards** for custom tools: `guard(requireAuth, requireOrg, requireRole('admin'), handler)`
+
+**Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.
+
+**Permission filters**: `PermissionResult.filters` from resource permissions flow into MCP tools — same as REST. Define once, works everywhere:
+
+```typescript
+permissions: {
+  list: (ctx) => ({
+    granted: !!ctx.user,
+    filters: { orgId: ctx.user?.orgId, branchId: ctx.user?.branchId },
+  }),
+}
+// MCP tools automatically scope queries by orgId + branchId
+```
+
+**Project structure** — custom MCP tools co-located with resources:
+
+```
+src/resources/order/
+  order.resource.ts
+  order.mcp.ts              ← defineTool('fulfill_order', { ... })
+```
+
+Generate: `arc generate resource order --mcp` | Wire: `extraTools: [fulfillOrderTool]`
+
+## Subpath Imports
+
+```typescript
+import { defineResource, BaseController, allowPublic } from '@classytic/arc';
+import { createApp } from '@classytic/arc/factory';
+import { MemoryCacheStore, RedisCacheStore, QueryCache } from '@classytic/arc/cache';
+import { createBetterAuthAdapter, extractBetterAuthOpenApi } from '@classytic/arc/auth';
+import type { ExternalOpenApiPaths } from '@classytic/arc/docs';
+import { eventPlugin } from '@classytic/arc/events';
+import { RedisEventTransport } from '@classytic/arc/events/redis';
+import { healthPlugin, gracefulShutdownPlugin } from '@classytic/arc/plugins';
+import { tracingPlugin } from '@classytic/arc/plugins/tracing';
+import { auditPlugin } from '@classytic/arc/audit';
+import { idempotencyPlugin } from '@classytic/arc/idempotency';
+import { ssePlugin } from '@classytic/arc/plugins';
+import { jobsPlugin } from '@classytic/arc/integrations/jobs';
+import { websocketPlugin } from '@classytic/arc/integrations/websocket';
+import { eventGatewayPlugin } from '@classytic/arc/integrations/event-gateway';
+import { createHookSystem } from '@classytic/arc/hooks';
+import { createTestApp } from '@classytic/arc/testing';
+import { Type, ArcListResponse } from '@classytic/arc/schemas';
+import { createStateMachine, CircuitBreaker, withCompensation, defineCompensation } from '@classytic/arc/utils';
+import { defineMigration } from '@classytic/arc/migrations';
+import { isMember, isElevated, getOrgId, getUserId, getUserRoles } from '@classytic/arc/scope';
+import { createTenantKeyGenerator } from '@classytic/arc/scope';
+import { createRoleHierarchy } from '@classytic/arc/permissions';
+import { createServiceClient } from '@classytic/arc/rpc';
+import { metricsPlugin, versioningPlugin } from '@classytic/arc/plugins';
+import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
+import { mcpPlugin, createMcpServer, defineTool, definePrompt, fieldRulesToZod, resourceToTools } from '@classytic/arc/mcp';
+import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
+import { bulkPreset } from '@classytic/arc/presets';
+```
+
+## References (Progressive Disclosure)
+
+- **[auth](references/auth.md)** — JWT, Better Auth, API key auth, custom auth, multi-tenant
+- **[events](references/events.md)** — Domain events, transports, retry, outbox pattern, auto-emission
+- **[integrations](references/integrations.md)** — BullMQ jobs, WebSocket, EventGateway, Streamline, Webhooks
+- **[mcp](references/mcp.md)** — MCP tools for AI agents, auto-generation from resources, custom tools, Better Auth OAuth 2.1
+- **[production](references/production.md)** — Health, audit, idempotency, tracing, metrics, versioning, SSE, QueryCache, bulk ops, saga, RPC schema versioning, tenant rate limiting
+- **[testing](references/testing.md)** — Test app, mocks, data factories, in-memory MongoDB