@classytic/arc 2.11.3 → 2.13.1

package/skills/arc/SKILL.md

@@ -8,11 +8,9 @@ description: |
   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.11.1
 license: MIT
 metadata:
   author: Classytic
-  version: "2.11.1"
 tags:
   - fastify
   - rest-api
@@ -27,48 +25,58 @@ tags:
   - openapi
 progressive_disclosure:
   entry_point:
-    summary: "Resource-oriented Fastify framework: defineResource(), presets, permissions, QueryCache, events, multi-tenant, OpenAPI"
+    summary: "Resource-oriented Fastify framework: defineResource(), presets, permissions, QueryCache, events, multi-tenant, OpenAPI, MCP"
     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
+    quick_start: "1. arc init my-api --mongokit --jwt --ts  2. defineResource({ name, adapter, presets, permissions })  3. createApp({ preset: 'production', resources, auth })"
 ---
 
 # @classytic/arc
 
-Resource-oriented backend framework for Fastify. Database-agnostic, tree-shakable, production-ready.
+Resource-oriented backend framework for Fastify. **Fastify ≥5.8.5 · Node ≥22 · ESM only.**
 
-**Requires:** Fastify `^5.7.4` | Node.js `>=22` | ESM only
+One `defineResource()` call → REST + auth + permissions + events + cache + OpenAPI + MCP. Database-agnostic (Mongoose, Drizzle/sqlitekit, Prisma, custom).
 
-## Install
+## Scaffold a project
 
 ```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
+npx @classytic/arc@latest init my-api --mongokit --jwt --ts
+cd my-api && npm install && npm run dev
 ```
 
-## Quick Start
+Flags: `--mongokit | --custom`, `--jwt | --better-auth`, `--single | --multi`, `--ts | --js`. The scaffold seeds full `dependencies` + `devDependencies` so `npm install` works without the CLI's pre-pass.
+
+## createApp()
 
 ```typescript
 import { createApp } from '@classytic/arc/factory';
-import mongoose from 'mongoose';
-
-await mongoose.connect(process.env.DB_URI);
 
 const app = await createApp({
-  preset: 'production',
+  preset: 'production',                  // production | development | testing | edge
+  runtime: 'memory',                     // memory (default) | distributed
   auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
-  cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') },
-  resources: [productResource, orderResource],   // canonical path — factory registers in the right lifecycle slot
+  cors: { origin: ['https://myapp.com'] },
+  helmet: true,                          // false to disable
+  rateLimit: { max: 100 },               // false to disable
+  ajv: { keywords: ['x-internal'] },
+  resources: [productResource, orderResource],   // canonical: factory wires them in the right slot
+  arcPlugins: {
+    events: true,                        // default true — disables CRUD event emission if false
+    queryCache: true,                    // default false
+    sse: true,                           // default false
+    caching: true,                       // ETag + Cache-Control
+  },
+  stores: {                              // required when runtime: 'distributed'
+    events: new RedisEventTransport({ client: redis }),
+    queryCache: new RedisCacheStore({ client: redis }),
+  },
 });
 
 await app.listen({ port: 8040, host: '0.0.0.0' });
 ```
 
-For async-booted engines (repository wired in `bootstrap[]`), use the factory form:
+**Boot sequence:** `plugins` → `bootstrap[]` → `resources` (factory form runs here) → `afterResources` → `onReady`.
+
+**Async-booted engines** — use the factory form for `resources` so it runs after `bootstrap[]`:
 
 ```typescript
 resources: async (fastify) => {
@@ -77,32 +85,35 @@ resources: async (fastify) => {
 }
 ```
 
-Advanced escape hatch: `await app.register(productResource.toPlugin())` registers a single resource directly. Use only when you need manual control over the scope/prefix — the `resources` factory option is preferred.
+**Auto-discover resources:**
 
-## Security defaults (active in 2.11)
+```typescript
+import { loadResources } from '@classytic/arc/factory';
 
-- **Field-write perms: `reject`** — requests carrying non-writable fields get 403 with denied-field list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
-- **multiTenant injects org on UPDATE** — body-supplied `organizationId` overwritten with caller's scope. Closes tenant-hop vector.
-- **Elevation emits `arc.scope.elevated`** — audit via `fastify.events.subscribe(...)`.
-- **`verifySignature(body, ...)`** throws on parsed body — pass `req.rawBody`.
-- **Upload `sanitizeFilename`** strict by default. Pass `false` / `'*'` / custom fn to relax.
-- **Idempotency `namespace`** option for shared-store prod+canary deployments.
-- **`systemManaged` fields auto-strip from `required[]`** — framework-injected fields (tenant, audit) removed from create/update `required[]` so Fastify preValidation doesn't reject before arc's injection runs.
+resources: await loadResources(import.meta.url),                          // discovers *.resource.ts
+resources: await loadResources(import.meta.url, { context: { engine } }), // threads ctx into (ctx) => defineResource(...)
+```
 
-For removed APIs and version-by-version breaking changes, see [CHANGELOG.md](../../CHANGELOG.md). For the full tenant-pipeline walkthrough, see [docs/production-ops/tenant-pipeline.mdx](../../docs/production-ops/tenant-pipeline.mdx).
+Pass `import.meta.url` for dev/prod parity (resolves `src/` in dev, `dist/` in prod). Discovers `default` export, `export const resource`, OR any named export with `.toPlugin()`. Works with relative imports + Node `#` subpath imports — **NOT** tsconfig path aliases (`@/*` are compile-time only).
 
 ## defineResource()
 
-Single API to define a full REST resource:
-
 ```typescript
-import { defineResource, createMongooseAdapter, allowPublic, requireRoles } from '@classytic/arc';
+import { defineResource, allowPublic, requireRoles } from '@classytic/arc';
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';
+import { buildCrudSchemasFromModel } from '@classytic/mongokit';
 
 const productResource = defineResource({
   name: 'product',
-  adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
-  controller: productController,  // optional — auto-created if omitted
+  adapter: createMongooseAdapter({
+    model: ProductModel,
+    repository: productRepo,
+    schemaGenerator: buildCrudSchemasFromModel,   // required (no built-in fallback)
+  }),
+  controller: productController,        // optional — auto-built if omitted
+
   presets: ['softDelete', 'slugLookup', { name: 'multiTenant', tenantField: 'orgId' }],
+
   permissions: {
     list: allowPublic(),
     get: allowPublic(),
@@ -110,31 +121,27 @@ const productResource = defineResource({
     update: requireRoles(['admin']),
     delete: requireRoles(['admin']),
   },
+
   cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
 
-  // routeGuards — auto-apply to ALL routes (CRUD + custom + preset)
-  routeGuards: [modeGuard, orgGuard.preHandler],
+  routeGuards: [orgGuard.preHandler],   // applied to ALL routes (CRUD + custom + preset)
 
-  // fieldRules — portable constraints + framework-injection hints
   schemaOptions: {
     fieldRules: {
-      name: { minLength: 2, maxLength: 200, description: 'Product name' },
-      price: { min: 0, max: 100000 },
+      name: { minLength: 2, maxLength: 200 },
       sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
       status: { enum: ['draft', 'active', 'archived'] },
-      deletedAt: { systemManaged: true },                 // arc stamps it — strip from body + required[]
-      priceMode: { nullable: true },                      // Zod .nullable() lost through Mongoose — widen to accept null
+      deletedAt: { systemManaged: true },     // arc stamps it; strip from body + required[]
+      priceMode: { nullable: true },          // widen JSON-Schema type to accept null
     },
   },
 
-  // Custom routes (compose with presets — softDelete adds /deleted, /:id/restore)
   routes: [
-    { method: 'GET', path: '/stats', handler: 'getStats', permissions: requireAuth() },
+    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic() },
     { method: 'POST', path: '/webhook', handler: webhookFn, raw: true, permissions: requireAuth() },
   ],
 
-  // Actions — single POST /:id/action endpoint, discriminated on `action` body field
-  actions: {
+  actions: {                            // single POST /:id/action endpoint, discriminated on `action`
     approve: async (id, data, req) => service.approve(id, req.user._id),
     cancel: {
       handler: async (id, data, req) => service.cancel(id, data.reason, req.user._id),
@@ -142,309 +149,145 @@ const productResource = defineResource({
       schema: { reason: { type: 'string' } },
     },
   },
-  actionPermissions: requireAuth(),
-});
-
-// Register via createApp — canonical path:
-//   createApp({ resources: [productResource] })
-// Auto-generates: GET /, GET /:id, POST /, PATCH /:id, DELETE /:id
-// + softDelete preset adds: GET /deleted, POST /:id/restore
-```
-
-## routeGuards + defineGuard
-
-Resource-level guards that apply to **every** route (CRUD + custom + preset):
-
-```typescript
-import { defineGuard } from '@classytic/arc/utils';
-import type { RouteHandlerMethod } from '@classytic/arc';
-
-// Simple guard — reject if condition fails
-const modeGuard: RouteHandlerMethod = async (req, reply) => {
-  if (!req.headers['x-mode']) {
-    reply.code(403).send({ error: 'Mode header required' });
-  }
-};
-
-// Typed guard — resolve context once, extract anywhere
-const orgGuard = defineGuard({
-  name: 'org',
-  resolve: (req) => {
-    const orgId = req.headers['x-org-id'] as string;
-    if (!orgId) throw new Error('Missing x-org-id');
-    return { orgId, actorId: req.user?.id ?? 'system' };
-  },
-});
-
-defineResource({
-  name: 'procurement',
-  routeGuards: [modeGuard, orgGuard.preHandler],  // all routes protected
-  routes: [{
-    method: 'GET', path: '/summary', raw: true, permissions: requireAuth(),
-    handler: async (req, reply) => {
-      const { orgId } = orgGuard.from(req);  // typed, no re-computation
-      reply.send({ orgId, count: await Model.countDocuments() });
-    },
-  }],
-  // ...
+  actionPermissions: requireAuth(),     // fallback gate for actions without per-action perm
 });
 ```
 
-**Execution order:** auth → permissions → cache/idempotency → `routeGuards` → per-route `preHandler`
-
-## fieldRules → OpenAPI + AJV
-
-One definition, two outputs — constraints auto-map to OpenAPI schema + Fastify AJV validation. Extends repo-core's `FieldRule` floor with arc extensions.
-
-```typescript
-schemaOptions: {
-  fieldRules: {
-    name: { minLength: 2, maxLength: 200, description: 'Product name' },
-    price: { min: 0, max: 100000 },
-    sku: { pattern: '^[A-Z]{3}-\\d{3}$' },
-    status: { enum: ['draft', 'active', 'archived'] },
-    password: { hidden: true },                   // blocked from select + OpenAPI
-    deletedAt: { systemManaged: true },           // blocked from input schemas; framework stamps it
-    slug: { immutable: true },                    // excluded from update body
-    priceMode: { nullable: true },                // widen JSON-Schema type to include null
-    organizationId: { systemManaged: true, preserveForElevated: true }, // tenant field (auto-injected)
-  },
-},
-```
-
-| Flag | Effect |
-|---|---|
-| `systemManaged` | Strip from body on ingest, drop from `required[]`. Framework stamps the value (tenant, audit, engine-derived slug). |
-| `preserveForElevated` | Elevated admins keep the field on ingest (platform-level cross-tenant writes). |
-| `immutable` / `immutableAfterCreate` | Omit from update body. Inheritance: repo-core floor. |
-| `optional` | Strip from `required[]` without touching `properties`. |
-| `nullable` | Widen JSON-Schema `type` to include null (+ appends `null` to `enum` if present). |
-| `hidden` | Block from response projection + OpenAPI. |
-| `minLength` / `maxLength` / `min` / `max` / `pattern` / `enum` | Map to AJV validators + OpenAPI constraints. |
-| `description` | Maps to OpenAPI `description`. |
+**Generated routes:** `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Presets add `/deleted` + `/:id/restore` (softDelete), `/slug/:slug` (slugLookup), etc.
 
-Mongoose model-level constraints (`minlength`, `maxlength`, `min`, `max`, `enum`) take precedence. `fieldRules` supplements what the model doesn't declare. Kit schema generators see only the repo-core floor; arc's extensions apply post-kit via `mergeFieldRuleConstraints`.
+## Active behavior to know about
 
-See [docs/framework-extension/custom-adapters.mdx — Field Rules](../../docs/framework-extension/custom-adapters.mdx#field-rules--shaping-kit-generated-schemas) for the `systemManaged` decision table.
+- **Field-write reject (default).** Requests carrying non-writable fields → 403 with denied list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
+- **multiTenant injects org on UPDATE.** Body `organizationId` is overwritten with caller's scope (closes tenant-hop).
+- **MCP tools fail-closed.** A resource action without per-action perm + no `actionPermissions` + no `permissions.update` fallback → throws at tool generation. Declare `allowPublic()` to opt into unauthenticated.
+- **`systemManaged` fields** auto-strip from `required[]` so AJV doesn't reject before arc's framework injection runs.
+- **`request.user`** is `Record<string, unknown> | undefined` — guard with `if (req.user)` on public routes.
+- **Arc's permission engine reads singular `user.role`** (string, comma-separated, or array). Don't use plural `roles` on the model.
+- **`verifySignature(body, ...)`** throws on parsed body — pass `req.rawBody`.
+- **Upload `sanitizeFilename`** strict by default; pass `false` / `'*'` / fn to relax.
 
 ## Authentication
 
-Auth uses a **discriminated union** with `type` field:
+Discriminated union on `type`:
 
 ```typescript
-// Arc JWT (with optional token extraction and revocation)
+// Arc JWT (with optional revocation + custom token extractor)
 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
+  tokenExtractor: (req) => req.cookies?.['auth-token'] ?? null,
+  isRevoked: async (decoded) => redis.sismember('revoked', decoded.jti),
 }
 
 // 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)
+// Custom Fastify plugin / function
 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`
-
-### Better Auth + Mongoose populate bridge (`@classytic/arc/auth/mongoose`)
+Decorates `app.authenticate`, `app.optionalAuthenticate`, `app.authorize`.
 
-When BA uses `@better-auth/mongo-adapter`, it writes via the native `mongodb` driver and never registers Mongoose models. arc resources doing `Schema({ userId: { ref: 'user' } })` then throw `MissingSchemaError` on `.populate()`.
+**Better Auth — arc is plugin-agnostic.** `auth.$context.tables` introspection lets the kit overlays read whatever plugins you've enabled — no per-plugin code in arc/mongokit/sqlitekit. Tested combinations: `organization`, `twoFactor`, `admin`, `bearer` (built-in), plus `apiKey` from the **separate** `@better-auth/api-key` package.
 
 ```typescript
-import mongoose from 'mongoose';
-import { registerBetterAuthMongooseModels } from '@classytic/arc/auth/mongoose';
-
-// Default: core only (user/session/account/verification). Plugins are opt-in.
-registerBetterAuthMongooseModels(mongoose, {
-  plugins: ['organization', 'organization-teams', 'mcp'],
-  // For separate @better-auth/* packages (passkey, sso, api-key):
-  extraCollections: ['passkey', 'ssoProvider'],
-  // Optional:
-  usePlural: false,                                     // matches mongodbAdapter({ usePlural })
-  modelOverrides: { user: 'profile' },                  // for custom user.modelName configs
+import { betterAuth } from 'better-auth';
+import { mongodbAdapter } from '@better-auth/mongo-adapter';
+import { organization, twoFactor, admin, bearer } from 'better-auth/plugins';
+import { apiKey } from '@better-auth/api-key';                        // ← separate npm package
+import { createBetterAuthOverlay, registerBetterAuthStubs } from '@classytic/mongokit/better-auth';
+
+const auth = betterAuth({
+  database: mongodbAdapter(mongoose.connection.getClient().db()),
+  emailAndPassword: { enabled: true },
+  plugins: [organization(), twoFactor(), admin(), bearer(), apiKey({ enableSessionForAPIKeys: true })],
 });
+
+// Bulk-register populate() stubs. extraCollections covers tables not in the plugin map (apikey, passkey, …).
+registerBetterAuthStubs(mongoose, { plugins: ['organization'], extraCollections: ['apikey'] });
+
+// Per-resource overlay — DataAdapter ready for defineResource. Async (reads BA's resolved schema once at boot).
+const orgAdapter    = await createBetterAuthOverlay({ auth, mongoose, collection: 'organization' });
+const apiKeyAdapter = await createBetterAuthOverlay({ auth, mongoose, collection: 'apikey' });
+
+// Sqlitekit is symmetric: { auth, db, collection } + additionalColumns instead of additionalFields.
 ```
 
-**Plugin keys** (core BA only — separate packages use `extraCollections`):
-- `organization` → `organization`, `member`, `invitation`
-- `organization-teams` → `team`, `teamMember`
-- `twoFactor` → `twoFactor`
-- `jwt` → `jwks`
-- `oidcProvider` / `oauthProvider` (alias) → `oauthApplication`, `oauthAccessToken`, `oauthConsent`
-- `mcp` → reuses oidcProvider schema (per BA docs)
-- `deviceAuthorization` → `deviceCode`
+**Multi-role members**: BA stores `member.role = "admin,recruiter,viewer"` (comma-separated string). Arc splits it into `scope.orgRoles = ['admin', 'recruiter', 'viewer']`; `requireOrgRole('admin')` matches. Filtering by exact `?role=admin` will NOT match — use `role[like]=admin`.
+
+**API key flow**: client sends `x-api-key: ak_live_...` + `x-organization-id: org_abc` (header required because API-key sessions have no `activeOrganizationId`). Arc adds `apiKeyAuth` to OpenAPI security only when the plugin is active.
 
-**Field-only plugins** (admin, username, phoneNumber, magicLink, emailOtp, anonymous, bearer, multiSession, siwe, lastLoginMethod, genericOAuth) need NO entry — `strict: false` stubs round-trip extra fields automatically.
+**Bearer plugin** (`bearer()` from `better-auth/plugins`): SPA / mobile clients use `Authorization: Bearer <session>` instead of cookies — same `auth.api.getSession()` path, no arc config change. Enable both for hybrid apps.
 
-Lives at a dedicated subpath so non-Mongoose users (Prisma/Drizzle/Kysely) never get Mongoose pulled into their bundle. Idempotent + de-dupes overlapping plugin sets, so `plugins: ['mcp', 'oidcProvider']` won't crash.
+Full overlay recipes (Tier 1 hand-roll vs Tier 2 factory), plugin matrix, `registerBetterAuthStubs` options, multi-plugin merge, write path, and CLI scaffolding flags → [references/auth.md](references/auth.md). Live end-to-end smoke: [`playground/better-auth/mongo/`](../../playground/better-auth/mongo/) · [`playground/better-auth/sqlite/`](../../playground/better-auth/sqlite/).
 
 ## Permissions
 
-Function-based. A `PermissionCheck` returns `boolean | { granted, reason?, filters?, scope? }`:
+A `PermissionCheck` returns `boolean | { granted, reason?, filters?, scope? }`. `filters` propagate into the repo query (row-level ABAC). `scope` stamps attributes downstream.
 
 ```typescript
 import {
-  // Core
   allowPublic, requireAuth, requireRoles, requireOwnership,
-  // Org-bound
   requireOrgMembership, requireOrgRole, requireTeamMembership,
-  // Service / API key (OAuth-style)
-  requireServiceScope,
-  // App-defined scope dimensions (branch, project, region, …)
-  requireScopeContext,
-  // Parent-child org hierarchy
-  requireOrgInScope,
-  // Combinators
+  requireServiceScope,           // OAuth-style API-key scopes
+  requireScopeContext,           // app-defined dimensions (branch, project, region)
+  requireOrgInScope,             // parent-child org hierarchy
   allOf, anyOf, when, denyAll,
-  // Dynamic ACL
-  createDynamicPermissionMatrix,
+  createDynamicPermissionMatrix, // DB-managed ACL
 } from '@classytic/arc';
 
 permissions: {
   list: allowPublic(),
-  get: requireAuth(),
   create: requireRoles(['admin', 'editor']),
   update: anyOf(requireOwnership('userId'), requireRoles(['admin'])),
   delete: allOf(requireAuth(), requireRoles(['admin'])),
+
+  // Mixed human + machine
+  bulkImport: anyOf(requireOrgRole('admin'), requireServiceScope('jobs:bulk-write')),
 }
 ```
 
-**Mixed human + machine routes** — accept both an org admin and an API key:
+**Custom check:**
 
 ```typescript
-import { requireServiceScope } from '@classytic/arc';
-
-permissions: {
-  // Human admins OR API keys with the right OAuth scope
-  create: anyOf(
-    requireOrgRole('admin'),
-    requireServiceScope('jobs:write'),
-  ),
-
-  // Org-bound API key with a specific scope (no human path)
-  bulkImport: allOf(
-    requireOrgMembership(),                  // accepts member, service, elevated
-    requireServiceScope('jobs:bulk-write'),  // OAuth-style scope check
-  ),
-}
+const requirePro = (): PermissionCheck => async (ctx) => {
+  if (!ctx.user) return { granted: false, reason: 'Auth required' };
+  return { granted: ctx.user.plan === 'pro' };
+};
 ```
 
-**Multi-level tenancy** — for app-defined scope dimensions beyond org/team
-(branch, project, region, workspace, department, …):
+**Field-level:**
 
 ```typescript
-import { requireScopeContext } from '@classytic/arc';
-import { multiTenantPreset } from '@classytic/arc/presets';
-
-// 1. Populate scope.context in your auth function (from headers, JWT claims,
-//    BA session fields — arc takes no position on the source).
-authFn: async (request) => {
-  const session = await myAuth.getSession(request);
-  request.scope = {
-    kind: 'member',
-    userId: session.userId,
-    userRoles: session.userRoles,
-    organizationId: session.orgId,
-    orgRoles: session.orgRoles,
-    context: {
-      branchId: request.headers['x-branch-id'],
-      projectId: request.headers['x-project-id'],
-    },
-  };
-}
-
-// 2. Gate routes by context dimensions
-permissions: {
-  branchAdmin: allOf(requireOrgRole('admin'), requireScopeContext('branchId')),
-  euOnly:      requireScopeContext('region', 'eu'),
-  projectEdit: requireScopeContext({ projectId: undefined, region: 'eu' }),
+import { fields } from '@classytic/arc';
+fields: {
+  password: fields.hidden(),
+  salary: fields.visibleTo(['admin', 'hr']),
+  role: fields.writableBy(['admin']),
+  email: fields.redactFor(['viewer'], '***'),
 }
-
-// 3. Auto-filter resource queries across all dimensions in lockstep
-defineResource({
-  name: 'job',
-  presets: [
-    multiTenantPreset({
-      tenantFields: [
-        { field: 'organizationId', type: 'org' },
-        { field: 'branchId',       contextKey: 'branchId' },
-        { field: 'projectId',      contextKey: 'projectId' },
-      ],
-    }),
-  ],
-});
 ```
 
-Fail-closed: missing dimensions → 403 with the specific missing field name.
-Elevated scopes (platform admins) apply whatever resolves and skip the rest
-(cross-context bypass).
-
-**Parent-child org hierarchy** — for holding companies, MSPs managing
-multiple tenants, white-label parent → child accounts. Arc takes no position
-on the source: your auth function loads the chain from your own org table.
+**Dynamic ACL (DB-backed):**
 
 ```typescript
-import { requireOrgInScope } from '@classytic/arc';
-
-// 1. Auth function loads ancestorOrgIds from your org table.
-//    Order is closest-first (immediate parent → root).
-authFn: async (request) => {
-  const session = await myAuth.getSession(request);
-  const ancestors = await orgRepo.findAncestors(session.orgId);
-  request.scope = {
-    kind: 'member',
-    userId: session.userId,
-    userRoles: session.userRoles,
-    organizationId: session.orgId,
-    orgRoles: session.orgRoles,
-    ancestorOrgIds: ancestors.map(a => a.id),  // ['acme-eu', 'acme-holding']
-  };
-}
-
-// 2. Gate routes — accepts current org or any ancestor in the chain
-permissions: {
-  // GET /orgs/:orgId/jobs — caller can act on any org in their hierarchy
-  list: requireOrgInScope((ctx) => ctx.request.params.orgId),
-
-  // Static target (rare): one route, one specific org
-  holdingDashboard: requireOrgInScope('acme-holding'),
-
-  // Composed: must be admin AND target must be in hierarchy
-  childAdmin: allOf(
-    requireOrgRole('admin'),
-    requireOrgInScope((ctx) => ctx.request.params.orgId),
-  ),
-}
+const acl = createDynamicPermissionMatrix({
+  resolveRolePermissions: async (ctx) => aclService.getRoleMatrix(ctx.user.orgId),
+  cacheStore: new RedisCacheStore({ client: redis, prefix: 'acl:' }),
+});
+permissions: { list: acl.canAction('product', 'read') }
 ```
 
-**No automatic inheritance** — every check is explicit. `multiTenantPreset`
-does NOT auto-include ancestor data (would be a footgun). Sibling
-subsidiaries naturally don't see each other's data because they aren't in
-each other's chain. Elevated bypass still applies on the permission helper.
+`requireRoles()` checks BOTH platform roles (`user.role`) and org roles (`scope.orgRoles`). `requireOrgRole()` is human-only — use `anyOf(requireOrgRole(...), requireServiceScope(...))` for mixed routes.
 
-**Auth source agnostic** — `requireRoles()` checks platform roles
-(`user.role`) AND org roles (`scope.orgRoles`) by default, so it works
-identically with arc JWT, Better Auth user roles, and Better Auth org plugin.
-`requireOrgMembership()` accepts `member`, `service` (API key), and
-`elevated` scopes. `requireOrgRole()` is human-only by design — use
-`anyOf(requireOrgRole(...), requireServiceScope(...))` for mixed routes.
-`scope.context` and `scope.ancestorOrgIds` are populated by your own auth
-function or adapter — arc doesn't bake in any specific dimension or transport.
+### RequestScope — the auth context
 
-### RequestScope (quick reference)
-
-Five kinds, all opt-in. Always read via accessors from `@classytic/arc/scope`,
-never via direct property access.
+Five kinds, populated by your auth function. **Always read via accessors from `@classytic/arc/scope`, never direct property access.**
 
 ```typescript
 type RequestScope =
@@ -455,192 +298,171 @@ type RequestScope =
   | { kind: 'elevated'; userId?; organizationId?; elevatedBy; context?; ancestorOrgIds? };
 ```
 
-| Kind | Identity | Org context | Set by |
-|---|---|---|---|
-| `public` | none | none | Default for anonymous requests |
-| `authenticated` | userId, userRoles | none | Logged in, no active org |
-| `member` | userId, userRoles | organizationId + orgRoles (+ teamId, context, ancestorOrgIds) | BA org plugin / JWT custom auth |
-| `service` | clientId, scopes | organizationId (required) | API key via `PermissionResult.scope` |
-| `elevated` | userId | organizationId optional | Elevation plugin via `x-arc-scope: platform` header |
-
 | Helper | `member` | `service` | `elevated` |
 |---|---|---|---|
 | `requireOrgMembership()` | ✅ | ✅ | ✅ |
-| `requireOrgRole(roles)` | If role matches | ❌ deny w/ guidance | ✅ bypass |
-| `requireServiceScope(scopes)` | ❌ | If scope matches | ✅ bypass |
-| `requireScopeContext(...)` | If keys match | If keys match | ✅ bypass |
-| `requireTeamMembership()` | If `teamId` set | (n/a) | ✅ bypass |
-| `requireOrgInScope(target)` | If target in chain | If target in chain | ✅ bypass |
+| `requireOrgRole(roles)` | role match | ❌ deny | ✅ bypass |
+| `requireServiceScope(scopes)` | ❌ | scope match | ✅ bypass |
+| `requireScopeContext(...)` | key match | key match | ✅ bypass |
+| `requireTeamMembership()` | `teamId` set | n/a | ✅ bypass |
+| `requireOrgInScope(target)` | target in chain | target in chain | ✅ bypass |
 
 ```typescript
 import {
   isMember, isService, isElevated, hasOrgAccess,
-  getOrgId, getUserId, getOrgRoles, getServiceScopes,
+  getOrgId, getUserId, getUserRoles, getOrgRoles, getServiceScopes,
   getScopeContext, getAncestorOrgIds, isOrgInScope,
 } from '@classytic/arc/scope';
 
-if (hasOrgAccess(scope))   // member | service | elevated
-if (isService(scope))      // narrows to API key
-const orgId  = getOrgId(scope);                    // member | service | elevated
-const branch = getScopeContext(scope, 'branchId'); // custom dimension
-isOrgInScope(scope, 'acme-holding');               // pure predicate (no elevated bypass)
+if (hasOrgAccess(scope))                               // member | service | elevated
+const branch = getScopeContext(scope, 'branchId');
+isOrgInScope(scope, 'acme-holding');                   // pure predicate (no elevated bypass)
 ```
 
-**Custom permission:**
-
-```typescript
-const requirePro = (): PermissionCheck => async (ctx) => {
-  if (!ctx.user) return { granted: false, reason: 'Auth required' };
-  return { granted: ctx.user.plan === 'pro' };
-};
-```
+### Multi-level tenancy + parent-child org hierarchy
 
-**Field-level permissions:**
+Populate `scope.context` and `scope.ancestorOrgIds` in your auth function (arc takes no position on the source — load from headers / JWT / BA session / your org table):
 
 ```typescript
-import { fields } from '@classytic/arc';
-
-fields: {
-  password: fields.hidden(),
-  salary: fields.visibleTo(['admin', 'hr']),
-  role: fields.writableBy(['admin']),
-  email: fields.redactFor(['viewer'], '***'),
+authFn: async (request) => {
+  const session = await myAuth.getSession(request);
+  const ancestors = await orgRepo.findAncestors(session.orgId);   // closest-first
+  request.scope = {
+    kind: 'member',
+    userId: session.userId,
+    userRoles: session.userRoles,
+    organizationId: session.orgId,
+    orgRoles: session.orgRoles,
+    context: { branchId: request.headers['x-branch-id'], projectId: request.headers['x-project-id'] },
+    ancestorOrgIds: ancestors.map(a => a.id),   // ['acme-eu', 'acme-holding']
+  };
 }
-```
 
-**Dynamic ACL (DB-managed):**
+// Gate routes by context dimensions / org hierarchy
+permissions: {
+  branchAdmin: allOf(requireOrgRole('admin'), requireScopeContext('branchId')),
+  euOnly: requireScopeContext('region', 'eu'),
+  list: requireOrgInScope((ctx) => ctx.request.params.orgId),
+}
 
-```typescript
-const acl = createDynamicPermissionMatrix({
-  resolveRolePermissions: async (ctx) => aclService.getRoleMatrix(orgId),
-  cacheStore: new RedisCacheStore({ client: redis, prefix: 'acl:' }),
+// Auto-filter resource queries across all dimensions
+defineResource({
+  name: 'job',
+  presets: [multiTenantPreset({
+    tenantFields: [
+      { field: 'organizationId', type: 'org' },
+      { field: 'branchId', contextKey: 'branchId' },
+      { field: 'projectId', contextKey: 'projectId' },
+    ],
+  })],
 });
-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 }` OR `{ tenantFields: TenantFieldSpec[] }` (2.7.1+) |
-| `audited` | none (middleware) | — | — |
-| `bulk` | POST/PATCH/DELETE /bulk | — | `{ operations?, maxCreateItems? }` |
-| `filesUpload` | POST /upload, GET /:id, DELETE /:id | — (uses `Storage` adapter) | `{ storage, sanitizeFilename?, allowedMimeTypes?, maxFileSize? }` |
-| `search` | POST /search, /search-similar, /embed (opt-in) | — | `{ repository?, search?, similar?, embed?, routes? }` |
+Fail-closed: missing dimensions → 403 with the specific missing field name. **No automatic ancestor inheritance** — sibling subsidiaries don't see each other's data naturally.
 
-```typescript
-// Single-field (default, backwards compatible)
-presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
+Full multi-tenancy guide → [references/multi-tenancy.md](references/multi-tenancy.md).
 
-// Multi-field — org + branch + project in lockstep (2.7.1+)
-presets: [
-  multiTenantPreset({
-    tenantFields: [
-      { field: 'organizationId', type: 'org' },                // → getOrgId(scope)
-      { field: 'teamId',         type: 'team' },               // → getTeamId(scope)
-      { field: 'branchId',       contextKey: 'branchId' },     // → scope.context.branchId
-      { field: 'projectId',      contextKey: 'projectId' },
-    ],
-  }),
-]
+## fieldRules — OpenAPI + AJV in one place
 
-// Bulk: presets: ['bulk'] or bulkPreset({ operations: ['createMany', 'updateMany'] })
-```
+| Flag | Effect |
+|---|---|
+| `systemManaged` | Strip from body, drop from `required[]`. Framework stamps the value. |
+| `preserveForElevated` | Elevated admins keep the field on ingest (cross-tenant writes). |
+| `immutable` / `immutableAfterCreate` | Omit from update body. |
+| `optional` | Strip from `required[]` without touching `properties`. |
+| `nullable` | Widen JSON-Schema `type` to include null. |
+| `hidden` | Block from response projection + OpenAPI. |
+| `minLength` / `maxLength` / `min` / `max` / `pattern` / `enum` | Map to AJV + OpenAPI. |
+| `description` | OpenAPI `description`. |
 
-`multiTenant` recognizes `member`, `service` (API key), and `elevated`
-scopes uniformly via `hasOrgAccess()`. Multi-field uses fail-closed
-semantics: missing dimensions → 403 with the specific missing field name.
-Elevated scopes apply whatever resolves and skip the rest.
+Mongoose model-level constraints take precedence; `fieldRules` supplements what the model doesn't declare.
 
-### tenantField — When to Use and When to Disable
+## routeGuards + defineGuard
 
-Arc defaults `tenantField` to `'organizationId'` on BaseController. This silently adds `{ organizationId: scope.organizationId }` to every query when the user has an org context. Correct for per-org resources, wrong for company-wide resources.
+Apply guards to **every** route on a resource:
 
 ```typescript
-// Per-org resource (default) — each org sees only its own data
-defineResource({ name: 'invoice', ... });
-// → queries auto-scoped: { organizationId: 'org-123' }
+import { defineGuard } from '@classytic/arc/utils';
 
-// Company-wide resource — ALL orgs share the same data
-defineResource({ name: 'account-type', tenantField: false, ... });
-// → no org filter applied, all users see all records
+// Typed guard — resolve once, extract anywhere
+const orgGuard = defineGuard({
+  name: 'org',
+  resolve: (req) => {
+    const orgId = req.headers['x-org-id'] as string;
+    if (!orgId) throw new Error('Missing x-org-id');
+    return { orgId, actorId: req.user?.id ?? 'system' };
+  },
+});
 
-// Custom tenant field — your schema uses a different name
-defineResource({ name: 'workspace-item', tenantField: 'workspaceId', ... });
-// → queries scoped by workspaceId instead of organizationId
+defineResource({
+  name: 'procurement',
+  routeGuards: [orgGuard.preHandler],
+  routes: [{
+    method: 'GET', path: '/summary', raw: true, permissions: requireAuth(),
+    handler: async (req, reply) => {
+      const { orgId } = orgGuard.from(req);     // typed, no re-computation
+      reply.send({ orgId });
+    },
+  }],
+});
 ```
 
-When to use `tenantField: false`:
-- Lookup tables (account types, categories, currencies)
-- Platform-wide settings or config
-- Cross-org reports or analytics
-- Single-tenant apps where org scoping isn't needed
+**Order:** auth → permissions → cache/idempotency → `routeGuards` → per-route `preHandler`.
 
-### idField — Custom Primary Key
+## Presets
 
-Default is `'_id'`. Override for resources keyed by a business identifier (UUID, slug, `ORD-2026-0001`, `job-5219f346-a4d`, etc.).
+| Preset | Routes added | Config |
+|---|---|---|
+| `softDelete` | `GET /deleted`, `POST /:id/restore` | `{ deletedField }` |
+| `slugLookup` | `GET /slug/:slug` | `{ slugField }` |
+| `tree` | `GET /tree`, `GET /:parent/children` | `{ parentField }` |
+| `ownedByUser` | none (middleware) | `{ ownerField }` |
+| `multiTenant` | none (middleware) | `{ tenantField }` OR `{ tenantFields: TenantFieldSpec[] }` |
+| `audited` | none (middleware) | — |
+| `bulk` | `POST/PATCH/DELETE /bulk` | `{ operations?, maxCreateItems? }` |
+| `filesUpload` | `POST /upload`, `GET /:id`, `DELETE /:id` | `{ storage, sanitizeFilename?, allowedMimeTypes?, maxFileSize? }` |
+| `search` | `POST /search`, `/search-similar`, `/embed` | `{ repository?, search?, similar?, embed?, routes? }` |
 
 ```typescript
-defineResource({
-  name: 'job',
-  adapter: createMongooseAdapter(JobModel, jobRepository),
-  idField: 'jobId',     // ← one line (or omit and auto-derive from repository.idField — see below)
-});
-
-// GET /jobs/job-5219f346-a4d  → controller runs { jobId: 'job-5219f346-a4d' }
-// GET /jobs/<uuid>             → accepted (no ObjectId pattern enforcement)
+presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
 ```
 
-Changes all three layers:
-- **Fastify AJV** — strips any ObjectId pattern from `params.id` so custom formats aren't pre-rejected
-- **BaseController** — `get`/`update`/`delete` query by `{ [idField]: id }` (merged with tenant + policy filters)
-- **OpenAPI docs** — `spec.paths['/jobs/{id}']` emits a plain string `id` with description
-- **MCP tools** — auto-generated CRUD tools use `idField` transparently
-
-**Auto-derive from repository** (2.7.x+). If you don't set `idField` on `defineResource` but your `adapter.repository` exposes one (e.g. `new Repository(Model, [], {}, { idField: 'slug' })`), Arc picks it up automatically. Configure in one place, not two.
+### tenantField — when to use, when to disable
 
-**URL path segment is ALWAYS `:id` and `req.params.id` is ALWAYS named `id`** — regardless of what `idField` is set to. `idField` controls the *lookup field*, not the *URL parameter name*. This is the same convention Stripe / GitHub / most REST APIs use:
+Default `'organizationId'` silently scopes queries to the caller's org. Correct for per-org resources, **wrong** for company-wide:
 
 ```typescript
-// idField: 'slug'
-// Client sends:  POST /agents/sadman/action
-// In handler:    req.params.id === 'sadman'       ← always keyed 'id'
-//                repo.update(id, data)             ← mongokit resolves by slug via repo.idField
+defineResource({ name: 'invoice' });                                // → { organizationId: scope.orgId }
+defineResource({ name: 'account-type', tenantField: false });       // company-wide lookup
+defineResource({ name: 'workspace-item', tenantField: 'workspaceId' });
 ```
 
-This applies to CRUD routes (`GET/PATCH/DELETE /:id`), action routes (`POST /:id/action`), and any `routes: [...]` entries that use `:id`.
+Use `tenantField: false` for lookup tables, platform settings, cross-org reports, single-tenant apps. **2.12 auto-inference:** if the Mongoose model has no `organizationId` path (and no other tenant field is configured), arc auto-infers `tenantField: false` instead of generating queries that filter on a non-existent column.
 
-**Common confusion pattern.** A 404 on `PATCH /agents/sadman` when `GET /agents/sadman` returns 200 looks like an `idField` bug but usually isn't. Check whether your **update permission** returns `filters` — arc merges those into the compound DB lookup (`{ slug: 'sadman', ...filters }`), and a filter that excludes the doc is what's returning null. Fix is in the permission, not `idField`.
+### idField — custom primary key
 
-User-provided `openApiSchemas.params` still overrides everything.
+Default `'_id'`. Override for business identifiers (UUID, slug, `ORD-2026-0001`):
 
-For custom adapters, honor the new `AdapterSchemaContext` passed to `generateSchemas(options, context?)` to emit the right `params.id` pattern from the start. Legacy adapters still work — Arc's safety net strips mismatched ObjectId patterns automatically.
+```typescript
+defineResource({ name: 'job', adapter, idField: 'jobId' });
+// GET /jobs/job-5219f346-a4d → controller queries { jobId: 'job-5219f346-a4d' }
+```
+
+Auto-derived from `repository.idField` if your kit declares one. URL segment is **always** `:id` and `req.params.id` is **always** named `id` — `idField` controls the *lookup field*, not the URL parameter (Stripe / GitHub convention).
+
+**404 confusion pattern.** A 404 on `PATCH /agents/sadman` when `GET /agents/sadman` works isn't usually an `idField` bug — check whether your update permission returns `filters`. Arc merges those into the lookup (`{ slug: 'sadman', ...filters }`); an excluding filter returns null.
 
-## searchPreset (text + vector + embed)
+### searchPreset (text + vector + embed)
 
-Backend-agnostic routes for Elasticsearch / OpenSearch / Algolia / Typesense / Atlas `$vectorSearch` / Pinecone / Qdrant / Milvus. Opt-in per section; `mcp: false` skips per path.
+Backend-agnostic for Elasticsearch / OpenSearch / Algolia / Typesense / Atlas `$vectorSearch` / Pinecone / Qdrant.
 
 ```typescript
 import { searchPreset } from '@classytic/arc/presets/search';
 
 // A — auto-wire from a repo with search/searchSimilar/embed methods
-// (mongokit's elasticSearchPlugin + vectorPlugin register exactly these).
-// Each method's native calling convention is honoured:
-//   search(query, options)          — positional (elasticSearchPlugin)
-//   searchSimilar(VectorSearchParams) — single object (vectorPlugin)
-//   embed(input)                    — single arg (vectorPlugin)
-searchPreset({
-  repository: productRepo,
-  search: true,    // POST /search         → repo.search(body.query, body)
-  similar: true,   // POST /search-similar → repo.searchSimilar(body)
-  // embed omitted → /embed not mounted
-})
+searchPreset({ repository: productRepo, search: true, similar: true })
 
-// B — external backends + custom path + Zod schema
+// B — external backends
 searchPreset({
   search: {
     path: '/full-text',
@@ -648,179 +470,101 @@ searchPreset({
     handler: (req) => elastic.search({ index: 'products', q: req.body.q }),
   },
   similar: { handler: (req) => pinecone.query({ vector: req.body.vector, topK: 10 }), mcp: false },
-  routes: [  // bespoke paths
-    { method: 'GET', path: '/autocomplete', permissions: allowPublic(),
-      handler: (req) => algolia.suggest((req.query as { q: string }).q) },
-  ],
 })
 ```
 
-**Defaults:** search/similar → POST, permissions fall back to resource `list` → `allowPublic()`. Embed → POST + `requireAuth()`. Every field (`path`, `method`, `schema`, `permissions`, `mcp`, `summary`, `tags`, `operation`) is overridable per section. Zod v4 schemas auto-convert to JSON Schema for both Fastify validation and OpenAPI.
-
-**MCP namespacing:** tool names are `{op}_{resource}` — many resources can register their own searchPreset under one `mcpPlugin` endpoint without colliding (`product_search`, `order_search`, …).
+Defaults: search/similar inherit `list` perms → `allowPublic()`. Embed → `requireAuth()`. Zod v4 schemas auto-convert. MCP tools namespaced as `{op}_{resource}`.
 
-**When to use `routes` directly instead:** one-off search endpoints, or when you want full control without the preset's defaults.
-
-## QueryCache
+## Adapters
 
-TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
+In arc 2.12 the cross-framework adapter contract lives in `@classytic/repo-core/adapter`. Every kit-specific adapter ships from its kit's `/adapter` subpath; arc has zero kit-bound adapters in `src/`.
 
 ```typescript
-// Enable globally
-const app = await createApp({ arcPlugins: { queryCache: true } });
+// Mongoose — from mongokit
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';
+import { buildCrudSchemasFromModel } from '@classytic/mongokit';
 
-// 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 },
-  },
+const adapter = createMongooseAdapter({
+  model: ProductModel,
+  repository: productRepo,
+  schemaGenerator: buildCrudSchemasFromModel,    // no cast needed
 });
+
+// Drizzle — from sqlitekit
+import { createDrizzleAdapter } from '@classytic/sqlitekit/adapter';
+import { buildCrudSchemasFromTable } from '@classytic/sqlitekit';
+
+createDrizzleAdapter({ table, repository, schemaGenerator: buildCrudSchemasFromTable });
+
+// Prisma — from prismakit
+import { createPrismaAdapter } from '@classytic/prismakit/adapter';
 ```
 
-**Auto-invalidation:** POST/PATCH/DELETE bumps resource version. Old cached queries expire naturally via TTL.
+Custom kits implementing `DataAdapter<TDoc>` from `@classytic/repo-core/adapter` plug in identically. Kit factories accept `AdapterRepositoryInput<TDoc>` — kit-native repos plug in **without** `as RepositoryLike` casts.
 
-**Runtime modes:** `memory` (default, zero-config) | `distributed` (requires `stores.queryCache: RedisCacheStore`)
+**Custom adapter** — implement `DataAdapter` / `MinimalRepo` from `@classytic/repo-core/adapter`:
 
-**Response header:** `x-cache: HIT | STALE | MISS`
+```typescript
+import type {
+  DataAdapter, RepositoryLike, AdapterRepositoryInput,
+} from '@classytic/repo-core/adapter';
+import type { MinimalRepo } from '@classytic/repo-core/repository';
+// MinimalRepo<TDoc>  = 5-method floor (getAll, getById, create, update, delete)
+// StandardRepo<TDoc> = MinimalRepo + optional batch ops, CAS, soft-delete, …
+// Arc feature-detects optional methods at call sites.
+```
 
-## Controllers (v2.11 mixin split)
+## Controllers
 
-`BaseController` was split in 2.11 from a 1,589-LOC god class into a mixin composition. `extends BaseController<Product>` still works exactly the same — a declaration-merged interface threads `TDoc` through every CRUD + preset method.
+`BaseController` is mixin-composed; declaration-merged interfaces thread `TDoc` through every CRUD + preset method.
 
 ```typescript
 import { BaseController } from '@classytic/arc';
 import type { IRequestContext, IControllerResponse } from '@classytic/arc';
 
-// Full surface: CRUD + SoftDelete + Tree + Slug + Bulk
 class ProductController extends BaseController<Product> {
-  constructor() { super(productRepo); }
+  // When you pass your own controller, arc CANNOT thread tenantField /
+  // schemaOptions / idField / cache / onFieldWriteDenied into it. Forward
+  // them via super() and pass them to defineResource() too:
+  constructor(opts: { tenantField?: string | false; idField?: string } = {}) {
+    super(productRepo, { resourceName: 'product', ...opts });
+  }
 
   async getFeatured(req: IRequestContext): Promise<IControllerResponse<Product[]>> {
     const products = await this.repository.getAll({ filters: { isFeatured: true } });
-    return { success: true, data: products };
+    return { data: products };
   }
 }
-```
 
-**Slim CRUD-only surface** (869 LOC instead of 1,650):
-
-```typescript
-import { BaseCrudController } from '@classytic/arc';
-class ReportController extends BaseCrudController<Report> {}
+defineResource({ name: 'product', controller: new ProductController({ tenantField: '_id' }), tenantField: '_id' });
 ```
 
-**Pick specific mixins:**
+Presets that inject controller fields (slugLookup → slugField, softDelete, tree) only reach arc's auto-built `BaseController`. With a custom controller + such a preset, drop the preset OR extend `BaseController` so arc auto-builds it.
+
+**Slim CRUD-only base** (no soft-delete/tree/slug/bulk):
 
 ```typescript
 import { BaseCrudController, SoftDeleteMixin, BulkMixin } from '@classytic/arc';
+class ReportController extends BaseCrudController<Report> {}
 class OrderController extends SoftDeleteMixin(BulkMixin(BaseCrudController)) {}
-// → list/get/create/update/delete + getDeleted/restore + bulkCreate/bulkUpdate/bulkDelete
-```
-
-**Mixin surface:** `SoftDeleteMixin` (`getDeleted`, `restore`) · `TreeMixin` (`getTree`, `getChildren`) · `SlugMixin` (`getBySlug`) · `BulkMixin` (`bulkCreate`, `bulkUpdate`, `bulkDelete`). Each exported from `@classytic/arc` and `@classytic/arc/core`.
-
-**Shared helpers** (protected on `BaseCrudController` so mixins can extend): `meta(req)`, `getHooks(req)`, `tenantRepoOptions(req)`, `resolveRepoId(id, existing)`, `notFoundResponse(reason)`, `resolveCacheConfig(op)`, `cacheScope(req)`.
-
-**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 — canonical arc factory
-import { createMongooseAdapter } from '@classytic/arc';
-import { buildCrudSchemasFromModel } from '@classytic/mongokit';
-
-const adapter = createMongooseAdapter({
-  model: ProductModel,
-  repository: productRepo,
-  schemaGenerator: buildCrudSchemasFromModel,   // ← no cast; RouteSchemaOptions extends SchemaBuilderOptions
-});
-
-// Custom adapter — implement MinimalRepo from @classytic/repo-core/repository:
-import type { MinimalRepo } from '@classytic/repo-core/repository';
-// MinimalRepo<TDoc> = five-method floor (getAll, getById, create, update, delete)
-// StandardRepo<TDoc> = MinimalRepo + optional batch ops, CAS, soft-delete, etc.
-// Arc feature-detects optional methods at call sites.
-```
-
-- `createMongooseAdapter` is the **canonical arc export**. Use directly — no cast on `schemaGenerator` (arc's `RouteSchemaOptions extends SchemaBuilderOptions`; `ArcFieldRule extends FieldRule`).
-- `createAdapter` is a **CLI-scaffolded host wrapper** (`src/lib/adapter.ts`). Keep for scaffolded apps; hand-built apps should import `createMongooseAdapter` directly.
-- Built-in mongoose fallback detects `{ default: null }` on schema paths and widens the emitted JSON-Schema type automatically — no `fieldRules` entry needed for that case.
-
-## 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. Pass `repository: RepositoryLike` (mongokit / prismakit / custom) for production, or `store: MemoryOutboxStore()` for dev. Arc adapts the repo to the `OutboxStore` contract internally — `create` / `findAll` / `deleteMany` / `findOneAndUpdate` cover save, claim, ack, fail, DLQ.
-
-**Event contract (v2.9):** `EventMeta` = `id`, `timestamp`, optional `schemaVersion`, `correlationId`, `causationId`, `partitionKey`, `source`, `idempotencyKey`, `resource`, `resourceId`, `userId`, `organizationId`, `aggregate: { type, id }`. `createChildEvent(parent, ...)` inherits correlation/causation/source/idempotencyKey; aggregate stays explicit. `DeadLetteredEvent<T>` + optional `transport.deadLetter()` for typed DLQ. `withRetry({ transport })` auto-routes exhausted events — no custom plumbing for Kafka/SQS. `@classytic/primitives` mirrors these shapes — arc is source of truth.
+Mixin surface: `SoftDeleteMixin` · `TreeMixin` · `SlugMixin` · `BulkMixin`. Protected helpers on `BaseCrudController`: `meta(req)`, `getHooks(req)`, `tenantRepoOptions(req)`, `resolveRepoId(id, existing)`, `notFoundResponse(reason)`, `resolveCacheConfig(op)`, `cacheScope(req)`.
 
-**Outbox (v2.9):** `EventOutbox.store()` auto-maps `meta.idempotencyKey` → `dedupeKey`. `new EventOutbox({ failurePolicy: ({ attempts }) => ({ retryAt, deadLetter }) })` centralises retry/DLQ. `outbox.getDeadLettered(limit)` returns typed `DeadLetteredEvent[]`. `RelayResult.deadLettered` for per-batch DLQ count. Durable store: `new EventOutbox({ repository: new Repository(OutboxModel), transport })` (v2.9.1) — multi-worker claim, session-threaded writes, and dedupe semantics come from the repo's backing kit.
-
-## 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 }),
-  },
-});
-```
+`IRequestContext` = `{ params, query, body, user, headers, context, metadata, server }`.
+`IControllerResponse` = `{ success, data?, error?, status?, meta?, headers? }`.
 
 ## Hooks
 
-**Inline on resource (recommended):**
+Inline on resource — `ResourceHookContext` = `{ data, user?, meta? }`; `meta` has `id` and `existing` for update/delete:
 
 ```typescript
 defineResource({
   name: 'chat',
   hooks: {
     beforeCreate: async (ctx) => { ctx.data.slug = slugify(ctx.data.name); },
-    afterCreate: async (ctx) => { analytics.track('created', { id: ctx.data._id, user: ctx.user?.id }); },
-    beforeUpdate: async (ctx) => { console.log('Updating', ctx.meta?.id, 'existing:', ctx.meta?.existing); },
+    afterCreate: async (ctx) => { analytics.track('created', { id: ctx.data._id }); },
+    beforeUpdate: async (ctx) => { /* ctx.meta.existing has the pre-image */ },
     afterUpdate: async (ctx) => { await invalidateCache(ctx.data._id); },
     beforeDelete: async (ctx) => { if (ctx.data.isProtected) throw new Error('Cannot delete'); },
     afterDelete: async (ctx) => { await cleanupFiles(ctx.meta?.id); },
@@ -828,9 +572,7 @@ defineResource({
 });
 ```
 
-`ResourceHookContext`: `{ data, user?, meta? }` — `data` is the document, `meta` has `id` and `existing` (for update/delete).
-
-**App-level (cross-resource):**
+App-level (cross-resource):
 
 ```typescript
 import { createHookSystem, beforeCreate, afterUpdate } from '@classytic/arc/hooks';
@@ -855,66 +597,125 @@ defineResource({
 });
 ```
 
-## Query Parsing
+## Query parsing
 
-Arc's default parser handles filters, sort, select, populate, and pagination. Swap in MongoKit's `QueryParser` for $lookup joins.
+Default parser handles filters, sort, select, populate, pagination.
 
 ```
 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
+GET /products?after=<cursor_id>&limit=20                            # keyset pagination
+GET /products?populate=category
+GET /products?populate[category][select]=name,slug
+GET /products?populate[category][match][isActive]=true
 ```
 
-**Lookup/join (no refs — $lookup via MongoKit QueryParser):**
+Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `like`, `regex`, `exists`.
+
+**MongoKit `$lookup` joins:**
 
 ```
 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 >=3.4.5 for $lookup, whitelists, MCP auto-derive):**
+**Custom parser (whitelists, MCP auto-derive):**
 
 ```typescript
 import { QueryParser } from '@classytic/mongokit';
 
 defineResource({
   name: 'product',
-  adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
+  adapter,
   queryParser: new QueryParser({
-    allowedFilterFields: ['status', 'category', 'orgId'],  // whitelist filter fields
-    allowedSortFields: ['createdAt', 'price'],              // whitelist sort fields
-    allowedOperators: ['eq', 'gte', 'lte', 'in'],          // whitelist operators
+    allowedFilterFields: ['status', 'category', 'orgId'],
+    allowedSortFields: ['createdAt', 'price'],
+    allowedOperators: ['eq', 'gte', 'lte', 'in'],
   }),
-  // MCP auto-derives filterableFields from queryParser — no duplication needed
   schemaOptions: {
-    query: {
-      allowedPopulate: ['category', 'brand'],
-      allowedLookups: ['categories', 'brands'],
-    },
+    query: { allowedPopulate: ['category', 'brand'], allowedLookups: ['categories', 'brands'] },
+  },
+});
+```
+
+MCP auto-derives `filterableFields` from `queryParser`.
+
+## QueryCache
+
+TanStack Query-style server cache, stale-while-revalidate, auto-invalidation on mutations.
+
+```typescript
+const app = await createApp({ arcPlugins: { queryCache: true } });
+
+defineResource({
+  name: 'product',
+  cache: {
+    staleTime: 30,
+    gcTime: 300,
+    tags: ['catalog'],
+    invalidateOn: { 'category.*': ['catalog'] },     // event pattern → tag targets
+    list: { staleTime: 60 },                          // per-operation override
+    byId: { staleTime: 10 },
   },
 });
 ```
 
-## Error Classes
+POST/PATCH/DELETE bumps resource version. Modes: `memory` (default) | `distributed` (requires `stores.queryCache: RedisCacheStore`). Response header: `x-cache: HIT | STALE | MISS`.
+
+## Events
+
+`createApp` auto-registers `eventPlugin` (default: `MemoryEventTransport`).
+
+```typescript
+const app = await createApp({
+  stores: { events: new RedisEventTransport(redis) },     // optional
+  arcPlugins: { events: { 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 · Redis Pub/Sub (fire-and-forget) · Redis Streams (durable, at-least-once, consumer groups, DLQ).
+
+**EventMeta:** `id`, `timestamp`, optional `schemaVersion`, `correlationId`, `causationId`, `partitionKey`, `source`, `idempotencyKey`, `resource`, `resourceId`, `userId`, `organizationId`, `aggregate: { type, id }`. Import event types from `@classytic/primitives/events` (`EventMeta`, `DomainEvent`, `EventHandler`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern`); arc re-exports the runtime `MemoryEventTransport` only. Use `createChildEvent(parent, ...)` to inherit correlation/causation/source/idempotencyKey.
+
+Calling both `app.events.publish('order.placed', ...)` *and* a notification helper that internally publishes the same logical event triggers a one-shot dev-mode warning ("dual-publish"). Pick one path: manual publish OR `eventStrategy: 'auto'`.
+
+**Event Outbox** — at-least-once via transactional outbox. Production: `new EventOutbox({ repository: outboxRepo, transport })` (multi-worker claim, session-threaded writes). Dev: `new EventOutbox({ store: new MemoryOutboxStore(), transport })`. `EventOutbox.store()` auto-maps `meta.idempotencyKey` → `dedupeKey`. `failurePolicy` centralises retry/DLQ.
+
+Full event recipes → [references/events.md](references/events.md).
+
+## Errors
 
 ```typescript
 import { ArcError, NotFoundError, ValidationError, createDomainError } from '@classytic/arc';
-throw new NotFoundError('Product not found');                      // 404
-throw createDomainError('MEMBER_NOT_FOUND', 'Not found', 404);    // domain error with code
+
+throw new NotFoundError('Product not found');                                       // 404
 throw createDomainError('SELF_REFERRAL', 'Cannot self-refer', 422, { field: 'referralCode' });
 ```
 
-Error handler catches: `ArcError` → `.statusCode` (Fastify) → `.status` (MongoKit, http-errors) → `errorMap` → Mongoose/MongoDB → fallback 500. DB-agnostic — any error with `.status` or `.statusCode` gets the correct HTTP response.
+Resolution: `ArcError` → `.statusCode` (Fastify) → `.status` (MongoKit, http-errors) → user `errorMap` → Mongoose/MongoDB → 500. Any error with `.status` or `.statusCode` gets the correct HTTP response.
 
-## Compensating Transaction
+`ArcError` implements the `HttpError` throwable contract from `@classytic/repo-core/errors` (`status` getter mirrors `statusCode`, `meta` getter mirrors `details`). Wire envelope: `{ code, message, status, meta?, correlationId? }` — HTTP status code is the success/error discriminator, no redundant `success` field. For non-Arc errors, `toErrorContract(err)` (from `@classytic/repo-core/errors`) serialises any `HttpError` to the canonical `ErrorContract` wire shape; `statusToErrorCode(status)` maps numeric status to canonical `ErrorCode`.
 
-In-process rollback for multi-step operations. Not a distributed saga — use Temporal/Streamline for that.
+**Class-based mappers:**
+
+```typescript
+const app = await createApp({
+  errorHandler: {
+    errorMappers: [{
+      type: AccountingError,
+      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
+    }],
+  },
+});
+```
+
+## 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';
@@ -922,32 +723,22 @@ 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),
-});
+  { name: 'notify', execute: sendEmail, fireAndForget: true },
+], { orderId });
 // result: { success, completedSteps, results, failedStep?, error?, compensationErrors? }
 ```
 
 ## Testing
 
-Three entry points — pick by what you're testing. Full details in [references/testing.md](references/testing.md).
-
 ```typescript
-import {
-  createTestApp,                 // turnkey Fastify + in-memory Mongo + auth + fixtures
-  createHttpTestHarness,         // auto-generates ~16 CRUD/permission/validation tests
-  expectArc,                     // fluent envelope matchers
-  createTestFixtures,            // DB-agnostic seeding with per-record destroyers
-} from '@classytic/arc/testing';
+import { createTestApp, expectArc } from '@classytic/arc/testing';
 
 const ctx = await createTestApp({
   resources: [productResource],
-  authMode: 'jwt',                    // 'jwt' | 'better-auth' | 'none'
-  db: 'in-memory',                    // default
-  connectMongoose: true,              // one-liner for Mongoose-backed resources
+  authMode: 'jwt',                  // 'jwt' | 'better-auth' | 'none'
+  connectMongoose: true,            // in-memory Mongo + Mongoose connect
 });
-ctx.auth.register('admin', { user: { id: '1', roles: ['admin'] }, orgId: 'org-1' });
+ctx.auth.register('admin', { user: { id: '1', role: 'admin' }, orgId: 'org-1' });
 
 const res = await ctx.app.inject({
   method: 'POST', url: '/products',
@@ -955,34 +746,35 @@ const res = await ctx.app.inject({
   payload: { name: 'Widget' },
 });
 expectArc(res).ok().hidesField('password');
+
+await ctx.close();
 ```
 
-`TestAppContext` = `{ app, auth, fixtures, dbUri, close }`. `authMode: 'better-auth'` requires the caller to also pass `auth: { type: 'better-auth', ... }`.
+Three entry points: `createTestApp` (custom scenarios), `createHttpTestHarness` (~16 auto-generated CRUD/permission/validation tests per resource), `runStorageContract` (adapter conformance).
+
+Full testing recipes → [references/testing.md](references/testing.md).
 
 ## 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 init my-api --mongokit --jwt --ts          # scaffold (also: --custom, --better-auth, --multi)
+arc generate resource product                   # generate a resource
+arc generate resource product --mcp             # + MCP tools file
+arc generate mcp analytics                      # standalone MCP tools file
+arc docs ./openapi.json --entry ./dist/index.js # emit OpenAPI
 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)
+Set `"mcp": true` in `.arcrc` to always generate `.mcp.ts` alongside resources.
 
-Expose Arc resources as MCP tools for AI agents. Stateless by default — fresh server per request, zero session overhead.
+## MCP (AI agent tools)
 
-See [mcp reference](references/mcp.md) for full details.
+Resources auto-generate Model Context Protocol tools — same permissions, same field rules. Stateless by default (fresh server per request, scalable).
 
 ```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
@@ -994,18 +786,18 @@ await app.register(mcpPlugin, {
 await app.register(mcpPlugin, { resources, stateful: true, sessionTtlMs: 600000 });
 ```
 
-Connect Claude CLI: `claude mcp add --transport http my-api http://localhost:3000/mcp`
+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:
+**Auth modes** — `false` | `getAuth()` (Better Auth OAuth 2.1) | custom function:
 
 ```typescript
-// Human user auth
+// Human user
 auth: async (headers) => {
   if (headers['x-api-key'] !== process.env.MCP_KEY) return null;
   return { userId: 'bot', organizationId: 'org-1', roles: ['admin'] };
 },
 
-// Service account / machine-to-machine (produces kind: "service" scope)
+// Service / machine — produces kind: "service" scope
 auth: async (headers) => ({
   clientId: 'ingestion-pipeline',
   organizationId: 'org-1',
@@ -1013,14 +805,14 @@ auth: async (headers) => ({
 }),
 ```
 
-`auth: false` → `ctx.user` is `null`, `scope.kind` is `"public"`. Permission guards like `!!ctx.user` correctly block anonymous callers.
+`auth: false` → `ctx.user` null, `scope.kind: "public"`. `clientId` set → `kind: "service"` works with `requireServiceScope()`. `PermissionResult.filters` flow into MCP tools — same as REST.
 
-**Guards** for custom tools: `guard(requireAuth, requireOrg, requireRole('admin'), handler)`
+**Custom tools** — co-locate with resources (`order.mcp.ts`), wire via `extraTools: [fulfillOrderTool]`. Generate: `arc generate resource order --mcp`.
 
-**AI SDK bridge** (v2.8.4+) — expose AI SDK `tool()` definitions over MCP without duplicating glue. Handles auth, guards, `{ error } → isError` translation, and thrown-error mapping:
+**AI SDK bridge** — expose AI SDK `tool()` definitions over MCP without duplicating glue:
 
 ```typescript
-import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
+import { buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
 
 export const triggerJobBridge: McpBridge = {
   name: 'trigger_job',
@@ -1033,246 +825,190 @@ export const triggerJobBridge: McpBridge = {
 
 await app.register(mcpPlugin, {
   resources,
-  extraTools: buildMcpToolsFromBridges([triggerJobBridge], {
-    exclude: process.env.DEPLOYMENT === 'readonly' ? ['trigger_job'] : [],
-  }),
+  extraTools: buildMcpToolsFromBridges([triggerJobBridge]),
 });
 ```
 
-**Service scope**: When `clientId` is set in auth result, MCP produces `kind: "service"` RequestScope — works with `requireServiceScope()`, `getClientId()`, `getServiceScopes()`. No synthetic userId needed for machine principals.
-
-**Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.
+Full MCP recipes → [references/mcp.md](references/mcp.md).
 
-**Permission filters**: `PermissionResult.filters` from resource permissions flow into MCP tools — same as REST. Define once, works everywhere:
+## Audit per-resource opt-in
 
 ```typescript
-permissions: {
-  list: (ctx) => ({
-    granted: !!ctx.user,
-    filters: { orgId: ctx.user?.orgId, branchId: ctx.user?.branchId },
-  }),
-}
-// MCP tools automatically scope queries by orgId + branchId
-```
+await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
 
-**Project structure** — custom MCP tools co-located with resources:
+defineResource({ name: 'order', audit: true });
+defineResource({ name: 'payment', audit: { operations: ['delete'] } });
+defineResource({ name: 'product' });   // not audited
 
+// Manual custom() for MCP tools / read auditing
+app.post('/orders/:id/refund', async (req) => {
+  await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
+});
 ```
-src/resources/order/
-  order.resource.ts
-  order.mcp.ts              ← defineTool('fulfill_order', { ... })
-```
-
-Generate: `arc generate resource order --mcp` | Wire: `extraTools: [fulfillOrderTool]`
 
-**Auto-load resources** — no barrel files, no manual `toPlugin()`:
+## DX helpers
 
 ```typescript
-import { createApp, loadResources } from '@classytic/arc/factory';
+import type { ArcRequest } from '@classytic/arc';
+import { envelope, createDomainError } from '@classytic/arc';
+import { getOrgContext } from '@classytic/arc/scope';
+import { roles } from '@classytic/arc/permissions';
 
-const app = await createApp({
-  resourcePrefix: '/api/v1',                            // optional URL prefix
-  resources: await loadResources(import.meta.url),      // discovers *.resource.ts
-  auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
-});
-```
+// Typed request for raw routes — no `(req as any).user`
+handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
 
-`loadResources()` discovers files matching `*.resource.{ts,js,mts,mjs}`, recursively. Pass `import.meta.url` for dev/prod parity (resolves to `src/` in dev, `dist/` in prod automatically). Discovers `default` export, `export const resource`, OR any named export with `toPlugin()` (e.g., `export const userResource`).
+// Response envelope
+reply.send(envelope(data, { total: 100 }));
 
-Options: `exclude`, `include`, `suffix`, `recursive`, `context`, `logger`. Silent by default — pass `logger: { warn(msg) {...} }` to receive skip / factory-failure diagnostics.
+// Canonical org extraction
+const { userId, organizationId, roles: userRoles, orgRoles } = getOrgContext(request);
 
-**Per-resource opt-out of `resourcePrefix`** — for webhooks, admin routes:
-```typescript
-defineResource({ name: 'webhook', prefix: '/hooks', skipGlobalPrefix: true })
-// Registers at /hooks even with createApp({ resourcePrefix: '/api/v1' })
+// Unified role check — platform AND org roles
+permissions: { create: roles('admin', 'editor'), delete: roles('admin') }
 ```
 
-**Boot sequence:**
-```typescript
-const app = await createApp({
-  resourcePrefix: '/api/v1',
-  plugins: async (f) => { await connectDB(); },     // 1. infra (DB, docs)
-  bootstrap: [inventoryInit, accountingInit],        // 2. domain init (engines)
-  resources: await loadResources(import.meta.url),   // 3. routes
-  afterResources: async (f) => { subscribeEvents(f); }, // 4. post-wiring
-  onReady: async (f) => { logger.info('ready'); },   // 5. lifecycle
-});
-```
+**Reply helpers** — opt-in via `createApp({ replyHelpers: true })`. Arc has no `{ success, data }` envelope: HTTP status discriminates, single-doc handlers `return doc` or `reply.send(doc)`, errors throw `ArcError` (the global handler serialises to `ErrorContract`). The two decorators cover the cases that DO need framework support:
 
-**Audit per-resource opt-in** — no growing exclude lists:
 ```typescript
-// Register audit plugin with perResource mode
-await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
+return reply.sendList({ method: 'offset', data, total, page, limit, pages, hasNext, hasPrev });
+return reply.sendList(canonicalListResult);                   // any kit-shaped paginated/array result
+return reply.stream(csvReadable, { contentType: 'text/csv', filename: 'export.csv' });
+```
 
-// Opt-in at the resource level
-defineResource({ name: 'order', audit: true });
-defineResource({ name: 'payment', audit: { operations: ['delete'] } });
-defineResource({ name: 'product' }); // not audited
+`reply.sendList()` accepts a bare `T[]` or any kit pagination result (`OffsetPaginationResult` / `KeysetPaginationResult` / `AggregatePaginationResult`) and routes through `toCanonicalList` from `@classytic/repo-core/pagination` so the server and the typed `@classytic/arc-next` client share one declaration — `method` as the discriminant cannot drift between them.
 
-// Manual custom() for MCP tools / custom routes / read auditing
-app.post('/orders/:id/refund', async (req) => {
-  await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
-});
-```
+**BigInt serialization** — `createApp({ serializeBigInt: true })` converts BigInt → Number in JSON.
 
-**Import compatibility:** `loadResources()` uses runtime `import()`. Works with relative imports (`./foo.js`) and Node.js `#` subpath imports (`#shared/utils.js` via `package.json` `imports`). Does **NOT** work with tsconfig path aliases (`@/*`, `~/`) — those are compile-time only.
+**Multipart body middleware** — opt-in file upload (no-op for JSON requests, safe to always add):
 
-**Vitest workaround** (rare): if resources need engine bootstrap or transitive `node_modules` imports that don't compose with dynamic import:
 ```typescript
-import { preloadResources } from '@classytic/arc/testing';
+import { multipartBody } from '@classytic/arc/middleware';
 
-export const preloadedResources = preloadResources(
-  import.meta.glob('../../src/resources/**/*.resource.ts', { eager: true, import: 'default' }),
-);
+defineResource({
+  name: 'product',
+  middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5 * 1024 * 1024 })] },
+  hooks: {
+    'before:create': async (data) => {
+      if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
+      return data;
+    },
+  },
+});
 ```
 
-**Unified role check** — checks both platform AND org roles:
+**SSE auth + streaming** — `preAuth` runs before auth (EventSource can't set headers); `raw: true` streams the response:
 
 ```typescript
-import { roles } from '@classytic/arc/permissions';
-permissions: {
-  create: roles('admin', 'editor'),  // works with BA org roles + platform roles
-  delete: roles('admin'),
-}
-// Also: requireRoles(['admin'], { includeOrgRoles: true }) for backward compat
+routes: [
+  { preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] },
+  { method: 'GET', path: '/stream', raw: true, handler: async (req, reply) => reply.send(stream) },
+]
 ```
 
-**DX helpers:**
+**Per-resource opt-out of `resourcePrefix`** — for webhooks, admin routes:
 
 ```typescript
-// Typed request for raw routes — no more (req as any).user
-import type { ArcRequest } from '@classytic/arc';
-handler: async (req: ArcRequest, reply) => { req.user?.id; req.scope; req.signal; }
+defineResource({ name: 'webhook', prefix: '/hooks', skipGlobalPrefix: true })
+// Registers at /hooks even with createApp({ resourcePrefix: '/api/v1' })
+```
 
-// Response envelope — no manual { success, data } wrapping
-import { envelope } from '@classytic/arc';
-reply.send(envelope(data, { total: 100 }));
+## Enterprise auth (2.13)
 
-// Canonical org extraction — replaces 19 duplicated patterns
-import { getOrgContext } from '@classytic/arc/scope';
-const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
+Three opt-in surfaces close the procurement-gate gaps without forcing parallel infrastructure. Sessions / refresh / OAuth flows stay in Better Auth's hands.
 
-// Domain errors with auto HTTP status mapping
-import { createDomainError } from '@classytic/arc';
-throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+### SCIM 2.0 — IdP provisioning (`@classytic/arc/scim`)
 
-// Custom routes — always `routes: [...]` with optional `raw: true` for non-JSON
-defineResource({
-  routes: [{ method: 'GET', path: '/stats', handler: 'getStats', permissions: allowPublic() }],
-});
+Auto-derived `/scim/v2/Users` + `/scim/v2/Groups` from existing arc resources. Okta / Azure AD / Google Workspace / JumpCloud / OneLogin out of the box. No shadow tables.
 
-// SSE auth — preAuth runs BEFORE auth middleware (EventSource can't set headers)
-routes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
+```typescript
+import { scimPlugin } from '@classytic/arc/scim';
 
-// SSE streaming — raw: true + stream the response
-routes: [{ method: 'GET', path: '/stream', raw: true, handler: async (req, reply) => reply.send(stream) }]
+await app.register(scimPlugin, {
+  users: { resource: userResource },
+  groups: { resource: orgResource },
+  bearer: process.env.SCIM_TOKEN,        // or: verify: async (req) => …
+});
 ```
 
-## DX Helpers (v2.7.3+)
+Mounts `GET/POST/PUT/PATCH/DELETE /scim/v2/Users[/:id]`, same for `Groups`, plus `ServiceProviderConfig` / `ResourceTypes` / `Schemas` discovery. SCIM filter language → arc query DSL. RFC 7644 PatchOp translates to canonical operators (`$set`/`$unset`/`$push`/`$pull`) and flows through `repo.findOneAndUpdate(...)`; PUT goes through `repo.bulkWrite([{ replaceOne }])`. SCIM does **not** run arc's HTTP controller pipeline — audit / multi-tenant / field-policy compose at the kit-plugin layer (`repo.use(...)`) and fire identically for arc REST + SCIM because both surfaces hit the same repository methods. → [references/scim.md](references/scim.md).
 
-**Reply helpers** — consistent response envelopes (opt-in via `createApp({ replyHelpers: true })`):
-
-```typescript
-return reply.ok({ name: 'MacBook' });              // → 200 { success: true, data: {...} }
-return reply.ok(product, 201);                      // → 201 { success: true, data: {...} }
-return reply.fail('Not found', 404);                // → 404 { success: false, error: '...' }
-return reply.fail(['err1', 'err2'], 422);           // → 422 { success: false, errors: [...] }
-return reply.paginated({ docs, total, page, limit });
-return reply.stream(csvReadable, { contentType: 'text/csv', filename: 'export.csv' });
-```
+### Agent-auth helpers — DPoP + capability mandates
 
-**Error mappers** — class-based domain error → HTTP response (in `errorHandler` options):
+For AI-agent flows on protected resources (AP2 / Stripe x402 / MCP authorization). Three new helpers in `@classytic/arc/permissions`:
 
 ```typescript
-const app = await createApp({
-  errorHandler: {
-    errorMappers: [{
-      type: AccountingError,
-      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
-    }],
+import { requireAgentScope, requireMandate, requireDPoP } from '@classytic/arc/permissions';
+
+defineResource({
+  name: 'invoice',
+  actions: {
+    pay: {
+      handler: payInvoice,
+      permissions: requireAgentScope({
+        capability: 'payment.charge',
+        scopes: ['payment.write'],
+        requireDPoP: true,                                  // RFC 9449 sender-constrained
+        audience: (ctx) => `invoice:${ctx.params?.id}`,    // mandate must bind to this resource
+        validateAmount: (ctx, m) => (ctx.data as { amount: number }).amount <= (m.cap ?? 0),
+      }),
+    },
   },
 });
-// Handlers just throw — Arc catches and maps automatically
 ```
 
-**BigInt serialization** — opt-in via `createApp({ serializeBigInt: true })`. Converts BigInt → Number in all JSON responses.
+`RequestScope.service` gains optional `mandate` + `dpopJkt` fields. Your `authenticate` callback verifies the mandate JWT (one `jose.jwtVerify()` call) + DPoP proof (one `jose.dpop.verify()` call) and populates them. Arc validates *what's already proved* against the action — no peer-deps on `jose`. → [references/agent-auth.md](references/agent-auth.md).
 
-**Multipart body middleware** — opt-in file upload for CRUD routes:
+### Auth-event audit bridge (`@classytic/arc/auth/audit`)
+
+BA's `databaseHooks` + endpoint hooks routed through the existing `auditPlugin` — one canonical row shape for resource AND auth events. Single query for "everything user X did".
 
 ```typescript
-import { multipartBody } from '@classytic/arc/middleware';
+import { wireBetterAuthAudit } from '@classytic/arc/auth/audit';
 
-defineResource({
-  name: 'product',
-  adapter,
-  middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png', 'image/jpeg'], maxFileSize: 5 * 1024 * 1024 })] },
-  hooks: {
-    'before:create': async (data) => {
-      if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
-      return data;
-    },
-  },
+const audit = wireBetterAuthAudit({
+  events: ['session.*', 'user.*', 'mfa.*', 'org.invite.*'],
+});
+
+const auth = betterAuth({
+  hooks: audit.hooks,                  // endpoint hooks (MFA, OAuth, password reset)
+  databaseHooks: audit.databaseHooks,  // sign-in/up/out via session.create/delete
+  // ...
 });
+
+const app = await createApp({ ... });
+audit.attach(app);                      // drains boot-time buffer + connects live logger
 ```
 
-`multipartBody()` is a no-op for JSON requests — safe to always add.
+Buffered until `attach(app)` is called — works for hosts that build BA before Fastify. Manual `audit.emit({ name, subjectId, ... })` for non-BA flows (webhook signature failures, custom MFA).
+
+### What's NOT in arc 2.13
+
+SAML / SCIM-EnterpriseUser / device trust / SOC2 attestations / session storage. Reasons + workarounds → [references/enterprise-auth.md](references/enterprise-auth.md). Compliance control matrix → [`docs/compliance/{soc2,hipaa}.md`](../../docs/compliance/).
 
-## Subpath Imports
+## Subpath imports
+
+The most common imports — full enumeration in [references/api-reference.md](references/api-reference.md).
 
 ```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';
-// Optional Mongoose stub-models bridge for `populate()` against Better Auth
-// collections — subpath gate keeps Mongoose out of Prisma/Drizzle/Kysely bundles.
-import { registerBetterAuthMongooseModels } from '@classytic/arc/auth/mongoose';
-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';
-// Scope accessors
-import {
-  // Type guards
-  isMember, isService, isElevated, isAuthenticated, hasOrgAccess,
-  // Identity / org accessors
-  getUserId, getUserRoles, getOrgId, getOrgRoles, getTeamId, getClientId,
-  // Service scopes (OAuth-style strings on API keys)
-  getServiceScopes,
-  // App-defined scope dimensions (branch, project, region, …)
-  getScopeContext, getScopeContextMap,
-  // Parent-child org hierarchy
-  getAncestorOrgIds, isOrgInScope,
-  // Generic request-side helper
-  getRequestScope,
-} from '@classytic/arc/scope';
-import { createTenantKeyGenerator } from '@classytic/arc/scope';
-import { createRoleHierarchy } from '@classytic/arc/permissions';
-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, multiTenantPreset, type TenantFieldSpec } from '@classytic/arc/presets';
+import { createApp, loadResources } from '@classytic/arc/factory';
+import { createMongooseAdapter } from '@classytic/mongokit/adapter';     // or sqlitekit/adapter, prismakit/adapter
+import type { DataAdapter, RepositoryLike } from '@classytic/repo-core/adapter';
+import { getUserId, getOrgId, requireOrgId } from '@classytic/arc/scope';
+import { mcpPlugin } from '@classytic/arc/mcp';
+import { createTestApp, expectArc } from '@classytic/arc/testing';
 ```
 
-## References (Progressive Disclosure)
+## References
 
-- **[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
+- **[api-reference](references/api-reference.md)** — full subpath import map (every plugin, helper, type)
+- **[auth](references/auth.md)** — JWT, Better Auth, API key, custom auth
+- **[scim](references/scim.md)** — SCIM 2.0 plugin (Okta / Azure AD / Google Workspace provisioning)
+- **[agent-auth](references/agent-auth.md)** — DPoP + capability mandates (AP2 / x402 / MCP authorization)
+- **[enterprise-auth](references/enterprise-auth.md)** — what's in vs out of the box for enterprise auth
+- **[events](references/events.md)** — Domain events, transports, retry, outbox
 - **[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
-- **[multi-tenancy](references/multi-tenancy.md)** — Scope ladder, `tenantField` read sites, `PermissionResult.scope`, API key auth without a separate auth plugin
-- **[production](references/production.md)** — Health, audit, idempotency, tracing, metrics, versioning, SSE, QueryCache, bulk ops, saga, RPC schema versioning, tenant rate limiting
+- **[mcp](references/mcp.md)** — MCP tools, custom tools, Better Auth OAuth 2.1
+- **[multi-tenancy](references/multi-tenancy.md)** — Scope ladder, `tenantField`, `PermissionResult.scope`, API key auth
+- **[production](references/production.md)** — Health, audit, idempotency, tracing, metrics, versioning, SSE, QueryCache, bulk ops
 - **[testing](references/testing.md)** — Test app, mocks, data factories, in-memory MongoDB