@classytic/arc 2.11.4 → 2.13.1

package/skills/arc/references/scim.md

@@ -0,0 +1,247 @@
+# SCIM 2.0 — IdP Provisioning
+
+Arc ships a SCIM 2.0 plugin (`@classytic/arc/scim`) that auto-mounts `/scim/v2/Users` + `/scim/v2/Groups` REST endpoints and translates SCIM wire shapes onto the canonical **repository contract** (`@classytic/repo-core/adapter`). Arc does NOT introduce a SCIM-specific repository subset, controller pipeline, or storage tier — it composes with what kits already expose.
+
+## Honest architecture (what SCIM actually is)
+
+**SCIM is a thin REST layer over the kit's `RepositoryLike`.** Whatever plugins you wire at the kit/repo layer (audit, multi-tenant, field-policy, etc.) fire for SCIM exactly the way they fire for arc REST, because **both surfaces call the same repository methods**.
+
+```
+SCIM request → arc/scim plugin → resource.adapter.repository.<method> → kit hooks fire
+```
+
+This is NOT what some earlier docs implied. SCIM does not run arc's HTTP controller pipeline (`auth → permissions → preHandlers → controller → hooks → audit`). SCIM authentication is bearer/verify only at the REST edge; everything else (row-level perms, audit trail, hooks) is composed at the kit layer where it already lives.
+
+| Layer | Where it composes | Fires for SCIM? |
+|---|---|---|
+| Bearer / OIDC verify | `scimPlugin({ bearer, verify })` | ✓ at the SCIM edge |
+| Audit trail | `repo.use(auditTrailPlugin())` (mongokit) — kit-specific identifier | ✓ via repo hooks |
+| Multi-tenant scope | `repo.use(multiTenantPlugin)` | ✓ via repo hooks |
+| Field redaction (read) | mongokit's `fieldFilterPlugin` | ✓ on `getAll` / `getById` |
+| Resource hooks | `defineResource({ hooks: { ... } })` | ✗ — those are HTTP-controller hooks; not on the repo path |
+| Per-action permissions | `defineResource({ permissions: { ... } })` | ✗ — same reason; gate at the edge via `verify` |
+
+If you want resource hooks to fire for SCIM writes too, install them as **kit plugins** (`repo.on('before:create', fn)`) rather than `defineResource({ hooks: ... })`. The docs for your kit (mongokit / sqlitekit) cover the hook surface.
+
+## CRUD → repository contract mapping
+
+| SCIM method | Repository call | Notes |
+|---|---|---|
+| `GET /Users` | `repo.getAll({ filters, page, limit, sort })` | Filter parser maps SCIM filter language → query DSL |
+| `GET /Users/:id` | `repo.getById(id)` | |
+| `POST /Users` | `repo.create(data)` | Inbound SCIM body maps onto resource shape via `mapping.attributes` |
+| `PUT /Users/:id` | `repo.bulkWrite([{ replaceOne: { filter, replacement } }])` | **Kit-conditional** — see "Feature gating" below |
+| `PATCH /Users/:id` | `repo.findOneAndUpdate({ id }, ops)` | Operators flow through unchanged (`$set`, `$unset`, `$push`, `$pull`) |
+| `DELETE /Users/:id` | `repo.delete(id)` | |
+
+## Feature gating (honest about what each kit supports)
+
+**SCIM PATCH** translates the RFC 7644 PatchOp body into canonical Mongo-style operators and forwards them to `findOneAndUpdate`. The kit decides what's portable:
+
+| Kit | `$set` / scalar overwrite | `$unset` | `$push` / `$pull` (array mutations) |
+|---|---|---|---|
+| **mongokit** | ✓ | ✓ | ✓ — applied natively |
+| **sqlitekit** | ✓ (compiled to flat column writes) | ✓ | ✗ — JSON columns have no array-op semantics; sqlitekit throws cleanly, SCIM 400s with `scimType: invalidValue` |
+| **prismakit** | ✓ | ✓ | depends on column type |
+| **Custom kit (only `MinimalRepo`)** | ✓ via `update(id, $set)` fallback | ✗ — no `findOneAndUpdate` exposed → SCIM 400 | ✗ → SCIM 400 |
+
+**SCIM PUT** requires `repo.bulkWrite([{ replaceOne }])` OR a top-level `repo.replace(id, doc)`. Kits that expose neither return **HTTP 501** with a clear message — no silent merge into `update(id, partial)` (which would leave omitted fields surviving and violate SCIM PUT semantics).
+
+| Kit | `PUT` (full replace) |
+|---|---|
+| **mongokit** | ✓ via `bulkWrite([{ replaceOne }])` |
+| **sqlitekit** | ✓ via `bulkWrite([{ replaceOne }])` AND `replace(id, doc)` (sqlitekit ≥0.4.0). Routes through `replaceById` (UPDATE with explicit NULLs for omitted columns) so SCIM PUT semantics are honored — omitted fields don't survive. |
+| **prismakit** | varies |
+| **Custom kit (only `MinimalRepo`)** | ✗ — 501 |
+
+If your IdP requires PUT semantics and your kit doesn't expose `bulkWrite`, two options: (1) ask the kit team to add it, (2) configure your IdP to use PATCH instead (Okta / Azure AD both support PATCH-only flows).
+
+## Quick start
+
+```typescript
+import { scimPlugin } from "@classytic/arc/scim";
+
+await app.register(scimPlugin, {
+  users: { resource: userResource },     // your existing arc resource
+  groups: { resource: orgResource },     // optional
+  bearer: process.env.SCIM_TOKEN,        // OR: verify: async (req) => …
+});
+```
+
+That's it. Endpoints mounted: `GET/POST/PUT/PATCH/DELETE /scim/v2/Users[/:id]`, same for `Groups`, plus `ServiceProviderConfig` / `ResourceTypes` / `Schemas` discovery.
+
+## Default mapping (Better Auth aligned)
+
+If you don't override `mapping`, SCIM assumes the BA `user` / `organization` schema:
+
+| SCIM attribute | Backend field |
+|---|---|
+| `id` | `id` |
+| `userName` | `email` |
+| `name.formatted` / `displayName` | `name` |
+| `emails[].value` | `email` (primary) |
+| `active` | `isActive` |
+| `externalId` | `externalId` |
+| `meta.created` | `createdAt` |
+| `meta.lastModified` | `updatedAt` |
+
+For non-BA schemas, override per-attribute:
+
+```typescript
+import { scimPlugin, DEFAULT_USER_MAPPING } from "@classytic/arc/scim";
+
+await app.register(scimPlugin, {
+  users: {
+    resource: userResource,
+    mapping: {
+      attributes: {
+        ...DEFAULT_USER_MAPPING.attributes,
+        userName: "username",
+        "name.familyName": "lastName",
+      },
+    },
+  },
+  bearer: process.env.SCIM_TOKEN,
+});
+```
+
+## Filter language (RFC 7644 §3.4.2.2)
+
+Operators supported: `eq`, `ne`, `co` (contains), `sw` (starts with), `ew` (ends with), `gt`/`ge`/`lt`/`le`, `pr` (present), `and` / `or` / `not`, grouped with `( )`.
+
+Real production filters that work out of the box:
+
+```
+filter=userName eq "alice@acme.com" and active eq true
+filter=externalId eq "ad:f3e9-..."
+filter=meta.lastModified gt "2025-01-01T00:00:00Z"
+```
+
+## Auth — bearer or verify
+
+```typescript
+bearer: process.env.SCIM_TOKEN,                          // simplest
+// OR
+verify: async (request) => {
+  const auth = request.headers.authorization;
+  if (!auth?.startsWith("Bearer ")) return false;
+  const claims = await verifyJwt(auth.slice(7));
+  return claims.scope?.includes("scim:write") ?? false;
+},
+```
+
+Pass exactly one — `bearer` XOR `verify`. The plugin throws at boot if both / neither are configured.
+
+## Observability
+
+Every request emits one `ScimObservedEvent`:
+
+```typescript
+{
+  resourceType: "Users" | "Groups" | "discovery",
+  op: "list" | "get" | "create" | "replace" | "patch" | "delete" | "discovery.<endpoint>",
+  status: number,
+  durationMs: number,
+  scimType?: string,        // SCIM error type when failed
+  path: string,
+}
+```
+
+Wire to your metrics / logging stack via `observe`:
+
+```typescript
+await app.register(scimPlugin, {
+  users: { resource: userResource },
+  bearer: process.env.SCIM_TOKEN,
+  observe: (event) => {
+    metrics.histogram("scim.duration_ms", event.durationMs, {
+      op: event.op,
+      status: String(event.status),
+    });
+  },
+});
+```
+
+Default (when `observe` is omitted): `request.log.info({ scim: event }, "scim.request")` — Pino-friendly structured log line.
+
+## Discovery endpoints
+
+Auto-mounted; every IdP probes them during connector setup:
+
+- `/scim/v2/ServiceProviderConfig` — capability advertisement (`patch.supported: true`, `bulk.supported: false`, `oauthbearertoken` auth)
+- `/scim/v2/ResourceTypes` — `User` (always) + `Group` (when `groups` binding present)
+- `/scim/v2/Schemas` — id + name stub (most IdPs treat as a sanity check)
+
+## Error envelope (RFC 7644 §3.12)
+
+Every error response uses the canonical SCIM shape:
+
+```json
+{
+  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
+  "status": "400",
+  "scimType": "invalidFilter",
+  "detail": "Attribute 'xyz' is not filterable"
+}
+```
+
+Content-Type: `application/scim+json` on every response. Parser auto-registered, idempotent on redeclare.
+
+## What's NOT supported (yet)
+
+- **Bulk operations** (`/Bulk`) — most IdPs don't use them; discovery advertises `bulk.supported: false`
+- **EnterpriseUser extension** (`employeeNumber`, `manager`, `costCenter`) — pass-through via `mapping.attributes` works today; first-class extension support lands when a paying customer asks
+- **Schema introspection beyond IDs** — `/Schemas` returns id+name only
+
+## Production checklist
+
+- [ ] Mount on the same host as your REST surface (no separate SCIM service)
+- [ ] Rotate `SCIM_TOKEN` quarterly; use `verify` callback with short-lived JWTs for multi-IdP setups
+- [ ] Wire your kit's audit plugin at the **kit** layer (mongokit: `repo.use(auditTrailPlugin())` from `@classytic/mongokit/plugins`), not via `defineResource({ audit: true })` — only the kit-layer plugin fires for SCIM writes
+- [ ] Test the Okta / Azure AD connector against `playground/enterprise-auth/` before production cutover
+- [ ] Confirm your kit exposes `findOneAndUpdate` (for PATCH operators) and `bulkWrite` (for PUT) — see "Feature gating" above; otherwise pick the IdP flows your kit supports
+
+## sqlitekit gap message — RESOLVED in sqlitekit ≥0.4.0
+
+sqlitekit ≥0.4.0 ships both asks. The original message is preserved below for historical context.
+
+**Status of each ask:**
+
+1. **`bulkWrite([{ replaceOne }])` with full-replace semantics — ✓ shipped.** Routes through `actions/update.replaceById` which UPDATE-with-explicit-NULLs every column omitted from the replacement. Pinned by `tests/integration/replace-and-array-ops.test.ts`. The earlier behavior (silent partial-update) is fixed; SCIM PUT clients now see the contract honored.
+2. **JSON-column array policy — ✓ shipped (option a, refuse cleanly).** `findOneAndUpdate` and `updateMany` throw a clear actionable error on `$push` / `$pull` / `$addToSet` / `$pop` / `$pullAll`, mirroring the refusal `claim()` already shipped. Arc's SCIM plugin translates the throw into `400 Bad Request` with `scimType: invalidValue`.
+3. **Top-level `replace(id, doc)` — ✓ shipped.** Available alongside `bulkWrite([{ replaceOne }])`; arc can feature-detect either.
+
+**Bonus fix:** `findOneAndUpdate` and `updateMany` now also accept raw mongo `$set` / `$unset` / `$inc` / `$setOnInsert` operator records (compiled to flat column writes via the existing `UpdateSpec` path). Previously these silently produced `near "where": syntax error` from Drizzle. SCIM PATCH operator forwarding now works on sqlitekit without an arc-side translation step.
+
+---
+
+### Original gap message (historical)
+
+If your sqlitekit-backed app needs SCIM PUT (full replace) or PATCH array ops (`$push`/`$pull`), the underlying repository needs to expose two ops it currently doesn't:
+
+> **From:** arc 2.13 SCIM consumer
+>
+> **Subject:** `bulkWrite` + JSON-column array operators for SCIM 2.0 PUT / PATCH
+>
+> **Context.** Arc 2.13 ships a SCIM 2.0 plugin that translates IdP requests onto the canonical `@classytic/repo-core/adapter` `RepositoryLike` contract. PATCH uses `findOneAndUpdate(filter, ops)` so operators (`$set` / `$unset` / `$push` / `$pull`) flow through unchanged. PUT uses `bulkWrite([{ replaceOne }])` because full-document replace isn't in `MinimalRepo`. mongokit covers both today; sqlitekit doesn't.
+>
+> **Asks (in priority order):**
+>
+> 1. **`bulkWrite([...])` with `replaceOne` support.** SCIM PUT (full replace) currently 501s on sqlitekit. The contract: `replaceOne: { filter, replacement }` should DELETE then INSERT (or UPDATE all columns) atomically. Other op types (`updateOne`, `deleteOne`) can stub or fan out to existing methods. Returning `{ matchedCount, modifiedCount }` is enough.
+>
+> 2. **Documented JSON-column array policy for `findOneAndUpdate`.** sqlitekit currently rejects `$push` / `$pull` on `text` (JSON) columns. Three reasonable options for the kit team to pick:
+>    - **(a)** Refuse cleanly (current behaviour) — sqlitekit throws; arc 400s with `scimType: invalidValue`. Honest. Document it.
+>    - **(b)** Read-modify-write helper (non-atomic). Reads the JSON, mutates, writes back. Document the non-atomicity for hosts to evaluate.
+>    - **(c)** SQLite `json_insert` / `json_remove` functions. Atomic via SQL; sqlite-version dependent.
+>
+>    arc consumes whatever sqlitekit decides; the SCIM plugin doesn't depend on (b) or (c) being shipped.
+>
+> 3. **Optional: a `replace(id, doc)` top-level convenience.** If the team prefers not to expose `bulkWrite`, a kit-specific `replace(id, doc)` method on `SqliteRepository` would also unlock PUT — arc could feature-detect either path.
+>
+> **No urgency** — SCIM PUT can be substituted with PATCH for most IdPs (Okta / Azure AD support PATCH-only reconciliation modes). This is a "ship when natural" ask, not a blocker for any current consumer.
+
+## See also
+
+- [enterprise-auth.md](enterprise-auth.md) — feature matrix
+- [agent-auth.md](agent-auth.md) — DPoP + capability mandates
+- [`playground/enterprise-auth/`](../../../playground/enterprise-auth/) — runnable smoke

package/skills/arc/references/testing.md

@@ -114,7 +114,7 @@ describe('Product resource — full coverage', () => {
 ## `expectArc(response)` — fluent envelope matchers
 
 ```typescript
-expectArc(res).ok();                         // 200/201, success: true
+expectArc(res).ok();                         // 200/201 with data envelope
 expectArc(res).forbidden();                  // 403, arc error envelope
 expectArc(res).notFound().hasError(/not exist/);
 expectArc(res).validationError().hasData({ fields: ['email'] });

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

@@ -0,0 +1,141 @@
+---
+name: arc-code-review
+description: |
+  Audit a client codebase that has @classytic/arc installed for gaps in arc-convention adoption.
+  Surfaces hand-rolled CRUD/auth/query/cache code that should be one defineResource() call,
+  Mongoose models that should use @classytic/mongokit, manual JSON Schema that should be fieldRules,
+  bypassed RequestScope, missing presets, and other patterns that defeat arc's "less code, more
+  maintainability" promise. Produces a prioritized migration report with before/after recipes.
+  Use when reviewing/auditing a downstream project that depends on @classytic/arc, when the
+  user asks for an "arc audit", "arc gap analysis", "arc migration plan", "why isn't arc helping
+  us", or when refactoring a Fastify/Express service to arc conventions.
+  Triggers: arc audit, arc review, arc gap, arc migration, arc convention check, arc compliance,
+  classytic audit, defineResource refactor, mongoose to mongokit, hand-rolled crud to arc,
+  arc adoption, arc lint, arc smell, arc anti-pattern.
+license: MIT
+metadata:
+  author: Classytic
+tags:
+  - arc
+  - code-review
+  - audit
+  - migration
+  - refactor
+  - fastify
+  - mongoose
+  - mongokit
+  - convention-check
+progressive_disclosure:
+  entry_point:
+    summary: "Audit a client codebase using @classytic/arc for unrealized convention gains. Detect hand-rolled CRUD/auth/query/cache, Mongoose-without-mongokit, bypassed scope, and emit a prioritized migration report."
+    when_to_use: "Reviewing or migrating a project that has arc installed but hasn't adopted defineResource()/presets/permissions/scope/mongokit. Use whenever the user asks 'why isn't arc helping us' or wants a gap analysis."
+    quick_start: "1. Confirm arc/mongokit versions  2. Run detection sweep (references/anti-patterns.md)  3. Score each finding (references/severity.md)  4. Emit report using template below"
+  context_limit: 900
+---
+
+# arc-code-review
+
+Audit skill for client projects that depend on `@classytic/arc`. Detects places where the team is writing code arc would have generated, then emits a prioritized migration plan with concrete before/after diffs.
+
+## When to use
+
+Invoke when:
+- The user asks for an "arc audit", "arc gap analysis", "arc migration plan", or "why isn't arc helping us".
+- A repo `dependsOn @classytic/arc` (or `@classytic/mongokit`) and the conversation is about refactoring, code-review, or onboarding.
+- The user mentions hand-rolled CRUD, manual JSON Schema, raw `req.user` access, manual `Model.find()` in route handlers, or hand-written OpenAPI alongside arc.
+- Migrating a Fastify/Express service to arc conventions.
+
+**Do NOT use** for arc framework development itself — that's the `arc` skill in `skills/arc/`. This skill audits *consumers* of arc.
+
+## Mental model — what arc replaces
+
+One `defineResource()` call **replaces all of these** in a typical Fastify service:
+
+| Hand-rolled today | Arc capability that subsumes it | Reference |
+|---|---|---|
+| 5 × `fastify.get/post/patch/delete` per resource | CRUD auto-generation | [arc-cheatsheet.md](references/arc-cheatsheet.md) |
+| `if (req.user.role !== 'admin')` inside handler | `permissions: { create: requireRoles(['admin']) }` | [anti-patterns.md §4](references/anti-patterns.md) |
+| Manual `req.query.filter` parsing, `$or`/`$and` building | `ArcQueryParser` / mongokit `QueryParser` | [anti-patterns.md §1](references/anti-patterns.md) |
+| Hand-written `schema: { body, response }` per route | `schemaOptions.fieldRules` | [anti-patterns.md §2](references/anti-patterns.md) |
+| `schema.set('toJSON', { transform })` to strip `password`/`__v` | `fieldRules: { password: { hidden: true } }` | [anti-patterns.md §5](references/anti-patterns.md) |
+| Hand-maintained `openapi.yaml` / `swagger.json` | `arc docs ./openapi.json` | [anti-patterns.md §6](references/anti-patterns.md) |
+| `eventBus.emit('product.created', ...)` in handler | `events: { created: {} }` (auto-emitted) | [anti-patterns.md §7](references/anti-patterns.md) |
+| `cache.del('products-*')` after mutation | `cache: { tags: ['catalog'] }` (auto-invalidated) | [anti-patterns.md §8](references/anti-patterns.md) |
+| `req.user._id`, `req.user.orgId` direct access | `getUserId(scope)`, `getOrgId(scope)` from `@classytic/arc/scope` | [anti-patterns.md §9](references/anti-patterns.md) |
+| `import mongoose from 'mongoose'` in route/service files | Adapter-only via `createMongooseAdapter` | [anti-patterns.md §10](references/anti-patterns.md) |
+| Soft-delete: `/deleted` route + `deletedAt` field + restore handler | `presets: ['softDelete']` | [anti-patterns.md §14](references/anti-patterns.md) |
+| `class UserRepository { async create() { Model.create() } }` | `new Repository(Model)` (mongokit) | [mongokit-migration.md](references/mongokit-migration.md) |
+| Per-schema `schema.pre('save', ...)` for timestamps/validation | `timestampPlugin()`, `validationChainPlugin()` | [mongokit-migration.md](references/mongokit-migration.md) |
+| Hand-written `name === 'admin'` MCP tool handlers | `mcpPlugin({ resources })` (auto-generated) | [anti-patterns.md §15](references/anti-patterns.md) |
+
+## Audit workflow
+
+1. **Confirm arc is actually installed.** Read root `package.json`. Note `@classytic/arc`, `@classytic/mongokit`, `@classytic/repo-core`, `@classytic/sqlitekit` versions. If arc is absent, this skill doesn't apply — recommend `npx @classytic/arc init` instead.
+2. **Locate the entry point.** Search for `createApp(` or `defineResource(` to see what arc surface is already in use. Note `auth`, `runtime`, `arcPlugins`, `presets` config.
+3. **Inventory resources.** For each `defineResource()` call: list `name`, `permissions`, `presets`, `cache`, `schemaOptions`, custom `routes`/`actions`. Compare to what's used.
+4. **Run the detection sweep.** Walk every section of [anti-patterns.md](references/anti-patterns.md). For each pattern, run the listed grep against `src/` (excluding `node_modules`, `dist`, `test*`). Record file:line of each hit.
+5. **Score findings.** Apply [severity.md](references/severity.md) rubric (critical / high / medium / low). Critical = security gap or duplicated arc behavior that drifts. Low = cosmetic.
+6. **Cross-check mongokit adoption.** If `mongoose` is a direct dep but `@classytic/mongokit` is not, every model is a candidate for migration. Use [mongokit-migration.md](references/mongokit-migration.md).
+7. **Check arc CLI scaffolding hygiene.** Look for `.arcrc`, `arc generate resource` output structure (`{name}.model.ts`, `{name}.repository.ts`, `{name}.resource.ts`). Mismatch = team is hand-creating files. See [scaffolding.md](references/scaffolding.md).
+8. **Emit the report** using the template below.
+
+## Reporting template
+
+```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>
+**Files scanned:** <N> · **Findings:** <N critical · <N high · <N medium · <N low>
+
+## Executive summary
+- <1-2 sentences: how much manual code could be deleted, biggest single risk>
+- Estimated LOC removable: ~<N> lines across <N> files
+- Estimated effort: <S/M/L> per resource (<N> resources affected)
+
+## Critical findings
+### C1. <short title> (<N occurrences>)
+**Pattern:** <what's wrong, in 1 sentence>
+**Locations:** `src/foo/bar.ts:42`, `src/foo/baz.ts:118`, ...
+**Why it matters:** <security / drift / maintainability impact>
+**Fix:** <link to migration recipe>
+
+## High / Medium / Low findings
+(same shape)
+
+## Migration plan (recommended order)
+1. <Step 1 — usually scope/permissions because they're security-critical>
+2. <Step 2 — usually CRUD consolidation>
+3. ...
+
+## Per-resource scorecard
+| Resource | defineResource? | presets used | permissions | cache | events | mongokit | Score |
+|---|---|---|---|---|---|---|---|
+| product | ✅ | softDelete | ✅ | ❌ | manual | ❌ | 6/10 |
+```
+
+## Severity quick rule
+
+- **Critical:** auth bypass, scope leak, fields exposed that should be `hidden`, hand-rolled idempotency that diverges from arc's behavior under load.
+- **High:** duplicated CRUD that will rot (one resource gets a fix the others don't), manual permissions instead of combinators, mongoose imports leaking outside adapters.
+- **Medium:** manual query parsing, manual cache invalidation, missing presets, hand-written OpenAPI.
+- **Low:** style (default exports, `console.log`, `any`), naming conventions, missing `displayName`/`module` metadata.
+
+Full rubric → [severity.md](references/severity.md).
+
+## Output discipline
+
+- **Cite file:line for every finding.** Do not generalize.
+- **Show the before/after diff** for the first occurrence of each pattern. Subsequent occurrences just list locations.
+- **Quote arc's exact API** in fixes (e.g., `requireRoles(['admin'])` from `@classytic/arc`, not "use arc's role helper").
+- **Sort by severity, then by file count.** A pattern repeated 30× outranks an isolated critical bug for migration ROI.
+- **Distinguish "missing arc feature" from "arc misuse".** The first is opportunity; the second is a bug.
+- **Don't recommend arc features the project hasn't enabled.** If `arcPlugins.queryCache: false`, don't suggest cache tags — recommend enabling it first.
+
+## References
+
+- **[anti-patterns.md](references/anti-patterns.md)** — every greppable anti-pattern with detection regex, severity, and fix
+- **[migration-recipes.md](references/migration-recipes.md)** — concrete before/after diffs (manual CRUD → defineResource, manual perms → combinators, manual events, etc.)
+- **[mongokit-migration.md](references/mongokit-migration.md)** — Mongoose-only project → mongokit Repository + plugins
+- **[arc-cheatsheet.md](references/arc-cheatsheet.md)** — what arc provides at a glance (defineResource fields, presets, permissions, scope, hooks, events, cache, MCP)
+- **[scaffolding.md](references/scaffolding.md)** — arc CLI (`init`, `generate resource`, `docs`, `introspect`, `doctor`), `.arcrc`, file conventions
+- **[severity.md](references/severity.md)** — severity rubric and triage examples