kitcn 0.25.4 → 0.25.6

package/dist/orm/index.js

@@ -277,7 +277,7 @@ const resolveOrmCapabilities = (capabilities) => {
 	}
 	return resolved;
 };
-const AGGREGATE_SETUP_HINT = "Generated ORM: declare an aggregateIndex(...)/rankIndex(...) in your schema and rerun `kitcn codegen`, which registers the capability in <functionsDir>/generated/server.ts. Hand-written ORM: import { aggregateCapability } from 'kitcn/orm/aggregate-index' and pass createOrm({ schema, capabilities: [aggregateCapability()] }).";
+const AGGREGATE_SETUP_HINT = "Generated ORM: `kitcn codegen` registers the capability in <functionsDir>/generated/server.ts from the aggregateIndex(...)/rankIndex(...) declarations in your schema — if you are seeing this from that generated file, delete it and run `kitcn codegen` again. Hand-written ORM: import { aggregateCapability } from 'kitcn/orm/aggregate-index' and pass createOrm({ schema, capabilities: [aggregateCapability()] }).";
 const missingAggregateCapabilityError = (usage) => /* @__PURE__ */ new Error(`${usage} requires the aggregate capability. ${AGGREGATE_SETUP_HINT}`);
 const requireAggregateCapability = (capabilities, usage) => {
 	const aggregate = capabilities?.aggregate;
@@ -286,7 +286,7 @@ const requireAggregateCapability = (capabilities, usage) => {
 };
 const requireMigrationCapability = (capabilities, usage) => {
 	const migrations = capabilities?.migrations;
-	if (!migrations) throw new Error(`${usage} requires the migration capability. Generated ORM: add a migration under <functionsDir>/migrations and rerun \`kitcn codegen\`, which registers the capability in <functionsDir>/generated/server.ts. Hand-written ORM: import { migrationCapability } from 'kitcn/orm/migrations' and pass createOrm({ schema, capabilities: [migrationCapability()] }).`);
+	if (!migrations) throw new Error(`${usage} requires the migration capability. Generated ORM: \`kitcn codegen\` registers the capability in <functionsDir>/generated/server.ts once <functionsDir>/migrations/manifest.ts exists — if you are seeing this from that generated file, delete it and run \`kitcn codegen\` again. Hand-written ORM: import { migrationCapability } from 'kitcn/orm/migrations' and pass createOrm({ schema, capabilities: [migrationCapability()] }).`);
 	return migrations;
 };
 

package/dist/orm/migrations/index.d.ts

@@ -1,3 +1,3 @@
 import { C as MigrationTableName, D as defineMigrationSet, E as defineMigration, O as detectMigrationDrift, S as MigrationStep, T as buildMigrationPlan, _ as MigrationMigrateOne, a as MigrationCancelArgs, b as MigrationSet, c as MigrationStatusArgs, d as MigrationDefinition, f as MigrationDirection, g as MigrationManifestEntry, h as MigrationDriftIssue, l as createMigrationHandlers, m as MigrationDocContext, o as MigrationRunArgs, p as MigrationDoc, s as MigrationRunChunkArgs, u as MigrationAppliedState, v as MigrationPlan, w as MigrationWriteMode, x as MigrationStateMap, y as MigrationRunStatus } from "../../capabilities-DtDfpdcH.js";
-import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-CCMtAIdx.js";
+import { Ct as migrationCapability, dt as MIGRATION_STORAGE_TABLE_NAMES, ft as injectMigrationStorageTables, lt as MIGRATION_RUN_TABLE, mt as migrationStorageTables, pt as migrationExtension, ut as MIGRATION_STATE_TABLE } from "../../where-clause-compiler-eTewPUGq.js";
 export { MIGRATION_RUN_TABLE, MIGRATION_STATE_TABLE, MIGRATION_STORAGE_TABLE_NAMES, type MigrationAppliedState, type MigrationCancelArgs, type MigrationDefinition, type MigrationDirection, type MigrationDoc, type MigrationDocContext, type MigrationDriftIssue, type MigrationManifestEntry, type MigrationMigrateOne, type MigrationPlan, type MigrationRunArgs, type MigrationRunChunkArgs, type MigrationRunStatus, type MigrationSet, type MigrationStateMap, type MigrationStatusArgs, type MigrationStep, type MigrationTableName, type MigrationWriteMode, buildMigrationPlan, createMigrationHandlers, defineMigration, defineMigrationSet, detectMigrationDrift, injectMigrationStorageTables, migrationCapability, migrationExtension, migrationStorageTables };

package/dist/plugins/index.js

@@ -1,3 +1,3 @@
-import { n as resolvePluginOptions, t as definePlugin } from "../middleware-DIj-bwVi.js";
+import { n as resolvePluginOptions, t as definePlugin } from "../middleware-BvnabcNq.js";
 
 export { definePlugin, resolvePluginOptions };

package/dist/{procedure-caller-Dxae9DW5.js → procedure-caller-BR-Wb0si.js}

@@ -1,5 +1,5 @@
 import { i as decodeWire, o as encodeWire } from "./transformer-D8wO-kEj.js";
-import { _ as CRPCError } from "./builder-DoeyW4Vq.js";
+import { _ as CRPCError } from "./builder-CsAw-DK8.js";
 import * as z$1 from "zod";
 
 //#region src/server/env.ts

package/dist/ratelimit/index.js

@@ -1,6 +1,6 @@
 import { u as requireMutationCtx } from "../api-entry-CkDpGYVg.js";
-import { _ as CRPCError } from "../builder-DoeyW4Vq.js";
-import { t as definePlugin } from "../middleware-DIj-bwVi.js";
+import { _ as CRPCError } from "../builder-CsAw-DK8.js";
+import { t as definePlugin } from "../middleware-BvnabcNq.js";
 import { v } from "convex/values";
 import { mutationGeneric, queryGeneric } from "convex/server";
 

package/dist/server/index.js

@@ -1,6 +1,6 @@
 import { a as isMutationCtx, c as isSchedulerCtx, d as requireQueryCtx, f as requireRunMutationCtx, i as isActionCtx, l as requireActionCtx, n as createGeneratedFunctionReference, o as isQueryCtx, p as requireSchedulerCtx, r as getGeneratedValue, s as isRunMutationCtx, t as createApiLeaf, u as requireMutationCtx } from "../api-entry-CkDpGYVg.js";
 import { n as createLazyCaller, r as createServerCaller, t as createCallerFactory } from "../caller-factory-Dd3H7j3V.js";
-import { A as zid, C as toCRPCError, D as zCustomAction, E as withSystemFields, M as zodOutputToConvexFields, N as zodToConvex, O as zCustomMutation, P as zodToConvexFields, S as isCRPCError, T as convexToZodFields, _ as CRPCError, a as createMiddlewareFactory, b as getCRPCErrorFromUnknown, c as registerProcedureNameLookup, d as createHttpRouterFactory, f as extractRouteMap, g as matchPathParams, h as handleHttpError, i as QueryProcedureBuilder, j as zodOutputToConvex, k as zCustomQuery, l as HttpRouterWithHono, m as extractPathParams, n as MutationProcedureBuilder, o as initCRPC, p as createHttpProcedureBuilder, r as ProcedureBuilder, s as inferProcedureNameFromCallsite, t as ActionProcedureBuilder, u as createHttpRouter, v as CRPC_ERROR_CODES_BY_KEY, w as convexToZod, x as getHTTPStatusCodeFromError, y as CRPC_ERROR_CODE_TO_HTTP } from "../builder-DoeyW4Vq.js";
-import { a as createProcedureHandlerFactory, c as typedProcedureResolver, i as createProcedureCallerFactory, l as createEnv, n as createGenericCallerFactory, o as defineProcedure, r as createGenericHandlerFactory, s as getGeneratedFunctionReference, t as createGeneratedRegistryRuntime } from "../procedure-caller-Dxae9DW5.js";
+import { A as zid, C as toCRPCError, D as zCustomAction, E as withSystemFields, M as zodOutputToConvexFields, N as zodToConvex, O as zCustomMutation, P as zodToConvexFields, S as isCRPCError, T as convexToZodFields, _ as CRPCError, a as createMiddlewareFactory, b as getCRPCErrorFromUnknown, c as registerProcedureNameLookup, d as createHttpRouterFactory, f as extractRouteMap, g as matchPathParams, h as handleHttpError, i as QueryProcedureBuilder, j as zodOutputToConvex, k as zCustomQuery, l as HttpRouterWithHono, m as extractPathParams, n as MutationProcedureBuilder, o as initCRPC, p as createHttpProcedureBuilder, r as ProcedureBuilder, s as inferProcedureNameFromCallsite, t as ActionProcedureBuilder, u as createHttpRouter, v as CRPC_ERROR_CODES_BY_KEY, w as convexToZod, x as getHTTPStatusCodeFromError, y as CRPC_ERROR_CODE_TO_HTTP } from "../builder-CsAw-DK8.js";
+import { a as createProcedureHandlerFactory, c as typedProcedureResolver, i as createProcedureCallerFactory, l as createEnv, n as createGenericCallerFactory, o as defineProcedure, r as createGenericHandlerFactory, s as getGeneratedFunctionReference, t as createGeneratedRegistryRuntime } from "../procedure-caller-BR-Wb0si.js";
 
 export { ActionProcedureBuilder, CRPCError, CRPC_ERROR_CODES_BY_KEY, CRPC_ERROR_CODE_TO_HTTP, HttpRouterWithHono, MutationProcedureBuilder, ProcedureBuilder, QueryProcedureBuilder, convexToZod, convexToZodFields, createApiLeaf, createCallerFactory, createEnv, createGeneratedFunctionReference, createGeneratedRegistryRuntime, createGenericCallerFactory, createGenericHandlerFactory, createHttpProcedureBuilder, createHttpRouter, createHttpRouterFactory, createLazyCaller, createMiddlewareFactory, createProcedureCallerFactory, createProcedureHandlerFactory, createServerCaller, defineProcedure, extractPathParams, extractRouteMap, getCRPCErrorFromUnknown, getGeneratedFunctionReference, getGeneratedValue, getHTTPStatusCodeFromError, handleHttpError, inferProcedureNameFromCallsite, initCRPC, isActionCtx, isCRPCError, isMutationCtx, isQueryCtx, isRunMutationCtx, isSchedulerCtx, matchPathParams, registerProcedureNameLookup, requireActionCtx, requireMutationCtx, requireQueryCtx, requireRunMutationCtx, requireSchedulerCtx, toCRPCError, typedProcedureResolver, withSystemFields, zCustomAction, zCustomMutation, zCustomQuery, zid, zodOutputToConvex, zodOutputToConvexFields, zodToConvex, zodToConvexFields };

package/dist/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as generateMeta, d as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, u as logger } from "./local-env-Dkh4a_BK.mjs";
+import { a as generateMeta, d as PARSE_SNAPSHOT_SUFFIX, i as resolveConfiguredBackend, n as withLocalCodegenEnv, o as getConvexConfig, r as loadCliConfig, u as logger } from "./local-env-CiPqNKS_.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

package/dist/{where-clause-compiler-CCMtAIdx.d.ts → where-clause-compiler-eTewPUGq.d.ts}

@@ -111,6 +111,15 @@ declare const migrationStorageTables: {
           fieldName: "cursor";
         };
       };
+      direction: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -150,15 +159,6 @@ declare const migrationStorageTables: {
           fieldName: "applied";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "direction";
-        };
-      };
       runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
@@ -1008,7 +1008,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1018,10 +1018,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1031,7 +1031,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "count";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1133,7 +1133,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_member: ConvexTableWithColumns<{
     name: "aggregate_member";
     columns: {
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1143,10 +1143,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "kind";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1156,7 +1156,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "kind";
+          fieldName: "updatedAt";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1323,7 +1323,11 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_extrema: ConvexTableWithColumns<{
     name: "aggregate_extrema";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
+      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
+        _: {
+          $type: convex_values0.Value;
+        };
+      } & {
         _: {
           notNull: true;
         };
@@ -1333,7 +1337,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "value";
         };
       };
       updatedAt: ConvexNumberBuilderInitial<""> & {
@@ -1349,11 +1353,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "updatedAt";
         };
       };
-      value: ConvexCustomBuilderInitial<"", convex_values0.VAny<any, "required", string>> & {
-        _: {
-          $type: convex_values0.Value;
-        };
-      } & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -1363,7 +1363,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "value";
+          fieldName: "count";
         };
       };
       indexName: ConvexTextBuilderInitial<""> & {
@@ -1589,6 +1589,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "status";
         };
       };
+      kind: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "kind";
+        };
+      };
       cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "aggregate_state";
@@ -1655,19 +1668,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "lastError";
         };
       };
-      kind: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "kind";
-        };
-      };
       indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1753,6 +1753,15 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "cursor";
         };
       };
+      direction: ConvexTextBuilderInitial<""> & {
+        _: {
+          tableName: "migration_state";
+        };
+      } & {
+        _: {
+          fieldName: "direction";
+        };
+      };
       migrationId: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -1792,15 +1801,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "applied";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
-        _: {
-          tableName: "migration_state";
-        };
-      } & {
-        _: {
-          fieldName: "direction";
-        };
-      };
       runId: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.25.4",
+  "version": "0.25.6",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",
@@ -47,6 +47,7 @@
     "intent": "./bin/intent.js"
   },
   "files": [
+    "CHANGELOG.md",
     "dist",
     "skills",
     "bin",

package/skills/kitcn/SKILL.md

@@ -32,34 +32,35 @@ Default assumption:
 Only remember these non-parity deltas:
 1. Procedure input root must be `z.object(...)` (no primitive root args).
 2. No `z.void()` outputs; omit `.output(...)` for no-value mutations.
-3. Stacked `.input(...)` calls merge input shapes.
-4. `.paginated({ limit, item })` must be before `.query()` and auto-adds `input.cursor` + `input.limit`, output `{ page, continueCursor, isDone }`.
-5. Metadata is codegen’d onto `@convex/api` leaves (`api.namespace.fn.meta`) so never put secrets in `.meta(...)`; chaining `.meta(...)` is shallow merge and supports `defaultMeta`.
-6. Auth metadata drives client behavior: `auth: "optional"` waits for auth load then runs, `auth: "required"` waits then skips when logged out.
-7. `ctx.orm` enforces constraints + RLS; `ctx.db` bypasses them.
-8. Non-paginated `findMany()` must be explicitly sized (`limit`, cursor mode, schema `defaultLimit`, or explicit `allowFullScan`).
-9. Predicate `where` requires explicit `.withIndex(...)`; no implicit full scan fallback.
-10. Cursor pagination uses the first `orderBy` field; index that field for stable paging.
-11. `maxScan` applies to cursor mode only; `allowFullScan` is for non-cursor full-scan opt-in.
-12. String operators / `columns` projection / many-relation subfilters can run post-fetch; bound result size early.
-13. Search mode is relevance-ordered and does not support `orderBy`; vector mode has stricter limits (no cursor/offset/top-level where/order).
-14. Update/delete without `where` throws unless `allowFullScan()`.
-15. `count()`, `aggregate()`, and `groupBy()` require a matching `aggregateIndex`. Use `groupBy({ by, _count, _sum })` instead of multiple `.count()` calls or `findMany` + manual JS grouping. Every `by` field must be finite-constrained (`eq`/`in`/`isNull`) in `where`. See `references/features/aggregates.md`.
-16. cRPC React queries are real-time by default (`subscribe: true`); never use `queryClient.invalidateQueries` for these subscribed paths.
-17. In RSC, `prefetch` hydrates client, `caller` is server-only and not hydrated, `preloadQuery` hydrates but can cause stale split ownership if also rendered client-side.
-18. Better Auth Next.js shortcut is `convexBetterAuth(...)`; generic server-only shortcut is `createCallerFactory(...)`.
-19. On the kitcn auth client path, use `createAuthMutations(authClient)` wrappers so logout unsubscribes auth queries before sign out. Raw Convex preset keeps a smaller plain `authClient`.
-20. **NEVER** use `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction` directly for module-to-module calls. Use the generated runtime helpers from `convex/functions/generated/<module>.runtime`.
-21. **`create<Module>Handler(ctx)`** is the default in queries/mutations: zero overhead, query/mutation ctx only, and no redundant validation or middleware.
-22. **`create<Module>Caller(ctx)`** is for actions and HTTP routes. Action procedures live under `caller.actions.*`; scheduling lives under `caller.schedule.now|after|at|cancel`. Use `requireActionCtx(ctx)` only for true `ActionCtx` callbacks; use `requireSchedulerCtx(ctx)` when mutation or action contexts can schedule. Each caller/handler eagerly loads its module, so split large modules.
-23. API types (`Api`, `ApiInputs`, `ApiOutputs`, `Select`, `Insert`, `TableName`) import from `@convex/api` — no manual `inferApiInputs<typeof api>`.
-24. HTTP router must export as `httpRouter` (not `appRouter`) for codegen.
-25. Server wiring imports come from `convex/functions/generated/` directory: `getAuth`, `defineAuth` from `generated/auth`; `initCRPC`, `QueryCtx`, `MutationCtx`, `OrmCtx` from `generated/server`; `create<Module>Caller`, `create<Module>Handler` from `generated/<module>.runtime`. No manual `convex/lib/orm.ts`.
-26. `defineAuth(() => ({ ...options, triggers }))` replaces split `getAuthOptions` + `authTriggers`. Trigger callbacks are doc-first: `beforeCreate(data)`, `onCreate(doc)`, `onUpdate(newDoc, oldDoc)` — no `ctx` first param.
-27. Internal auth functions at `internal.generated.*` (not `internal.auth.*`).
-28. Async mutation batching is the default (codegen wires it). Customize per call: `execute({ batchSize, delayMs })`. Opt into sync: `execute({ mode: 'sync' })` or `defineSchema(..., { defaults: { mutationExecutionMode: 'sync' } })`. Relevant defaults: `mutationBatchSize`, `mutationLeafBatchSize`, `mutationMaxRows`, `mutationScheduleCallCap`.
-29. Polymorphic unions are schema-first: use `actionType: discriminator({ variants, as? })` in `convexTable(...)`. Query config does not include a `polymorphic` option. Writes stay flat; reads synthesize nested `details` (or custom alias). Use `withVariants: true` to auto-load all `one()` relations on discriminator tables.
-30. Do not add manual ORM mutation batching loops in app/plugin code by default. Convex runtime batching already handles mutation execution. Prefer set-based deletes/updates over per-row loops. Only add explicit chunking when batching external side effects (for example Resend API calls) or bounded cleanup sweeps.
+3. `.output(...)` parses the handler's value as-is and substitutes nothing: a handler must return the schema's *input* type, so `z.string().nullable()` needs an explicit `null` (`?? null`), not `undefined`. Model absent values as `.nullable()`, never a top-level `.optional()` — Convex wires `undefined` as `null` and cannot express top-level optionality, so `.output(z.string().optional())` publishes `v.string()` and the deployment rejects the `null` whenever the handler returns `undefined`. `.optional()` inside an object is fine. The low-level `returns:` option on `zCustomQuery`/`zCustomMutation`/`zCustomAction` differs — it substitutes `null` for `undefined` before parsing.
+4. Stacked `.input(...)` calls merge input shapes.
+5. `.paginated({ limit, item })` must be before `.query()` and auto-adds `input.cursor` + `input.limit`, output `{ page, continueCursor, isDone }`.
+6. Metadata is codegen’d onto `@convex/api` leaves (`api.namespace.fn.meta`) so never put secrets in `.meta(...)`; chaining `.meta(...)` is shallow merge and supports `defaultMeta`.
+7. Auth metadata drives client behavior: `auth: "optional"` waits for auth load then runs, `auth: "required"` waits then skips when logged out.
+8. `ctx.orm` enforces constraints + RLS; `ctx.db` bypasses them.
+9. Non-paginated `findMany()` must be explicitly sized (`limit`, cursor mode, schema `defaultLimit`, or explicit `allowFullScan`).
+10. Predicate `where` requires explicit `.withIndex(...)`; no implicit full scan fallback.
+11. Cursor pagination uses the first `orderBy` field; index that field for stable paging.
+12. `maxScan` applies to cursor mode only; `allowFullScan` is for non-cursor full-scan opt-in.
+13. String operators / `columns` projection / many-relation subfilters can run post-fetch; bound result size early.
+14. Search mode is relevance-ordered and does not support `orderBy`; vector mode has stricter limits (no cursor/offset/top-level where/order).
+15. Update/delete without `where` throws unless `allowFullScan()`.
+16. `count()`, `aggregate()`, and `groupBy()` require a matching `aggregateIndex`. Use `groupBy({ by, _count, _sum })` instead of multiple `.count()` calls or `findMany` + manual JS grouping. Every `by` field must be finite-constrained (`eq`/`in`/`isNull`) in `where`. See `references/features/aggregates.md`.
+17. cRPC React queries are real-time by default (`subscribe: true`); never use `queryClient.invalidateQueries` for these subscribed paths.
+18. In RSC, `prefetch` hydrates client, `caller` is server-only and not hydrated, `preloadQuery` hydrates but can cause stale split ownership if also rendered client-side.
+19. Better Auth Next.js shortcut is `convexBetterAuth(...)`; generic server-only shortcut is `createCallerFactory(...)`.
+20. On the kitcn auth client path, use `createAuthMutations(authClient)` wrappers so logout unsubscribes auth queries before sign out. Raw Convex preset keeps a smaller plain `authClient`.
+21. **NEVER** use `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction` directly for module-to-module calls. Use the generated runtime helpers from `convex/functions/generated/<module>.runtime`.
+22. **`create<Module>Handler(ctx)`** is the default in queries/mutations: zero overhead, query/mutation ctx only, and no redundant validation or middleware.
+23. **`create<Module>Caller(ctx)`** is for actions and HTTP routes. Action procedures live under `caller.actions.*`; scheduling lives under `caller.schedule.now|after|at|cancel`. Use `requireActionCtx(ctx)` only for true `ActionCtx` callbacks; use `requireSchedulerCtx(ctx)` when mutation or action contexts can schedule. Each caller/handler eagerly loads its module, so split large modules.
+24. API types (`Api`, `ApiInputs`, `ApiOutputs`, `Select`, `Insert`, `TableName`) import from `@convex/api` — no manual `inferApiInputs<typeof api>`.
+25. HTTP router must export as `httpRouter` (not `appRouter`) for codegen.
+26. Server wiring imports come from `convex/functions/generated/` directory: `getAuth`, `defineAuth` from `generated/auth`; `initCRPC`, `QueryCtx`, `MutationCtx`, `OrmCtx` from `generated/server`; `create<Module>Caller`, `create<Module>Handler` from `generated/<module>.runtime`. No manual `convex/lib/orm.ts`.
+27. `defineAuth(() => ({ ...options, triggers }))` replaces split `getAuthOptions` + `authTriggers`. Trigger callbacks are doc-first: `beforeCreate(data)`, `onCreate(doc)`, `onUpdate(newDoc, oldDoc)` — no `ctx` first param.
+28. Internal auth functions at `internal.generated.*` (not `internal.auth.*`).
+29. Async mutation batching is the default (codegen wires it). Customize per call: `execute({ batchSize, delayMs })`. Opt into sync: `execute({ mode: 'sync' })` or `defineSchema(..., { defaults: { mutationExecutionMode: 'sync' } })`. Relevant defaults: `mutationBatchSize`, `mutationLeafBatchSize`, `mutationMaxRows`, `mutationScheduleCallCap`.
+30. Polymorphic unions are schema-first: use `actionType: discriminator({ variants, as? })` in `convexTable(...)`. Query config does not include a `polymorphic` option. Writes stay flat; reads synthesize nested `details` (or custom alias). Use `withVariants: true` to auto-load all `one()` relations on discriminator tables.
+31. Do not add manual ORM mutation batching loops in app/plugin code by default. Convex runtime batching already handles mutation execution. Prefer set-based deletes/updates over per-row loops. Only add explicit chunking when batching external side effects (for example Resend API calls) or bounded cleanup sweeps.
 ## Directory Boundary
 Use `references/setup/` when the task needs:
 1. Project/file structure setup → `setup/index.md` + `setup/server.md`
@@ -314,7 +315,10 @@ Use this map consistently:
 4. `NOT_FOUND`: missing or inaccessible resource.
 5. `CONFLICT`: duplicate or conflicting write.
 6. `TOO_MANY_REQUESTS`: rate limit.
-7. `INTERNAL_SERVER_ERROR`: unexpected failures only.
+7. `INTERNAL_SERVER_ERROR`: unexpected failures only. cRPC also raises it for a
+   failed `.output(...)` parse, with message `Output validation failed` and
+   sanitized structural Zod issues in `error.data.ZodError`. Custom issue
+   messages and fields stay server-side because they can contain handler output.
 8. Add small custom `data` payloads on `CRPCError` when the client needs
    domain metadata like conflicting ids. Read them on the client from
    `error.data`.
@@ -454,6 +458,7 @@ Before calling a feature done:
 | Infinite list with TanStack native hook directly                | Use `useInfiniteQuery` from `kitcn/react`                                                                                                                                    |
 | Primitive root input (`z.string()`)                             | Use root `z.object(...)` input schema                                                                                                                                                |
 | Returning nothing with `z.void()`                               | Omit explicit output                                                                                                                                                                 |
+| Returning a possibly-missing lookup under `.output(...nullable())` | Coalesce it: `?? null`. `.output(...)` substitutes nothing for `undefined`                                                                                                         |
 | Manual pagination wrappers for infinite endpoints               | Use `.paginated({ limit, item })`                                                                                                                                                    |
 | Synthetic Convex IDs in tests (`"missing-id"`)                  | Use inserted IDs or semantic lookup keys                                                                                                                                             |
 | Aggregates disabled but helper/config still present             | Remove aggregate helper + `defineTriggers` handlers + app config together                                                                                                            |

package/skills/kitcn/references/setup/index.md

@@ -141,6 +141,7 @@ bunx kitcn add resend
 - `convex/functions/schema.ts`
 - `convex/functions/http.ts`
 - `convex/functions/generated/server.ts`
+- `convex/functions/generated/procedure-names.gen.ts`
 - `convex/lib/crpc.ts`
 - `convex/lib/get-env.ts`
 - `convex/shared/api.ts`

package/skills/kitcn/references/setup/server.md

@@ -218,6 +218,15 @@ This generates:
 - `convex/functions/generated/` directory
 - `convex/shared/api.ts`
 
+Everything under `convex/functions/generated/` is codegen-owned. Never edit it,
+and never hand-repair it. `convex/functions/generated/server.ts` is rewritten
+from the schema before codegen reads any app module.
+
+`convex/functions/generated/procedure-names.gen.ts` holds the procedure-name
+lookup. It is the only generated output that depends on scanning procedures, so
+only default-scope runs rebuild it; `kitcn codegen --scope auth|orm` preserves
+the recorded lookup.
+
 Agent command policy:
 
 1. Default to `bunx kitcn dev`.