kitcn 0.12.27 → 0.13.0

package/dist/token-tpipF-7y.js

@@ -0,0 +1,47 @@
+import { t as JWT_COOKIE_NAME } from "./convex-plugin-C3N9BB-J.js";
+import { betterFetch } from "@better-fetch/fetch";
+import { getSessionCookie } from "better-auth/cookies";
+import * as jose from "jose";
+
+//#region src/auth/internal/token-utils.ts
+const TRAILING_SLASH_RE = /\/$/;
+const resolveConvexTokenPath = (basePath) => {
+	return `${basePath && basePath !== "/" ? basePath.replace(TRAILING_SLASH_RE, "") : "/api/auth"}/convex/token`;
+};
+const isTokenExpired = (exp, expirationToleranceSeconds = 60, now = Math.floor(Date.now() / 1e3)) => {
+	if (!exp) return true;
+	return now >= exp - expirationToleranceSeconds;
+};
+
+//#endregion
+//#region src/auth/internal/token.ts
+const getToken = async (siteUrl, headers, opts) => {
+	const fetchToken = async () => {
+		const { data } = await betterFetch(resolveConvexTokenPath(opts?.basePath), {
+			baseURL: siteUrl,
+			headers
+		});
+		return {
+			isFresh: true,
+			token: data?.token
+		};
+	};
+	if (!opts?.jwtCache?.enabled || opts.forceRefresh) return await fetchToken();
+	const token = getSessionCookie(new Headers(headers), {
+		cookieName: JWT_COOKIE_NAME,
+		cookiePrefix: opts?.cookiePrefix
+	});
+	if (!token) return await fetchToken();
+	try {
+		if (!isTokenExpired(jose.decodeJwt(token)?.exp, opts?.jwtCache?.expirationToleranceSeconds ?? 60)) return {
+			isFresh: false,
+			token
+		};
+	} catch (error) {
+		console.error("Error decoding JWT", error);
+	}
+	return await fetchToken();
+};
+
+//#endregion
+export { getToken as t };

package/dist/{types-C6pQrnzD.d.ts → types-YHpe0rsb.d.ts}

@@ -1,4 +1,4 @@
-import { O as CombinedDataTransformer, n as HttpClientError } from "./http-types-BLFA9zS7.js";
+import { O as CombinedDataTransformer, n as HttpClientError } from "./http-types-zsMHb_QN.js";
 import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
 
 //#region src/crpc/http-client.d.ts

package/dist/upstream-BR6sBLg3.js

@@ -0,0 +1,84 @@
+//#region src/internal/upstream/index.ts
+/** biome-ignore-all lint: vendored upstream helper source */
+/**
+* Vendored from upstream helper repository at commit c5e52c8.
+* Source path: packages/convex_helpers/index.ts
+*/
+/**
+* asyncMap returns the results of applying an async function over an list.
+*
+* The list can even be a promise, or an iterable like a Set.
+* @param list - Iterable object of items, e.g. an Array, Set, Object.keys
+* @param asyncTransform
+* @returns
+*/
+async function asyncMap(list, asyncTransform) {
+	const promises = [];
+	let index = 0;
+	list = await list;
+	for (const item of list) {
+		promises.push(asyncTransform(item, index));
+		index += 1;
+	}
+	return Promise.all(promises);
+}
+/**
+* pick helps you pick keys from an object more concisely.
+*
+* e.g. `pick({a: v.string(), b: v.number()}, ["a"])` is equivalent to
+* `{a: v.string()}`
+* The alternative could be something like:
+* ```js
+* const obj = { a: v.string(), b: v.number() };
+* // pick does the following
+* const { a } = obj;
+* const onlyA = { a };
+* ```
+*
+* @param obj The object to pick from. Often like { a: v.string() }
+* @param keys The keys to pick from the object.
+* @returns A new object with only the keys you picked and their values.
+*/
+function pick(obj, keys) {
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k)));
+}
+/**
+* omit helps you omit keys from an object more concisely.
+*
+* e.g. `omit({a: v.string(), b: v.number()}, ["a"])` is equivalent to
+* `{b: v.number()}`
+*
+* The alternative could be something like:
+* ```js
+* const obj = { a: v.string(), b: v.number() };
+* // omit does the following
+* const { a, ...rest } = obj;
+* const withoutA = rest;
+* ```
+*
+* @param obj The object to return a copy of without the specified keys.
+* @param keys The keys to omit from the object.
+* @returns A new object with the keys you omitted removed.
+*/
+function omit(obj, keys) {
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k)));
+}
+/**
+* A utility to validate truthiness at runtime, providing a type guard
+*
+* @example
+* ```ts
+* const x: string | null = getValue();
+* assert(x);
+* // x is now of type string
+* ```
+* You can also provide a function, to avoid doing expensive string templating.
+* @param arg A value to assert the truthiness of.
+* @param message An optional message to throw if the value is not truthy, or a function to generate the message.
+*/
+function assert(value, message) {
+	if (!value) throw new Error(typeof message === "function" ? message() : message);
+}
+
+//#endregion
+export { pick as i, asyncMap as n, omit as r, assert as t };

package/dist/upstream-BUCdbLok.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+//#region src/internal/upstream/index.ts
+/**
+* omit helps you omit keys from an object more concisely.
+*
+* e.g. `omit({a: v.string(), b: v.number()}, ["a"])` is equivalent to
+* `{b: v.number()}`
+*
+* The alternative could be something like:
+* ```js
+* const obj = { a: v.string(), b: v.number() };
+* // omit does the following
+* const { a, ...rest } = obj;
+* const withoutA = rest;
+* ```
+*
+* @param obj The object to return a copy of without the specified keys.
+* @param keys The keys to omit from the object.
+* @returns A new object with the keys you omitted removed.
+*/
+function omit(obj, keys) {
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k)));
+}
+
+//#endregion
+export { omit as t };

package/dist/{validators-B7oIJCAp.js → validators-C7LelqTN.js}

@@ -1,88 +1,6 @@
+import { t as assert } from "./upstream-BR6sBLg3.js";
 import { asObjectValidator, v } from "convex/values";
 
-//#region src/internal/upstream/index.ts
-/** biome-ignore-all lint: vendored upstream helper source */
-/**
-* Vendored from upstream helper repository at commit c5e52c8.
-* Source path: packages/convex_helpers/index.ts
-*/
-/**
-* asyncMap returns the results of applying an async function over an list.
-*
-* The list can even be a promise, or an iterable like a Set.
-* @param list - Iterable object of items, e.g. an Array, Set, Object.keys
-* @param asyncTransform
-* @returns
-*/
-async function asyncMap(list, asyncTransform) {
-	const promises = [];
-	let index = 0;
-	list = await list;
-	for (const item of list) {
-		promises.push(asyncTransform(item, index));
-		index += 1;
-	}
-	return Promise.all(promises);
-}
-/**
-* pick helps you pick keys from an object more concisely.
-*
-* e.g. `pick({a: v.string(), b: v.number()}, ["a"])` is equivalent to
-* `{a: v.string()}`
-* The alternative could be something like:
-* ```js
-* const obj = { a: v.string(), b: v.number() };
-* // pick does the following
-* const { a } = obj;
-* const onlyA = { a };
-* ```
-*
-* @param obj The object to pick from. Often like { a: v.string() }
-* @param keys The keys to pick from the object.
-* @returns A new object with only the keys you picked and their values.
-*/
-function pick(obj, keys) {
-	return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k)));
-}
-/**
-* omit helps you omit keys from an object more concisely.
-*
-* e.g. `omit({a: v.string(), b: v.number()}, ["a"])` is equivalent to
-* `{b: v.number()}`
-*
-* The alternative could be something like:
-* ```js
-* const obj = { a: v.string(), b: v.number() };
-* // omit does the following
-* const { a, ...rest } = obj;
-* const withoutA = rest;
-* ```
-*
-* @param obj The object to return a copy of without the specified keys.
-* @param keys The keys to omit from the object.
-* @returns A new object with the keys you omitted removed.
-*/
-function omit(obj, keys) {
-	return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k)));
-}
-/**
-* A utility to validate truthiness at runtime, providing a type guard
-*
-* @example
-* ```ts
-* const x: string | null = getValue();
-* assert(x);
-* // x is now of type string
-* ```
-* You can also provide a function, to avoid doing expensive string templating.
-* @param arg A value to assert the truthiness of.
-* @param message An optional message to throw if the value is not truthy, or a function to generate the message.
-*/
-function assert(value, message) {
-	if (!value) throw new Error(typeof message === "function" ? message() : message);
-}
-
-//#endregion
 //#region src/internal/upstream/validators.ts
 function partial(fieldsOrObjOrUnion) {
 	if (fieldsOrObjOrUnion.isConvexValidator) {
@@ -276,4 +194,4 @@ function vRequired(validator) {
 }
 
 //#endregion
-export { pretendRequired as a, omit as c, pretend as i, pick as l, deprecated as n, vRequired as o, partial as r, asyncMap as s, addFieldsToValidator as t };
+export { pretendRequired as a, pretend as i, deprecated as n, vRequired as o, partial as r, addFieldsToValidator as t };

package/dist/watcher.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { A as resolveConfiguredBackend, Ct as generateMeta, K as withLocalCodegenEnv, P as resolveRunDeps, Tt as logger, wt as getConvexConfig } from "./backend-core-DqCCa0nr.mjs";
+import { Dt as logger, Et as getConvexConfig, F as resolveRunDeps, Tt as generateMeta, j as resolveConfiguredBackend, q as withLocalCodegenEnv } from "./backend-core-CXmrWqdi.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 

package/dist/{where-clause-compiler-DdjN63Io.d.ts → where-clause-compiler-TMppDl9g.d.ts}

@@ -1,4 +1,4 @@
-import { a as ReturnTypeOrValue, i as KnownKeysOnly, o as Simplify$1, t as Assume } from "./types-BTb_4BaU.js";
+import { a as ReturnTypeOrValue, i as KnownKeysOnly, o as Simplify$1, t as Assume } from "./types-DF2cg_w0.js";
 import * as convex_values0 from "convex/values";
 import { GenericId, Validator, Value } from "convex/values";
 import { DefineSchemaOptions, FilterExpression, GenericDatabaseReader, GenericDatabaseWriter, GenericIndexFields, GenericSchema, GenericTableIndexes, GenericTableSearchIndexes, GenericTableVectorIndexes, IndexRange, IndexRangeBuilder, SchedulableFunctionReference, Scheduler, SchemaDefinition, TableDefinition, VectorFilterBuilder, internalActionGeneric, internalMutationGeneric } from "convex/server";
@@ -3717,19 +3717,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_bucket: ConvexTableWithColumns<{
     name: "aggregate_bucket";
     columns: {
-      count: ConvexNumberBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_bucket";
-        };
-      } & {
-        _: {
-          fieldName: "count";
-        };
-      };
       tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -3799,6 +3786,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "keyParts";
         };
       };
+      count: ConvexNumberBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_bucket";
+        };
+      } & {
+        _: {
+          fieldName: "count";
+        };
+      };
       sumValues: (NotNull<$Type<ConvexCustomBuilderInitial<"", convex_values0.VRecord<Record<string, any>, convex_values0.VString<string, "required">, convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>, "required", string>>, Record<string, number>>> | NotNull<$Type<ConvexCustomBuilderInitial<"", convex_values0.VId<any, any> | convex_values0.VString<any, any> | convex_values0.VFloat64<any, any> | convex_values0.VInt64<any, any> | convex_values0.VBoolean<any, any> | convex_values0.VNull<any, any> | convex_values0.VAny<any, any, string> | convex_values0.VLiteral<any, any> | convex_values0.VBytes<any, any> | convex_values0.VObject<any, Record<string, convex_values0.Validator<any, convex_values0.OptionalProperty, any>>, any, any> | convex_values0.VArray<any, convex_values0.Validator<any, "required", any>, any> | convex_values0.VRecord<any, convex_values0.Validator<string, "required", any>, convex_values0.Validator<any, "required", any>, any, any> | convex_values0.VUnion<any, convex_values0.Validator<any, "required", any>[], any, any>>, Record<string, number>>>) & {
         _: {
           tableName: "aggregate_bucket";
@@ -4009,7 +4009,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "value";
         };
       };
-      count: ConvexNumberBuilderInitial<""> & {
+      tableKey: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4019,10 +4019,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "count";
+          fieldName: "tableKey";
         };
       };
-      tableKey: ConvexTextBuilderInitial<""> & {
+      indexName: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4032,10 +4032,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "tableKey";
+          fieldName: "indexName";
         };
       };
-      indexName: ConvexTextBuilderInitial<""> & {
+      updatedAt: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4045,10 +4045,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "indexName";
+          fieldName: "updatedAt";
         };
       };
-      updatedAt: ConvexNumberBuilderInitial<""> & {
+      keyHash: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4058,10 +4058,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "updatedAt";
+          fieldName: "keyHash";
         };
       };
-      keyHash: ConvexTextBuilderInitial<""> & {
+      count: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4071,7 +4071,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "keyHash";
+          fieldName: "count";
         };
       };
       fieldName: ConvexTextBuilderInitial<""> & {
@@ -4244,6 +4244,19 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly aggregate_state: ConvexTableWithColumns<{
     name: "aggregate_state";
     columns: {
+      status: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
+        _: {
+          tableName: "aggregate_state";
+        };
+      } & {
+        _: {
+          fieldName: "status";
+        };
+      };
       kind: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4318,19 +4331,6 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
           fieldName: "metricDefinitionHash";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
-        _: {
-          tableName: "aggregate_state";
-        };
-      } & {
-        _: {
-          fieldName: "status";
-        };
-      };
       processed: ConvexNumberBuilderInitial<""> & {
         _: {
           notNull: true;
@@ -4398,35 +4398,35 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_state: ConvexTableWithColumns<{
     name: "migration_state";
     columns: {
-      cursor: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
+        _: {
+          notNull: true;
+        };
+      } & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "cursor";
+          fieldName: "status";
         };
       };
-      direction: ConvexTextBuilderInitial<""> & {
+      cursor: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "cursor";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
-        _: {
-          notNull: true;
-        };
-      } & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           tableName: "migration_state";
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "direction";
         };
       };
       processed: ConvexNumberBuilderInitial<""> & {
@@ -4552,7 +4552,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
   readonly migration_run: ConvexTableWithColumns<{
     name: "migration_run";
     columns: {
-      direction: ConvexTextBuilderInitial<""> & {
+      status: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4562,10 +4562,10 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "direction";
+          fieldName: "status";
         };
       };
-      status: ConvexTextBuilderInitial<""> & {
+      direction: ConvexTextBuilderInitial<""> & {
         _: {
           notNull: true;
         };
@@ -4575,7 +4575,7 @@ declare const BUILTIN_SCHEMA_EXTENSIONS: readonly [SchemaExtension<{
         };
       } & {
         _: {
-          fieldName: "status";
+          fieldName: "direction";
         };
       };
       startedAt: ConvexNumberBuilderInitial<""> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitcn",
-  "version": "0.12.27",
+  "version": "0.13.0",
   "description": "kitcn - React Query integration and CLI tools for Convex",
   "keywords": [
     "convex",
@@ -58,8 +58,8 @@
   },
   "dependencies": {
     "@babel/parser": "^7.28.4",
+    "@better-fetch/fetch": "^1.1.21",
     "@clack/prompts": "^0.11.0",
-    "@convex-dev/better-auth": "^0.11.1",
     "chokidar": "^5.0.0",
     "common-tags": "^1.8.2",
     "diff": "^8.0.2",
@@ -69,6 +69,7 @@
     "jiti": "^2.6.1",
     "jotai": "^2.18.0",
     "jotai-x": "^2.3.3",
+    "jose": "^6.1.3",
     "picocolors": "^1.1.1",
     "remeda": "^2.33.6",
     "svix": "^1.84.1",
@@ -88,8 +89,8 @@
     "@tanstack/query-core": ">=5",
     "@tanstack/react-query": ">=5",
     "@tanstack/solid-query": ">=5",
-    "better-auth": "1.5.3",
-    "convex": ">=1.33",
+    "better-auth": "1.6.5",
+    "convex": ">=1.35",
     "hono": "4.12.9",
     "next": ">=14",
     "react": ">=18",

package/skills/convex/references/features/auth.md

@@ -161,6 +161,9 @@ If you want to own the auth tables by hand, use `setup/server.md`.
 
 Import auth route helpers from `kitcn/auth/http`.
 That entrypoint auto-installs the Convex-safe `MessageChannel` polyfill.
+`registerRoutes` is lazy by default, so Better Auth does not initialize during
+`convex/http.ts` registration. If your auth config uses a custom base path, pass
+the same `basePath` to `registerRoutes`.
 
 ### 7. HTTP Routes
 
@@ -186,6 +189,23 @@ app.use(authMiddleware(getAuth));
 export default createHttpRouter(app, httpRouter);
 ```
 
+```ts
+// convex/functions/http.ts - plain Convex option
+import { registerRoutes } from 'kitcn/auth/http';
+import { httpRouter } from 'convex/server';
+import { getAuth } from './generated/auth';
+
+const http = httpRouter();
+
+registerRoutes(http, getAuth, {
+  cors: {
+    allowedOrigins: [process.env.SITE_URL!],
+  },
+});
+
+export default http;
+```
+
 ### 8. Environment Variables
 
 ```bash

package/skills/convex/references/setup/auth.md

@@ -200,6 +200,8 @@ Keep all auth reads/writes on ORM table definitions in `convex/functions/schema.
 
 Use `kitcn/auth/http` for `authMiddleware` or `registerRoutes`.
 It auto-installs the Convex-safe `MessageChannel` polyfill, so no manual `http-polyfills.ts` file is needed.
+`registerRoutes` is lazy by default. If the auth config uses a custom base path,
+pass that same `basePath` in the route options.
 
 **Create:** `convex/functions/http.ts`
 

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

@@ -91,9 +91,9 @@ npx kitcn@latest init -t next --yes
 
 Then start the long-running backend with `bunx kitcn dev`, run the
 framework dev server (`bun dev` for the Next starter), and open `/convex` for
-the scaffolded messages demo. In `--yes` mode, kitcn provisions an anonymous
-local Convex deployment when no account is linked yet, so the starter path does
-not stop on a login prompt.
+the scaffolded messages demo. In `--yes` mode, Convex uses anonymous local
+deployment setup when no account is linked yet, so the starter path does not
+stop on a login prompt.
 
 Use the CLI first:
 
@@ -759,7 +759,7 @@ This runbook + references map to the canonical template shape as follows:
 | Symptom                                                                               | Likely Cause                                                                                    | Fix                                                                                                                                                                                         |
 | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@convex/api` not found                                                               | `kitcn dev` not run                                                                     | Run `bunx kitcn dev` and regenerate API metadata                                                                                                                                    |
-| `Cannot prompt for input in non-interactive terminals` during bootstrap               | Convex deployment selection still needs a local choice                                          | Use `bunx kitcn verify` for local proof, or pass `--env-file` / deployment-target args so Convex can resolve the deployment without prompting                                      |
+| `Cannot prompt for input in non-interactive terminals` during bootstrap               | Convex deployment targeting is ambiguous                                                        | Use `bunx kitcn verify` for local proof, or pass `--env-file` / deployment-target args so Convex can resolve the deployment without prompting                                      |
 | Can't find new local backend files under `~/.convex`                                  | Convex now stores new local deployment state per project                                        | Check `.convex/local/default/` in the current project root; treat `~/.convex/**` as legacy storage                                                                                          |
 | `kitcn env push` fails to set auth vars                                       | Target deployment is not active or not initialized                                              | For local proof, run `bunx kitcn verify`. For remote targets, resolve deployment targeting, then rerun `bunx kitcn env push`                                             |
 | `Failed to analyze auth.js` with `Unexpected token` / `map is not a function` on JWKS | Static `JWKS` value is malformed JSON                                                           | Unset/fix `JWKS`; use `getAuthConfigProvider()` fallback or repush with `bunx kitcn env push`                                                                                       |
@@ -772,7 +772,7 @@ This runbook + references map to the canonical template shape as follows:
 | `Property 'insert'/'update' does not exist on type 'OrmReader'`                       | Using query context for mutations                                                               | Ensure mutation handlers use `publicMutation` / `protectedMutation` builders                                                                                                                |
 | `useCRPC must be used within CRPCProvider`                                            | Provider chain not mounted around route tree                                                    | Wrap app with `AppConvexProvider` and verify `CRPCProvider` is inside QueryClientProvider (Section 7.4 / 8.A.4)                                                                          |
 | Route auth cookies not set                                                            | Missing CORS auth headers                                                                       | Add `Better-Auth-Cookie` allow/expose headers + credentials                                                                                                                                 |
-| TanStack Start auth helper import errors                                              | Using `kitcn/auth/nextjs` in Start app                                                  | Use TanStack Start exception with `@convex-dev/better-auth/*` helpers                                                                                                                       |
+| TanStack Start auth helper import errors                                              | Using `kitcn/auth/nextjs` in Start app                                                  | Use the TanStack Start helper from `kitcn/auth/start`                                                                                                                                        |
 | `Returned promise will never resolve` from internal function                          | Trigger path is recursively querying/updating related rows or stale component wiring still runs | Isolate failing write with logs, disable/move trigger-side sync into explicit mutation helper, rerun `bunx kitcn verify`, then retry the runtime proof                            |
 | Better Auth secret mismatch/warnings in setup flows                                   | `BETTER_AUTH_SECRET` manually set inconsistently or low entropy                                 | Let `bunx kitcn dev` manage local bootstrap, or regenerate/push via `bunx kitcn env push` for active non-local targets                                                   |
 | `Invalid orderBy value. Use a column or asc()/desc()`                                 | Wrong `orderBy` shape (`[{ field, direction }]`)                                                | Use object form only, e.g. `orderBy: { updatedAt: "desc" }`                                                                                                                                 |

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

@@ -205,7 +205,7 @@ Do not fake generated files.
 Automation/non-interactive path:
 
 1. Run `npx kitcn@latest init --yes` when you want scaffold or adoption plus the one-shot local Convex bootstrap in one command.
-2. Run `bunx kitcn verify` when you want a non-interactive local runtime proof in the current app. Stop any long-running local backend first. It reuses an existing local deployment when one is already configured, and only falls back to anonymous fresh-local setup when it has to.
+2. Run `bunx kitcn verify` when you want a non-interactive local runtime proof in the current app. Stop any long-running local backend first. It reuses an existing local deployment when one is already configured, and lets Convex create anonymous local state when no local deployment is configured.
 3. Confirm the generated runtime exists in `convex/functions/generated/server.ts`.
 4. Then run `bunx kitcn dev` for ongoing codegen/API refresh.