@classytic/arc 2.4.2 → 2.5.0

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
-import { Lt as ResourceDefinition, l as AnyRecord, zt as CrudRepository } from "../interface-DGmPxakH.mjs";
-import { r as CreateAppOptions } from "../types-Dt0-AI6E.mjs";
+import { Bt as ResourceDefinition, Ht as CrudRepository, l as AnyRecord } from "../interface-BnNjdl33.mjs";
+import { r as CreateAppOptions } from "../types-Guk83PDz.mjs";
 import Fastify, { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Connection } from "mongoose";
 import { Mock } from "vitest";

package/dist/testing/index.mjs

@@ -1752,7 +1752,7 @@ function runEventTests(resourceName, displayName, events) {
 * ```
 */
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-ByWNRsZj.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-oic3-ieX.mjs").then((n) => n.r);
 	const { useInMemoryDb = true, mongoUri: providedMongoUri, ...appOptions } = options;
 	const defaultAuth = {
 		type: "jwt",

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { a as AUTHENTICATED_SCOPE, c as getOrgId, g as isMember, h as isElevated, l as getOrgRoles, m as isAuthenticated, n as ElevationOptions, o as PUBLIC_SCOPE, p as hasOrgAccess, s as RequestScope, t as ElevationEvent, u as getTeamId } from "../elevation-Ca_yveIO.mjs";
-import { $ as RegistryStats, A as HealthCheck, At as FastifyHandler, B as MiddlewareConfig, Bt as InferDoc, C as EventDefinition, D as FastifyWithDecorators, E as FastifyWithAuth, F as IntrospectionData, G as ParsedQuery, H as ObjectId, Ht as PaginationParams, I as IntrospectionPluginOptions, J as PresetHook, K as PopulateOption, L as JWTPayload, M as InferAdapterDoc, Mt as IControllerResponse, N as InferDocType, Nt as IRequestContext, O as FieldRule, Ot as ControllerHandler, P as InferResourceDoc, Pt as RouteHandler, Q as RegistryEntry, R as JwtContext, S as CrudSchemas, T as FastifyRequestExtras, U as OpenApiSchemas, Ut as QueryOptions, V as MiddlewareHandler, Vt as PaginatedResult, W as OwnershipCheck, X as QueryParserInterface, Y as PresetResult, Z as RateLimitConfig, _ as ConfigError, _t as ValidateOptions, at as ResourceHooks, b as CrudRouteKey, c as AdditionalRoute, ct as RouteHandlerMethod, d as ArcDecorator, dt as TokenPair, et as RequestContext, f as ArcInternalMetadata, ft as TypedController, g as AuthenticatorContext, gt as UserOrganization, h as Authenticator, ht as UserLike, it as ResourceConfig, j as HealthOptions, jt as IController, k as GracefulShutdownOptions, kt as ControllerLike, l as AnyRecord, lt as RouteSchemaOptions, m as AuthPluginOptions, mt as TypedResourceConfig, nt as RequestWithExtras, ot as ResourceMetadata, p as AuthHelpers, pt as TypedRepository, q as PresetFunction, rt as ResourceCacheConfig, st as ResourcePermissions, tt as RequestIdOptions, u as ApiResponse, ut as ServiceContext, v as ControllerQueryOptions, vt as ValidationResult, w as EventsDecorator, x as CrudRouterOptions, xt as BaseControllerOptions, y as CrudController, yt as getUserId, z as LookupOption, zt as CrudRepository } from "../interface-DGmPxakH.mjs";
+import { _ as isMember, a as AUTHENTICATED_SCOPE, d as getTeamId, g as isElevated, h as isAuthenticated, l as getOrgId, m as hasOrgAccess, n as ElevationOptions, o as PUBLIC_SCOPE, s as RequestScope, t as ElevationEvent, u as getOrgRoles } from "../elevation-C_taLQrM.mjs";
+import { $ as RegistryEntry, A as GracefulShutdownOptions, B as LookupOption, C as CrudSchemas, D as FastifyWithAuth, E as FastifyRequestExtras, F as InferResourceDoc, Ft as IControllerResponse, G as OwnershipCheck, Gt as PaginationParams, H as MiddlewareHandler, Ht as CrudRepository, I as IntrospectionData, It as IRequestContext, J as PresetFunction, K as ParsedQuery, Kt as QueryOptions, L as IntrospectionPluginOptions, Lt as RouteHandler, M as HealthOptions, Mt as ControllerLike, N as InferAdapterDoc, Nt as FastifyHandler, O as FastifyWithDecorators, P as InferDocType, Pt as IController, Q as RateLimitConfig, R as JWTPayload, S as CrudRouterOptions, St as getUserId, T as EventsDecorator, U as ObjectId, Ut as InferDoc, V as MiddlewareConfig, W as OpenApiSchemas, Wt as PaginatedResult, X as PresetResult, Y as PresetHook, Z as QueryParserInterface, _ as AuthenticatorContext, _t as UserLike, at as ResourceConfig, b as CrudController, bt as ValidationResult, c as AdditionalRoute, ct as ResourceMetadata, d as ArcDecorator, dt as RouteSchemaOptions, et as RegistryStats, f as ArcInternalMetadata, ft as ServiceContext, g as Authenticator, gt as TypedResourceConfig, h as AuthPluginOptions, ht as TypedRepository, it as ResourceCacheConfig, j as HealthCheck, jt as ControllerHandler, k as FieldRule, l as AnyRecord, lt as ResourcePermissions, m as AuthHelpers, mt as TypedController, nt as RequestIdOptions, ot as ResourceHookContext, p as ArcRequest, pt as TokenPair, q as PopulateOption, rt as RequestWithExtras, st as ResourceHooks, tt as RequestContext, u as ApiResponse, ut as RouteHandlerMethod, v as ConfigError, vt as UserOrganization, w as EventDefinition, wt as BaseControllerOptions, x as CrudRouteKey, xt as envelope, y as ControllerQueryOptions, yt as ValidateOptions, z as JwtContext } from "../interface-BnNjdl33.mjs";
 import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-BNUccdcf.mjs";
-export { AUTHENTICATED_SCOPE, AdditionalRoute, AnyRecord, ApiResponse, ArcDecorator, ArcInternalMetadata, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRepository, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PUBLIC_SCOPE, PaginatedResult, PaginationParams, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryOptions, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteHandler, RouteHandlerMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+export { AUTHENTICATED_SCOPE, AdditionalRoute, AnyRecord, ApiResponse, ArcDecorator, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRepository, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OpenApiSchemas, OwnershipCheck, PUBLIC_SCOPE, PaginatedResult, PaginationParams, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryOptions, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteHandler, RouteHandlerMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };

package/dist/types/index.mjs

@@ -1,6 +1,27 @@
-import { a as getTeamId, c as hasOrgAccess, d as isMember, i as getOrgRoles, l as isAuthenticated, n as PUBLIC_SCOPE, r as getOrgId, t as AUTHENTICATED_SCOPE, u as isElevated } from "../types-C6TQjtdi.mjs";
+import { a as getOrgRoles, d as isElevated, f as isMember, i as getOrgId, l as hasOrgAccess, n as PUBLIC_SCOPE, o as getTeamId, t as AUTHENTICATED_SCOPE, u as isAuthenticated } from "../types-BhtYdxZU.mjs";
 //#region src/types/index.ts
 /**
+* Response envelope helper — wraps data in Arc's standard `{ success, data }` format.
+*
+* @example
+* ```typescript
+* import { envelope } from '@classytic/arc';
+*
+* handler: async (req, reply) => {
+*   const data = await getResults();
+*   return envelope(data);
+*   // → { success: true, data }
+* }
+* ```
+*/
+function envelope(data, meta) {
+	return {
+		success: true,
+		data,
+		...meta
+	};
+}
+/**
 * Extract user ID from a user object (supports both id and _id)
 */
 function getUserId(user) {
@@ -9,4 +30,4 @@ function getUserId(user) {
 	return id ? String(id) : void 0;
 }
 //#endregion
-export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };

package/dist/{types-C6TQjtdi.mjs → types-BhtYdxZU.mjs}

@@ -58,9 +58,34 @@ function getUserRoles(scope) {
 	if (scope.kind === "member") return scope.userRoles;
 	return [];
 }
+/**
+* Org context — canonical extraction from a Fastify request.
+*
+* Works regardless of auth type (JWT, Better Auth, custom) by reading
+* `request.scope` and `request.user`. Eliminates the need for each resource
+* to re-invent org extraction from headers/user/scope.
+*
+* @example
+* ```typescript
+* import { getOrgContext } from '@classytic/arc/scope';
+*
+* handler: async (request, reply) => {
+*   const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
+* }
+* ```
+*/
+function getOrgContext(request) {
+	const scope = request.scope ?? { kind: "public" };
+	return {
+		userId: getUserId(scope) ?? request.user?.id ?? request.user?._id,
+		organizationId: getOrgId(scope) ?? request.user?.organizationId ?? request.headers?.["x-organization-id"],
+		roles: getUserRoles(scope),
+		orgRoles: getOrgRoles(scope)
+	};
+}
 /** Default public scope — used as initial decoration value */
 const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
 /** Default authenticated scope — used when user is logged in but no org */
 const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
 //#endregion
-export { getTeamId as a, hasOrgAccess as c, isMember as d, getOrgRoles as i, isAuthenticated as l, PUBLIC_SCOPE as n, getUserId as o, getOrgId as r, getUserRoles as s, AUTHENTICATED_SCOPE as t, isElevated as u };
+export { getOrgRoles as a, getUserRoles as c, isElevated as d, isMember as f, getOrgId as i, hasOrgAccess as l, PUBLIC_SCOPE as n, getTeamId as o, getOrgContext as r, getUserId as s, AUTHENTICATED_SCOPE as t, isAuthenticated as u };

package/dist/{types-BJmgxNbF.d.mts → types-ByCPlfZ1.d.mts}

@@ -1,4 +1,4 @@
-import { Lt as ResourceDefinition } from "./interface-DGmPxakH.mjs";
+import { Bt as ResourceDefinition } from "./interface-BnNjdl33.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts

package/dist/{types-Dt0-AI6E.d.mts → types-Guk83PDz.d.mts}

@@ -1,5 +1,5 @@
-import { n as ElevationOptions } from "./elevation-Ca_yveIO.mjs";
-import { h as Authenticator } from "./interface-DGmPxakH.mjs";
+import { n as ElevationOptions } from "./elevation-C_taLQrM.mjs";
+import { g as Authenticator } from "./interface-BnNjdl33.mjs";
 import { t as ExternalOpenApiPaths } from "./externalPaths-DpO-s7r8.mjs";
 import { i as CacheStore } from "./interface-D_BWALyZ.mjs";
 import { r as QueryCachePluginOptions } from "./queryCachePlugin-DcmETvcB.mjs";

package/dist/utils/index.d.mts

@@ -1,5 +1,5 @@
-import { G as ParsedQuery, U as OpenApiSchemas, X as QueryParserInterface, l as AnyRecord } from "../interface-DGmPxakH.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createError, i as ForbiddenError, l as ServiceUnavailableError, n as ConflictError, o as OrgAccessDeniedError, p as isArcError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CPpvPHT0.mjs";
+import { K as ParsedQuery, W as OpenApiSchemas, Z as QueryParserInterface, l as AnyRecord } from "../interface-BnNjdl33.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CcVbl1-T.mjs";
 import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-JP2GdJ4b.mjs";
 import { FastifyInstance } from "fastify";
 

package/dist/utils/index.mjs

@@ -1,7 +1,7 @@
 import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
 import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
 import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-Dc0WhlIl.mjs";
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createError, f as isArcError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-rxhfP7Hf.mjs";
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-NoQKsbAT.mjs";
 import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DjzHpFam.mjs";
 import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, defineCompensation, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -220,7 +220,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.4.3",
+    "@classytic/mongokit": ">=3.5.0",
     "@classytic/streamline": ">=2.0.0",
     "@fastify/cors": "^11.0.0",
     "@fastify/helmet": "^13.0.0",
@@ -244,7 +244,7 @@
     "fastify-raw-body": "^5.0.0",
     "ioredis": "^5.0.0",
     "mongodb": "^6.0.0 || ^7.0.0",
-    "mongoose": "^8.0.0 || ^9.0.0",
+    "mongoose": ">=9.0.0",
     "pino-pretty": "^13.0.0",
     "zod": "^4.0.0"
   },
@@ -337,7 +337,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "^3.4.3",
+    "@classytic/mongokit": "^3.5.2",
     "@fastify/jwt": "^10.0.0",
     "@fastify/multipart": "^9.0.0",
     "@fastify/type-provider-typebox": "^6.0.0",
@@ -349,6 +349,7 @@
     "@vitest/coverage-v8": "^3.2.4",
     "fastify-raw-body": "^5.0.0",
     "jsonwebtoken": "^9.0.0",
+    "knip": "^6.3.0",
     "mongodb": "^7.1.0",
     "mongodb-memory-server": "^11.0.1",
     "tsdown": "^0.21.7",

package/skills/arc/SKILL.md

@@ -314,6 +314,26 @@ const app = await createApp({
 
 ## Hooks
 
+**Inline on resource (recommended):**
+
+```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); },
+    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); },
+  },
+});
+```
+
+`ResourceHookContext`: `{ data, user?, meta? }` — `data` is the document, `meta` has `id` and `existing` (for update/delete).
+
+**App-level (cross-resource):**
+
 ```typescript
 import { createHookSystem, beforeCreate, afterUpdate } from '@classytic/arc/hooks';
 
@@ -360,7 +380,7 @@ 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):**
+**Custom query parser (e.g., MongoKit >=3.4.5 for $lookup, whitelists, MCP auto-derive):**
 
 ```typescript
 import { QueryParser } from '@classytic/mongokit';
@@ -368,11 +388,16 @@ import { QueryParser } from '@classytic/mongokit';
 defineResource({
   name: 'product',
   adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
-  queryParser: new QueryParser(),  // enables lookup, advanced populate, keyset pagination
+  queryParser: new QueryParser({
+    allowedFilterFields: ['status', 'category', 'orgId'],  // whitelist filter fields
+    allowedSortFields: ['createdAt', 'price'],              // whitelist sort fields
+    allowedOperators: ['eq', 'gte', 'lte', 'in'],          // whitelist operators
+  }),
+  // MCP auto-derives filterableFields from queryParser — no duplication needed
   schemaOptions: {
     query: {
-      allowedPopulate: ['category', 'brand'],     // whitelist populate paths
-      allowedLookups: ['categories', 'brands'],   // whitelist lookup collections
+      allowedPopulate: ['category', 'brand'],
+      allowedLookups: ['categories', 'brands'],
     },
   },
 });
@@ -381,10 +406,14 @@ defineResource({
 ## Error Classes
 
 ```typescript
-import { ArcError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError } from '@classytic/arc';
-throw new NotFoundError('Product not found');  // 404
+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 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.
+
 ## Compensating Transaction
 
 In-process rollback for multi-step operations. Not a distributed saga — use Temporal/Streamline for that.
@@ -474,6 +503,35 @@ src/resources/order/
 
 Generate: `arc generate resource order --mcp` | Wire: `extraTools: [fulfillOrderTool]`
 
+**DX helpers** (v2.4.4):
+
+```typescript
+// Typed request for wrapHandler: false 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; }
+
+// Response envelope — no manual { success, data } wrapping
+import { envelope } from '@classytic/arc';
+reply.send(envelope(data, { total: 100 }));
+
+// Canonical org extraction — replaces 19 duplicated patterns
+import { getOrgContext } from '@classytic/arc/scope';
+const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
+
+// Domain errors with auto HTTP status mapping
+import { createDomainError } from '@classytic/arc';
+throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+
+// Resource lifecycle hook — wire singletons during registration
+defineResource({ name: 'notification', onRegister: (f) => setSseManager(f.sseManager) });
+
+// SSE auth — preAuth runs BEFORE auth middleware (EventSource can't set headers)
+additionalRoutes: [{ preAuth: [(req) => { req.headers.authorization = `Bearer ${req.query.token}`; }] }]
+
+// SSE streaming — auto headers + bypasses response wrapper
+additionalRoutes: [{ streamResponse: true, handler: async (req, reply) => reply.send(stream) }]
+```
+
 ## Subpath Imports
 
 ```typescript

package/skills/arc/references/mcp.md

@@ -429,3 +429,138 @@ await app.register(mcpPlugin, {
 - `DELETE /mcp` — terminates session
 
 Sessions: lazily created, TTL-cached, LRU-evicted at max capacity, auto-cleaned on shutdown.
+
+## Health Endpoint
+
+`GET /mcp/health` — no MCP protocol needed, plain JSON:
+
+```json
+{
+  "status": "ok",
+  "mode": "stateless",
+  "tools": 11,
+  "resources": 2,
+  "toolNames": ["list_products", "get_product", ...],
+  "sessions": null
+}
+```
+
+Use to verify the MCP server is alive before configuring Claude CLI.
+
+## DX Helpers (v2.4.4)
+
+### ArcRequest — Typed Fastify Request
+
+For `wrapHandler: false` routes, use `ArcRequest` instead of `(req as any).user`:
+
+```typescript
+import type { ArcRequest } from '@classytic/arc';
+
+handler: async (req: ArcRequest, reply) => {
+  req.user?.id;                    // typed
+  req.scope.organizationId;        // typed (when member)
+  req.signal;                      // AbortSignal (Fastify 5 built-in)
+}
+```
+
+### envelope() — Response Helper
+
+```typescript
+import { envelope } from '@classytic/arc';
+
+handler: async (req, reply) => {
+  const data = await service.getResults();
+  return reply.send(envelope(data));
+  // → { success: true, data }
+  return reply.send(envelope(data, { total: 100, page: 1 }));
+  // → { success: true, data, total: 100, page: 1 }
+}
+```
+
+### getOrgContext() — Canonical Org Extraction
+
+Eliminates duplicated `req.user.organizationId || req.headers['x-organization-id']` patterns:
+
+```typescript
+import { getOrgContext } from '@classytic/arc/scope';
+
+handler: async (req, reply) => {
+  const { userId, organizationId, roles, orgRoles } = getOrgContext(req);
+  // Works regardless of auth type (JWT, Better Auth, custom)
+}
+```
+
+### createDomainError() — Error Factory
+
+Eliminates manual `if (err.code) return status` mapping:
+
+```typescript
+import { createDomainError } from '@classytic/arc';
+
+throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
+throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
+throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
+// Arc's error handler auto-maps statusCode to HTTP response
+```
+
+### onRegister — Resource Lifecycle Hook
+
+Called during plugin registration with the scoped Fastify instance:
+
+```typescript
+defineResource({
+  name: 'notification',
+  onRegister: (fastify) => {
+    setSseManager(fastify.sseManager);
+  },
+})
+```
+
+### preAuth — Pre-Auth Handlers for SSE/WebSocket
+
+Run before auth middleware. Use for promoting `?token=` to `Authorization` header (EventSource can't set headers):
+
+```typescript
+additionalRoutes: [{
+  method: 'GET',
+  path: '/stream',
+  wrapHandler: false,
+  permissions: requireAuth(),
+  preAuth: [(req) => {
+    const token = req.query?.token;
+    if (token) req.headers.authorization = `Bearer ${token}`;
+  }],
+  handler: sseHandler,
+}]
+```
+
+### streamResponse — SSE Route Flag
+
+Auto-sets SSE headers and bypasses Arc's response wrapper:
+
+```typescript
+additionalRoutes: [{
+  method: 'POST',
+  path: '/stream',
+  streamResponse: true,        // SSE headers + no { success, data } wrapper
+  permissions: requireAuth(),
+  handler: async (request, reply) => {
+    const { stream } = await generateStream({ abortSignal: request.signal });
+    return reply.send(stream);
+  },
+}]
+```
+
+## Test Coverage
+
+165 test files, 2439 tests. MCP-specific:
+
+| Test File | Tests | Covers |
+|-----------|-------|--------|
+| `mcp-auth-e2e.test.ts` | 16 | All auth modes, multi-tenancy, permission filters, async permissions |
+| `mcp-dx-features.test.ts` | 14 | include, names, prefix, disableDefaultRoutes, mcpHandler, guards, CRUD lifecycle |
+| `resourceToTools.test.ts` | 12 | Tool generation, annotations, field hiding, soft delete |
+| `createMcpServer.test.ts` | 10 | Server creation, tool registration, InMemoryTransport |
+| `guards.test.ts` | 8 | requireAuth, requireOrg, requireRole, customGuard, composition |
+| `dx-features.test.ts` | 17 | envelope, getOrgContext, createDomainError, onRegister, preAuth, streamResponse |
+| Others | 32 | fieldRulesToZod, defineTool, definePrompt, buildRequestContext, sessionCache, authCache |