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

Favor
```
ctx.orm
```
for app data access.
Keep list/read paths bounded and index-aware.
Use cRPC builders and middleware; avoid raw handler objects for new feature code.
Use
```
CRPCError
```
for expected failures.
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).
Keep auth/rate-limit checks server-side.
Inter-procedure calls:
```
create<Module>Handler(ctx)
```
in queries/mutations (zero overhead) unless validation is relevant,
```
create<Module>Caller(ctx)
```
in actions/HTTP routes. In action context use
```
caller.actions.*
```
for action procedures and
```
caller.schedule.*
```
for scheduling. Import from
```
./generated/<module>.runtime
```
. 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:

Procedure input root must be
```
z.object(...)
```
(no primitive root args).
No
```
z.void()
```
outputs; omit
```
.output(...)
```
for no-value mutations.
Stacked
```
.input(...)
```
calls merge input shapes.

.paginated({ limit, item })

must be before

.query()

and auto-adds

input.cursor

input.limit

, output

{ page, continueCursor, isDone }

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
```
.
Auth metadata drives client behavior:
```
auth: "optional"
```
waits for auth load then runs,
```
auth: "required"
```
waits then skips when logged out.
```
ctx.orm
```
enforces constraints + RLS;
```
ctx.db
```
bypasses them.
Non-paginated
```
findMany()
```
must be explicitly sized (
```
limit
```
, cursor mode, schema
```
defaultLimit
```
, or explicit
```
allowFullScan
```
).
Predicate
```
where
```
requires explicit
```
.withIndex(...)
```
; no implicit full scan fallback.
Cursor pagination uses the first
```
orderBy
```
field; index that field for stable paging.
```
maxScan
```
applies to cursor mode only;
```
allowFullScan
```
is for non-cursor full-scan opt-in.
String operators /
```
columns
```
projection / many-relation subfilters can run post-fetch; bound result size early.
Search mode is relevance-ordered and does not support
```
orderBy
```
; vector mode has stricter limits (no cursor/offset/top-level where/order).
Update/delete without
```
where
```
throws unless
```
allowFullScan()
```
.

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

cRPC React queries are real-time by default (
```
subscribe: true
```
); never use
```
queryClient.invalidateQueries
```
for these subscribed paths.
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.
Better Auth Next.js shortcut is
```
convexBetterAuth(...)
```
; generic server-only shortcut is
```
createCallerFactory(...)
```
.
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
```
.

NEVER use

ctx.runQuery

ctx.runMutation

ctx.runAction

directly for module-to-module calls. Use

create<Module>Handler(ctx)

create<Module>Caller(ctx)

from

convex/functions/generated/<module>.runtime

instead.

create<Module>Handler(ctx)
— default choice for queries/mutations. Bypasses input validation, middleware, output validation → zero overhead. Query/mutation ctx only. Import from
```
./generated/<module>.runtime
```
.
create<Module>Caller(ctx)
— use in actions and HTTP routes (where handler is unavailable). Goes through validation + middleware. Root caller exposes query+mutation procedures. In
```
ActionCtx
```
, action procedures are under
```
caller.actions.*
```
; scheduling is under
```
caller.schedule.now|after|at
```
with
```
caller.schedule.cancel(id)
```
. Use
```
requireActionCtx(ctx)
```
only when the callback truly runs in
```
ActionCtx
```
and you need
```
caller.actions.*
```
. If the callback can run from
```
MutationCtx | ActionCtx
```
or generic scheduler-capable context, keep the seam honest: use
```
requireSchedulerCtx(ctx)
```
and
```
caller.schedule.*
```
instead of pretending the path is action-only. Import from
```
./generated/<module>.runtime
```
. Each caller/handler eagerly loads every procedure in its module (no lazy loading) — split large modules to keep bundles lean.

API types (

Api

ApiInputs

ApiOutputs

Select

Insert

TableName

) import from

@convex/api

— no manual

inferApiInputs<typeof api>

HTTP router must export as
```
httpRouter
```
(not
```
appRouter
```
) for codegen.

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

defineAuth(() => ({ ...options, triggers }))

replaces split

getAuthOptions

authTriggers

. Trigger callbacks are doc-first:

beforeCreate(data)

onCreate(doc)

onUpdate(newDoc, oldDoc)

— no

ctx

first param.

Internal auth functions at
```
internal.generated.*
```
(not
```
internal.auth.*
```
).

Async mutation batching is the default (codegen wires it). Customize per call:

execute({ batchSize, delayMs })

. Opt into sync:

execute({ mode: 'sync' })

defineSchema(..., { defaults: { mutationExecutionMode: 'sync' } })

. Relevant defaults:

mutationBatchSize

mutationLeafBatchSize

mutationMaxRows

mutationScheduleCallCap

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.
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 (Important)

Use

references/setup/

when the task needs:

Project/file structure setup →
```
setup/index.md
```
+
```
setup/server.md
```
Auth bootstrap →
```
setup/auth.md
```
Client/provider wiring →
```
setup/react.md
```
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:

Auth level per endpoint:
```
public
```
/
```
optionalAuth
```
/
```
auth
```
/
```
private
```
.
Data invariants: what must always be true after writes?
Query shape: list, detail, relation-loaded, search, or stream composition.
Pagination mode: offset, cursor, infinite.
Side effects: trigger vs scheduled function vs inline mutation.
UI consumption: client hook only, RSC prefetch, or server-only caller.
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

convex/routers/**

for HTTP endpoints

```
convex/functions/crons.ts
```
or scheduled handlers if needed

E2E Build Order (Default)

Schema + indexes + relations.
Trigger hooks for cross-row invariants (or explicit mutation-side sync if trigger path is unstable).
Procedures with strict input/output + auth + rate limits.
React hooks (query/mutation/infinite) using cRPC options.
Optional: HTTP route(s), scheduling hooks.
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:

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

2) Procedure Builders + Middleware

import { getHeaders } from "kitcn/auth";
import { CRPCError } from "kitcn/server";
import { getAuth } from "../functions/generated/auth";
import { initCRPC } 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;
}
export const publicQuery = c.query.meta({ auth: "optional" });
export const authQuery = c.query
  .meta({ auth: "required" })
  .use(async ({ ctx, next }) => {
    const auth = getAuth(ctx);
    const session = await auth.api.getSession({
      headers: await getHeaders(ctx),
    });
    const user = requireAuth(session?.user ?? null);
    return next({ ctx: { ...ctx, user, userId: user.id } });
  });
export const authMutation = c.mutation
  .meta({ auth: "optional" })
  .use(async ({ ctx, next }) => {
    const auth = getAuth(ctx);
    const session = await auth.api.getSession({
      headers: await getHeaders(ctx),
    });
    return next({
      ctx: {
        ...ctx,
        user: session?.user ?? null,
        userId: session?.user?.id ?? null,
      },
    });
  });

Builder rules that matter:

Build

public

optional

auth

, and

private

procedure families once in

convex/lib/crpc.ts

```
.meta(...)
```
is client-visible via generated API metadata. Never put secrets there.
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.
Resolve session/user once in middleware. Do not re-fetch auth state in every procedure.
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>(...)
```
.

Keep deeper auth/runtime edge cases in

references/setup/server.md

and

references/features/auth*.md

3) Query + Mutation Procedure Template

import { 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,
      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:

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

3b) Inter-Procedure Composition

Use:

```
create<Module>Handler(ctx)
```
in queries/mutations.
```
create<Module>Caller(ctx)
```
in actions/HTTP routes.
```
caller.actions.*
```
for action procedures.
```
caller.schedule.*
```
for scheduled procedures.

Never

ctx.runQuery

ctx.runMutation

ctx.runAction

for module procedures.

4) Query Modes (Use The Right One)

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

5) Mutation Patterns (Most Used)

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

6) Error Model

Use this map consistently:

```
BAD_REQUEST
```
: invalid input or business precondition.
```
UNAUTHORIZED
```
: no session.
```
FORBIDDEN
```
: session exists, permission missing.
```
NOT_FOUND
```
: missing or inaccessible resource.
```
CONFLICT
```
: duplicate or conflicting write.
```
TOO_MANY_REQUESTS
```
: rate limit.
```
INTERNAL_SERVER_ERROR
```
: unexpected failures only.
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:

unauthenticated rejection
permission rejection when relevant
missing resource path
conflict path when relevant
rate-limited write path when relevant

7) React Query Integration

Preconditions (must be true before writing/using

useCRPC()

code paths):

Generated imports exist (
```
@convex/api
```
) from setup bootstrap.
Provider chain is mounted (
```
CRPCProvider
```
inside QueryClient + Convex provider flow).
If bootstrap/provider prerequisites are missing, stop feature work and finish
```
references/setup/
```
first.
Backend state is project-local in
```
.convex/
```
, not
```
~/.convex
```
.

useCRPC()

pattern:

const crpc = useCRPC(); const projects = useQuery(crpc.project.listProjects.queryOptions({ cursor: null, limit: 20 })); const createProject = useMutation(crpc.project.createProject.mutationOptions());

Key client defaults/deltas:

Queries are real-time by default (
```
subscribe: true
```
).
Never use
```
queryClient.invalidateQueries
```
for subscribed cRPC query paths.
Use
```
{ subscribe: false }
```
only for one-time fetches; refresh those with explicit
```
refetch
```
/
```
fetchQuery
```
.
Use
```
skipUnauth: true
```
to avoid unauthorized fetch churn.
For pagination, use
```
useInfiniteQuery
```
from
```
kitcn/react
```
.
Prefer typed
```
queryKey(...)
```
helpers for cache read/write/fetch ops instead of manual keys.
For kitcn auth flows, prefer
```
createAuthMutations(...)
```
wrappers (not raw auth client calls) to avoid logout race errors. Raw Convex preset keeps the plain auth client path.

For mutation toasts, prefer

error.data?.message

over

error.message

;

data.message

is the clean

CRPCError

payload.

Prefer one global
```
QueryClient
```
mutation
```
onError
```
toast with
```
mutation.meta.errorMessage
```
/
```
skipErrorToast
```
rather than copy-pasting
```
onError
```
in every component.
Full client/RSC depth lives in
```
references/features/react.md
```
.

8) RSC Patterns (Next.js)

Choose one per use case:

```
prefetch(...)
```
(preferred): non-blocking, hydrated, client owns data.
```
caller.*
```
: blocking server-only logic (redirects/auth checks), not hydrated.
```
preloadQuery(...)
```
: blocking + hydrated when server needs data immediately.

Do not render

preloadQuery

result on server and again on client for the same data path.

```
HydrateClient
```
must wrap all client components that consume prefetched queries.
Next.js-specific setup and deeper hydration tradeoffs live in
```
references/setup/next.md
```
and
```
references/features/react.md
```
.

9) HTTP Route Pattern (When Feature Needs REST/Webhooks)

import { createTaskCaller } from "../functions/generated/task.runtime";

export const createTaskRoute = authRoute
  .post("/api/projects/:projectId/tasks")
  .params(z.object({ projectId: z.string() }))
  .input(z.object({ title: z.string().min(1) }))
  .output(z.object({ id: z.string() }))
  .mutation(async ({ ctx, params, input }) => {
    const caller = createTaskCaller(ctx);
    const id = await caller.createFromHttp({
      projectId: params.projectId,
      title: input.title,
      userId: ctx.userId,
    });
    return { id };
  });

HTTP-specific rules:

Use
```
z.coerce.*
```
for search params.
Keep auth and permission checks in middleware/procedure.
Apply rate limits to public/heavy endpoints.
Validate webhook signatures before any side effects.

Use

publicRoute

authRoute

optionalAuthRoute

builders from

convex/lib/crpc.ts

Compose endpoints with
```
router(...)
```
for feature-level HTTP grouping.
Client calls must pass path/query args as
```
{ params, searchParams }
```
; query values are strings.
Webhooks, streaming, and Hono-specific patterns live in
```
references/features/http.md
```
.

10) Scheduling Pattern (If Needed)

Example:

const caller = createTaskCaller(ctx); await caller.schedule.now.sendTaskCreated({ taskId: created.id, userId: ctx.userId }); await caller.schedule.at(input.sendAt).sendReminder({ taskId: input.taskId, userId: ctx.userId });

Scheduling rules:

Auth context is not propagated; pass user/org IDs explicitly.
Mutation scheduling is atomic with the mutation transaction.
Store returned job IDs when cancellation is required.
Scheduling inside actions is not atomic with action failure.
Cron schedules run in UTC.
Use
```
ctx.scheduler.*
```
directly only when you must schedule non-procedure
```
internal.*
```
functions.
Cron expressions and operational details live in
```
references/features/scheduling.md
```
.

11) Testing Baseline (High Signal)

Minimum feature test set:

happy path query/mutation
unauthenticated rejection (
```
UNAUTHORIZED
```
)
permission/ownership rejection (
```
FORBIDDEN
```
where relevant)
missing resource (
```
NOT_FOUND
```
)
trigger side effect assertion
scheduler assertion if feature schedules work
not-found checks should use real IDs or non-ID lookup keys (slug/name/email), not synthetic IDs
Full testing recipes live in
```
references/features/testing.md
```
.
If Convex bootstrap blocks integration tests, extract pure guards/helpers and keep one smoke integration test once bootstrap works.

Performance + Safety Checklist

Before calling a feature done:

Every list query is bounded (
```
limit
```
/cursor).
Filters/order align with indexes.
Expensive post-fetch logic uses pre-narrowed index path.
Mutations use targeted
```
where
```
and avoid accidental full scans.
Trigger logic is bounded, idempotent, and avoids ping-pong loops.
Error codes are explicit and intentional.
User-facing writes have rate-limit metadata.
Tests cover auth + not-found + side effects.
```
ctx.db
```
is not used on paths that rely on ORM constraints/RLS.
Paginated endpoints use
```
.paginated(...)
```
+ ORM cursor flow (not ad-hoc wrappers).
For any predicate/full-scan-like path,
```
.withIndex(...)
```
+ bound (
```
limit
```
/
```
maxScan
```
) is explicit.
NEVER use
```
@ts-nocheck
```
, no global lint-rule downgrades, no unresolved lint warnings in touched files.

Common Mistakes (And Fixes)

Mistake	Correct pattern
Raw Convex handler for new feature procedures	cRPC builders ( `publicQuery` , `authMutation` , etc.)
Write-time side effects duplicated across mutations	Schema trigger, or one centralized mutation-side sync helper when trigger path is unsafe
Missing bounds on list/search	Add `limit` + cursor/pagination
`orderBy` written as array objects	Use object form: `orderBy: { updatedAt: "desc" }`
Using `ctx.db` for policy-sensitive reads	Use `ctx.orm` (RLS/constraints path)
Throwing generic `Error` for expected outcomes	Throw `CRPCError` with explicit code
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
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
Putting secrets in `.meta(...)`	Keep metadata non-sensitive (client-visible)
Using `ctx.runQuery` / `ctx.runMutation` / `ctx.runAction` directly	Use `create<Module>Handler(ctx)` in queries/mutations, `create<Module>Caller(ctx)` in actions/HTTP with `caller.actions.` / `caller.schedule.` (from `generated/<module>.runtime` )
Using `createCaller` in query/mutation context	Use `create<Module>Handler(ctx)` — zero overhead, bypasses redundant validation
Adding `// @ts-nocheck` to unblock compile	NEVER do this; fix the underlying types using canonical patterns in `references/setup/`
Relaxing lint rules to pass checks	Keep baseline lint config; fix code-level warnings/errors instead

Reference Escalation Map (Load Only If Needed)

Setup (once per project):

```
references/setup/index.md
```
: bootstrap, env, decision intake, gates, checklist, troubleshooting
```
references/setup/server.md
```
: core backend (schema, ORM, cRPC) + optional module gates
```
references/setup/auth.md
```
: auth core bootstrap + plugin setup
```
references/setup/react.md
```
: client core (QueryClient, provider, cRPC context)
```
references/setup/next.md
```
: Next.js App Router setup
```
references/setup/start.md
```
: TanStack Start setup
```
references/setup/doc-guidelines.md
```
: skill/docs sync contract

Features (per session, self-contained):

```
references/features/orm.md
```
: full ORM API, constraints, RLS, advanced mutations, filtering/search/composition/pagination
```
references/features/react.md
```
: full client, RSC, hydration, error handling matrix
```
references/features/http.md
```
: typed REST routes, webhooks, streaming
```
references/features/scheduling.md
```
: cron + delayed job patterns
```
references/features/testing.md
```
: deeper testing scenarios
```
references/features/aggregates.md
```
: aggregate component patterns
```
references/features/migrations.md
```
: built-in online data migrations (defineMigration, CLI, deploy, drift). Load when: task involves data backfills, optional→required field hardening, field renames/removals, type narrowing, or
```
kitcn migrate
```
CLI commands. Skip for backward-compatible changes (new optional fields, new tables, code-level defaults).
```
references/features/create-plugins.md
```
: canonical plugin authoring patterns (split package entries, token config, scaffold/lockfile/CLI manifest rules). Load when: creating or refactoring plugins.
```
references/features/auth.md
```
: full Better Auth core flow
```
references/features/auth-admin.md
```
: admin plugin details

references/features/auth-organizations.md

: org/multi-tenant plugin details

kitcn

NPX Install

Tags

SKILL.md Content

kitcn Core Skill (80% Path)

Scope

Skill Contract

Shortcut Mode (tRPC + Drizzle Mental Model)

Directory Boundary (Important)

First-Pass Feature Intake (Do This Before Edits)

Canonical File Targets

E2E Build Order (Default)

Core Patterns

1) Schema + Relations + Trigger

2) Procedure Builders + Middleware

3) Query + Mutation Procedure Template

3b) Inter-Procedure Composition

4) Query Modes (Use The Right One)

5) Mutation Patterns (Most Used)

6) Error Model

7) React Query Integration

8) RSC Patterns (Next.js)

9) HTTP Route Pattern (When Feature Needs REST/Webhooks)

10) Scheduling Pattern (If Needed)

11) Testing Baseline (High Signal)

Performance + Safety Checklist

Common Mistakes (And Fixes)

Reference Escalation Map (Load Only If Needed)