safebyok-convex 0.0.0-stage → 0.0.0

package/.claude/skills/LICENSE-convex-agent-skills

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/.claude/skills/README.md

@@ -0,0 +1,115 @@
+# Convex agent skills for safebyok-convex
+
+Six of Convex's official agent skills, chosen for what this package does: author a packaged
+Convex **component**, write its **schema and validators**, its **queries and mutations**, test
+them with **`convex-test`**, and review them. They are scoped to `packages/safebyok-convex/`:
+Claude Code loads a nested `.claude/skills/` the first time it reads or edits a file below this
+package (or sooner, with `/add-dir packages/safebyok-convex`), and not before.
+
+Nothing here is executable: every file is Markdown, outside every lint, typecheck and test glob.
+
+## Source
+
+| | |
+| --- | --- |
+| Repository | [get-convex/agent-skills](https://github.com/get-convex/agent-skills), the source [docs.convex.dev/ai/agent-skills](https://docs.convex.dev/ai/agent-skills) names and `npx convex ai-files install` installs from |
+| Commit | `191a5c33a7e7a22ec9d5ff13930f84748bbcf8f8` (2026-10-13, "Sync from convex-agents@cfccf3e"); retrieved 2026-10-14 |
+| License | Apache-2.0, copied beside this file as `LICENSE-convex-agent-skills` |
+
+Copied by hand from a clone, not by `npx skills add` or `npx convex ai-files install`: both run
+code fetched at install time, and the latter also writes into a `convex/` directory and the
+repo's `CLAUDE.md`. To update, clone the repository at a newer commit, diff each kept file
+against it, and carry the local changes below across.
+
+## What is here, and what to read it for
+
+| Skill | Files | Read it for |
+| --- | --- | --- |
+| `convex-create-component` | `SKILL.md`, `references/packaged-components.md`, `references/advanced-patterns.md` | Authoring the component: `defineComponent`, component-owned tables, the boundary rules (no `ctx.auth` or `process.env` inside, host IDs as strings, the host's re-export wrappers), package exports and build order, class-based wrappers like `.api({ getUserId })` |
+| `convex-expert` | `SKILL.md` | Schema, validators and functions: object form, `args` and `returns` on everything, `v.union` of `v.literal`, indexes over `.filter`, bounded reads, the import table, `null` not `undefined` |
+| `convex-test` | `SKILL.md` | The `convex-test` recipe: `convexTest(schema)`, `t.run`, `t.query` and `t.mutation` |
+| `convex-verify` | `SKILL.md` | The `edge-runtime` vitest configuration `convex-test` needs, and proving refusals: the wrong user, no user, data scoped to its owner |
+| `convex-reviewer` | `SKILL.md` | A review pass over component functions: auth on every function, indexes, validators |
+| `convex-docs` | `SKILL.md` | Pinning the installed `convex` version and checking its `.d.ts` before trusting memory or a doc page |
+
+Not covered by any Convex skill, so read the sources instead:
+
+* **The client** (`ConvexClient`, `ConvexReactClient`, `onUpdate`, `watchQuery`):
+  [JavaScript clients](https://docs.convex.dev/client/javascript/overview.md),
+  [ConvexClient](https://docs.convex.dev/api/classes/browser.ConvexClient.md),
+  [ConvexReactClient](https://docs.convex.dev/api/classes/react.ConvexReactClient.md), and the
+  installed types, `node_modules/convex/dist/esm-types/browser/simple_client.d.ts` and
+  `.../react/client.d.ts`.
+* **`ConvexError` and its `data`**: [Application Errors](https://docs.convex.dev/functions/error-handling/application-errors.md)
+  and `node_modules/convex/dist/esm-types/values/errors.d.ts`.
+* **Transactions and serializability**: [OCC and Atomicity](https://docs.convex.dev/database/advanced/occ.md).
+* **Components and testing them**: [Authoring Components](https://docs.convex.dev/components/authoring.md),
+  [convex-test](https://docs.convex.dev/testing/convex-test.md), and `node_modules/convex-test/README.md`.
+* Convex's own **guidelines** (`https://version.convex.dev/v1/guidelines`, what `ai-files`
+  installs) are dense and current, but carry no license, so they are not copied here.
+
+## Local changes
+
+Apache-2.0 asks that changed files say so: each changed file opens with a note pointing here.
+
+* `convex-create-component/SKILL.md`: the shape is settled as packaged, so the "ask the user"
+  step, the local and hybrid rows and references, and the local default are gone; `npx convex
+  dev` is replaced by codegen and `pnpm justify` (validation step, checklist), with "stop and ask
+  the Coach" for a login or a deployment; `convex-helpers` is marked as needing the Coach's yes.
+* `convex-create-component/references/advanced-patterns.md`: a handler that used `args` without
+  taking it now takes it; a note says the example's read of an app-owned table is illustration only.
+* `convex-create-component/references/packaged-components.md`: the scaffolder (`npx
+  create-convex@latest --component`) and the build flow's `npx convex dev
+  --typecheck-components` are gone, with a note that that step is the Coach's.
+* `convex-expert/SKILL.md`: the self-verify rule that pushed to a deployment (and could set
+  `CONVEX_AGENT_MODE=anonymous`, rebinding `.env.local`) is replaced by codegen and `pnpm
+  justify`; the step steering LLM features to `@convex-dev/agent` and `@convex-dev/workflow` is
+  gone; the `v.id` rule, the internal-by-default rule and the `convex/`-directory rule say how
+  they read inside a component.
+* `convex-verify/SKILL.md`: the steps that emitted findings to a "bus" whose schema is not in the
+  repository, and the hand-offs to skills not installed here, are gone; a note says how
+  identities reach a component (the host's `getUserId`) and that tests follow `STYLE.md`.
+* `convex-reviewer/SKILL.md`: a note maps its `ctx.auth` check onto this package's `getUserId`.
+
+`convex-test/SKILL.md` and `convex-docs/SKILL.md` are unchanged.
+
+## Left out
+
+From `convex-create-component`: `references/local-components.md` and
+`references/hybrid-components.md` (this is a packaged component), `agents/openai.yaml` (Codex
+metadata), `assets/icon.svg` (an icon).
+
+The other 27 skills at this commit:
+
+* `convex`: a router and product pitch; it has the agent fetch and follow instructions served from a Convex site.
+* `convex-add`: adds capabilities to an app from a remote catalog, installing as it goes.
+* `convex-advisor`: performance findings from a live deployment's insights.
+* `convex-agent`: AI agents and RAG.
+* `convex-auth`: auth providers; generates keys and sets deployment env vars.
+* `convex-authz`: rewrites an app's authorization around its users table; this package has neither.
+* `convex-backup`: deployment backups and restores.
+* `convex-billing`: Stripe billing over HTTP actions.
+* `convex-cost`: spend analysis of a live deployment.
+* `convex-crons`: scheduled jobs.
+* `convex-deploy-guard`: deployment targeting.
+* `convex-design`: a product pitch and app scaffolding, with the same push-to-deploy rule.
+* `convex-domains`: DNS and custom domains.
+* `convex-env`: deployment env vars.
+* `convex-explain-app`: explains an existing app.
+* `convex-improve-convex-plugin`: pipes a remote script into a shell and uploads the session transcript.
+* `convex-insights`: logs and health of a live deployment.
+* `convex-launch-readiness`: an aggregate of audits left out here.
+* `convex-migrate`: app data migrations.
+* `convex-migrate-rehearse`: production migration rehearsals.
+* `convex-monitor`: watches a live deployment, through a tool that does not exist here.
+* `convex-optimize`: an app audit and upgrade workflow.
+* `convex-quickstart`: app scaffolding.
+* `convex-seed`: seeds a deployment's data.
+* `convex-self-heal`: production error triage into PRs.
+* `convex-sentinel`: production error capture.
+* `convex-suggest`: suggests `@convex-dev` components, through a detector not in the repository.
+
+Also left out: Convex's plugins for Claude Code
+([get-convex/convex-backend-skill](https://github.com/get-convex/convex-backend-skill)), Cursor
+and Codex. Their skills are the same generated text, and they add session hooks that run code,
+telemetry on by default, a remote freshness check, background log monitors and an MCP server.

package/.claude/skills/convex-create-component/SKILL.md

@@ -0,0 +1,330 @@
+---
+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
+
+> **Changed for safebyok-convex** from get-convex/agent-skills at `191a5c33` (Apache-2.0; the
+> changes are listed in `../README.md`). Here the shape is settled: `safebyok-convex` is a
+> **packaged** component (`whiteboard/20261014-convex/design.md`), whose host app authenticates
+> through a `getUserId(ctx)` callback rather than `@convex-dev/auth`. Never run `npx convex dev`
+> or push to a deployment; if codegen needs a Convex login or a deployment, stop and ask the
+> Coach for that exact step.
+
+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. Confirm what you are building against `whiteboard/20261014-convex/design.md`
+   and the sprint plan, rather than asking afresh.
+2. Read `references/packaged-components.md`: the shape is settled (below).
+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 codegen (see Validation) and `pnpm justify` inside
+    `packages/safebyok-convex/`, and fix codegen, type, or boundary issues
+    before finishing.
+
+## Choose the Shape
+
+| Goal                         | Shape    | Reference                           |
+| ---------------------------- | -------- | ----------------------------------- |
+| Publish or share across apps | Packaged | `references/packaged-components.md` |
+
+This package is a packaged component. Upstream's local and hybrid references
+were left out of this install.
+
+## Default Approach
+
+Upstream's default, a local component inside one app, does not apply here. The
+skeleton below uses the local layout (`convex/components/<componentName>/`) only
+to illustrate; the parts carry over to a package unchanged:
+
+- Define it with `defineComponent(...)` in its own `convex.config.ts`
+- The host installs it from its `convex/convex.config.ts` with `app.use(...)`
+- Codegen generates 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. (`convex-helpers` is not a dependency of this
+  package, and adding it needs the Coach's yes.)
+- 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 <path to the component>`
+2. `npx convex codegen`
+
+Never `npx convex dev` here: it provisions or pushes to a deployment.
+
+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
+
+- `references/packaged-components.md`: the package layout, build order, exports
+  and testing
+- `references/advanced-patterns.md`: function handles, validators derived from
+  the schema, and class-based client wrappers
+
+Official docs:
+[Authoring Components](https://docs.convex.dev/components/authoring)
+
+## Checklist
+
+- [ ] Confirmed the plan against the design
+- [ ] Read `references/packaged-components.md`
+- [ ] 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 codegen and `pnpm justify`, and fixed codegen or type issues