@classytic/arc 2.15.4 → 2.16.0

package/skills/arc/references/auth.md

@@ -511,18 +511,30 @@ permissions: { list: acl.canAction('product', 'read') }
 - Supports `*` wildcard for resource/action
 - Cache failures fail open to resolver
 
-## Org Guards
+## Org-Scoped Permission Checks
 
 ```typescript
-import { orgGuard, requireOrg, requireOrgRole } from '@classytic/arc/org';
+import { allowPublic, requireAuth, requireOrgRole } from '@classytic/arc/permissions';
 
-// Require org context
-fastify.get('/invoices', { preHandler: [fastify.authenticate, requireOrg()] }, handler);
-
-// Require specific org role
-fastify.post('/invoices', { preHandler: [fastify.authenticate, requireOrgRole('admin')] }, handler);
+// Resource-level permission check on the active org's member.role
+defineResource({
+  name: 'invoice',
+  permissions: {
+    list: requireAuth(),
+    create: requireOrgRole('admin', 'owner'),
+  },
+});
 ```
 
+The 2.16 release removed the legacy `@classytic/arc/org` REST plugin
+and its `orgGuard` / `requireOrg` middleware (zero verified consumers).
+The PermissionCheck variant — `requireOrgRole` from
+`@classytic/arc/permissions` — is the canonical path: it composes with
+`anyOf` / `allOf`, integrates with the resource pipeline, and reads
+`request.scope.orgRoles` (set by auth adapters). For preHandler-style
+org enforcement on custom routes outside a resource, build a one-line
+preHandler that throws if `getOrgId(request.scope)` is missing.
+
 ## Request Scope
 
 ```typescript

package/skills/arc-code-review/SKILL.md

@@ -84,7 +84,7 @@ One `defineResource()` call **replaces all of these** in a typical Fastify servi
 ```markdown
 # Arc Convention Audit — <project-name>
 
-**Arc version:** 3.0.x · **Mongokit:** <version or "not installed"> · **Sqlitekit:** <version or "n/a"> · **Date:** <YYYY-MM-DD>
+**Arc version:** 2.16.x · **Mongokit:** <version or "not installed"> · **Sqlitekit:** <version or "n/a"> · **Date:** <YYYY-MM-DD>
 **Files scanned:** <N> · **Findings:** <N critical · <N high · <N medium · <N low>
 
 ## Executive summary

package/skills/arc-code-review/references/arc-cheatsheet.md

@@ -1,168 +1,93 @@
-# Arc Cheatsheet — what arc provides, in one page
+# Arc capabilities at a glance — for gap detection
 
-A condensed map of arc's capabilities so you can spot, during audit, what the team is *missing* vs hand-rolling. For deep API, see the existing `skills/arc/SKILL.md` and its `references/`.
+A condensed map of what arc provides, so during audit you can spot what the team is **hand-rolling** vs what's already a one-liner. For full API details, read [`skills/arc/SKILL.md`](../../arc/SKILL.md) and its references.
 
----
+## What arc replaces (audit signals)
 
-## Boot order (FIXED — don't reorder)
+| If you see this in the codebase… | …it should be this arc surface |
+|---|---|
+| 5× `fastify.get/post/patch/delete` for one resource | `defineResource({ name, adapter, permissions, … })` — CRUD auto-generated |
+| `if (req.user.role !== 'admin') return reply.code(403)…` | `permissions: { update: requireRoles(['admin']) }` |
+| `req.user._id`, `req.user.orgId` direct reads | `getUserId(scope)` / `getOrgId(scope)` from `@classytic/arc/scope` |
+| Hand-written `schema: { body, response }` per route | `schemaOptions.fieldRules` |
+| `schema.set('toJSON', { transform })` to strip `password`/`__v` | `fieldRules: { password: { hidden: true } }` |
+| Manual `req.query.filter` parsing, `$or`/`$and` building | `ArcQueryParser` / mongokit `QueryParser` |
+| Hand-maintained `openapi.yaml` | `arc docs ./openapi.json` |
+| `eventBus.emit('product.created', …)` in handler | CRUD events auto-emit; `events: { created: {} }` for custom |
+| `cache.del('products-*')` after mutation | `cache: { tags: ['catalog'] }` — auto-invalidated |
+| Soft-delete: hand-rolled `/deleted` route + `deletedAt` field + restore handler | `presets: ['softDelete']` |
+| `class UserRepository { async create() { Model.create() } }` | `new Repository(Model)` from mongokit |
+| Per-schema `schema.pre('save', …)` for timestamps/validation | mongokit's `timestampPlugin()`, `validationChainPlugin()` |
+| Hand-written MCP tool handlers | `mcpPlugin({ resources })` — auto-generated, same perms |
+| `Model.aggregate([…])` in route handler | `aggregations: { name: defineAggregation({ … }) }` |
+| Custom `withRetry` / `withDLQ` plumbing on events | `RedisStreamTransport` (durable, consumer groups, DLQ) |
+| Hand-rolled idempotency token check | `idempotencyPlugin` (header-based, configurable store) |
+| Manual SCIM provisioning endpoints | `@classytic/arc/scim` — `scimPlugin({ users, groups, bearer })` |
+
+## Boot order (FIXED)
 
 ```
 1. Arc core (security, auth, events)
-2. plugins()                  ← user infra (DB, docs, webhooks)
-3. bootstrap[]                ← domain init (engines, singletons)
-4. resources factory          ← if async: resolved here, after bootstrap
-5. resources[]                ← register each resource
-6. afterResources()           ← post-registration wiring
-7. onReady / onClose          ← Fastify lifecycle hooks
+2. plugins()        ← user infra (DB, docs, webhooks)
+3. bootstrap[]      ← domain init (engines, singletons)
+4. resources (factory runs after bootstrap)
+5. resources[]      ← register each
+6. afterResources()
+7. onReady / onClose
 ```
 
-When auditing: top-level `await ensureCatalogEngine()` in a `*.resource.ts` file = lifecycle violation. Use `resources: async (fastify) => [...]`.
-
----
+**Lifecycle smell:** top-level `await ensureCatalogEngine()` in a `*.resource.ts` file. Fix: pass `resources` as `async (fastify) => [...]` so it runs after `bootstrap[]`.
 
-## `createApp()` essentials
-
-```typescript
-const app = await createApp({
-  preset: 'production',                     // production | development | testing | edge
-  runtime: 'memory',                        // memory (default) | distributed
-  auth: { type: 'jwt', jwt: { secret } },   // | 'betterAuth' | 'custom' | false
-  resources: [resource1, resource2],        // OR async (fastify) => [...]
-  arcPlugins: { events: true, queryCache: false, sse: false, caching: true },
-  stores: { events: ..., queryCache: ..., idempotency: ... },  // distributed only
-  cors: { origin: [...], credentials: true },
-  helmet: true, rateLimit: { max: 100 },
-  resourcePrefix: '/api/v1',
-  bootstrap: [async () => { ... }],
-  afterResources: async (app) => { ... },
-});
-```
-
----
-
-## `defineResource()` — full surface
+## defineResource — full surface
 
 ```typescript
 defineResource({
-  name: 'product',                  // required
-  adapter: createMongooseAdapter({ model, repository, schemaGenerator? }),  // required
-  controller?: new MyController(),  // optional — auto-built if omitted
-  permissions: {                    // required
-    list, get, create, update, delete: PermissionCheck,
-  },
-  presets?: ['softDelete', { name: 'multiTenant', tenantField: 'orgId' }, ...],
-  schemaOptions?: {
-    fieldRules: { [field]: FieldRuleEntry },
-    query: { allowedPopulate, allowedLookups, filterableFields },
-  },
-  routes?: [{ method, path, handler, permissions, raw?, mcp?, summary? }],
-  actions?: { [name]: { handler, permissions?, schema?, mcp?, description? } },
-  actionPermissions?: PermissionCheck,
-  hooks?: { beforeCreate, afterCreate, beforeUpdate, afterUpdate, beforeDelete, afterDelete },
-  events?: { created: {}, updated: {}, deleted: {}, [custom]: { description?, schema? } },
-  cache?: { staleTime, gcTime, tags, invalidateOn?, list?, byId? },
-  routeGuards?: [preHandlerFn],
-  middlewares?: { create: [multipartBody(...)], ... },
-  pipe?: { create: [guard(...), transform(...), intercept(...)] },
-  rateLimit?: { max, timeWindow },
-  tenantField?: string | false,
-  idField?: string,
-  prefix?: string, skipGlobalPrefix?: boolean,
-  queryParser?: QueryParserInterface,
-  onFieldWriteDenied?: 'reject' | 'strip',
-  audit?: boolean | { operations: [...] },
-  displayName?: string, module?: string,
+  name: 'product',                                  // required
+  adapter,                                          // required — from kit's /adapter subpath
+  controller?,                                      // optional — auto-built if omitted
+  permissions: { list, get, create, update, delete },
+  presets?: [...],
+  schemaOptions?: { fieldRules, query },
+  routes?, actions?, actionPermissions?,
+  hooks?, events?, cache?,
+  routeGuards?, middlewares?, pipe?,
+  rateLimit?, tenantField?, idField?,
+  prefix?, skipGlobalPrefix?,
+  queryParser?, onFieldWriteDenied?,
+  audit?, mcp?,                                     // mcp: false to exclude from MCP tool gen
+  displayName?, module?,
+  onTenantDelete?,                                  // GDPR cascade strategy
 });
 ```
 
-### `FieldRuleEntry` flags
-
-| 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`. |
-
-Mongoose model-level constraints take precedence; `fieldRules` supplements.
+## Permissions
 
----
-
-## Permissions — combinators
-
-From `@classytic/arc`:
 ```typescript
-allowPublic()                    // always grant
-requireAuth()                    // any authenticated user
-requireRoles(['admin', 'editor'])// platform OR org roles
-requireOwnership('userId')       // row-level: filters → { userId: scope.userId }
-requireOrgMembership()           // member | service | elevated
-requireOrgRole(['admin'])        // human-only role within org
-requireTeamMembership()
-requireServiceScope('jobs:bulk-write')   // OAuth-style API-key scopes
-requireScopeContext('branchId')          // app-defined dimensions
-requireOrgInScope(targetId)              // parent-child org hierarchy
-allOf(check1, check2, ...)
-anyOf(check1, check2, ...)
-not(check)
-when(condition, ifTrue, ifFalse)
-denyAll()
+allowPublic()                              requireOrgRole(['admin'])
+requireAuth()                              requireTeamMembership()
+requireRoles(['admin'])                    requireServiceScope('jobs:bulk')
+requireOwnership('userId')                 requireScopeContext('branchId')
+requireOrgMembership()                     requireOrgInScope(targetId)
+allOf(...) · anyOf(...) · not(...) · when(...) · denyAll()
 createDynamicPermissionMatrix({ resolveRolePermissions, cacheStore })
 ```
 
-Convenience bundles: `publicRead()`, `publicReadAdminWrite()`, `adminOnly()`, `ownerWithAdminBypass()`.
-
-`PermissionCheck` returns `boolean | { granted, reason?, filters?, scope? }`. `filters` flow into the repo query (row-level ABAC). `scope` stamps attributes downstream.
-
-### Field-level
-```typescript
-import { fields } from '@classytic/arc';
-fieldRules: {
-  password: fields.hidden(),
-  salary:   fields.visibleTo(['admin', 'hr']),
-  role:     fields.writableBy(['admin']),
-  email:    fields.redactFor(['viewer'], '***'),
-}
-```
+Returns `boolean | { granted, reason?, filters?, scope? }`. `filters` propagate into the repo query (row-level ABAC).
 
----
+Field-level: `fields.hidden()`, `fields.visibleTo([...])`, `fields.writableBy([...])`, `fields.redactFor([...], '***')`.
 
-## RequestScope — five kinds
+## RequestScope
 
 ```typescript
 type RequestScope =
   | { kind: 'public' }
   | { kind: 'authenticated'; userId?; userRoles? }
   | { kind: 'member';   userId?; userRoles; organizationId; orgRoles; teamId?; context?; ancestorOrgIds? }
-  | { kind: 'service';  clientId; organizationId; scopes?; context?; ancestorOrgIds? }
+  | { kind: 'service';  clientId; organizationId; scopes?; context?; ancestorOrgIds?; mandate?; dpopJkt? }
   | { kind: 'elevated'; userId?; organizationId?; elevatedBy; context?; ancestorOrgIds? };
 ```
 
-**Always read via accessors from `@classytic/arc/scope`:**
-```typescript
-isPublic, isAuthenticated, isMember, isService, isElevated, hasOrgAccess,
-getUserId, getUserRoles, getOrgId, getOrgRoles, getTeamId, getClientId,
-getServiceScopes, getScopeContext, getScopeContextMap,
-getAncestorOrgIds, isOrgInScope, getRequestScope,
-requireUserId, requireClientId,                                // throw 401 (UnauthorizedError) if absent
-requireOrgId, requireTeamId,                                   // throw 403 (OrgRequiredError) if absent
-createTenantKeyGenerator,
-```
-
-| Helper | `member` | `service` | `elevated` |
-|---|---|---|---|
-| `requireOrgMembership()` | ✅ | ✅ | ✅ |
-| `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 |
-
----
+Always access via `@classytic/arc/scope`: `getUserId`, `getOrgId`, `hasOrgAccess`, `requireOrgId` (throws 403), `requireUserId` (throws 401), `getScopeContext`, `isOrgInScope`. **Never read `scope.organizationId` directly.**
 
 ## Presets
 
@@ -171,237 +96,90 @@ createTenantKeyGenerator,
 | `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) | — |
+| `ownedByUser` | (middleware) | `{ ownerField }` |
+| `multiTenant` | (middleware) | `{ tenantField }` or `{ tenantFields: [...] }` |
+| `audited` | (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
-presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
-```
-
----
-
-## Hooks
-
-Inline (per-resource):
-```typescript
-hooks: {
-  beforeCreate: async (ctx) => { /* ctx.data, ctx.user, ctx.meta */ },
-  afterCreate:  async (ctx) => { ... },
-  beforeUpdate: async (ctx) => { /* ctx.meta.existing has the pre-image */ },
-  afterUpdate:  async (ctx) => { ... },
-  beforeDelete: async (ctx) => { ... },
-  afterDelete:  async (ctx) => { ... },
-}
-```
-
-App-level (cross-resource):
-```typescript
-import { createHookSystem, beforeCreate, afterUpdate } from '@classytic/arc/hooks';
-
-const hooks = createHookSystem();
-beforeCreate(hooks, 'product', async (ctx) => { ctx.data.slug = slugify(ctx.data.name); });
-```
-
-Pipeline (for finer control):
-```typescript
-import { guard, transform, intercept } from '@classytic/arc/pipeline';
-
-pipe: {
-  create: [
-    guard('verified', async (ctx) => ctx.user?.verified === true),
-    transform('inject', async (ctx) => { ctx.body.createdBy = ctx.user._id; }),
-  ],
-}
-```
-
----
-
-## Events
+| `filesUpload` | `POST /upload`, `GET /:id`, `DELETE /:id` | `{ storage, sanitizeFilename?, … }` |
+| `search` | `POST /search`, `/search-similar`, `/embed` | `{ repository?, search?, similar?, embed? }` |
 
-```typescript
-events: { created: {}, updated: {}, deleted: {}, custom: { description, schema } }
-```
-
-CRUD events auto-emit. Custom: `await req.fastify.events.publish(eventType, payload)`. Subscribe: `app.events.subscribe('order.*', handler)`.
+## fieldRules flags
 
-**Transports:** `MemoryEventTransport` · `RedisEventTransport` (pub/sub fire-and-forget) · `RedisStreamTransport` (durable, at-least-once, consumer groups, DLQ) · `EventOutbox` (transactional outbox).
+`systemManaged` · `preserveForElevated` · `immutable` / `immutableAfterCreate` · `optional` · `nullable` · `hidden` · `minLength` / `maxLength` / `min` / `max` / `pattern` / `enum` · `description`.
 
----
-
-## Cache (QueryCache)
+## Aggregations
 
 ```typescript
-cache: {
-  staleTime: 30, gcTime: 300, tags: ['catalog'],
-  invalidateOn: { 'category.*': ['catalog'] },
-  list:  { staleTime: 60 },
-  byId:  { staleTime: 10 },
-}
-```
-Modes: `memory` (default) | `distributed` (`stores.queryCache: RedisCacheStore`). Response: `x-cache: HIT | STALE | MISS`.
-
----
-
-## Aggregations (declarative dashboards)
-
-```typescript
-import { defineAggregation } from '@classytic/arc';
-
 aggregations: {
   byMethod: defineAggregation({
     groupBy: 'method',
     measures: { total: 'sum:amount', count: 'count' },
-    sort: { total: -1 },
-    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
-    permissions: canViewRevenue(),
-  }),
-  byDay: defineAggregation({
-    dateBuckets: { day: { field: 'createdAt', interval: 'day' } },
-    groupBy: 'flow',
-    measures: { total: 'sum:amount' },
     requireDateRange: { field: 'createdAt', maxRangeDays: 365 },
+    cache: { staleTime: 60, swr: true, tags: ['revenue'] },
     permissions: canViewRevenue(),
   }),
 }
 ```
 
-Registers `GET /:prefix/aggregations/:name` per entry. Same permissions, OpenAPI, MCP tool, cache + tag invalidation as CRUD. Tenant flows via the kit's multi-tenant plugin (string → ObjectId casting handled by the kit, **not** by hand). Caller filters via query string (`?status=verified&createdAt[gte]=...`) compose with the declaration. Safety: `requireFilters`, `requireDateRange`, `maxGroups`. **Anti-pattern:** custom routes calling `Model.aggregate([...])` directly — see anti-patterns §33.
-
----
+Registers `GET /:prefix/aggregations/:name`. Same perms + cache + tag invalidation + MCP tool as CRUD. **Anti-pattern:** custom routes calling `Model.aggregate([...])` directly.
 
 ## CLI
 
 ```bash
-arc init my-api --mongokit --jwt --ts          # scaffold (also: --custom, --better-auth, --multi)
-arc generate resource product                   # generate resource files
-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          # list registered resources
-arc describe product                            # detail a resource's routes/actions/permissions
-arc doctor                                      # diagnose env
-```
-
-`.arcrc`: project config used by `arc generate`. Set `"mcp": true` to always emit `.mcp.ts` alongside resources.
-
-Generated layout:
-```
-src/resources/{name}/
-  {name}.model.ts          # Mongoose schema (with --mongokit)
-  {name}.repository.ts     # Repository class (mongokit Repository)
-  {name}.resource.ts       # defineResource() config
-  {name}.mcp.ts            # (optional) custom MCP tools
-```
-
-Naming: kebab input (`org-profile`) → PascalCase class (`OrgProfile`), camelCase var (`orgProfile`), kebab files.
-
----
-
-## MCP
-
-```typescript
-import { mcpPlugin } from '@classytic/arc/mcp';
-
-await app.register(mcpPlugin, {
-  resources: [productResource, orderResource],
-  auth: false,                              // | getAuth() | custom function
-  exclude: ['credential'],
-  overrides: { product: { operations: ['list', 'get'] } },
-});
-
-// Stateful (server-initiated messages)
-await app.register(mcpPlugin, { resources, stateful: true, sessionTtlMs: 600000 });
+arc init my-api --mongokit --better-auth --ts
+arc generate resource product [--mcp]
+arc docs ./openapi.json --entry ./dist/index.js
+arc introspect --entry ./dist/index.js
+arc describe ./dist/resources.js --json
+arc doctor
 ```
 
-Auto-generates 5 CRUD tools per resource + custom routes + actions. Permissions and field rules carry through. Connect via `claude mcp add --transport http my-api http://localhost:3000/mcp`.
-
-Custom tools alongside resources: co-locate `order.mcp.ts`, wire via `extraTools: [...]`. AI SDK bridge: `buildMcpToolsFromBridges([bridge])`.
-
----
+Generated layout: `src/resources/{name}/{name}.{model,repository,resource,mcp}.ts`. Naming: `org-profile` (kebab input) → `OrgProfile` (class) / `orgProfile` (var) / `org-profile.*.ts` (files).
 
 ## Adapters
 
-In arc 2.12, every kit-specific adapter ships from its kit's `/adapter` subpath. Arc has zero kit-bound adapters. The cross-framework contract lives in `@classytic/repo-core/adapter`.
+Every kit ships its adapter from `@classytic/<kit>/adapter`. Arc has **zero** kit-bound adapters in `src/` since 2.12.
 
 ```typescript
-// Mongoose — from mongokit
 import { createMongooseAdapter } from '@classytic/mongokit/adapter';
-import { buildCrudSchemasFromModel, Repository } from '@classytic/mongokit';
+import { createDrizzleAdapter }  from '@classytic/sqlitekit/adapter';
+import { createPrismaAdapter }   from '@classytic/prismakit/adapter';
 
-const adapter = createMongooseAdapter({
-  model: ProductModel,
-  repository: new Repository(ProductModel),
-  schemaGenerator: buildCrudSchemasFromModel,
-});
-
-// Drizzle — from sqlitekit
-import { createDrizzleAdapter } from '@classytic/sqlitekit/adapter';
-import { buildCrudSchemasFromTable } from '@classytic/sqlitekit';
-
-// Prisma — from prismakit
-import { createPrismaAdapter } from '@classytic/prismakit/adapter';
+import type { DataAdapter, RepositoryLike } from '@classytic/repo-core/adapter';
+// RepositoryLike<TDoc> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>
 ```
 
-Custom adapter: implement `DataAdapter` / `MinimalRepo<TDoc>` from `@classytic/repo-core/adapter` (5-method floor). Any kit (mongokit, sqlitekit, prismakit, future pgkit, custom) plugs in identically. `RepositoryLike<TDoc> = MinimalRepo<TDoc> & Partial<StandardRepo<TDoc>>` — arc feature-detects optional methods at call sites. Arc re-exports `RepositoryLike`; the rest of the contract types come from `@classytic/repo-core/adapter` directly.
-
-| Plugin | Required methods on repo |
+| Plugin | Required repo methods |
 |---|---|
 | `auditPlugin` | `create`, `findAll` |
 | `idempotencyPlugin` | `getOne`, `deleteMany`, `findOneAndUpdate` |
 | `EventOutbox` | `create`, `getOne`, `findAll`, `deleteMany`, `findOneAndUpdate` |
 
----
-
-## Plugins (`@classytic/arc/plugins`)
-
-```typescript
-import {
-  healthPlugin, gracefulShutdownPlugin, ssePlugin,
-  metricsPlugin, versioningPlugin,
-} from '@classytic/arc/plugins';
-import { tracingPlugin } from '@classytic/arc/plugins/tracing';
-import { auditPlugin } from '@classytic/arc/audit';
-import { idempotencyPlugin } from '@classytic/arc/idempotency';
-import { jobsPlugin } from '@classytic/arc/integrations/jobs';
-import { websocketPlugin } from '@classytic/arc/integrations/websocket';
-import { eventGatewayPlugin } from '@classytic/arc/integrations/event-gateway';
-import { webhookPlugin } from '@classytic/arc/integrations/webhooks';
-```
-
----
-
-## Subpath imports (tree-shakeable)
+## Subpath imports — audit signals
 
 ```typescript
-import { defineResource, BaseController, allowPublic, requireRoles } from '@classytic/arc';
-import { createApp, loadResources } from '@classytic/arc/factory';
-import { MemoryCacheStore, RedisCacheStore, QueryCache } from '@classytic/arc/cache';
-import { createBetterAuthAdapter } from '@classytic/arc/auth';
-import { eventPlugin, EventOutbox } from '@classytic/arc/events';
-import { RedisEventTransport } from '@classytic/arc/events/redis';
-import { mcpPlugin, defineTool } from '@classytic/arc/mcp';
-import { bulkPreset, multiTenantPreset } from '@classytic/arc/presets';
-import { isMember, getUserId, getOrgId, hasOrgAccess } from '@classytic/arc/scope';
-import { createTestApp, expectArc } from '@classytic/arc/testing';
-import { multipartBody } from '@classytic/arc/middleware';
-import { defineGuard, withCompensation, CircuitBreaker, createStateMachine } from '@classytic/arc/utils';
+import { defineResource, BaseController, allowPublic }    from '@classytic/arc';
+import { createApp, loadResources }                        from '@classytic/arc/factory';
+import { MemoryCacheStore, RedisCacheStore, QueryCache }   from '@classytic/arc/cache';
+import { eventPlugin, EventOutbox }                        from '@classytic/arc/events';
+import { RedisEventTransport, RedisStreamTransport }       from '@classytic/arc/events/redis-stream';
+import { mcpPlugin, defineTool }                           from '@classytic/arc/mcp';
+import { bulkPreset, multiTenantPreset }                   from '@classytic/arc/presets';
+import { isMember, getUserId, getOrgId, requireOrgId }     from '@classytic/arc/scope';
+import { createTestApp, expectArc }                        from '@classytic/arc/testing';
+import { multipartBody }                                   from '@classytic/arc/middleware';
+import { defineGuard, withCompensation }                   from '@classytic/arc/utils';
 ```
 
-Audit signal: a project importing only from the `@classytic/arc` root barrel is probably under-using subpath features (caching, scope accessors, presets, MCP, testing harness).
-
----
+A project importing only from the root barrel is probably under-using subpath features (caching, scope accessors, presets, MCP, testing harness).
 
-## Non-negotiable conventions (mirror in client projects)
+## Non-negotiables (mirror in client projects)
 
 1. No `console.log` in `src/` (except `cli/`) — use logger.
-2. No `mongoose`/`drizzle-orm`/`@prisma/client` imports anywhere in the host outside the host's adapter wiring file. Every kit-specific adapter factory (`createMongooseAdapter` / `createDrizzleAdapter` / `createPrismaAdapter`) MUST come from the kit's `/adapter` subpath, never from `@classytic/arc` — the `@classytic/arc/adapters` subpath was removed in arc 2.12.
+2. No `mongoose` / `drizzle-orm` / `@prisma/client` imports outside the host's adapter wiring file.
 3. No `any` — use `unknown`. No `@ts-ignore` — fix the type.
-4. No default exports in `src/` (knip enforces in arc; recommend in clients).
-5. Always read `request.user` via guard or use `@classytic/arc/scope` accessors.
+4. No default exports in `src/` (knip enforces in arc).
+5. Always read `request.user` via guard, or use `@classytic/arc/scope` accessors.
 6. Always use `req.rawBody` for `verifySignature(...)`, never parsed body.
-7. Set headers in `onRequest` or `preSerialization`, never `onSend`.
+7. Set response headers in `onRequest` or `preSerialization`, never `onSend`.
 8. `request.user: Record<string, unknown> | undefined` — required property, NOT optional.