initial commit

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

@@ -0,0 +1,325 @@
+---
+name: convex-create-component
+description:
+  Builds reusable Convex components with isolated tables and app-facing APIs.
+  Use for new components, reusable backend modules, integrations, or component
+  boundary work.
+---
+
+# Convex Create Component
+
+Create reusable Convex components with clear boundaries and a small app-facing
+API.
+
+## When to Use
+
+- Creating a new Convex component in an existing app
+- Extracting reusable backend logic into a component
+- Building a third-party integration that should own its own tables and
+  workflows
+- Packaging Convex functionality for reuse across multiple apps
+
+## When Not to Use
+
+- One-off business logic that belongs in the main app
+- Thin utilities that do not need Convex tables or functions
+- App-level orchestration that should stay in `convex/`
+- Cases where a normal TypeScript library is enough
+
+## Workflow
+
+1. Ask the user what they are building and what the end goal is. If the repo
+   already makes the answer obvious, say so and confirm before proceeding.
+2. Choose the shape using the decision tree below and read the matching
+   reference file.
+3. Decide whether a component is justified. Prefer normal app code or a regular
+   library if the feature does not need isolated tables, backend functions, or
+   reusable persistent state.
+4. Make a short plan for:
+   - what tables the component owns
+   - what public functions it exposes
+   - what data must be passed in from the app (auth, env vars, parent IDs)
+   - what stays in the app as wrappers or HTTP mounts
+5. Create the component structure with `convex.config.ts`, `schema.ts`, and
+   function files.
+6. Implement functions using the component's own `./_generated/server` imports,
+   not the app's generated files.
+7. Wire the component into the app with `app.use(...)`. If the app does not
+   already have `convex/convex.config.ts`, create it.
+8. Call the component from the app through `components.<name>` using
+   `ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction`.
+9. If React clients, HTTP callers, or public APIs need access, create wrapper
+   functions in the app instead of exposing component functions directly.
+10. Run `npx convex dev` and fix codegen, type, or boundary issues before
+    finishing.
+
+## Choose the Shape
+
+Ask the user, then pick one path:
+
+| Goal                                              | Shape            | Reference                           |
+| ------------------------------------------------- | ---------------- | ----------------------------------- |
+| Component for this app only                       | Local            | `references/local-components.md`    |
+| Publish or share across apps                      | Packaged         | `references/packaged-components.md` |
+| User explicitly needs local + shared library code | Hybrid           | `references/hybrid-components.md`   |
+| Not sure                                          | Default to local | `references/local-components.md`    |
+
+Read exactly one reference file before proceeding.
+
+## Default Approach
+
+Unless the user explicitly wants an npm package, default to a local component:
+
+- Put it under `convex/components/<componentName>/`
+- Define it with `defineComponent(...)` in its own `convex.config.ts`
+- Install it from the app's `convex/convex.config.ts` with `app.use(...)`
+- Let `npx convex dev` generate the component's own `_generated/` files
+
+## Component Skeleton
+
+A minimal local component with a table and two functions, plus the app wiring.
+
+```ts
+// convex/components/notifications/convex.config.ts
+import { defineComponent } from "convex/server";
+
+export default defineComponent("notifications");
+```
+
+```ts
+// convex/components/notifications/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  notifications: defineTable({
+    userId: v.string(),
+    message: v.string(),
+    read: v.boolean(),
+  }).index("by_user_read", ["userId", "read"]),
+});
+```
+
+```ts
+// convex/components/notifications/lib.ts
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+export const send = mutation({
+  args: { userId: v.string(), message: v.string() },
+  returns: v.id("notifications"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("notifications", {
+      userId: args.userId,
+      message: args.message,
+      read: false,
+    });
+  },
+});
+
+export const listUnread = query({
+  args: { userId: v.string() },
+  returns: v.array(
+    v.object({
+      _id: v.id("notifications"),
+      _creationTime: v.number(),
+      userId: v.string(),
+      message: v.string(),
+      read: v.boolean(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("notifications")
+      .withIndex("by_user_read", (q) =>
+        q.eq("userId", args.userId).eq("read", false),
+      )
+      .collect();
+  },
+});
+```
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import notifications from "./components/notifications/convex.config.js";
+
+const app = defineApp();
+app.use(notifications);
+
+export default app;
+```
+
+```ts
+// convex/notifications.ts  (app-side wrapper)
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { components } from "./_generated/api";
+import { getAuthUserId } from "@convex-dev/auth/server";
+
+export const sendNotification = mutation({
+  args: { message: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+
+    await ctx.runMutation(components.notifications.lib.send, {
+      userId,
+      message: args.message,
+    });
+    return null;
+  },
+});
+
+export const myUnread = query({
+  args: {},
+  handler: async (ctx) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+
+    return await ctx.runQuery(components.notifications.lib.listUnread, {
+      userId,
+    });
+  },
+});
+```
+
+Note the reference path shape: a function in
+`convex/components/notifications/lib.ts` is called as
+`components.notifications.lib.send` from the app.
+
+## Critical Rules
+
+- Keep authentication in the app, because `ctx.auth` is not available inside
+  components.
+- Keep environment access in the app, because component functions cannot read
+  `process.env`.
+- Pass parent app IDs across the boundary as strings, because `Id` types become
+  plain strings in the app-facing `ComponentApi`.
+- Do not use `v.id("parentTable")` for app-owned tables inside component args or
+  schema, because the component has no access to the app's table namespace.
+- Import `query`, `mutation`, and `action` from the component's own
+  `./_generated/server`, not the app's generated files.
+- Do not expose component functions directly to clients. Create app wrappers
+  when client access is needed, because components are internal and need
+  auth/env wiring the app provides.
+- If the component defines HTTP handlers, mount the routes in the app's
+  `convex/http.ts`, because components cannot register their own HTTP routes.
+- If the component needs pagination, use `paginator` from `convex-helpers`
+  instead of built-in `.paginate()`, because `.paginate()` does not work across
+  the component boundary.
+- Define indexes for queried fields instead of using Convex `.filter()` after a
+  database query.
+- Add `args` and `returns` validators to all public component functions, because
+  the component boundary requires explicit type contracts.
+
+## Patterns
+
+### Authentication and environment access
+
+```ts
+// Bad: component code cannot rely on app auth or env
+const identity = await ctx.auth.getUserIdentity();
+const apiKey = process.env.OPENAI_API_KEY;
+```
+
+```ts
+// Good: the app resolves auth and env, then passes explicit values
+const userId = await getAuthUserId(ctx);
+if (!userId) throw new Error("Not authenticated");
+
+await ctx.runAction(components.translator.translate, {
+  userId,
+  apiKey: process.env.OPENAI_API_KEY,
+  text: args.text,
+});
+```
+
+### Client-facing API
+
+```ts
+// Bad: assuming a component function is directly callable by clients
+export const send = components.notifications.send;
+```
+
+```ts
+// Good: re-export through an app mutation or query
+export const sendNotification = mutation({
+  args: { message: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+
+    await ctx.runMutation(components.notifications.lib.send, {
+      userId,
+      message: args.message,
+    });
+    return null;
+  },
+});
+```
+
+### IDs across the boundary
+
+```ts
+// Bad: parent app table IDs are not valid component validators
+args: {
+  userId: v.id("users"),
+}
+```
+
+```ts
+// Good: treat parent-owned IDs as strings at the boundary
+args: {
+  userId: v.string(),
+}
+```
+
+### Advanced Patterns
+
+For additional patterns including function handles for callbacks, deriving
+validators from schema, static configuration with a globals table, and
+class-based client wrappers, see `references/advanced-patterns.md`.
+
+## Validation
+
+Try validation in this order:
+
+1. `npx convex codegen --component-dir convex/components/<name>`
+2. `npx convex codegen`
+3. `npx convex dev`
+
+Important:
+
+- Fresh repos may fail these commands until `CONVEX_DEPLOYMENT` is configured.
+- Until codegen runs, component-local `./_generated/*` imports and app-side
+  `components.<name>...` references will not typecheck.
+- If validation blocks on Convex login or deployment setup, stop and ask the
+  user for that exact step instead of guessing.
+
+## Reference Files
+
+Read exactly one of these after the user confirms the goal:
+
+- `references/local-components.md`
+- `references/packaged-components.md`
+- `references/hybrid-components.md`
+
+Official docs:
+[Authoring Components](https://docs.convex.dev/components/authoring)
+
+## Checklist
+
+- [ ] Asked the user what they want to build and confirmed the shape
+- [ ] Read the matching reference file
+- [ ] Confirmed a component is the right abstraction
+- [ ] Planned tables, public API, boundaries, and app wrappers
+- [ ] Component lives under `convex/components/<name>/` (or package layout if
+      publishing)
+- [ ] Component imports from its own `./_generated/server`
+- [ ] Auth, env access, and HTTP routes stay in the app
+- [ ] Parent app IDs cross the boundary as `v.string()`
+- [ ] Public functions have `args` and `returns` validators
+- [ ] Ran `npx convex dev` and fixed codegen or type issues

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

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Convex Create Component"
+  short_description:
+    "Design and build reusable Convex components with clear boundaries."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#14B8A6"
+  default_prompt:
+    "Help me create a Convex component for this feature. First check that a
+    component is actually justified, then design the tables, API surface, and
+    app-facing wrappers before implementing it."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/convex-create-component/assets/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m21 7.5-2.25-1.313M21 7.5v2.25m0-2.25-2.25 1.313M3 7.5l2.25-1.313M3 7.5l2.25 1.313M3 7.5v2.25m9 3 2.25-1.313M12 12.75l-2.25-1.313M12 12.75V15m0 6.75 2.25-1.313M12 21.75V19.5m0 2.25-2.25-1.313m0-16.875L12 2.25l2.25 1.313M21 14.25v2.25l-2.25 1.313m-13.5 0L3 16.5v-2.25"/>
+</svg>

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

@@ -0,0 +1,140 @@
+# Advanced Component Patterns
+
+Additional patterns for Convex components that go beyond the basics covered in
+the main skill file.
+
+## Function Handles for callbacks
+
+When the app needs to pass a callback function to the component, use function
+handles. This is common for components that run app-defined logic on a schedule
+or in a workflow.
+
+```ts
+// App side: create a handle and pass it to the component
+import { createFunctionHandle } from "convex/server";
+
+export const startJob = mutation({
+  handler: async (ctx) => {
+    const handle = await createFunctionHandle(internal.myModule.processItem);
+    await ctx.runMutation(components.workpool.enqueue, {
+      callback: handle,
+    });
+  },
+});
+```
+
+```ts
+// Component side: accept and invoke the handle
+import { v } from "convex/values";
+import type { FunctionHandle } from "convex/server";
+import { mutation } from "./_generated/server.js";
+
+export const enqueue = mutation({
+  args: { callback: v.string() },
+  handler: async (ctx, args) => {
+    const handle = args.callback as FunctionHandle<"mutation">;
+    await ctx.scheduler.runAfter(0, handle, {});
+  },
+});
+```
+
+## Deriving validators from schema
+
+Instead of manually repeating field types in return validators, extend the
+schema validator:
+
+```ts
+import { v } from "convex/values";
+import schema from "./schema.js";
+
+const notificationDoc = schema.tables.notifications.validator.extend({
+  _id: v.id("notifications"),
+  _creationTime: v.number(),
+});
+
+export const getLatest = query({
+  args: {},
+  returns: v.nullable(notificationDoc),
+  handler: async (ctx) => {
+    return await ctx.db.query("notifications").order("desc").first();
+  },
+});
+```
+
+## Static configuration with a globals table
+
+A common pattern for component configuration is a single-document "globals"
+table:
+
+```ts
+// schema.ts
+export default defineSchema({
+  globals: defineTable({
+    maxRetries: v.number(),
+    webhookUrl: v.optional(v.string()),
+  }),
+  // ... other tables
+});
+```
+
+```ts
+// lib.ts
+export const configure = mutation({
+  args: { maxRetries: v.number(), webhookUrl: v.optional(v.string()) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db.query("globals").first();
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+    } else {
+      await ctx.db.insert("globals", args);
+    }
+    return null;
+  },
+});
+```
+
+## Class-based client wrappers
+
+For components with many functions or configuration options, a class-based
+client provides a cleaner API. This pattern is common in published components.
+
+```ts
+// src/client/index.ts
+import type { GenericMutationCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+type MutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
+
+export class Notifications {
+  constructor(
+    private component: ComponentApi,
+    private options?: { defaultChannel?: string },
+  ) {}
+
+  async send(ctx: MutationCtx, args: { userId: string; message: string }) {
+    return await ctx.runMutation(this.component.lib.send, {
+      ...args,
+      channel: this.options?.defaultChannel ?? "default",
+    });
+  }
+}
+```
+
+```ts
+// App usage
+import { Notifications } from "@convex-dev/notifications";
+import { components } from "./_generated/api";
+
+const notifications = new Notifications(components.notifications, {
+  defaultChannel: "alerts",
+});
+
+export const send = mutation({
+  args: { message: v.string() },
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    await notifications.send(ctx, { userId, message: args.message });
+  },
+});
+```

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

@@ -0,0 +1,38 @@
+# Hybrid Convex Components
+
+Read this file only when the user explicitly wants a hybrid setup.
+
+## What This Means
+
+A hybrid component combines a local Convex component with shared library code.
+
+This can help when:
+
+- the user wants a local install but also shared package logic
+- the component needs extension points or override hooks
+- some logic should live in normal TypeScript code outside the component
+  boundary
+
+## Default Advice
+
+Treat hybrid as an advanced option, not the default.
+
+Before choosing it, ask:
+
+- Why is a plain local component not enough?
+- Why is a packaged component not enough?
+- What exactly needs to stay overridable or shared?
+
+If the answer is vague, fall back to local or packaged.
+
+## Risks
+
+- More moving parts
+- Harder upgrades and backwards compatibility
+- Easier to blur the component boundary
+
+## Checklist
+
+- [ ] User explicitly needs hybrid behavior
+- [ ] Local-only and packaged-only options were considered first
+- [ ] The extension points are clearly defined before coding

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

@@ -0,0 +1,39 @@
+# Local Convex Components
+
+Read this file when the component should live inside the current app and does
+not need to be published as an npm package.
+
+## When to Choose This
+
+- The user wants the simplest path
+- The component only needs to work in this repo
+- The goal is extracting app logic into a cleaner boundary
+
+## Default Layout
+
+Use this structure unless the repo already has a clear alternative pattern:
+
+```text
+convex/
+  convex.config.ts
+  components/
+    <name>/
+      convex.config.ts
+      schema.ts
+      <feature>.ts
+```
+
+## Workflow Notes
+
+- Define the component with `defineComponent("<name>")`
+- Install it from the app with `defineApp()` and `app.use(...)`
+- Keep auth, env access, public API wrappers, and HTTP route mounting in the app
+- Let the component own isolated tables and reusable backend workflows
+- Add app wrappers if clients need to call into the component
+
+## Checklist
+
+- [ ] Component is inside `convex/components/<name>/`
+- [ ] App installs it with `app.use(...)`
+- [ ] Component owns only its own tables
+- [ ] App wrappers handle client-facing calls when needed

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

@@ -0,0 +1,54 @@
+# Packaged Convex Components
+
+Read this file when the user wants a reusable npm package or a component shared
+across multiple apps.
+
+## When to Choose This
+
+- The user wants to publish the component
+- The user wants a stable reusable package boundary
+- The component will be shared across multiple apps or teams
+
+## Default Approach
+
+- Prefer starting from `npx create-convex@latest --component` when possible
+- Keep the official authoring docs as the source of truth for package layout and
+  exports
+- Validate the bundled package through an example app, not just the source files
+
+## Build Flow
+
+When building a packaged component, make sure the bundled output exists before
+the example app tries to consume it.
+
+Recommended order:
+
+1. `npx convex codegen --component-dir ./path/to/component`
+2. Run the package build command
+3. Run `npx convex dev --typecheck-components` in the example app
+
+Do not assume normal app codegen is enough for packaged component workflows.
+
+## Package Exports
+
+If publishing to npm, make sure the package exposes the entry points apps need:
+
+- package root for client helpers, types, or classes
+- `./convex.config.js` for installing the component
+- `./_generated/component.js` for the app-facing `ComponentApi` type
+- `./test` for testing helpers when applicable
+
+## Testing
+
+- Use `convex-test` for component logic
+- Register the component schema and modules with the test instance
+- Test app-side wrapper code from an example app that installs the package
+- Export a small helper from `./test` if consumers need easy test registration
+
+## Checklist
+
+- [ ] Packaging is actually required
+- [ ] Build order avoids bundle and codegen races
+- [ ] Package exports include install and typing entry points
+- [ ] Example app exercises the packaged component
+- [ ] Core behavior is covered by tests