@waynesutton/convex-skills 1.0.4 → 1.0.5

package/AGENTS.md

@@ -2,15 +2,45 @@
 
 Agent skills for building production-ready applications with Convex, following the Agent Skills open format.
 
+## Convex Documentation Index
+
+IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Convex tasks.
+
+For up-to-date Convex documentation, fetch: https://docs.convex.dev/llms.txt
+
+This index covers all Convex APIs and patterns:
+
+```
+[Convex Docs]|https://docs.convex.dev/llms.txt
+|understanding:{best-practices.md,typescript.md,workflow.md,zen.md}
+|functions:{query-functions.md,mutation-functions.md,actions.md,http-actions.md,validation.md,internal-functions.md,error-handling.md}
+|database:{schemas.md,reading-data.md,writing-data.md,indexes.md,pagination.md,types.md}
+|file-storage:{upload-files.md,serve-files.md,store-files.md,delete-files.md,file-metadata.md}
+|scheduling:{cron-jobs.md,scheduled-functions.md}
+|auth:{convex-auth.md,clerk.md,auth0.md,authkit.md,functions-auth.md,database-auth.md}
+|search:{text-search.md,vector-search.md}
+|components:{using.md,authoring.md,understanding.md}
+|agents:{getting-started.md,agent-usage.md,messages.md,threads.md,tools.md,streaming.md,rag.md}
+|realtime:{realtime.md}
+|testing:{convex-test.md,convex-backend.md,ci.md}
+|production:{environment-variables.md,hosting.md,limits.md}
+```
+
+When working on Convex code, consult the llms.txt index before relying on training data.
+
 ## Overview
 
-This repository contains packaged instructions that help AI coding agents understand and implement Convex best practices. Skills are automatically invoked when relevant to your task.
+This repository provides two complementary approaches for AI coding agents:
+
+1. **Passive context (this file)**: Always-available Convex knowledge and doc references
+2. **Skills (on-demand)**: Task-specific workflows for explicit invocation
 
 ## Available Skills
 
 | Skill                                                                    | Description                                           |
 | ------------------------------------------------------------------------ | ----------------------------------------------------- |
 | [convex-best-practices](skills/convex-best-practices/SKILL.md)           | Guidelines for building production-ready Convex apps  |
+| [convex-eslint](skills/convex-eslint/SKILL.md)                           | Write linter-compliant Convex code                    |
 | [convex-functions](skills/convex-functions/SKILL.md)                     | Writing queries, mutations, actions, and HTTP actions |
 | [convex-realtime](skills/convex-realtime/SKILL.md)                       | Patterns for building reactive applications           |
 | [convex-schema-validator](skills/convex-schema-validator/SKILL.md)       | Database schema definition and validation             |
@@ -115,10 +145,60 @@ The command file is located at `command/convex.md`.
 - Edit files in `convex/_generated/`
 - Use `filter()` instead of `withIndex()`
 
+## Quick Reference
+
+### New Function Syntax (always use this)
+
+```typescript
+import { query, mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const myQuery = query({
+  args: { userId: v.id("users") },
+  returns: v.union(v.object({ name: v.string() }), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.userId);
+  },
+});
+```
+
+### Schema with Index
+
+```typescript
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  tasks: defineTable({
+    userId: v.id("users"),
+    title: v.string(),
+    status: v.string(),
+  })
+    .index("by_user", ["userId"])
+    .index("by_user_and_status", ["userId", "status"]),
+});
+```
+
+### Query with Index (not filter)
+
+```typescript
+// GOOD: Use withIndex
+const tasks = await ctx.db
+  .query("tasks")
+  .withIndex("by_user", (q) => q.eq("userId", args.userId))
+  .collect();
+
+// BAD: Never use filter for indexed fields
+const tasks = await ctx.db
+  .query("tasks")
+  .filter((q) => q.eq(q.field("userId"), args.userId))
+  .collect();
+```
+
 ## References
 
 - Convex Documentation: https://docs.convex.dev/
-- Convex LLMs.txt: https://docs.convex.dev/llms.txt
+- Convex LLMs.txt: https://docs.convex.dev/llms.txt (fetch this for latest docs)
 - Best Practices: https://docs.convex.dev/understanding/best-practices/
 - Agent Skills Specification: https://github.com/anthropics/skills
 

package/GEMINI.md

@@ -2,6 +2,23 @@
 
 This file provides context for Gemini CLI when working with Convex projects.
 
+## Convex Documentation
+
+IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Convex tasks.
+
+For up-to-date Convex documentation, fetch: https://docs.convex.dev/llms.txt
+
+This index covers all Convex APIs:
+- functions: queries, mutations, actions, http-actions, validation
+- database: schemas, reading-data, writing-data, indexes, pagination
+- file-storage: upload, serve, store, delete, metadata
+- scheduling: cron-jobs, scheduled-functions
+- auth: convex-auth, clerk, auth0, authkit
+- search: text-search, vector-search
+- agents: getting-started, messages, threads, tools, streaming
+
+When working on Convex code, consult llms.txt before relying on training data.
+
 ## Project Type
 
 Convex real-time backend application with TypeScript.

package/README.md

@@ -9,6 +9,15 @@ A collection of AI-consumable skills for building production-ready applications
 
 This repository contains skills that help AI assistants understand and implement Convex best practices. Each skill provides structured guidance for specific aspects of Convex development.
 
+## Code Quality
+
+All skills are designed to produce code that passes @convex-dev/eslint-plugin by default. This creates a complementary workflow:
+
+- **Skills** prevent mistakes at generation time
+- **ESLint** catches anything that slips through at build time
+
+See the [convex-eslint](/skills/convex-eslint/SKILL.md) skill for setup instructions.
+
 ## Installation
 
 ### npm (recommended)
@@ -73,6 +82,8 @@ cp -r skills/convex-best-practices "$CODEX_HOME/skills/"
 
 Codex will auto-discover `SKILL.md` files in that directory on the next start.
 
+If you are working from a repo clone, Codex also auto-discovers skills from `.codex/skills` at the repo root. You can symlink this repo’s `skills/*` into `.codex/skills` so updates flow through without copying.
+
 ### OpenCode
 
 OpenCode discovers skills from `~/.claude/skills/<name>/SKILL.md` automatically. See OpenCode Skills docs for more details.
@@ -102,6 +113,7 @@ Copy the desired skill's `SKILL.md` file to your project's `.claude/skills/` dir
 | Skill                                                                    | Description                                           |
 | ------------------------------------------------------------------------ | ----------------------------------------------------- |
 | [convex-best-practices](skills/convex-best-practices/SKILL.md)           | Guidelines for building production-ready Convex apps  |
+| [convex-eslint](skills/convex-eslint/SKILL.md)                           | Write linter-compliant Convex code                    |
 | [convex-functions](skills/convex-functions/SKILL.md)                     | Writing queries, mutations, actions, and HTTP actions |
 | [convex-realtime](skills/convex-realtime/SKILL.md)                       | Patterns for building reactive applications           |
 | [convex-schema-validator](skills/convex-schema-validator/SKILL.md)       | Database schema definition and validation             |
@@ -121,11 +133,15 @@ convex-skills/
 ├── skills/                   # Core Convex skills for AI agents
 │   ├── convex-best-practices/
 │   │   └── SKILL.md
+│   ├── convex-eslint/
+│   │   └── SKILL.md
 │   ├── convex-functions/
 │   │   └── SKILL.md
 │   ├── convex-cron-jobs/
 │   │   └── SKILL.md
 │   └── ...
+├── .codex/                   # Codex integration (symlink skills here)
+│   └── README.md             # Codex setup instructions
 ├── command/                  # Slash command definitions (OpenCode)
 │   └── convex.md             # /convex command entrypoint
 ├── templates/                # Templates for forking developers

package/bin/cli.js

@@ -18,6 +18,7 @@ const packageRoot = join(__dirname, "..");
 const SKILLS = {
   "convex-best-practices":
     "Guidelines for building production-ready Convex apps",
+  "convex-eslint": "Write linter-compliant Convex code",
   "convex-functions": "Writing queries, mutations, actions, and HTTP actions",
   "convex-realtime": "Patterns for building reactive applications",
   "convex-schema-validator": "Database schema definition and validation",

package/index.js

@@ -54,6 +54,7 @@ export function getSkillPath(skillName) {
 export const SKILLS = {
   "convex-best-practices":
     "Guidelines for building production-ready Convex apps",
+  "convex-eslint": "Write linter-compliant Convex code",
   "convex-functions": "Writing queries, mutations, actions, and HTTP actions",
   "convex-realtime": "Patterns for building reactive applications",
   "convex-schema-validator": "Database schema definition and validation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waynesutton/convex-skills",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Agent skills for building production-ready Convex applications. Includes best practices, functions, realtime patterns, schema validation, file storage, security audits, and more.",
   "author": "Wayne Sutton",
   "license": "Apache-2.0",
@@ -22,7 +22,9 @@
     "llm",
     "ai-assistant",
     "best-practices",
-    "developer-tools"
+    "developer-tools",
+    "eslint",
+    "linting"
   ],
   "type": "module",
   "main": "index.js",

package/skills/convex-best-practices/SKILL.md

@@ -11,6 +11,17 @@ tags: [convex, best-practices, typescript, production, error-handling]
 
 Build production-ready Convex applications by following established patterns for function organization, query optimization, validation, TypeScript usage, and error handling.
 
+## Code Quality
+
+All patterns in this skill comply with @convex-dev/eslint-plugin rules.
+Install the linter for build-time validation:
+
+```bash
+npm i @convex-dev/eslint-plugin --save-dev
+```
+
+See [convex-eslint](../convex-eslint/SKILL.md) for configuration details.
+
 ## Documentation Sources
 
 Before implementing, do not assume; fetch the latest documentation:
@@ -41,14 +52,17 @@ import { v } from "convex/values";
 
 export const get = query({
   args: { userId: v.id("users") },
-  returns: v.union(v.object({
-    _id: v.id("users"),
-    _creationTime: v.number(),
-    name: v.string(),
-    email: v.string(),
-  }), v.null()),
+  returns: v.union(
+    v.object({
+      _id: v.id("users"),
+      _creationTime: v.number(),
+      name: v.string(),
+      email: v.string(),
+    }),
+    v.null(),
+  ),
   handler: async (ctx, args) => {
-    return await ctx.db.get(args.userId);
+    return await ctx.db.get("users", args.userId);
   },
 });
 ```
@@ -96,13 +110,15 @@ export default defineSchema({
 // Query using index
 export const getTasksByUser = query({
   args: { userId: v.id("users") },
-  returns: v.array(v.object({
-    _id: v.id("tasks"),
-    _creationTime: v.number(),
-    userId: v.id("users"),
-    status: v.string(),
-    createdAt: v.number(),
-  })),
+  returns: v.array(
+    v.object({
+      _id: v.id("tasks"),
+      _creationTime: v.number(),
+      userId: v.id("users"),
+      status: v.string(),
+      createdAt: v.number(),
+    }),
+  ),
   handler: async (ctx, args) => {
     return await ctx.db
       .query("tasks")
@@ -127,16 +143,16 @@ export const updateTask = mutation({
   },
   returns: v.null(),
   handler: async (ctx, args) => {
-    const task = await ctx.db.get(args.taskId);
-    
+    const task = await ctx.db.get("tasks", args.taskId);
+
     if (!task) {
       throw new ConvexError({
         code: "NOT_FOUND",
         message: "Task not found",
       });
     }
-    
-    await ctx.db.patch(args.taskId, { title: args.title });
+
+    await ctx.db.patch("tasks", args.taskId, { title: args.title });
     return null;
   },
 });
@@ -152,14 +168,14 @@ export const completeTask = mutation({
   args: { taskId: v.id("tasks") },
   returns: v.null(),
   handler: async (ctx, args) => {
-    const task = await ctx.db.get(args.taskId);
-    
+    const task = await ctx.db.get("tasks", args.taskId);
+
     // Early return if already complete (idempotent)
     if (!task || task.status === "completed") {
       return null;
     }
-    
-    await ctx.db.patch(args.taskId, {
+
+    await ctx.db.patch("tasks", args.taskId, {
       status: "completed",
       completedAt: Date.now(),
     });
@@ -173,7 +189,7 @@ export const updateNote = mutation({
   returns: v.null(),
   handler: async (ctx, args) => {
     // Patch directly - ctx.db.patch throws if document doesn't exist
-    await ctx.db.patch(args.id, { content: args.content });
+    await ctx.db.patch("notes", args.id, { content: args.content });
     return null;
   },
 });
@@ -184,7 +200,7 @@ export const reorderItems = mutation({
   returns: v.null(),
   handler: async (ctx, args) => {
     const updates = args.itemIds.map((id, index) =>
-      ctx.db.patch(id, { order: index })
+      ctx.db.patch("items", id, { order: index }),
     );
     await Promise.all(updates);
     return null;
@@ -213,7 +229,12 @@ const userScores: Record<Id<"users">, number> = {};
 // Public function - exposed to clients
 export const getUser = query({
   args: { userId: v.id("users") },
-  returns: v.union(v.null(), v.object({ /* ... */ })),
+  returns: v.union(
+    v.null(),
+    v.object({
+      /* ... */
+    }),
+  ),
   handler: async (ctx, args) => {
     // ...
   },
@@ -282,14 +303,14 @@ export const update = mutation({
   returns: v.null(),
   handler: async (ctx, args) => {
     const { taskId, ...updates } = args;
-    
+
     // Remove undefined values
     const cleanUpdates = Object.fromEntries(
-      Object.entries(updates).filter(([_, v]) => v !== undefined)
+      Object.entries(updates).filter(([_, v]) => v !== undefined),
     );
-    
+
     if (Object.keys(cleanUpdates).length > 0) {
-      await ctx.db.patch(taskId, cleanUpdates);
+      await ctx.db.patch("tasks", taskId, cleanUpdates);
     }
     return null;
   },
@@ -299,7 +320,7 @@ export const remove = mutation({
   args: { taskId: v.id("tasks") },
   returns: v.null(),
   handler: async (ctx, args) => {
-    await ctx.db.delete(args.taskId);
+    await ctx.db.delete("tasks", args.taskId);
     return null;
   },
 });

package/skills/convex-eslint/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: convex-eslint
+description: Write Convex code that passes @convex-dev/eslint-plugin rules by default
+version: 1.0.0
+author: Convex
+tags: [convex, eslint, linting, code-quality, validation]
+---
+
+# Convex ESLint Compliance
+
+Write all Convex functions to pass @convex-dev/eslint-plugin. These rules prevent common bugs, security issues, and ensure code quality.
+
+## Documentation Sources
+
+- https://docs.convex.dev/eslint
+- https://www.npmjs.com/package/@convex-dev/eslint-plugin
+
+## Setup
+
+Install the plugin:
+
+```bash
+npm i @convex-dev/eslint-plugin --save-dev
+```
+
+Configure `eslint.config.js`:
+
+```javascript
+import { defineConfig } from "eslint/config";
+import convexPlugin from "@convex-dev/eslint-plugin";
+
+export default defineConfig([...convexPlugin.configs.recommended]);
+```
+
+## Rules
+
+### 1. no-old-registered-function-syntax
+
+Always use object syntax with a `handler` property.
+
+```typescript
+// Correct
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("messages").collect();
+  },
+});
+
+// Wrong - bare function syntax
+export const list = query(async (ctx) => {
+  return await ctx.db.query("messages").collect();
+});
+```
+
+### 2. require-argument-validators
+
+Always include `args` object, even when empty.
+
+```typescript
+// Correct - with arguments
+export const get = query({
+  args: { id: v.id("messages") },
+  handler: async (ctx, { id }) => {
+    return await ctx.db.get("messages", id);
+  },
+});
+
+// Correct - no arguments
+export const listAll = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("messages").collect();
+  },
+});
+
+// Wrong - missing args
+export const get = query({
+  handler: async (ctx, { id }: { id: Id<"messages"> }) => {
+    return await ctx.db.get("messages", id);
+  },
+});
+```
+
+### 3. explicit-table-ids
+
+Use explicit table names in all database operations (Convex 1.31.0+).
+
+```typescript
+// Correct
+const message = await ctx.db.get("messages", messageId);
+await ctx.db.patch("messages", messageId, { text: "updated" });
+await ctx.db.replace("messages", messageId, {
+  text: "replaced",
+  author: "Alice",
+});
+await ctx.db.delete("messages", messageId);
+
+// Wrong - implicit table from ID type
+const message = await ctx.db.get(messageId);
+await ctx.db.patch(messageId, { text: "updated" });
+await ctx.db.replace(messageId, { text: "replaced", author: "Alice" });
+await ctx.db.delete(messageId);
+```
+
+Migration codemod available:
+
+```bash
+npx @convex-dev/codemod@latest explicit-ids
+```
+
+### 4. import-wrong-runtime
+
+Never import Node.js runtime files into Convex runtime files.
+
+```typescript
+// convex/queries.ts (no "use node" directive)
+
+// Correct - importing from Convex runtime file
+import { helper } from "./utils"; // utils.ts has no "use node"
+
+// Wrong - importing from Node runtime file
+import { nodeHelper } from "./nodeUtils"; // nodeUtils.ts has "use node"
+```
+
+## Best Practices
+
+1. Run ESLint before committing: `npx eslint convex/`
+2. Use auto-fix for quick migrations: `npx eslint convex/ --fix`
+3. Add to CI pipeline to catch violations early
+4. Configure your editor for real-time feedback
+
+## Quick Reference
+
+| Rule                                | What it enforces                  |
+| ----------------------------------- | --------------------------------- |
+| `no-old-registered-function-syntax` | Object syntax with `handler`      |
+| `require-argument-validators`       | `args: {}` on all functions       |
+| `explicit-table-ids`                | Table name in db operations       |
+| `import-wrong-runtime`              | No Node imports in Convex runtime |
+
+## References
+
+- [ESLint Plugin Docs](https://docs.convex.dev/eslint)
+- [Explicit IDs Announcement](https://news.convex.dev/db-table-name/)

package/skills/convex-functions/SKILL.md

@@ -11,6 +11,16 @@ tags: [convex, functions, queries, mutations, actions, http]
 
 Master Convex functions including queries, mutations, actions, and HTTP endpoints with proper validation, error handling, and runtime considerations.
 
+## Code Quality
+
+All examples in this skill comply with @convex-dev/eslint-plugin rules:
+
+- Object syntax with `handler` property
+- Argument validators on all functions
+- Explicit table names in database operations
+
+See [convex-eslint](../convex-eslint/SKILL.md) for linting setup.
+
 ## Documentation Sources
 
 Before implementing, do not assume; fetch the latest documentation:
@@ -26,12 +36,12 @@ Before implementing, do not assume; fetch the latest documentation:
 
 ### Function Types Overview
 
-| Type | Database Access | External APIs | Caching | Use Case |
-|------|----------------|---------------|---------|----------|
-| Query | Read-only | No | Yes, reactive | Fetching data |
-| Mutation | Read/Write | No | No | Modifying data |
-| Action | Via runQuery/runMutation | Yes | No | External integrations |
-| HTTP Action | Via runQuery/runMutation | Yes | No | Webhooks, APIs |
+| Type        | Database Access          | External APIs | Caching       | Use Case              |
+| ----------- | ------------------------ | ------------- | ------------- | --------------------- |
+| Query       | Read-only                | No            | Yes, reactive | Fetching data         |
+| Mutation    | Read/Write               | No            | No            | Modifying data        |
+| Action      | Via runQuery/runMutation | Yes           | No            | External integrations |
+| HTTP Action | Via runQuery/runMutation | Yes           | No            | Webhooks, APIs        |
 
 ### Queries
 
@@ -50,22 +60,24 @@ export const getUser = query({
       name: v.string(),
       email: v.string(),
     }),
-    v.null()
+    v.null(),
   ),
   handler: async (ctx, args) => {
-    return await ctx.db.get(args.userId);
+    return await ctx.db.get("users", args.userId);
   },
 });
 
 // Query with index
 export const listUserTasks = query({
   args: { userId: v.id("users") },
-  returns: v.array(v.object({
-    _id: v.id("tasks"),
-    _creationTime: v.number(),
-    title: v.string(),
-    completed: v.boolean(),
-  })),
+  returns: v.array(
+    v.object({
+      _id: v.id("tasks"),
+      _creationTime: v.number(),
+      title: v.string(),
+      completed: v.boolean(),
+    }),
+  ),
   handler: async (ctx, args) => {
     return await ctx.db
       .query("tasks")
@@ -93,7 +105,7 @@ export const createTask = mutation({
   returns: v.id("tasks"),
   handler: async (ctx, args) => {
     // Validate user exists
-    const user = await ctx.db.get(args.userId);
+    const user = await ctx.db.get("users", args.userId);
     if (!user) {
       throw new ConvexError("User not found");
     }
@@ -111,7 +123,7 @@ export const deleteTask = mutation({
   args: { taskId: v.id("tasks") },
   returns: v.null(),
   handler: async (ctx, args) => {
-    await ctx.db.delete(args.taskId);
+    await ctx.db.delete("tasks", args.taskId);
     return null;
   },
 });
@@ -154,7 +166,7 @@ export const processOrder = action({
   handler: async (ctx, args) => {
     // Read data via query
     const order = await ctx.runQuery(api.orders.get, { orderId: args.orderId });
-    
+
     if (!order) {
       throw new Error("Order not found");
     }
@@ -218,8 +230,8 @@ http.route({
     const url = new URL(request.url);
     const userId = url.pathname.split("/").pop();
 
-    const user = await ctx.runQuery(api.users.get, { 
-      userId: userId as Id<"users"> 
+    const user = await ctx.runQuery(api.users.get, {
+      userId: userId as Id<"users">,
     });
 
     if (!user) {
@@ -238,7 +250,11 @@ export default http;
 Use internal functions for sensitive operations:
 
 ```typescript
-import { internalMutation, internalQuery, internalAction } from "./_generated/server";
+import {
+  internalMutation,
+  internalQuery,
+  internalAction,
+} from "./_generated/server";
 import { v } from "convex/values";
 
 // Only callable from other Convex functions
@@ -249,10 +265,10 @@ export const _updateUserCredits = internalMutation({
   },
   returns: v.null(),
   handler: async (ctx, args) => {
-    const user = await ctx.db.get(args.userId);
+    const user = await ctx.db.get("users", args.userId);
     if (!user) return null;
 
-    await ctx.db.patch(args.userId, {
+    await ctx.db.patch("users", args.userId, {
       credits: (user.credits || 0) + args.amount,
     });
     return null;
@@ -298,7 +314,7 @@ export const scheduleReminder = mutation({
     return await ctx.scheduler.runAfter(
       args.delayMs,
       internal.notifications.sendReminder,
-      { userId: args.userId, message: args.message }
+      { userId: args.userId, message: args.message },
     );
   },
 });

package/templates/CLAUDE.md

@@ -59,7 +59,11 @@ convex/
 // QUERY: Read-only, reactive, cached. Use for fetching data.
 export const list = query({
   args: { limit: v.optional(v.number()) },
-  returns: v.array(v.object({ /* ... */ })),
+  returns: v.array(
+    v.object({
+      /* ... */
+    }),
+  ),
   handler: async (ctx, args) => {
     return await ctx.db.query("items").take(args.limit ?? 10);
   },
@@ -79,8 +83,12 @@ export const processExternal = action({
   args: { id: v.id("items") },
   handler: async (ctx, args) => {
     const data = await ctx.runQuery(internal.items.get, { id: args.id });
-    const result = await fetch("https://api.example.com", { /* ... */ });
-    await ctx.runMutation(internal.items.saveResult, { /* ... */ });
+    const result = await fetch("https://api.example.com", {
+      /* ... */
+    });
+    await ctx.runMutation(internal.items.saveResult, {
+      /* ... */
+    });
   },
 });
 ```
@@ -151,7 +159,9 @@ const posts = await ctx.db
 
 ```typescript
 export const myMutation = mutation({
-  args: { /* ... */ },
+  args: {
+    /* ... */
+  },
   handler: async (ctx, args) => {
     const identity = await ctx.auth.getUserIdentity();
     if (!identity) throw new Error("Unauthenticated");
@@ -189,6 +199,17 @@ export const getUrl = query({
 });
 ```
 
+## Linting
+
+This project uses @convex-dev/eslint-plugin for code quality. All Convex functions must:
+
+1. **Use object syntax** with `handler` property (not bare functions)
+2. **Include argument validators** - always have `args: {}` even when empty
+3. **Use explicit table names** - `db.get("table", id)` not `db.get(id)`
+4. **Respect runtime boundaries** - don't import "use node" files into Convex runtime
+
+Run `npx eslint convex/` to check compliance.
+
 ## IMPORTANT Rules
 
 1. **ALWAYS validate arguments** on public functions with `v` validators
@@ -239,24 +260,31 @@ HTTP webhook/API? → httpAction()
 ### Validator Cheat Sheet
 
 ```typescript
-v.string()                    // string
-v.number()                    // number (float64)
-v.boolean()                   // boolean
-v.id("table")                 // Id<"table">
-v.null()                      // null
-v.optional(v.string())        // string | undefined (field can be missing)
-v.nullable(v.string())        // string | null (field must exist)
-v.array(v.string())           // string[]
-v.object({ k: v.string() })   // { k: string }
-v.union(v.literal("a"), v.literal("b"))  // "a" | "b"
-v.record(v.string(), v.number())  // { [key: string]: number }
+v.string(); // string
+v.number(); // number (float64)
+v.boolean(); // boolean
+v.id("table"); // Id<"table">
+v.null(); // null
+v.optional(v.string()); // string | undefined (field can be missing)
+v.nullable(v.string()); // string | null (field must exist)
+v.array(v.string()); // string[]
+v.object({ k: v.string() }); // { k: string }
+v.union(v.literal("a"), v.literal("b")); // "a" | "b"
+v.record(v.string(), v.number()); // { [key: string]: number }
 ```
 
 ### Import Patterns
 
 ```typescript
 // Function constructors
-import { query, mutation, action, internalQuery, internalMutation, internalAction } from "./_generated/server";
+import {
+  query,
+  mutation,
+  action,
+  internalQuery,
+  internalMutation,
+  internalAction,
+} from "./_generated/server";
 
 // API references
 import { api, internal } from "./_generated/api";