update and add ai guidance

[djanogly]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opencom-landing	Ready	Preview, Comment	Apr 16, 2026 9:57pm
opencom-web	Ready	Preview, Comment	Apr 16, 2026 9:57pm

[qodo-code-review]

Review Summary by Qodo

Upgrade Convex to 1.35.1 and add comprehensive AI guidance with agent skills

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• **Upgraded Convex framework to version 1.35.1** across all workspace packages (package.json,
  pnpm-lock.yaml, and individual app/package dependencies)
• **Added comprehensive AI guidance and agent skills** for Convex development:
  - Core guidelines covering function registration, HTTP endpoints, validators, pagination, schema
  design, authentication, and testing patterns
  - Five new agent skills: convex-quickstart, convex-setup-auth, convex-create-component,
  convex-migration-helper, and convex-performance-audit
  - Each skill includes detailed reference guides for specific workflows (Auth0, Clerk, WorkOS, Convex
  Auth, migrations, performance optimization)
• **Enhanced documentation** with new AGENTS.md and CLAUDE.md files directing developers to AI
  guidance
• **Added agent skill configurations** with OpenAI interface definitions for automatic skill
  invocation
• **Updated roadmap** with UI improvements and AI agent enhancements
• **Locked agent skills versions** in skills-lock.json for reproducible AI guidance

Diagram

flowchart LR
  A["Convex 1.33.0"] -- "upgrade" --> B["Convex 1.35.1"]
  C["Agent Skills"] -- "install" --> D["AI Guidelines & References"]
  D -- "enable" --> E["AI-Assisted Development"]
  B --> E
  F["Documentation"] -- "enhance" --> E

Loading

File Changes

1. convex/_generated/ai/guidelines.md 📝 Documentation +365/-0

Comprehensive Convex development guidelines and best practices

• Added comprehensive Convex development guidelines covering function registration, HTTP endpoints,
 validators, and pagination patterns
• Included schema design best practices, authentication setup with JWT providers, and TypeScript
 type safety recommendations
• Documented query optimization rules, mutation patterns, action guidelines, and scheduling with
 cron jobs
• Added testing guidelines using convex-test with vitest, and file storage patterns with the
 _storage system table

convex/_generated/ai/guidelines.md

---

2. pnpm-lock.yaml Dependencies +31/-28

Upgrade Convex framework to version 1.35.1

• Updated convex dependency from 1.33.0 to 1.35.1 across all workspace packages
• Updated @convex-dev/auth peer dependency references to use convex@1.35.1
• Updated convex-test dependency to use convex@1.35.1
• Added optional peer dependency @clerk/react@^6.0.0 to convex package

pnpm-lock.yaml

---

3. .agents/skills/convex-quickstart/SKILL.md 📝 Documentation +347/-0

Convex project initialization and setup skill guide

• Added comprehensive quickstart skill for initializing new Convex projects or adding Convex to
 existing apps
• Documented scaffolding with npm create convex@latest templates and provider wiring for React,
 Next.js, and other frameworks
• Included environment variable configuration, agent mode for headless environments, and first
 function examples
• Provided development vs production deployment guidance and next steps for authentication and
 schema design

.agents/skills/convex-quickstart/SKILL.md

---

View more (35)

4. .agents/skills/convex-performance-audit/references/hot-path-rules.md 📝 Documentation +369/-0

Hot path optimization rules for Convex performance

• Documented rules for optimizing hot paths including pushing filters to storage with indexes
• Covered denormalization patterns, row size minimization with digest tables, and isolation of
 frequently-updated fields
• Included migration safety rules for index rollouts and redundant index detection
• Provided Convex-specific patterns for reactive queries, point-in-time reads, triggers, and
 backfill strategies

.agents/skills/convex-performance-audit/references/hot-path-rules.md

---

5. .agents/skills/convex-create-component/SKILL.md 📝 Documentation +288/-0

Convex component creation and architecture skill

• Added skill for designing and building reusable Convex components with isolated tables and clear
 boundaries
• Documented local vs packaged component shapes and decision tree for choosing component
 architecture
• Included component skeleton example with schema, functions, and app-side wrappers
• Provided critical rules for authentication, environment access, ID handling across boundaries, and
 client-facing API patterns

.agents/skills/convex-create-component/SKILL.md

---

6. .agents/skills/convex-performance-audit/references/subscription-cost.md 📝 Documentation +252/-0

Subscription cost analysis and optimization guide

• Documented subscription cost optimization for reactive queries and live subscriptions
• Covered symptoms and common causes including overly broad queries and frequently-updated fields on
 widely-read documents
• Provided fix strategies: point-in-time reads, batching related data, using skip, isolating
 high-churn fields, and pagination strategies
• Included verification checklist and guidance on separating backend cost from UI churn

.agents/skills/convex-performance-audit/references/subscription-cost.md

---

7. .agents/skills/convex-setup-auth/references/convex-auth.md 📝 Documentation +143/-0

Convex Auth setup and configuration reference

• Added reference guide for setting up Convex Auth as the authentication provider
• Documented workflow from installation through schema updates, provider wiring, and auth method
 configuration
• Included concrete steps for npx @convex-dev/auth initialization and environment setup
• Provided gotchas, production deployment guidance, and validation checklist for sign-in flows

.agents/skills/convex-setup-auth/references/convex-auth.md

---

8. .agents/skills/convex-performance-audit/references/function-budget.md 📝 Documentation +232/-0

Function execution budget and resource limits guide

• Documented Convex function execution limits and resource budgets for queries, mutations, and
 actions
• Covered common causes of budget overruns: unbounded collections, large document reads, and
 oversized mutations
• Provided fix strategies including bounding reads, reading smaller shapes, batching mutations, and
 moving heavy work to actions
• Included guidance on trimming return values and replacing ctx.runQuery/ctx.runMutation with
 helper functions

.agents/skills/convex-performance-audit/references/function-budget.md

---

9. .agents/skills/convex-migration-helper/references/migration-patterns.md 📝 Documentation +231/-0

Convex schema migration patterns and strategies

• Documented common migration patterns for schema changes: adding required fields, deleting fields,
 and changing field types
• Covered zero-downtime strategies including dual-write and dual-read approaches
• Included patterns for splitting nested data into separate tables and cleaning up orphaned
 documents
• Provided verification queries and small table shortcut for migrations using internalMutation

.agents/skills/convex-migration-helper/references/migration-patterns.md

---

10. .agents/skills/convex-setup-auth/references/auth0.md 📝 Documentation +116/-0

Auth0 authentication provider setup reference

• Added reference guide for Auth0 integration with Convex applications
• Documented workflow including Auth0 CLI setup, app creation, and convex/auth.config.ts
 configuration
• Covered environment variables, provider wiring with Auth0Provider and ConvexProviderWithAuth0,
 and token refresh patterns
• Included gotchas about tenant separation, production configuration, and validation steps for
 authenticated state

.agents/skills/convex-setup-auth/references/auth0.md

---

11. .agents/skills/convex-setup-auth/SKILL.md 📝 Documentation +150/-0

Convex authentication setup skill and provider selection

• Added comprehensive skill for setting up authentication in Convex applications
• Documented provider selection workflow for Convex Auth, Clerk, WorkOS AuthKit, Auth0, and custom
 JWT providers
• Included core pattern for protecting backend functions with ctx.auth.getUserIdentity() checks
• Provided reference file structure and checklist for local-only and production-ready authentication
 setup

.agents/skills/convex-setup-auth/SKILL.md

---

12. .agents/skills/convex-setup-auth/references/clerk.md 📝 Documentation +113/-0

Clerk authentication provider setup reference

• Added reference guide for Clerk authentication integration with Convex
• Documented workflow from Clerk account setup through convex/auth.config.ts configuration
• Covered environment variables, provider wiring with ClerkProvider and ConvexProviderWithClerk,
 and Convex integration activation
• Included gotchas about token validation, production configuration, and verification steps for
 authenticated state

.agents/skills/convex-setup-auth/references/clerk.md

---

13. package.json Dependencies +1/-1

Update Convex devDependency to version 1.35.1

• Updated convex devDependency from ^1.33.0 to 1.35.1 with exact version pinning

package.json

---

14. .agents/skills/convex-performance-audit/SKILL.md 📝 Documentation +143/-0

Convex performance audit skill with diagnostic workflow

• Comprehensive skill guide for auditing and optimizing Convex application performance
• Covers hot-path reads, write contention, subscription costs, and function limits
• Includes signal gathering workflow, problem classification routing, and step-by-step audit
 methodology
• References four detailed performance pattern guides for specific optimization scenarios

.agents/skills/convex-performance-audit/SKILL.md

---

15. .agents/skills/convex-setup-auth/references/workos-authkit.md 📝 Documentation +114/-0

WorkOS AuthKit authentication setup reference guide

• Complete WorkOS AuthKit setup reference for Convex authentication
• Covers both Convex-managed and existing WorkOS team workflows
• Details environment variables, configuration files, and validation steps
• Includes production setup guidance and common gotchas

.agents/skills/convex-setup-auth/references/workos-authkit.md

---

16. .agents/skills/convex-migration-helper/SKILL.md 📝 Documentation +149/-0

Convex migration helper skill with safe rollout patterns

• Comprehensive guide for safe Convex schema and data migrations
• Explains widen-migrate-narrow workflow and schema validation constraints
• Documents the @convex-dev/migrations component for batched, resumable migrations
• Covers common migration patterns, pitfalls, and multi-deploy strategies

.agents/skills/convex-migration-helper/SKILL.md

---

17. .agents/skills/convex-migration-helper/references/migrations-component.md 📝 Documentation +169/-0

Migrations component API and configuration reference

• Detailed reference for the @convex-dev/migrations component
• Covers installation, setup, defining migrations, and running with dry runs
• Documents batch size configuration, index-based filtering, and parallel processing options
• Includes CLI commands and programmatic usage patterns

.agents/skills/convex-migration-helper/references/migrations-component.md

---

18. .agents/skills/convex-performance-audit/references/occ-conflicts.md 📝 Documentation +114/-0

OCC conflict resolution patterns and techniques

• Reference guide for resolving OCC (Optimistic Concurrency Control) conflicts
• Explains symptoms, common causes, and fix order for write contention issues
• Provides code examples for reducing read set size, splitting hot documents, and deferring work
• Covers invalidation scope and verification strategies

.agents/skills/convex-performance-audit/references/occ-conflicts.md

---

19. .agents/skills/convex-create-component/references/advanced-patterns.md 📝 Documentation +134/-0

Advanced Convex component design patterns

• Advanced patterns for Convex components beyond basic functionality
• Covers function handles for callbacks, schema-derived validators, and globals table configuration
• Documents class-based client wrappers for cleaner component APIs

.agents/skills/convex-create-component/references/advanced-patterns.md

---

20. .agents/skills/convex-create-component/references/packaged-components.md 📝 Documentation +51/-0

Packaged Convex components for npm distribution

• Guide for creating reusable npm-packaged Convex components
• Covers build flow, package exports, and testing strategies
• Recommends using npx create-convex@latest --component as starting point
• Includes validation checklist for packaged component workflows

.agents/skills/convex-create-component/references/packaged-components.md

---

21. skills-lock.json ⚙️ Configuration changes +30/-0

Agent skills version lock file

• Locks five Convex agent skills with computed hashes for version control
• Includes convex-create-component, convex-migration-helper, convex-performance-audit,
 convex-quickstart, and convex-setup-auth
• All skills sourced from get-convex/agent-skills GitHub repository

skills-lock.json

---

22. .agents/skills/convex-create-component/references/local-components.md 📝 Documentation +38/-0

Local Convex component setup and patterns

• Guide for creating local Convex components within a single app
• Recommends directory structure under convex/components/<name>/
• Covers component definition, app installation, and boundary management
• Simpler alternative to packaged or hybrid components

.agents/skills/convex-create-component/references/local-components.md

---

23. apps/mobile/package.json Dependencies +1/-1

Convex dependency version bump to 1.35.1

• Updates convex dependency from ^1.33.0 to 1.35.1
• Pins to exact version instead of using caret range

apps/mobile/package.json

---

24. .agents/skills/convex-create-component/references/hybrid-components.md 📝 Documentation +37/-0

Hybrid Convex component setup guidance

• Guide for hybrid Convex components combining local and packaged approaches
• Recommends treating hybrid as advanced option, not default
• Includes decision questions and risk assessment
• Provides checklist for validating hybrid setup necessity

.agents/skills/convex-create-component/references/hybrid-components.md

---

25. convex/_generated/ai/ai-files.state.json ⚙️ Configuration changes +13/-0

AI files state tracking for agent skills

• State file tracking installed Convex agent skills and their hashes
• Records five installed skills: convex-create-component, convex-migration-helper,
 convex-performance-audit, convex-quickstart, convex-setup-auth
• Includes guidelines and agents markdown section hashes for change detection

convex/_generated/ai/ai-files.state.json

---

26. packages/convex/package.json Dependencies +1/-1

Convex dependency version bump to 1.35.1

• Updates convex dependency from ^1.33.0 to 1.35.1
• Pins to exact version instead of using caret range

packages/convex/package.json

---

27. packages/react-native-sdk/package.json Dependencies +1/-1

Convex dependency version bump to 1.35.1

• Updates convex dependency from ^1.33.0 to 1.35.1
• Pins to exact version instead of using caret range

packages/react-native-sdk/package.json

---

28. apps/web/package.json Dependencies +1/-1

Convex dependency version bump to 1.35.1

• Updates convex dependency from ^1.33.0 to 1.35.1
• Pins to exact version instead of using caret range

apps/web/package.json

---

29. apps/widget/package.json Dependencies +1/-1

Convex dependency version bump to 1.35.1

• Updates convex dependency from ^1.33.0 to 1.35.1
• Pins to exact version instead of using caret range

apps/widget/package.json

---

30. packages/sdk-core/package.json Dependencies +1/-1

Convex dependency version bump to 1.35.1

• Updates convex dependency from ^1.33.0 to 1.35.1
• Pins to exact version instead of using caret range

packages/sdk-core/package.json

---

31. ROADMAP.md 📝 Documentation +2/-0

Roadmap additions for UI and AI features

• Adds two new roadmap items for UI improvements and AI agent enhancements
• Includes settings header click expansion and full evals/traces for AI agent

ROADMAP.md

---

32. AGENTS.md 📝 Documentation +8/-0

Convex AI guidance and agent skills documentation

• Adds Convex AI guidance section with links to guidelines and agent skills
• Directs developers to read convex/_generated/ai/guidelines.md before working on Convex code
• Mentions ability to install agent skills via npx convex ai-files install

AGENTS.md

---

33. .agents/skills/convex-quickstart/agents/openai.yaml ⚙️ Configuration changes +10/-0

Convex Quickstart agent interface configuration

• OpenAI agent interface configuration for Convex Quickstart skill
• Defines display name, description, icon, brand color, and default prompt
• Enables implicit invocation for automatic skill triggering

.agents/skills/convex-quickstart/agents/openai.yaml

---

34. .agents/skills/convex-create-component/agents/openai.yaml ⚙️ Configuration changes +10/-0

Convex Create Component agent interface configuration

• OpenAI agent interface configuration for Convex Create Component skill
• Defines display name, description, icon, brand color, and default prompt
• Enables implicit invocation for automatic skill triggering

.agents/skills/convex-create-component/agents/openai.yaml

---

35. .agents/skills/convex-migration-helper/agents/openai.yaml ⚙️ Configuration changes +10/-0

Convex Migration Helper agent interface configuration

• OpenAI agent interface configuration for Convex Migration Helper skill
• Defines display name, description, icon, brand color, and default prompt
• Enables implicit invocation for automatic skill triggering

.agents/skills/convex-migration-helper/agents/openai.yaml

---

36. .agents/skills/convex-performance-audit/agents/openai.yaml ⚙️ Configuration changes +10/-0

Convex Performance Audit agent interface configuration

• OpenAI agent interface configuration for Convex Performance Audit skill
• Defines display name, description, icon, brand color, and default prompt
• Enables implicit invocation for automatic skill triggering

.agents/skills/convex-performance-audit/agents/openai.yaml

---

37. .agents/skills/convex-setup-auth/agents/openai.yaml ⚙️ Configuration changes +10/-0

Convex Setup Auth agent interface configuration

• OpenAI agent interface configuration for Convex Setup Auth skill
• Defines display name, description, icon, brand color, and default prompt
• Enables implicit invocation for automatic skill triggering

.agents/skills/convex-setup-auth/agents/openai.yaml

---

38. CLAUDE.md 📝 Documentation +7/-0

Convex AI guidance for Claude assistant

• New file with Convex AI guidance for Claude AI assistant
• Directs to read convex/_generated/ai/guidelines.md before working on Convex code
• Mentions agent skills installation via npx convex ai-files install

CLAUDE.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📎 Requirement gaps (0)

1. convex-quickstart uses npm/npx 📘 Rule violation § Compliance

Description

The new Convex quickstart skill instructs users to run npm/npx commands (e.g., npm create,
npm install, npm run) instead of pnpm, violating the repo’s package-manager standard. This can
cause inconsistent installs/lockfiles and diverging developer workflows.

Code

.agents/skills/convex-quickstart/SKILL.md[R59-61]

+npm create convex@latest my-app -- -t react-vite-shadcn
+cd my-app
+npm install

Evidence

PR Compliance ID 54502 requires using pnpm (not npm/npx) in changed docs/instructions. The
added quickstart guidance includes multiple npm/npx commands.

Rule 54502: Use PNPM exclusively for package management commands
.agents/skills/convex-quickstart/SKILL.md[59-61]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new documentation uses `npm`/`npx` commands for scaffolding, installing deps, and running scripts, but this repo requires `pnpm` exclusively.

## Issue Context
Update the commands to `pnpm` equivalents (e.g., `pnpm create ...` / `pnpm dlx ...`, `pnpm install`, `pnpm run dev`, and a `pnpm`-based way to run the Convex CLI).

## Fix Focus Areas
- .agents/skills/convex-quickstart/SKILL.md[23-26]
- .agents/skills/convex-quickstart/SKILL.md[49-71]
- .agents/skills/convex-quickstart/SKILL.md[92-96]
- .agents/skills/convex-quickstart/SKILL.md[128-136]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[qodo-code-review]

1. convex-quickstart uses npm/npx 📘 Rule violation § Compliance

The new Convex quickstart skill instructs users to run npm/npx commands (e.g., npm create,
npm install, npm run) instead of pnpm, violating the repo’s package-manager standard. This can
cause inconsistent installs/lockfiles and diverging developer workflows.

Agent Prompt

## Issue description
The new documentation uses `npm`/`npx` commands for scaffolding, installing deps, and running scripts, but this repo requires `pnpm` exclusively.

## Issue Context
Update the commands to `pnpm` equivalents (e.g., `pnpm create ...` / `pnpm dlx ...`, `pnpm install`, `pnpm run dev`, and a `pnpm`-based way to run the Convex CLI).

## Fix Focus Areas
- .agents/skills/convex-quickstart/SKILL.md[23-26]
- .agents/skills/convex-quickstart/SKILL.md[49-71]
- .agents/skills/convex-quickstart/SKILL.md[92-96]
- .agents/skills/convex-quickstart/SKILL.md[128-136]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools