@dodopayments/opencode-plugin 0.5.1 → 0.6.1

package/.mcp.json

@@ -1,23 +1,13 @@
 {
     "mcpServers": {
         "dodopayments-api": {
-            "type": "stdio",
-            "command": "npx",
-            "args": [
-                "-y",
-                "mcp-remote@latest",
-                "https://mcp.dodopayments.com/mcp"
-            ],
+            "type": "http",
+            "url": "https://mcp.dodopayments.com/mcp",
             "enabled": true
         },
         "dodo-knowledge": {
-            "type": "stdio",
-            "command": "npx",
-            "args": [
-                "-y",
-                "mcp-remote@latest",
-                "https://knowledge.dodopayments.com/mcp"
-            ],
+            "type": "http",
+            "url": "https://knowledge.dodopayments.com/mcp",
             "enabled": true
         }
     }

package/README.md

@@ -5,7 +5,7 @@
 [![npm](https://img.shields.io/npm/v/@dodopayments/opencode-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@dodopayments/opencode-plugin)
 [![Discord](https://img.shields.io/discord/1305511580854779984?label=discord&style=flat-square)](https://discord.gg/bYqAp4ayYh)
 
-The official Dodo Payments plugin for AI coding agents. Installs seventeen integration skills and two MCP servers across **Claude Code**, **Codex CLI**, **Cursor**, **VS Code / GitHub Copilot**, and **OpenCode** from a single source of truth.
+The official Dodo Payments plugin for AI coding agents. Installs the Dodo Payments integration skills and two MCP servers across **Claude Code**, **Codex CLI**, **Cursor**, **VS Code / GitHub Copilot**, **Grok Build**, **Meta Muse Code**, **Gemini CLI**, **Antigravity**, **Junie**, **OpenCode**, and more, from a single source of truth.
 
 This plugin conforms to the [Agent Plugins 1.0.0](https://agent-plugins.org/specification) specification: a root [`plugin.json`](./plugin.json), skills as immediate children of [`skills/`](./skills), and MCP servers in [`mcp.json`](./mcp.json). Clients with native Agent Plugins support load it directly; the provider-specific manifests in this repo are generated compatibility shims for clients that do not.
 
@@ -13,10 +13,28 @@ This plugin conforms to the [Agent Plugins 1.0.0](https://agent-plugins.org/spec
 
 - **Dodo Payments API MCP server** - Live API access (payments, subscriptions, customers, products, refunds, licenses, usage). Authenticates via browser OAuth, no local credentials required.
 - **Dodo Knowledge MCP server** - No credentials. Semantic search over the current Dodo Payments documentation.
-- **Seventeen agent skills** - Written as `SKILL.md` files with YAML frontmatter. Your agent loads the relevant skill on its own when a task calls for it.
+- **Agent skills** - Integration guides (listed [below](#included-skills)), written as `SKILL.md` files with YAML frontmatter. Your agent loads the relevant skill on its own when a task calls for it.
 
 ## Install
 
+| Client | Skills | MCP | How |
+|---|---|---|---|
+| Claude Code | ✅ | ✅ | [Marketplace](#claude-code) |
+| Codex CLI / ChatGPT | ✅ | ✅ | [Marketplace](#codex-cli) |
+| Cursor (and Grok Bot) | ✅ | ✅ | [Clone](#cursor) |
+| VS Code / GitHub Copilot | ✅ | ✅ | [Plugins view](#vs-code--github-copilot) · [Copilot CLI](./docs/clients/more-clients.md) |
+| Grok Build | ✅ | ✅ | [`grok plugin install`](./docs/clients/grok.md) |
+| grok.com, xAI API | — | ✅ | [Connector / API tool](./docs/clients/grok.md) |
+| Meta Muse Code | ✅ | ✅ | [`muse plugins install`](./docs/clients/muse.md) |
+| Gemini CLI | ✅ | ✅ | [Extension](#gemini-cli) |
+| Google Antigravity | ✅ | ✅ | [`agy plugin install`](./docs/clients/antigravity-and-junie.md#antigravity) |
+| JetBrains Junie | ✅ | ✅ | [Extension](./docs/clients/antigravity-and-junie.md#junie) |
+| Kiro | ✅ | ✅ | [Power](#kiro) |
+| OpenCode | ✅ | ✅ | [npm](#opencode) |
+| Qwen Code, Devin, Goose, Factory Droid, Augment, OpenHands, OpenClaw, Hermes | ✅ | ✅ | [More clients](./docs/clients/more-clients.md) |
+| Cline, Kilo, Zed, Warp, Amp, Continue, Kimi, … | ✅ | ✅ | [`npx skills` + `npx add-mcp`](./docs/clients/more-clients.md#skills-and-mcp-separately) |
+| Claude.ai, ChatGPT, Perplexity, Mistral | — | ✅ | [Custom connector](./docs/clients/more-clients.md#mcp-only-assistants) |
+
 ### Claude Code
 
 ```bash
@@ -75,16 +93,13 @@ git clone https://github.com/dodopayments/dodo-agent-plugin.git
 
 Point Kiro at the cloned folder. Skills load from `skills/`, MCP servers from `mcp.json`, and Kiro-specific presentation comes from the `dev.kiro` extension namespace in `plugin.json`.
 
-### Gemini CLI (MCP only)
-
-Gemini CLI has no agent-skill primitive, so **only the two MCP servers are available** - the seventeen skills are not. `dodo-knowledge` still covers a good share of what the skills provide, and it stays current automatically.
+### Gemini CLI
 
 ```bash
-git clone https://github.com/dodopayments/dodo-agent-plugin.git \
-  ~/.gemini/extensions/dodopayments
+gemini extensions install https://github.com/dodopayments/dodo-agent-plugin
 ```
 
-Restart Gemini CLI. `gemini-extension.json` at the repo root is the manifest.
+`gemini-extension.json` at the repo root is the manifest, and Gemini auto-discovers the `skills/` directory next to it. Verified on Gemini CLI 0.63.0: `gemini skills list` shows every skill and `gemini mcp list` shows both servers.
 
 ### VS Code / GitHub Copilot
 
@@ -94,7 +109,7 @@ git clone https://github.com/dodopayments/dodo-agent-plugin.git
 
 Then open the Chat view, go to **Plugins**, and add the cloned folder. Skills load from `skills/`, and both MCP servers load from `.mcp.json`.
 
-> VS Code 1.125.1 does not key off the Agent Plugins `$schema` - the string appears nowhere in its bundle. Its loader picks a manifest by probing, in order, `.plugin/plugin.json`, then `.claude-plugin/plugin.json`, then a root `plugin.json`, and defaults MCP to `.mcp.json` rather than `mcp.json`. Because this repo ships a generated `.claude-plugin/plugin.json`, VS Code loads it through that branch. Everything works - seventeen skills and two MCP servers - but via the compatibility manifests rather than the spec ones, so VS Code gets the `mcp-remote` bridge rather than the native transports in `mcp.json`.
+> VS Code 1.125.1 does not key off the Agent Plugins `$schema` - the string appears nowhere in its bundle. Its loader picks a manifest by probing, in order, `.plugin/plugin.json`, then `.claude-plugin/plugin.json`, then a root `plugin.json`, and defaults MCP to `.mcp.json` rather than `mcp.json`. Because this repo ships a generated `.claude-plugin/plugin.json`, VS Code loads it through that branch. Everything works - all skills and both MCP servers - via the compatibility manifests rather than the spec ones.
 
 ### OpenCode
 
@@ -107,7 +122,7 @@ OpenCode distributes via npm. Add the plugin to your `opencode.json`:
 }
 ```
 
-Restart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's `config` hook. No manual `mcp` block required.
+Restart OpenCode. Both MCP servers (`dodopayments-api`, `dodo-knowledge`) are registered automatically via the plugin's `config` hook as native remote servers. No manual `mcp` block required. Run `opencode mcp auth dodopayments-api` to sign in to the API server.
 
 **Skills need the package installed locally plus one extra line.** OpenCode does not scan installed packages for skills, so point it at the package's `skills/` directory yourself. `skills.paths` entries resolve against the project directory, so the package must be present in the project's `node_modules` - OpenCode's own plugin cache is not the same location:
 
@@ -127,7 +142,7 @@ npm install --save-dev @dodopayments/opencode-plugin
 
 An absolute path works too, and avoids the local-install requirement.
 
-Verify with `opencode run "List every skill available to you by name."` - you should see all seventeen. A skills path that does not exist is ignored silently, so check rather than assume.
+Verify with `opencode run "List every skill available to you by name."` - you should see every skill listed under [Included Skills](#included-skills). A skills path that does not exist is ignored silently, so check rather than assume.
 
 > Versions before 0.5.0 documented these skills as auto-discovered. They were not: nothing in OpenCode scans an installed package, so OpenCode users had MCP servers but no skills. Setting `config.skills` from the plugin's `config` hook does not fix this either - the skill index is built before `config` hooks run, so it never registers anything.
 
@@ -160,6 +175,7 @@ If you prefer the local stdio API server with your own API key instead of the de
 | `dodo-best-practices` | SDK setup, environments, API keys, and the canonical checkout-to-webhook architecture |
 | `framework-adapters` | Official `@dodopayments/*` handlers for Next.js, Express, Hono, Astro, Remix, SvelteKit, Nuxt, Fastify, TanStack, Bun, Convex |
 | `testing-and-go-live` | Test mode, test payment methods, webhook testing, production launch checklist |
+| `dodo-mcp-usage` | When to use the documentation vs API MCP servers, test-mode safety rules, auth, troubleshooting |
 
 **Accepting payments**
 
@@ -209,7 +225,7 @@ Skills source: [`dodopayments/skills`](https://github.com/dodopayments/skills),
 | `dodopayments-api` | Live API access (payments, subscriptions, customers, products, refunds, licenses, usage) | OAuth (browser) |
 | `dodo-knowledge` | Semantic search over the Dodo Payments documentation | None |
 
-Both servers speak Streamable HTTP. The canonical `mcp.json` declares them natively (`type: "streamable-http"`), which is what spec-native clients such as Codex CLI and Cursor use. The generated compatibility manifests — `.mcp.json`, read by Claude Code, VS Code and Cursor's legacy path — wire the same two endpoints through `mcp-remote` instead, so they run in clients that cannot yet dial Streamable HTTP directly.
+Both servers speak Streamable HTTP over HTTPS, and every manifest dials them natively - no `npx mcp-remote` bridge and no Node dependency. The canonical `mcp.json` uses the spec's `type: "streamable-http"`; the generated `.mcp.json` (Claude Code, Cursor, VS Code, Grok Build, Devin, Goose, Droid) uses the same endpoints spelled `type: "http"`, the name that dialect uses; Muse, Antigravity, Junie and Gemini get their own spellings from the generator.
 
 ## Configure (optional, Claude Code)
 
@@ -269,9 +285,8 @@ These clients load MCPs from the static `.mcp.json` shipped with the plugin. To
 {
     "mcpServers": {
         "dodopayments-api": {
-            "type": "stdio",
-            "command": "npx",
-            "args": ["-y", "mcp-remote@latest", "https://mcp.dodopayments.com/mcp"],
+            "type": "http",
+            "url": "https://mcp.dodopayments.com/mcp",
             "enabled": false
         }
     }
@@ -327,9 +342,9 @@ npm run verify     # generated artifacts in sync + Agent Plugins conformance
 |---|---|
 | `plugin.json` | **Canonical.** Agent Plugins v1.0.0 manifest and the version source of truth |
 | `mcp.json` | **Canonical.** Agent Plugins v1.0.0 MCP config |
-| `skills/` | **Canonical.** Seventeen skills, vendored as real files |
+| `skills/` | **Canonical.** Skills, vendored as real files; the declared set lives in `.skills-source.json` |
 | `overlays/*.json` | Hand-authored provider extras the closed spec schema cannot express |
-| `.claude-plugin/`, `.cursor-plugin/`, `.agents/`, `.mcp.json`, `plugins/dodopayments/` | **Generated.** Do not hand-edit - run `npm run build` |
+| `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, `.muse-plugin/`, `.agents/`, `.mcp.json`, `gemini-extension.json`, `plugins/dodopayments/`, `providers/` | **Generated.** Do not hand-edit - run `npm run build` |
 | `scripts/build.mjs` | The single generator (`--check` for drift) |
 | `scripts/conformance.mjs` | Agent Plugins conformance validator |
 | `.skills-source.json` | Upstream provenance for the vendored skills |
@@ -343,7 +358,7 @@ The repo is configured to publish the OpenCode npm package on every GitHub Relea
 **One-time setup (already done for this repo):**
 
 - npm scope `@dodopayments` exists and is owned by Dodo Payments.
-- GitHub Actions secret `NPM_TOKEN` is provisioned with publish rights to the `@dodopayments` scope.
+- npm Trusted Publishing (OIDC) is configured for `@dodopayments/opencode-plugin` against `publish-opencode.yml`. No npm token is stored in the repo.
 
 **Release workflow:**
 
@@ -358,7 +373,7 @@ The repo is configured to publish the OpenCode npm package on every GitHub Relea
 
 **CI checks:**
 
-- `Verify` runs on every pull request and push to `main`: artifact drift, Agent Plugins conformance, live JSON Schema validation, a "seventeen skills, zero symlinks" assertion, and an npm payload check.
+- `Verify` runs on every pull request and push to `main`: artifact drift, Agent Plugins conformance, live JSON Schema validation, an "every declared skill, zero symlinks" assertion, per-client manifest checks (Muse, Antigravity, Junie, Gemini), and an npm payload check.
 - The release workflow re-runs the same gates before publishing.
 
 ## Resources

package/mcp.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+    "mcpServers": {
+        "dodopayments-api": {
+            "type": "streamable-http",
+            "url": "https://mcp.dodopayments.com/mcp"
+        },
+        "dodo-knowledge": {
+            "type": "streamable-http",
+            "url": "https://knowledge.dodopayments.com/mcp"
+        }
+    }
+}

package/opencode-plugin/README.md

@@ -1,6 +1,6 @@
 # @dodopayments/opencode-plugin
 
-Official OpenCode plugin for Dodo Payments. Ships seventeen integration skills and auto-registers two MCP servers.
+Official OpenCode plugin for Dodo Payments. Ships the Dodo Payments integration skills and auto-registers two MCP servers.
 
 This package is part of [`dodopayments/dodo-agent-plugin`](https://github.com/dodopayments/dodo-agent-plugin) - the universal Dodo Payments plugin that also installs into Claude Code, Codex, and Cursor.
 
@@ -25,7 +25,7 @@ npm install --save-dev @dodopayments/opencode-plugin
 Restart OpenCode.
 
 - Both MCP servers are registered automatically via the plugin's `config` hook.
-- The `skills.paths` entry is what makes the seventeen skills visible - OpenCode does not scan installed packages for skills. The path resolves against the **project** directory, not OpenCode's plugin cache, which is why the local install above is required. An absolute path works too and avoids that requirement.
+- The `skills.paths` entry is what makes the skills visible - OpenCode does not scan installed packages for skills. The path resolves against the **project** directory, not OpenCode's plugin cache, which is why the local install above is required. An absolute path works too and avoids that requirement.
 - The plugin module exports only its default function. OpenCode's loader throws `Plugin export is not a function` on any non-function named export, skips the plugin, and swallows the error - leaving you with no MCP servers. Verified on OpenCode 1.18.15.
 - The first call to `dodopayments-api` opens a browser for OAuth. `dodo-knowledge` needs no auth.
 
@@ -37,7 +37,7 @@ opencode run "List every skill available to you by name."
 
 ## What you get
 
-Seventeen agent skills (auto-loaded when relevant): `dodo-best-practices`, `framework-adapters`, `testing-and-go-live`, `checkout-integration`, `subscription-integration`, `mobile-checkout`, `webhook-integration`, `credit-based-billing`, `usage-based-billing`, `license-keys`, `product-catalog-management`, `discounts-and-promotions`, `localized-pricing`, `customer-management`, `refunds-and-disputes`, `billing-sdk`, `better-auth-integration`.
+Agent skills (auto-loaded when relevant): `dodo-best-practices`, `dodo-mcp-usage`, `framework-adapters`, `testing-and-go-live`, `checkout-integration`, `subscription-integration`, `mobile-checkout`, `webhook-integration`, `credit-based-billing`, `usage-based-billing`, `license-keys`, `product-catalog-management`, `discounts-and-promotions`, `localized-pricing`, `customer-management`, `refunds-and-disputes`, `billing-sdk`, `better-auth-integration`.
 
 Two MCP servers (registered automatically):
 

package/opencode-plugin/index.js

@@ -30,19 +30,21 @@
 //
 // The endpoint URLs below MUST match the canonical mcp.json. This file is
 // hand-written rather than generated - OpenCode's config shape is its own
-// (`type: "local"`, `command: [...]`) - so `build.mjs --check` cannot cover
+// (`type: "remote"`, `url`) - so `build.mjs --check` cannot cover
 // it. `scripts/conformance.mjs` asserts the URL sets are identical instead.
-// The `mcp-remote` bridge is deliberate here, matching the generated
-// `.mcp.json`: only the canonical mcp.json uses native streamable-http.
+// `type: "remote"` is OpenCode's native Streamable HTTP transport; OpenCode
+// runs OAuth discovery itself. Verified on 1.18.34 from a project-level
+// opencode.json with these exact entries: dodo-knowledge connects, and
+// dodopayments-api reports "needs authentication" (`opencode mcp auth`).
 const DODO_MCP_SERVERS = {
     "dodopayments-api": {
-        type: "local",
-        command: ["npx", "-y", "mcp-remote@latest", "https://mcp.dodopayments.com/mcp"],
+        type: "remote",
+        url: "https://mcp.dodopayments.com/mcp",
         enabled: true,
     },
     "dodo-knowledge": {
-        type: "local",
-        command: ["npx", "-y", "mcp-remote@latest", "https://knowledge.dodopayments.com/mcp"],
+        type: "remote",
+        url: "https://knowledge.dodopayments.com/mcp",
         enabled: true,
     },
 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@dodopayments/opencode-plugin",
-    "version": "0.5.1",
-    "description": "Dodo Payments skills and MCP server hints for OpenCode.",
+    "version": "0.6.1",
+    "description": "Dodo Payments agent skills and MCP servers for OpenCode.",
     "type": "module",
     "main": "opencode-plugin/index.js",
     "exports": {
@@ -10,6 +10,7 @@
     "files": [
         "opencode-plugin/",
         "skills/",
+        "mcp.json",
         ".mcp.json",
         "LICENSE"
     ],

package/skills/better-auth-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: better-auth-integration
-description: Guide only for applications using @dodopayments/better-auth, covering authenticated customer sync, checkout, portal access, usage ingestion, and verified webhook callbacks.
+description: Dodo Payments plugin for Better Auth (@dodopayments/better-auth) covering customer sync on signup, authenticated checkout, customer portal, usage ingestion, and verified webhooks. Use when an app uses Better Auth and needs the dodopayments, dodopaymentsClient, checkout, portal, usage, or webhooks plugins; for other auth stacks use framework-adapters.
 ---
 
 # Better Auth Integration
@@ -18,9 +18,11 @@ Use `@dodopayments/better-auth` to synchronize Better Auth users with Dodo Payme
 ## Install
 
 ```bash
-npm install @dodopayments/better-auth dodopayments better-auth
+npm install @dodopayments/better-auth dodopayments better-auth zod
 ```
 
+Requires Better Auth 1.4 or a later 1.x release.
+
 The package exports the lowercase server functions `dodopayments`, `checkout`, `portal`, `usage`, and `webhooks`. Its client entry point exports `dodopaymentsClient`.
 
 ## Server setup
@@ -76,6 +78,13 @@ export const auth = betterAuth({
 
 `products` maps an application slug to a Dodo product ID. `authenticatedUsersOnly: true` requires a Better Auth session for checkout. `getCustomerParams` adds application metadata when customer synchronization runs.
 
+The plugin adds a `dodoCustomerId` field to the Better Auth `user` table. After adding the plugin, update your database schema with the [Better Auth CLI](https://www.better-auth.com/docs/concepts/cli):
+
+```bash
+npx auth generate   # generate the ORM schema or SQL migration, then apply it yourself
+npx auth migrate    # or apply it directly (built-in Kysely adapter only)
+```
+
 ## Browser client setup
 
 ```typescript
@@ -170,7 +179,7 @@ if (error) {
 }
 ```
 
-The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.
+Both `usage.ingest` and `usage.meters.list` require a signed-in user with a verified email address. The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.
 
 ## Webhook endpoint
 

package/skills/billing-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: billing-sdk
-description: Guide for building billing UI with BillingSDK - the open-source React component library for pricing tables, subscription management, usage meters, invoice history, and customer portal flows wired to Dodo Payments.
+description: BillingSDK, the open-source React and shadcn component library for Dodo Payments billing UI. Use when building pricing tables, pricing pages, account billing pages, usage meters, credit balances, invoice history, or cancel and upgrade UI in React or Next.js, or running @billingsdk/cli init; keep Dodo API calls server-side.
 ---
 
 # BillingSDK
@@ -75,8 +75,10 @@ From the current official registry, grouped by purpose:
 | Payments | `payment-details`, `payment-details-two`, `payment-method-selector`, `payment-card`, `payment-failure` |
 | Promotion and trials | `banner`, `limited-offer-dialog`, `trial-expiry-card` |
 
-`pricing-table-one` is the only block with an officially published prop example, reproduced below. For
-every other block, run `add` and read the generated file's props type.
+Most blocks have a published usage example and props table on their page at
+[billingsdk.com/docs/components](https://billingsdk.com/docs/components) (for example `subscription-management`
+and `billing-settings`); `pricing-table-one` is reproduced below. The generated file's props type is still
+authoritative for the version you installed, so read it after running `add`.
 
 ## Server client
 
@@ -103,44 +105,75 @@ are `https://test.dodopayments.com` and `https://live.dodopayments.com`.
 
 ### 1. Plan catalogue
 
-Keep the product ids and the display copy in one module. The `price` here is a display number rendered by
-the component — the amount actually charged comes from the Dodo product catalogue, and Dodo API amounts
-are always in the smallest currency unit (cents). Treat this file as a mirror of the dashboard and
-reconcile it when you change a price.
+`pricing-table-one` takes BillingSDK's `Plan[]`, not an arbitrary shape. Adding the component generates
+`lib/billingsdk-config.ts`, which exports the `Plan` interface and a sample `plans` array — edit that array
+rather than defining your own type. Prices are display **strings** (`monthlyPrice`, `yearlyPrice`) and
+`features` are objects. The amount actually charged comes from the Dodo product catalogue (always in the
+smallest currency unit), so treat this file as a mirror of the dashboard and reconcile it when you change a
+price.
 
 ```typescript
-// lib/plans.ts
-export type PlanId = 'starter' | 'pro';
-
+// lib/billingsdk-config.ts (generated by `add pricing-table-one`; edit the plans)
 export interface Plan {
-  id: PlanId;
+  id: string;
   title: string;
-  price: number;
-  period: string;
-  features: string[];
-  popular: boolean;
+  description: string;
+  highlight?: boolean;
+  type?: 'monthly' | 'yearly';
+  currency?: string;
+  monthlyPrice: string;
+  yearlyPrice: string;
+  buttonText: string;
+  badge?: string;
+  features: {
+    name: string;
+    icon: string;
+    iconColor?: string;
+  }[];
 }
 
-export const PLANS: readonly Plan[] = [
+export const plans: Plan[] = [
   {
     id: 'starter',
     title: 'Starter',
-    price: 9,
-    period: 'month',
-    features: ['100 requests', 'Basic support', '1 project'],
-    popular: false,
+    description: 'For individuals getting started.',
+    currency: '$',
+    monthlyPrice: '9',
+    yearlyPrice: '90',
+    buttonText: 'Choose Starter',
+    features: [
+      { name: '100 requests', icon: 'check' },
+      { name: 'Basic support', icon: 'check' },
+      { name: '1 project', icon: 'check' },
+    ],
   },
   {
     id: 'pro',
     title: 'Pro',
-    price: 29,
-    period: 'month',
-    features: ['Unlimited requests', 'Priority support', '10 projects'],
-    popular: true,
+    description: 'For teams running in production.',
+    currency: '$',
+    monthlyPrice: '29',
+    yearlyPrice: '290',
+    buttonText: 'Choose Pro',
+    badge: 'Most popular',
+    highlight: true,
+    features: [
+      { name: 'Unlimited requests', icon: 'check' },
+      { name: 'Priority support', icon: 'check' },
+      { name: '10 projects', icon: 'check' },
+    ],
   },
 ];
 ```
 
+The generated file is the contract for your installed version; if its `Plan` differs from the above, follow
+the file. `onPlanSelect` receives only the plan `id`, so the ids here are the slugs the server maps below.
+
+This example sells **monthly plans only**: `yearlyPrice` is required by the `Plan` type and is displayed,
+but the server map below has only monthly products. To sell yearly too, create the yearly products in Dodo,
+track the table's billing-period toggle in your own state (it is not passed to `onPlanSelect`), send it with
+the plan id, and key the server map by plan and period (for example `pro:yearly`).
+
 ### 2. Product id map — server only
 
 Never let the browser choose an arbitrary `product_id`. Map the public plan slug to a `pdt_` id on the
@@ -149,16 +182,16 @@ server and reject anything else.
 ```typescript
 // lib/plan-products.server.ts
 import 'server-only';
-import type { PlanId } from './plans';
 
-const PRODUCT_IDS: Record<PlanId, string> = {
+// Keys must match the `id`s in lib/billingsdk-config.ts.
+const PRODUCT_IDS: Readonly<Record<string, string>> = {
   starter: 'pdt_starter_monthly',
   pro: 'pdt_pro_monthly',
 };
 
 export function productIdForPlan(value: unknown): string | null {
-  if (typeof value !== 'string') return null;
-  return PRODUCT_IDS[value as PlanId] ?? null;
+  if (typeof value !== 'string' || !Object.hasOwn(PRODUCT_IDS, value)) return null;
+  return PRODUCT_IDS[value];
 }
 ```
 
@@ -220,7 +253,7 @@ integrations. Checkout parameters are covered in depth in the `checkout-integrat
 
 import { useState } from 'react';
 import { PricingTableOne } from '@/components/billingsdk/pricing-table-one';
-import { PLANS } from '@/lib/plans';
+import { plans } from '@/lib/billingsdk-config';
 
 export function PricingPlans() {
   const [error, setError] = useState<string | null>(null);
@@ -249,7 +282,7 @@ export function PricingPlans() {
   return (
     <>
       <PricingTableOne
-        plans={PLANS}
+        plans={plans}
         title="Choose your plan"
         description="Select the plan that works best for you"
         onPlanSelect={handlePlanSelect}
@@ -458,14 +491,14 @@ signature verification is covered in the `webhook-integration` skill.
 **Accepting a raw `product_id` from the request body.** A caller can then check out against any product in
 your catalogue, including internal or discounted ones. Map an opaque plan slug to a `pdt_` id server-side.
 
-**Hardcoding prices in the client.** `PLANS[].price` is display text. When you change a price in the Dodo
+**Hardcoding prices in the client.** `plans[].monthlyPrice` / `yearlyPrice` are display text. When you change a price in the Dodo
 dashboard, the checkout charges the new amount while the pricing page keeps advertising the old one.
-Reconcile `lib/plans.ts` with the dashboard as part of any pricing change.
+Reconcile `lib/billingsdk-config.ts` with the dashboard as part of any pricing change.
 
 **`npm install billingsdk`.** The root repository package is private. Install through
 `@billingsdk/cli` or the shadcn registry instead.
 
-**Guessing prop names.** `pricing-table-one` is the only block with a published prop example. Open the
+**Guessing prop names.** Check the block's page on billingsdk.com/docs/components, then open the
 generated file under `components/billingsdk/` and read the exported props type before wiring anything else.
 
 **Using `DODO_PAYMENTS_WEBHOOK_SECRET`.** The SDK reads `DODO_PAYMENTS_WEBHOOK_KEY` for the `webhookKey`

package/skills/checkout-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: checkout-integration
-description: Guide for starting hosted Checkout Sessions, payment links, and overlay or inline checkout for one-time and recurring products; use subscription-integration for post-checkout lifecycle management.
+description: Dodo Payments checkout via hosted Checkout Sessions (client.checkoutSessions.create), static payment links, and overlay or inline checkout for one-time and subscription products. Use when building a pay button, checkout page, trial signup, custom fields, discount codes at checkout, or return_url redirects; use subscription-integration for post-checkout lifecycle.
 ---
 
 # Dodo Payments Checkout Integration
@@ -38,7 +38,7 @@ Dodo Payments offers three ways to collect payment:
 
 **Checkout Session:** A single-use session that generates a hosted checkout URL. Expires after 24 hours (or 15 minutes if `confirm=true`).
 
-**Return URL:** Where the customer lands after payment. Query parameters include `status=success` and `session_id`.
+**Return URL:** Where the customer lands after payment. Dodo appends `payment_id` (one-time) or `subscription_id` (subscription), `status`, and when available `license_key` and `email`. It is a UI hint only, never proof of payment.
 
 **Entitlement on webhook:** The browser redirect is not the source of truth. Always verify payment via webhook before granting access. See `webhook-integration` skill for verification.
 
@@ -637,31 +637,27 @@ async function createCheckoutUrl(planId: PlanId, quantity = 1): Promise<string>
   return data.checkoutUrl;
 }
 
-export async function openOverlayCheckout(planId: PlanId): Promise<void> {
-  const checkoutUrl = await createCheckoutUrl(planId);
-
+// Call ONCE when the app loads (e.g. in your root component or entry point),
+// not before every checkout. Pick the display type your page uses.
+export function initCheckout(displayType: 'overlay' | 'inline'): void {
   DodoPayments.Initialize({
     mode: 'test', // or 'live'
-    displayType: 'overlay',
+    displayType,
     onEvent: (event) => {
       console.log('Checkout event:', event);
     }
   });
+}
 
+// Requires initCheckout('overlay') to have run at app load.
+export async function openOverlayCheckout(planId: PlanId): Promise<void> {
+  const checkoutUrl = await createCheckoutUrl(planId);
   DodoPayments.Checkout.open({ checkoutUrl });
 }
 
+// Requires initCheckout('inline') to have run at app load.
 export async function openInlineCheckout(planId: PlanId): Promise<void> {
   const checkoutUrl = await createCheckoutUrl(planId);
-
-  DodoPayments.Initialize({
-    mode: 'test', // or 'live'
-    displayType: 'inline',
-    onEvent: (event) => {
-      console.log('Checkout event:', event);
-    }
-  });
-
   DodoPayments.Checkout.open({
     checkoutUrl,
     elementId: 'dodo-inline-checkout'
@@ -685,6 +681,8 @@ No-code shareable links. No server-side API call needed.
 https://checkout.dodopayments.com/buy/{productid}
 ```
 
+In test mode the host is `test.checkout.dodopayments.com` (for example `https://test.checkout.dodopayments.com/buy/{productid}`); a test-mode product does not exist on the live host.
+
 Example:
 ```text
 https://checkout.dodopayments.com/buy/pdt_example
@@ -789,12 +787,20 @@ const session = await client.checkoutSessions.create({
 After payment, the customer is redirected to your `return_url` with query parameters:
 
 ```text
-https://yoursite.com/success?status=success&session_id=cks_123
+# One-time payment
+https://yoursite.com/success?payment_id=pay_xxx&status=succeeded&email=customer%40example.com
+
+# Subscription (with license keys)
+https://yoursite.com/success?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com
 ```
 
 Query parameters:
-- `status`: `success` or `failed`
-- `session_id`: Checkout session ID
+- `payment_id` (one-time payments) or `subscription_id` (subscriptions)
+- `status`: `succeeded` (one-time) or `active` (subscription) on success; `failed` if declined; `processing` (or a `requires_*` value) if it settles later; `expired` if the session expired
+- `license_key`: present when the product issues license keys (comma-separated if several)
+- `email`: present when the customer has an email on record
+
+There is no `session_id` parameter. Treat `processing`/missing status as "unknown" and wait for the webhook.
 
 ### Verify Payment Server-Side
 
@@ -818,8 +824,8 @@ Do not use `client.payments.create()` or `client.subscriptions.create()` for new
 **3. Forgetting the `environment` flag**
 The default is `live_mode`. Always set `environment: 'test_mode'` during development to avoid charging real cards.
 
-**4. Assuming only one discount-code form is valid**
-Both `discount_code` (a string) and `discount_codes` (an array) are valid Checkout Session parameters.
+**4. Using the deprecated `discount_code`**
+Use `discount_codes` (an array). The singular `discount_code` string is deprecated (still accepted for backward compatibility) and cannot be combined with `discount_codes` in the same request.
 
 **5. Amounts in wrong unit**
 All amounts are in the smallest currency unit (cents for USD). $10 is `1000`, not `10`.