udecode · zbeyens · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.changeset/tidy-convex-upgrade.md b/.changeset/tidy-convex-upgrade.md
@@ -0,0 +1,16 @@
+---
+"@kitcn/resend": minor
+"kitcn": minor
+---
+
+## Breaking changes
+
+- Require Convex 1.42 or newer.
+
+  ```bash
+  # Before
+  bun add convex@1.38.0
+
+  # After
+  bun add convex@1.42.3
+  ```
diff --git a/bun.lock b/bun.lock
diff --git a/docs/plans/2026-07-30-convex-1-42-compatibility.md b/docs/plans/2026-07-30-convex-1-42-compatibility.md
diff --git a/docs/plans/2026-07-30-convex-release-audit.md b/docs/plans/2026-07-30-convex-release-audit.md
diff --git a/...solutions/integration-issues/convex-142-owns-local-backend-upgrades-20260730.md b/...solutions/integration-issues/convex-142-owns-local-backend-upgrades-20260730.md
@@ -0,0 +1,89 @@
+---
+title: Convex 1.42 owns non-interactive local backend upgrades
+date: 2026-07-30
+category: integration-issues
+module: kitcn cli
+problem_type: integration_issue
+component: development_workflow
+symptoms:
+  - kitcn retains a hidden `convex dev --local` recovery command
+  - Convex 1.40 rejects `convex dev --local`
+  - local bootstrap behavior is duplicated between kitcn and Convex
+root_cause: obsolete_workaround
+resolution_type: dependency_upgrade
+severity: high
+tags:
+  - kitcn
+  - convex
+  - dev
+  - bootstrap
+  - non-interactive
+  - local-backend
+---
+
+# Convex 1.42 owns non-interactive local backend upgrades
+
+## Problem
+
+Older Convex versions could fail `convex init` when a local backend upgrade
+needed interactive confirmation. Kitcn recovered by detecting the prompt and
+running a hidden command:
+
+```text
+convex dev --local --once --skip-push --local-force-upgrade --typecheck disable --codegen disable
+```
+
+That command is invalid on the supported Convex 1.42 contract. Convex 1.40
+replaced `dev --local` with explicit deployment selection, and Convex 1.42
+automatically confirms local upgrades when stdin is not a TTY.
+
+## Symptoms
+
+- Source or tests still mention `isLocalBackendUpgradePrompt`.
+- Kitcn runs `convex dev --local` after `convex init` fails.
+- A supported Convex CLI exits with `` `--local` is deprecated `` instead of
+  recovering.
+
+## What Didn't Work
+
+- Keeping the fallback and only removing `--local`.
+  Target Convex already owns non-interactive upgrade confirmation, so the
+  second bootstrap path has no supported failure to recover.
+- Preserving tests that synthesize the old prompt.
+  Those tests lock kitcn to behavior below its declared peer floor.
+- Adding another version check.
+  The package contract already defines the supported Convex behavior.
+
+## Solution
+
+Run `convex init` once and treat its result as authoritative:
+
+```ts
+const initCommandArgs = [
+  ...params.backendAdapter.argsPrefix,
+  "init",
+  ...(params.targetArgs ?? []),
+];
+
+const result = await runCommand(initCommandArgs);
+```
+
+Kitcn launches the command with piped stdio. Convex 1.42 reads that as
+non-interactive and transfers local data during the backend upgrade without
+asking a question. One upstream command owns deployment selection, upgrade
+policy, output, and failure.
+
+## Prevention
+
+- Do not preserve hidden Convex flags after the supported peer floor makes them
+  invalid.
+- Read the target CLI source before translating a removed flag into another
+  workaround.
+- Keep one regression test proving normal local dev stays on `convex init`.
+- Test supported behavior, not synthetic errors from versions below the peer
+  floor.
+
+## Related Issues
+
+- [published-cli-bootstrap-must-ship-runtime-deps-and-anonymous-convex-init-20260331](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/published-cli-bootstrap-must-ship-runtime-deps-and-anonymous-convex-init-20260331.md)
+- [dev-preflight-and-fast-failure-output-must-not-be-silent-20260325](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/dev-preflight-and-fast-failure-output-must-not-be-silent-20260325.md)
diff --git a/...n-issues/dev-local-preflight-must-auto-upgrade-local-convex-backend-20260410.md b/...n-issues/dev-local-preflight-must-auto-upgrade-local-convex-backend-20260410.md
diff --git a/...tion-issues/local-auth-env-sync-must-use-real-convex-cli-entrypoint-20260417.md b/...tion-issues/local-auth-env-sync-must-use-real-convex-cli-entrypoint-20260417.md
@@ -106,4 +106,4 @@ split-brain behavior.
 ## Related Issues
 
 - [auth-env-push-must-be-auth-aware-and-dev-bootstrap-must-stay-two-phase-20260324](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/auth-env-push-must-be-auth-aware-and-dev-bootstrap-must-stay-two-phase-20260324.md)
-- [dev-local-preflight-must-auto-upgrade-local-convex-backend-20260410](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/dev-local-preflight-must-auto-upgrade-local-convex-backend-20260410.md)
+- [Convex 1.42 owns non-interactive local backend upgrades](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/convex-142-owns-local-backend-upgrades-20260730.md)
diff --git a/...ions/workflow-issues/convex-135-owns-anonymous-noninteractive-setup-20260415.md b/...ions/workflow-issues/convex-135-owns-anonymous-noninteractive-setup-20260415.md
@@ -100,12 +100,12 @@ rg -n "CONVEX_AGENT_MODE|anonymous-agent|local-force-upgrade" \
   packages tooling docs
 ```
 
-Do not remove the local backend upgrade fallback just because anonymous setup
-improved. `--local-force-upgrade` still covers the older-backend upgrade prompt,
-which is a different upstream gap.
+For Convex 1.42 and newer, remove the separate local backend upgrade fallback.
+Piped `convex init` owns upgrade confirmation, and `convex dev --local` is
+rejected. See the current local-upgrade note below.
 
 ## Related
 
 - [Published CLI bootstrap must keep TypeScript off the cold path and use anonymous Convex init](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/published-cli-bootstrap-must-ship-runtime-deps-and-anonymous-convex-init-20260331.md)
 - [Verify must prove local runtime without leaking Convex agent plumbing](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/verify-command-must-prove-local-runtime-without-leaking-convex-agent-plumbing-20260325.md)
-- [dev local preflight must auto-upgrade local Convex backend](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/dev-local-preflight-must-auto-upgrade-local-convex-backend-20260410.md)
+- [Convex 1.42 owns non-interactive local backend upgrades](/Users/zbeyens/git/better-convex/docs/solutions/integration-issues/convex-142-owns-local-backend-upgrades-20260730.md)
diff --git a/example/package.json b/example/package.json
@@ -45,7 +45,7 @@
     "clsx": "2.1.1",
     "cmdk": "1.1.1",
     "common-tags": "1.8.2",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "date-fns": "4.1.0",
     "embla-carousel-react": "8.6.0",
     "hono": "4.12.9",

diff --git a/fixtures/expo-auth/package.json b/fixtures/expo-auth/package.json
@@ -7,7 +7,7 @@
     "@react-navigation/native": "^7.1.33",
     "@tanstack/react-query": "5.95.2",
     "better-auth": "1.6.18",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "expo": "~55.0.28",
     "expo-constants": "~55.0.17",
     "expo-device": "~55.0.19",

diff --git a/fixtures/expo/package.json b/fixtures/expo/package.json
@@ -5,7 +5,7 @@
     "@react-navigation/elements": "^2.9.10",
     "@react-navigation/native": "^7.1.33",
     "@tanstack/react-query": "5.95.2",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "expo": "~55.0.28",
     "expo-constants": "~55.0.17",
     "expo-device": "~55.0.19",

diff --git a/fixtures/next-auth/package.json b/fixtures/next-auth/package.json
@@ -6,10 +6,10 @@
     "better-auth": "1.6.18",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.28.0",
     "next": "16.2.6",
     "next-themes": "^0.4.6",
     "react": "19.2.4",

diff --git a/fixtures/next/package.json b/fixtures/next/package.json
@@ -5,10 +5,10 @@
     "@tanstack/react-query": "5.95.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.28.0",
     "next": "16.2.6",
     "next-themes": "^0.4.6",
     "react": "19.2.4",

diff --git a/fixtures/start-auth/package.json b/fixtures/start-auth/package.json
@@ -14,10 +14,10 @@
     "better-auth": "1.6.18",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.28.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

diff --git a/fixtures/start/package.json b/fixtures/start/package.json
@@ -13,10 +13,10 @@
     "@tanstack/router-plugin": "latest",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.28.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

diff --git a/fixtures/vite-auth/package.json b/fixtures/vite-auth/package.json
@@ -8,10 +8,10 @@
     "better-auth": "1.6.18",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.28.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",

diff --git a/fixtures/vite/package.json b/fixtures/vite/package.json
@@ -7,10 +7,10 @@
     "@tanstack/react-query": "5.95.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "convex": "1.38.0",
+    "convex": "1.42.3",
     "hono": "4.12.9",
     "kitcn": "workspace:*",
-    "lucide-react": "^1.27.0",
+    "lucide-react": "^1.28.0",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "shadcn": "latest",