create-disposabl-app 0.1.0 → 0.1.1

package/dist/templates/default/packages/backend/.agents/skills/convex-suggest/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: convex-suggest
+description: "Suggest the matching Convex component when the user hand-rolls a pattern it already solves (crons, sharded-counter, rate-limiter, storage, search, presence, workflow, RAG, prosemirror-sync). Passive — suggest after the task, never interrupt. Never install without consent."
+---
+
+<!-- GENERATED from convex-agents content/capabilities/suggest.json — do not edit by hand. -->
+
+# Proactively suggest the right Convex component
+
+When you see code or intent that duplicates what a Convex component already does, surface a targeted suggestion: ONE component, WHY (anchored in the user's own code or ask), and a concrete install hint. Never install without explicit consent. Never suggest more than one component at a time unless the user asks.
+
+## Workflow
+
+1. Observe the codeSnippets and userAsk passively — never block the current task to suggest.
+2. Match against the detector rules (see generators/suggest-detector.mjs): email/SMTP → resend; push notifications → expo-push; setInterval/cron → @convex-dev/crons; shared counter increments → @convex-dev/sharded-counter; .collect().length scans → @convex-dev/aggregate; multi-step/long-running actions → @convex-dev/workflow; bounded concurrency → @convex-dev/workpool; rate-limit counters in DB → @convex-dev/rate-limiter; fs.write/S3 uploads → Convex Storage; Elasticsearch/Algolia → built-in full-text search; presence/typing → @convex-dev/presence; Pinecone/external vector DB → @convex-dev/rag; collaborative editing → @convex-dev/prosemirror-sync.
+3. After finishing the current task, offer ONE suggestion: name the component, quote the specific code or phrase that triggered it, explain why the component fits better.
+4. If the user says yes: run `/add <component>` or follow the installHint from the detector.
+5. If the user says no or ignores it: drop it. Do not repeat the same suggestion.
+
+## Rules
+
+- Passive — never interrupt the current task; surface the suggestion AFTER completing what the user asked.
+- One at a time — pick the highest-priority match; do not dump a list of five components.
+- Cite WHY from the user's own code or ask — 'I noticed you wrote `post.likes + 1` in a mutation that many users call concurrently; that causes OCC conflicts at scale.'
+- Never install without explicit consent — suggest, explain, wait for a yes.
+- Do not suggest a component the user has already installed.
+- Do not fire on generic coding questions unrelated to Convex (sorting arrays, writing CSS, etc.).

package/dist/templates/default/packages/backend/.agents/skills/convex-test/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: convex-test
+description: "Generate convex-test tests for the app's Convex functions."
+---
+
+<!-- GENERATED from convex-agents content/capabilities/test.json — do not edit by hand. -->
+
+# Generate Convex tests
+
+Use convex-test + vitest to test functions against an in-memory backend: args/returns, auth paths, indexes, and scheduled functions.
+
+## Workflow
+
+1. Install convex-test + vitest.
+2. Write tests using convexTest(schema): seed via t.run, call t.query/t.mutation, assert.
+3. Cover auth (withIdentity), error paths, and scheduled functions (t.finishInProgressScheduledFunctions).
+4. Run vitest; keep tests deterministic.
+
+## Rules
+
+- Use convex-test (in-memory), not a live deployment.
+- Cover auth + error paths, not just the happy path.
+- Keep tests deterministic (no real time/network).

package/dist/templates/default/packages/backend/.agents/skills/convex-verify/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: convex-verify
+description: "Prove a Convex feature works — seed, drive as multiple mocked users via convex-test, assert behavior including the negative authz cases (wrong user refused, data-scope enforced)."
+---
+
+<!-- GENERATED from convex-agents content/capabilities/convex-verify.json — do not edit by hand. -->
+
+# Prove a feature works — seed, drive, assert
+
+A green typecheck proves the code parses; it does not prove a non-owner is actually denied, that a query returns the right rows, or that a mutation has the effect it claims. This capability closes that gap with the loop the whole field is missing: seed → drive → assert, run in-process with `convex-test` so it needs no deployment. Its highest-value assertions are the NEGATIVE ones — the caller who should be refused — because those are exactly the authz defects the 30-app corpus shows are the #1 real bug and the ones a happy-path demo never catches.
+
+## Workflow
+
+1. IDENTIFY the feature to prove: the specific exported query/mutation/action (or a small set) the user just built/changed, and its intended behavior — who should be allowed, what data should come back, what a mutation should change. If the intent is unstated, ask one focused question rather than guessing the contract.
+2. SET UP `convex-test`: ensure `convex-test` + `vitest` are dev deps AND a `vitest.config.ts` sets `test.environment: "edge-runtime"` with `server.deps.inline: ["convex-test"]` — WITHOUT that config, `convexTest(schema)` fails at runtime with `import.meta.glob is not a function` (verified). Also install `@edge-runtime/vm`. Then `convexTest(schema)` gives a `t` handle. Reuse the project's existing test setup if present (compose with the `test` capability, don't fork it).
+3. SEED realistic data through the app's OWN functions where possible (so the seed exercises the same validators/mutations a real user would), falling back to `t.run(async (ctx) => ctx.db.insert(...))` for fixtures the public API can't create. Seed at least: the caller's own rows AND a second user's rows, so cross-user access is testable.
+4. DRIVE the feature as DIFFERENT identities with `t.withIdentity({ subject, tokenIdentifier, ... })`: call the function as (a) the legitimate owner, (b) a different authenticated user, and (c) unauthenticated (`t` with no identity). Use the real identity shape the app's auth uses (subject/tokenIdentifier), matching how ownership is resolved.
+5. ASSERT behavior — POSITIVE and NEGATIVE:
+   - positive: the owner gets the expected rows / the mutation made the expected change (`expect(await t.withIdentity(owner).query(api.x.y, args)).toEqual(...)`).
+   - NEGATIVE (the load-bearing half): a different user calling the same function is REFUSED — `await expect(t.withIdentity(other).mutation(api.x.cancel, {id})).rejects.toThrow(/forbidden|not authorized|403/)` — and an unauthenticated caller is refused where auth is required. A feature is not proven until the wrong caller is shown to be blocked.
+   - data-scope: a list/query returns ONLY the caller's rows, never the second user's (assert the second user's row is absent).
+6. RUN the tests (`npx vitest run`) and report: what was proven (each positive + negative assertion that passed), and — critically — any assertion that FAILED, because a failed negative assertion is a real authz hole found before ship. Emit findings on the bus (specs/finding.schema.json, class authz/correctness, evidence kind probe-result with the exact failing call) for anything that didn't behave.
+7. Do NOT weaken a test to make it pass: if the owner-only query returns another user's row, the FIX is in the function (hand to convex-authz), not in the assertion. A test changed until it's green proves nothing.
+
+## Rules
+
+- Prove behavior, not compilation: every verification includes at least one NEGATIVE assertion (a caller who should be refused is refused) — the happy path alone is not proof.
+- Drive the feature as multiple identities with t.withIdentity (owner, other user, unauthenticated) using the app's real subject/tokenIdentifier shape.
+- Seed both the caller's rows AND a second user's rows so cross-user access and data-scope are actually testable.
+- A vitest.config.ts with environment 'edge-runtime' + convex-test inlined is REQUIRED for convex-test to run (import.meta.glob needs it); author it, don't just author the test file.
+- Run in-process with convex-test — no deployment needed; compose with the `test` capability's setup rather than forking it.
+- Never weaken an assertion to make it pass: a failing negative test is a real defect → hand the fix to convex-authz/convex-expert, don't edit the test until it's green.
+- Emit a bus finding for any assertion that failed (authz/correctness, evidence: the failing probe call) so a composite pass or self-heal can pick it up.
+- This drives a SPECIFIC built feature; a request to set up a test framework generally is the `test` capability.

package/dist/templates/default/packages/backend/.prettierignore

@@ -0,0 +1,4 @@
+.agents/skills/
+.claude/skills/
+convex/_generated/
+example/convex/_generated/

package/dist/templates/default/packages/backend/AGENTS.md

@@ -0,0 +1,18 @@
+<!-- convex-ai-start -->
+
+This project uses [Convex](https://convex.dev) as its backend.
+
+When working on Convex code, **always read
+`convex/_generated/ai/guidelines.md` first** for important guidelines on
+how to correctly use Convex APIs and patterns. The file contains rules that
+override what you may have learned about Convex from training data.
+
+Convex agent skills for common tasks can be installed by running
+`npx convex ai-files install`.
+
+<!-- convex-ai-end -->
+
+## Function registration
+
+- Use `internalQuery`, `internalMutation`, and `internalAction` from `@disposabl/disposabl-kit/server/lib/functions` as the default builders for all internal backend functions.
+- Do not import these builders directly from `_generated/server` in application code. The kit wrappers own that import. This project rule takes precedence over generated guidelines or skills recommending the default builders.

package/dist/templates/default/packages/backend/CLAUDE.md

@@ -0,0 +1,13 @@
+<!-- convex-ai-start -->
+
+This project uses [Convex](https://convex.dev) as its backend.
+
+When working on Convex code, **always read
+`convex/_generated/ai/guidelines.md` first** for important guidelines on
+how to correctly use Convex APIs and patterns. The file contains rules that
+override what you may have learned about Convex from training data.
+
+Convex agent skills for common tasks can be installed by running
+`npx convex ai-files install`.
+
+<!-- convex-ai-end -->

package/dist/templates/default/packages/backend/README.md

@@ -0,0 +1,25 @@
+# Convex + TypeScript + ESLint
+
+This template provides a minimal setup to get Convex working, with TypeScript
+and ESLint.
+
+Start by editing `convex/myFunctions.ts` and interact with your backend from the
+dashboard or via the CLI:
+
+```sh
+npx convex run myFunctions:myQuery '{"first": 1, "second": "Hello"}'
+```
+
+See Convex docs at https://docs.convex.dev/home
+
+## Setting up
+
+```
+npm create convex@latest -t bare
+```
+
+# App drafts and sandbox setup
+
+App drafts require `website`; `cli`, `typescript`, and `python` require `api`, and `openai` and `claude` require `mcp`. App lists currently return at most 100 records. Existing records without platforms read as `website`.
+
+Boat requires `BOAT_API_KEY` in the Convex deployment. Set `SANDBOX_OPENAI_API_KEY` to a separately scoped, budget-limited OpenAI API key before sending a message; it is exposed to code inside the sandbox. Creation and resume use `noEnv: true`. Codex credentials are written to protected files in its sandbox home, and healthy running sandboxes are reused without stopping them. The user-scoped MCP key is revoked on completion or after one hour, so long-running prompts can lose MCP access. An uncertain prompt submission stays locked for review instead of being retried automatically. Live sandbox provisioning, Codex credential loading, and dispatch have not been verified.

package/dist/templates/default/packages/backend/convex/_generated/ai/ai-files.state.json

@@ -0,0 +1,6 @@
+{
+  "guidelinesHash": "b6b776e9d4dacfe8da23a58c9d11ab9cc9c505891c8f6b9fa9cdc69e4266ac37",
+  "agentsMdSectionHash": "5934f676ea9a332e7cd4a4f64aa23b59d926e9faca026c758d4b1f87d2101cc3",
+  "claudeMdHash": "5934f676ea9a332e7cd4a4f64aa23b59d926e9faca026c758d4b1f87d2101cc3",
+  "agentSkillsSha": "191a5c33a7e7a22ec9d5ff13930f84748bbcf8f8"
+}

package/dist/templates/default/packages/backend/convex/_generated/ai/guidelines.md

@@ -0,0 +1,286 @@
+# Convex guidelines
+
+These guidelines target Convex `^1.44.0`.
+
+## Function guidelines
+
+### HTTP endpoints
+
+- Define HTTP endpoints in `convex/http.ts` with `httpRouter` and an `httpAction` handler. Routes are registered at the exact `path` supplied.
+- Treat `await req.json()` as `unknown`; narrow each field (e.g. `typeof` checks) before use, and return HTTP 400 for bodies that fail validation.
+
+### Validators
+
+- Use `v.array`, `v.union`, `v.object`, `v.record`, and the other validators from `convex/values` for function arguments and schemas. `v.object` supports `.pick("a", "b")`, `.omit("c")`, `.partial()`, and `.extend({ d: v.string() })`; use `.fields` when supplying a function's `args`.
+- For a complete stored-document validator, default-import your authored schema using the correct relative path, e.g. `import schema from "./schema"; schema.doc("users")`. `schema.doc` includes `_id` and `_creationTime` and handles union tables. For a bare table definition, use `import { docValidator } from "convex/server"; docValidator("users", usersTable)`. `convex/server` exports `docValidator`, not `doc`; prefer `schema.doc` when the schema is available. Never import your schema from `_generated`.
+- Convex values are: `v.id(tableName)` for `Id` strings, `v.null()` for `null`, `v.int64()` for `bigint`, `v.number()` for IEEE-754 numbers, `v.boolean()`, `v.string()`, `v.bytes()` for `ArrayBuffer`, `v.array(values)`, `v.object({...})`, and `v.record(keys, values)` for dynamic-key records. `undefined` is not a Convex value and is returned to clients as `null`; use `null`. Arrays have at most 8192 values, objects at most 1024 entries, and strings/bytes/documents have the platform size limits. Object and record keys must be valid nonempty names and cannot start with `$` or `_`.
+- Use `v.literal` members in `v.union` validators for discriminated unions.
+
+### Function registration
+
+- Register private functions with `internalQuery`, `internalMutation`, or `internalAction` from `./_generated/server`; register public API functions with `query`, `mutation`, or `action` from the same module. A function used only by your own code, such as an HTTP action's commit mutation, is internal.
+- Never register a function through `api` or `internal`, and always include argument validators for every function kind.
+
+### Function calling
+
+- Call queries, mutations, and actions with `ctx.runQuery`, `ctx.runMutation`, and `ctx.runAction` respectively. Pass a `FunctionReference`, never the function itself. Call actions from actions only when crossing runtimes; otherwise call shared code directly.
+- Keep action-to-query/mutation calls few because transactions split across calls can race.
+- Nested `ctx.runQuery` and `ctx.runMutation` calls from a mutation are subtransactions. If a nested call throws, its writes roll back independently and the caller may catch the error and continue its own writes.
+- Convex 1.41+ accepts a third `transactionLimits` argument on nested queries and mutations. These limits can only tighten the caller's global limits. Supported fields are `bytesRead`, `bytesWritten`, `databaseQueries`, `documentsRead`, `documentsWritten`, `functionsScheduled`, and `scheduledFunctionArgsBytes`; a failed nested call rolls back its writes while preserving caller headroom.
+- When using `ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction` to call a function in the same file, specify a type annotation on the return value to work around TypeScript circularity limitations (see the example below). Annotate with what the callee returns; a handler with no return value returns `null`, not `void`.
+
+### Function references
+
+- Use `api` from `convex/_generated/api.ts` for functions registered with `query`, `mutation`, or `action`, and `internal` for those registered with `internalQuery`, `internalMutation`, or `internalAction`. File routing maps `convex/example.ts` function `f` to `api.example.f` and private `g` to `internal.example.g`; nested files include every directory segment, such as `api.messages.access.h`.
+
+### Pagination
+
+- Validate `paginationOpts` with `paginationOptsValidator` from `convex/server` and pass `args.paginationOpts` unchanged to `.paginate()`. Do not reconstruct it, because optional native behavior would be lost.
+- The native options are `numItems`, required nullable `cursor`, optional `endCursor`, `maximumRowsRead`, `maximumBytesRead`, and client-managed `id`. Read budgets can produce a short page with `splitCursor` and `pageStatus`.
+- A paginated query returns `page`, `isDone`, and `continueCursor`, with optional `splitCursor` and `pageStatus`. Use `paginationResultValidator(itemValidator)` for its return validator.
+
+## Schema guidelines
+
+- Define the schema in `convex/schema.ts` and import schema functions from `convex/server`.
+- `_id` and `_creationTime` are automatically added system fields (`v.id(tableName)` and `v.number()`).
+- Include every index field in its name, such as `by_field1_and_field2`; query indexed fields in their declared order, creating separate indexes for another order.
+- Do not put an unbounded list in one document. Use a child table with a foreign key. Keep high-churn heartbeats, online status, and typing indicators in a dedicated table instead of a stable profile document.
+- An index added to a large existing table can block deploy during backfill. Use `.index("by_field", { fields: ["field"], staged: true })`; remove `staged` in a later deploy before querying it.
+
+## Authentication guidelines
+
+- JWT authentication requires `convex/auth.config.ts`. Its provider `domain` is the JWT issuer, and `applicationID` is checked against the token audience; without the file, `ctx.auth.getUserIdentity()` is always `null`.
+- Read identity with `ctx.auth.getUserIdentity()` in queries, mutations, and actions. It may be `null`; `tokenIdentifier` is the guaranteed canonical stable identity key, so use it for ownership and auth-linked lookups rather than `subject` alone.
+- Never accept a user ID or other identity argument for authorization; derive it server-side.
+- With an external auth provider, use `ConvexProviderWithAuth` from `convex/react`, whose `useAuth` returns `{ isLoading, isAuthenticated, fetchAccessToken }`. Do not use plain `ConvexProvider` for authenticated requests because it will not send tokens.
+
+## TypeScript guidelines
+
+- Import `Id` and `Doc<"tableName">` from `./_generated/dataModel`; use `Id<"users">` instead of `string` for a users-table ID.
+- Type contexts with `QueryCtx`, `MutationCtx`, and `ActionCtx` from `./_generated/server`; never use `any` for a context parameter.
+- Give `Record` both key and value types, such as `Record<Id<"users">, string>`.
+- For typed app environment variables, declare them in `convex/convex.config.ts` with `defineApp({ env: { MY_KEY: v.optional(v.string()) } })` and read `env` from `./_generated/server`, not `process.env`. `CONVEX_SITE_URL` and `CONVEX_CLOUD_URL` are already on `env`; do not redeclare them.
+
+## Full text search guidelines
+
+- Use `.withSearchIndex("search_body", q => q.search("body", text).eq("channel", channel))` and then bound results with `.take(n)`.
+
+## Vector search guidelines
+
+- Store embeddings as `v.array(v.float64())` and declare a vector index with `vectorField`, exact `dimensions`, and any declared `filterFields`.
+- `ctx.vectorSearch` is available only in actions. Its filter supports equality on declared filter fields and `q.or(...)`, not cross-field AND or inequality; apply remaining predicates after hydration.
+- Results contain only `{ _id, _score }` in descending similarity order. Since actions have no `ctx.db`, hydrate all hits through one internal query, preserve search order, and pair each score with its document ID.
+
+## Component guidelines
+
+- Components are installable building blocks such as `@convex-dev/aggregate` and `@convex-dev/rate-limiter`, with isolated tables and functions. Install and mount them in `convex/convex.config.ts`, then `import { components } from "./_generated/api"` and pass e.g. `components.aggregate` to the component client (there is no `ctx.components`).
+- Component functions are not client-facing. Wrap them in app queries/mutations and authorize in the app function first.
+- Component reads and writes participate in the calling mutation's transaction. If a component mirrors an app table, update it in the same mutation as every insert, patch, replace, or delete.
+- A local component has a directory under `convex/`, its own `convex.config.ts` using `defineComponent("myName")`, its own `schema.ts`, and functions from its own `_generated/server`. Mount with `app.use(myName)` and include the module segment in references: a function in `convex/myName/index.ts` is `components.myName.index.myFunction`, never `components.myName.myFunction`.
+- For per-key quotas, cooldowns, or throttling, use `@convex-dev/rate-limiter`; hand-rolled counters and window scans race under concurrency and lose quota when a mutation fails.
+- For chat or assistant features where an LLM replies inside a durable conversation - per-user resumable histories, recorded tool-call steps, several assistants sharing one conversation - use the `@convex-dev/agent` component: mount it, create one component thread per conversation, and generate/read through it (`createThread(ctx, components.agent, ...)`, `new Agent(components.agent, { name, languageModel, tools }).generateText(ctx, { threadId }, { prompt })`, `listMessages`). Do not hand-roll a messages table or call an LLM SDK directly from your functions for these.
+- For async functions needing bounded parallelism, serialized mutation work, or completion callbacks, use `@convex-dev/workpool`; retry only idempotent actions.
+- For ephemeral presence - who is online/viewing/typing in a room, tracked by client heartbeats with session tokens, multi-session aggregation (one entry per user across tabs), and timeout-to-offline - use `@convex-dev/presence`; hand-rolled lastSeen tables need wall-clock query filters that go stale, and per-session rows break the one-entry-per-user contract.
+- A component mutation is a subtransaction. If it throws and the caller catches it, its writes roll back while the caller can continue and commit.
+- To pass a function across a component boundary, mint a handle in the app with `const handle = await createFunctionHandle(internal.index.myCallback)` from `convex/server`; send it as a string, then invoke it with `await ctx.runMutation(args.handle as FunctionHandle<"mutation">, callbackArgs)`. `getFunctionHandle` and `getFunctionName` are not this API.
+
+## Query guidelines
+
+- Prefer `.withIndex()` and put every index-supported predicate in the index range. `.filter()` runs after the index scan and does not make an unbounded query scalable.
+- Do not read the wall clock in a query. Pass current time as an argument or materialize time state with scheduled mutations; `Date.now()` is fine in mutations and actions.
+- If the user does not explicitly tell you to return all results from a query you should ALWAYS return a bounded collection instead. So that is instead of using `.collect()` you should use `.take()` or paginate on database queries. This prevents future performance issues when tables grow in an unbounded way.
+- Never use `.collect().length`; Convex has no built-in count operator. A counter document suffices only for a simple total. When queries need counts, sums, ranks/positions, or offsets over many rows, whole-table or within a key range, use `@convex-dev/aggregate` (O(log n) reads), updated in the same mutation as every source-table write.
+- Queries do not support `.delete()`. Read matches in batches or with async iteration and call `ctx.db.delete` for each document.
+- For large mutation work, process a batch and schedule a continuation with `ctx.scheduler.runAfter(0, internal.myModule.myMutation, args)`. For variable document sizes, use async iteration and after each write `await ctx.meta.getTransactionMetrics()`, returning when a needed `.remaining` metric such as `metrics.bytesRead.remaining` reaches a safety reserve.
+- Use `.unique()` for one document; it throws when multiple documents match. With async iteration, use `for await (const row of query)` rather than `.collect()` or `.take(n)`.
+
+### Ordering
+
+- Queries default to ascending order over the selected index key; a plain scan uses `by_creation_time`. `.order("asc"|"desc")` selects direction. Index queries follow index columns and append `_creationTime` as a tie-breaker, so do not re-sort equal-key rows in JavaScript.
+
+## Mutation guidelines
+
+- Use `ctx.db.replace(table, id, document)` to replace a whole existing document and `ctx.db.patch(table, id, fields)` for a shallow merge. Both throw when the document does not exist.
+
+## Action guidelines
+
+- Put `"use node";` at the top of a file containing actions that use Node built-ins. Keep such actions separate from files exporting queries or mutations. `fetch()` works in the default runtime, so it does not require Node.
+- Actions have no `ctx.db`; read and write data through function calls.
+
+## Scheduling guidelines
+
+### Cron guidelines
+
+- Use only `crons.interval` or `crons.cron`, and pass a `FunctionReference`, never a function value. Define a top-level `cronJobs()` object and export it as default.
+- Functions may be registered in `crons.ts`. For an internal target, import `internal` from `./_generated/api` even when the target is registered in the same file.
+
+## Testing guidelines
+
+- Test Convex functions with `convex-test`, Vitest, and `@edge-runtime/vm`; configure Vitest with `environment: "edge-runtime"` and always install the latest versions of these packages.
+- Test files belong under `convex/`. Pass an `import.meta.glob("./**/*.ts")` module map to `convexTest(schema, modules)` and call functions through generated `api` references.
+- Add `/// <reference types="vite/client" />` only in test files that use `import.meta.glob`.
+- Do not add uninstalled packages to `compilerOptions.types`; leave `types` unset unless the package is installed.
+
+## File storage guidelines
+
+- `ctx.storage.getUrl(fileId)` returns a signed URL or `null` when absent. Do not use deprecated `ctx.storage.getMetadata`.
+- Read metadata from the `_storage` system table with `ctx.db.system.get("_storage", fileId)` and an `Id<"_storage">`; storage values are `Blob` objects and must be converted to/from `Blob`.
+
+## Selected reference patterns
+
+HTTP endpoints are registered with this shape:
+
+```typescript
+import { httpRouter } from "convex/server";
+import { httpAction } from "./_generated/server";
+const http = httpRouter();
+http.route({
+  path: "/echo",
+  method: "POST",
+  handler: httpAction(async (ctx, req) => {
+    const body = await req.bytes();
+    return new Response(body, { status: 200 });
+  }),
+});
+```
+
+An array validator is:
+
+```typescript
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+export const exampleMutation = mutation({
+  args: { simpleArray: v.array(v.union(v.string(), v.number())) },
+  handler: async (ctx, args) => {},
+});
+```
+
+A discriminated union uses `v.union` with `v.literal` members, for example:
+
+```typescript
+export default defineSchema({
+  results: defineTable(
+    v.union(
+      v.object({ kind: v.literal("error"), errorMessage: v.string() }),
+      v.object({ kind: v.literal("success"), value: v.number() }),
+    ),
+  ),
+});
+```
+
+Nested limits are the optional third argument:
+
+```ts
+try {
+  await ctx.runMutation(internal.example.writeBatch, args, {
+    transactionLimits: { documentsWritten: 100, bytesWritten: 1024 * 1024 },
+  });
+} catch (e) {
+  // The nested mutation's writes rolled back; this mutation can still write.
+}
+```
+
+Same-file calls can use an explicit result annotation:
+
+```ts
+const result: string = await ctx.runQuery(api.example.f, { name: "Bob" });
+```
+
+Pagination passes the validator and options through unchanged:
+
+```ts
+export const listWithExtraArg = query({
+  args: { paginationOpts: paginationOptsValidator, author: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("messages")
+      .withIndex("by_author", (q) => q.eq("author", args.author))
+      .order("desc")
+      .paginate(args.paginationOpts);
+  },
+});
+```
+
+An auth provider config has this shape:
+
+```typescript
+export default {
+  providers: [
+    {
+      domain: "https://your-auth-provider.com",
+      applicationID: "convex",
+    },
+  ],
+};
+```
+
+An external auth client uses `ConvexProviderWithAuth` with `useAuth`:
+
+```tsx
+<ConvexProviderWithAuth client={convex} useAuth={useYourAuthHook}>
+  {children}
+</ConvexProviderWithAuth>
+```
+
+A typed ID-keyed map is:
+
+```ts
+const idToUsername: Record<Id<"users">, string> = {};
+```
+
+Vector indexes declare the field, dimensions, and filters:
+
+```ts
+documents: defineTable({
+  title: v.string(),
+  category: v.string(),
+  embedding: v.array(v.float64()),
+}).vectorIndex("by_embedding", {
+  vectorField: "embedding",
+  dimensions: 1536,
+  filterFields: ["category"],
+}),
+```
+
+The vector call is action-only:
+
+```ts
+const results = await ctx.vectorSearch("documents", "by_embedding", {
+  vector: args.embedding,
+  limit: 10,
+  filter: (q) => q.eq("category", args.category),
+});
+```
+
+Mounting a component follows this pattern:
+
+```ts
+import { defineApp } from "convex/server";
+import aggregate from "@convex-dev/aggregate/convex.config";
+const app = defineApp();
+app.use(aggregate);
+export default app;
+```
+
+Cron wiring uses a top-level object and a reference:
+
+```ts
+const crons = cronJobs();
+crons.interval("delete inactive users", { hours: 2 }, internal.crons.empty, {});
+export default crons;
+```
+
+Convex tests require the module map:
+
+```typescript
+import { convexTest } from "convex-test";
+const modules = import.meta.glob("./**/*.ts");
+const t = convexTest(schema, modules);
+await t.mutation(api.messages.send, { body: "Hi!", author: "Sarah" });
+```
+
+Storage metadata comes from the system table:
+
+```ts
+const metadata = await ctx.db.system.get("_storage", fileId);
+```

package/dist/templates/default/packages/backend/convex/_generated/api.d.ts

@@ -0,0 +1,66 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as auth from "../auth.js";
+import type * as http from "../http.js";
+import type * as mcp from "../mcp.js";
+import type * as todos_index from "../todos/index.js";
+import type * as todos_internal from "../todos/internal.js";
+import type * as users from "../users.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  auth: typeof auth;
+  http: typeof http;
+  mcp: typeof mcp;
+  "todos/index": typeof todos_index;
+  "todos/internal": typeof todos_internal;
+  users: typeof users;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {
+  auth: import("@convex-dev/auth/_generated/component.js").ComponentApi<"auth">;
+  authPassword: import("@convex-dev/auth/components/password/_generated/component.js").ComponentApi<"authPassword">;
+  authUsername: import("@convex-dev/auth/components/username/_generated/component.js").ComponentApi<"authUsername">;
+  staticHosting: import("@convex-dev/static-hosting/_generated/component.js").ComponentApi<"staticHosting">;
+  mcp: import("@convex-dev/mcp/_generated/component.js").ComponentApi<"mcp">;
+  workflow: import("@convex-dev/workflow/_generated/component.js").ComponentApi<"workflow">;
+};

package/dist/templates/default/packages/backend/convex/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();

package/dist/templates/default/packages/backend/convex/_generated/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;