Kitcn

kitcn Core Skill (80% Path)

Use this file first for everyday feature delivery in an already configured kitcn app.

• If setup/bootstrap/env/auth wiring or project structure mirroring is missing, use references/setup/index.md (then the relevant setup file).
• If the task is advanced or niche, load only the specific feature reference listed at the end.

Scope

In scope:

• Add or update schema tables, indexes, relations, and triggers.
• Implement cRPC procedures (query, mutation, action, httpAction) with runtime auth + rate limits.
• Implement feature UI with useCRPC() + TanStack Query.
• Add minimal high-value tests for auth, errors, and side effects. Out of scope:
• Greenfield setup/install/env/bootstrap.
• Full plugin deep-dives (admin/organizations/polar).
• Internal package-level parity testing.

Skill Contract

1. Favor ctx.orm for app data access.
2. Keep list/read paths bounded and index-aware.
3. Use cRPC builders and middleware; avoid raw handler objects for new feature code.
4. Use CRPCError for expected failures.
5. Prefer schema triggers for cross-row invariants, but move invariant maintenance to explicit mutation helpers if trigger execution is unstable (for example init/seed hangs or recursive write paths).
6. Keep auth/rate-limit checks server-side.
7. Inter-procedure calls: use generated runtime helpers: create<Module>Handler(ctx) in queries/mutations, create<Module>Caller(ctx) in actions/HTTP routes, caller.actions.* for action procedures, and caller.schedule.* for scheduling. Never call ctx.runQuery/ctx.runMutation/ctx.runAction directly for module procedures.

Shortcut Mode (tRPC + Drizzle Mental Model)

Default assumption:

• cRPC behavior is tRPC-like (builder chain + middleware + TanStack options).
• ORM behavior is Drizzle-like (schema, relations, findMany/findFirst, insert/update/delete). 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. .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 adds input.cursor, input.endCursor, and input.limit; pass all three to ORM cursor queries so live splits stay bounded.
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
2. Auth bootstrap → setup/auth.md
3. Client/provider wiring → setup/react.md
4. Framework-specific setup → setup/next.md or setup/start.md For full template-level recreation: start with setup/index.md, then load relevant setup files, then load selected feature refs.

First-Pass Feature Intake (Do This Before Edits)

Lock these decisions first:

1. Auth level per endpoint: public / optionalAuth / auth / private.
2. Data invariants: what must always be true after writes?
3. Query shape: list, detail, relation-loaded, search, or stream composition.
4. Pagination mode: offset, cursor, infinite.
5. Side effects: trigger vs scheduled function vs inline mutation.
6. UI consumption: client hook only, RSC prefetch, or server-only caller.
7. Risk paths: unauthorized, forbidden, not found, conflicts, rate limit.

Canonical File Targets

Typical feature touches:

• convex/functions/schema.ts
• convex/functions/<feature>.ts
• convex/lib/crpc.ts (only if middleware/procedure builder changes)
• src/lib/convex/crpc.tsx (only if cRPC context/meta wiring changes)
• src/** feature UI files
• convex/functions/http.ts or convex/routers/** for HTTP endpoints
• convex/functions/crons.ts or scheduled handlers if needed

E2E Build Order (Default)

1. Schema + indexes + relations.
2. Trigger hooks for cross-row invariants (or explicit mutation-side sync if trigger path is unstable).
3. Procedures with strict input/output + auth + rate limits.
4. React hooks (query/mutation/infinite) using cRPC options.
5. Optional: HTTP route(s), scheduling hooks.
6. Tests for auth/error/trigger behavior.

Core Patterns

1) Schema + Relations + Trigger

import {
  convexTable,
  defineSchema,
  id,
  integer,
  index,
  text,
  timestamp,
} from "kitcn/orm";

export const project = convexTable(
  "project",
  {
    name: text().notNull(),
    ownerId: id("user").notNull(),
    updatedAt: timestamp()
      .notNull()
      .defaultNow()
      .$onUpdateFn(() => new Date()),
  },
  (t) => [index("ownerId_updatedAt").on(t.ownerId, t.updatedAt)]
);

export const task = convexTable(
  "task",
  {
    projectId: id("project").notNull(),
    title: text().notNull(),
    status: text().notNull().default("open"),
    updatedAt: timestamp()
      .notNull()
      .defaultNow()
      .$onUpdateFn(() => new Date()),
  },
  (t) => [index("projectId_updatedAt").on(t.projectId, t.updatedAt)]
);

export default defineSchema({ project, task })
  .relations((r) => ({
    project: {
      tasks: r.many.task(),
    },
    task: {
      project: r.one.project({ from: r.task.projectId, to: r.project.id }),
    },
  }))
  .triggers({
    task: {
      change: async (change, ctx) => {
        const projectId = change.newDoc?.projectId ?? change.oldDoc?.projectId;
        if (!projectId) return;
        const open = await ctx.orm.query.task.findMany({
          where: { projectId, status: "open" },
          columns: { id: true },
          limit: 500,
        });
        await ctx.orm.update(project).set({ openTaskCount: open.length });
      },
    },
  });

Schema rules that matter:

1. Index fields that power filters/order/search.
2. many() relation paths need child FK indexes.
3. Trigger logic must be bounded and non-recursive.
4. Use table defaults for consistent write behavior.
5. Keep full ORM/query edge cases in references/features/orm.md.

2) Procedure Builders + Middleware

import { getSession } from "kitcn/auth";
import { CRPCError } from "kitcn/server";
import { initCRPC, type QueryCtx } from "../functions/generated/server";

const c = initCRPC
  .meta<{
    auth?: "optional" | "required";
    role?: "admin";
    ratelimit?: string;
  }>()
  .create();

function requireAuth<T>(user: T | null): T {
  if (!user) {
    throw new CRPCError({ code: "UNAUTHORIZED", message: "Not authenticated" });
  }
  return user;
}
async function getSessionUser(ctx: QueryCtx) {
  const session = await getSession(ctx);
  if (!session) return null;
  return await ctx.orm.query.user.findFirst({
    where: { id: { eq: session.userId } },
  });
}

export const publicQuery = c.query.meta({ auth: "optional" });
export const authQuery = c.query
  .meta({ auth: "required" })
  .use(async ({ ctx, next }) => {
    const user = requireAuth(await getSessionUser(ctx));
    return next({ ctx: { ...ctx, user, userId: user.id } });
  });
export const authMutation = c.mutation
  .meta({ auth: "optional" })
  .use(async ({ ctx, next }) => {
    const user = await getSessionUser(ctx);
    return next({
      ctx: { ...ctx, user, userId: user?.id ?? null },
    });
  });

Builder rules that matter:

1. Build public, optional, auth, and private procedure families once in convex/lib/crpc.ts. Authenticated action builders live in convex/lib/crpc-action.ts, the only builder module that imports getAuth.
2. .meta(...) is client-visible via generated API metadata. Never put secrets there.
3. Middleware receives server-only procedure info. When procedures are built from your app generated/server helper, standard export const queries, mutations, and actions infer module:function automatically from file path + export name. Use .name("module:function") only to override or cover unusual export shapes.
4. Resolve session/user once in middleware. Do not re-fetch auth state in every procedure. Query/mutation middleware uses getSession(ctx) from kitcn/auth, which reads the session row directly. Keep getAuth(ctx) out of convex/lib/crpc.ts: it pulls the whole Better Auth definition and every auth plugin into the static import closure of every procedure module, and Convex has no dynamic import() to escape it. Import getAuth only in the modules that call auth.api.* — convex/lib/crpc-action.ts, HTTP routes, and organization/admin mutations.
5. Shared c.middleware() chains preserve mutation writer types on mutation procedures. If the middleware itself performs writes, type it as mutation-only with c.middleware<MutationCtx>(...).
6. Keep deeper auth/runtime edge cases in references/setup/server.md and references/features/auth*.md.

3) Query + Mutation Procedure Template

import * as z from "zod";
import { eq } from "kitcn/orm";
import { CRPCError } from "kitcn/server";
import { authMutation, authQuery } from "../lib/crpc";
import { project } from "./schema";

export const listProjects = authQuery
  .paginated({ limit: z.number().min(1).max(50).default(20), item: project })
  .query(async ({ ctx, input }) =>
    ctx.orm.query.project.findMany({
      where: { ownerId: ctx.userId },
      orderBy: { updatedAt: "desc" },
      cursor: input.cursor,
      endCursor: input.endCursor,
      limit: input.limit,
    })
  );

export const renameProject = authMutation
  .input(z.object({ id: z.string(), name: z.string().min(1).max(120) }))
  .mutation(async ({ ctx, input }) => {
    const current = await ctx.orm.query.project.findFirst({
      where: { id: input.id, ownerId: ctx.userId },
      columns: { id: true },
    });
    if (!current) {
      throw new CRPCError({ code: "NOT_FOUND", message: "Project not found" });
    }
    await ctx.orm
      .update(project)
      .set({ name: input.name })
      .where(eq(project.id, current.id));
    return null;
  });

Procedure rules that matter:

1. Root input must be z.object(...).
2. Use strict .input(...); add .output(...) only when needed.
3. Omit .output(...) for no-value mutations.
4. Use the default mutation rate limit; add .meta({ ratelimit: ... }) only for named bucket overrides.
5. Throw CRPCError for expected outcomes.
6. Bound every list with limit, cursor, or .paginated(...).
7. Move advanced query-builder shapes to references/features/orm.md.

3b) Inter-Procedure Composition

Use:

1. create<Module>Handler(ctx) in queries/mutations.
2. create<Module>Caller(ctx) in actions/HTTP routes.
3. caller.actions.* for action procedures.
4. caller.schedule.* for scheduled procedures.
5. Never ctx.runQuery / ctx.runMutation / ctx.runAction for module procedures.

4) Query Modes (Use The Right One)

1. Default to object where.
2. Use callback where only when composition reads better than object form.
3. Predicate/filter callbacks require .withIndex(...) first plus explicit limit/maxScan.
4. Full-text search uses search: { index, query, filters } and does not support orderBy.
5. Cursor paging is only stable when the orderBy field is indexed.
6. Advanced modes (pageByKey, vector search, pipelines, aggregate indexes) live in references/features/orm.md.

5) Mutation Patterns (Most Used)

1. Use .returning(...) on inserts when caller needs created ids.
2. Every update/delete path gets an explicit where(...).
3. Clear optional columns with unsetToken.
4. Async mutation execution is the default; use .execute({ mode: "sync" }) only when atomic all-at-once behavior is required.
5. Prefer set-based deletes/updates. Add chunking only for external side effects or bounded cleanups.
6. Upsert, conflict handling, mutation batching, and schema extension edge cases live in references/features/orm.md.

6) Error Model

Use this map consistently:

1. BAD_REQUEST: invalid input or business precondition.
2. UNAUTHORIZED: no session.
3. FORBIDDEN: session exists, permission missing.
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. 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.

Required tests:

1. unauthenticated rejection
2. permission rejection when relevant
3. missing resource path
4. conflict path when relevant
5. rate-limited write path when relevant