[plugin] build updated openai package with deployment card guidance

.github/workflows/ci.yml

@@ -36,3 +36,13 @@ jobs:
 
       - name: Test
         run: bun test
+
+      - name: Build OpenAI submission
+        run: bun run build:openai
+
+      - name: Upload OpenAI submission
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: vercel-openai
+          path: dist/openai/vercel-*.zip
+          if-no-files-found: error

CLAUDE.md

@@ -13,6 +13,7 @@
 - **Doctor**: `bun run doctor` (self-diagnosis: skill validation, hook timeouts, dedup health)
 - **Update snapshots**: `bun test:update-snapshots` (regenerate golden snapshot baselines)
 - **Playground**: `bun run playground:generate` (generate static skill files for external tools)
+- **Build OpenAI package**: `bun run build:openai` (generates `dist/openai/vercel/` and the submission ZIP; see [OpenAI Package](#openai-package-openai))
 
 Run `bun run build:hooks` after editing any `.mts` file. A pre-commit hook auto-compiles when `.mts` files are staged.
 
@@ -156,6 +157,32 @@ Heading extraction is case-insensitive and captures everything from the heading
 
 **Current templates** (7): `agents/ai-architect.md.tmpl`, `agents/deployment-expert.md.tmpl`, `agents/performance-optimizer.md.tmpl`, `commands/bootstrap.md.tmpl`, `commands/deploy.md.tmpl`, `commands/env.md.tmpl`, `commands/status.md.tmpl`.
 
+### OpenAI Package (`openai/`)
+
+`bun run build:openai` (`scripts/build-openai.ts`) generates the OpenAI/Codex plugin and its submission ZIP in `dist/openai/` from `skills/`, `agents/`, `commands/`, and `vercel.md`. CI runs it after the tests, so a skill change can fail CI here.
+
+**Every new skill needs display metadata.** Add an entry for `skills/<name>/` under `skillInterfaces` in `openai/config.json`, or list the skill in `excludedSkills`. The build fails without one. Rules (from Codex's `openai.yaml` reference):
+
+- `display_name`: the product name as Vercel writes it (`Vercel CLI`, `AI SDK`), at most 64 characters
+- `short_description`: a complete 25–64 character blurb. The build rejects longer or `...`-truncated values; it never truncates
+- `default_prompt` (optional): must mention the skill as `$<name>`
+
+An entry may land before its skill; it is ignored until `skills/<name>/SKILL.md` exists.
+
+**Refreshing `openai/content.patch`.** The patch holds OpenAI-only edits to skills, templates, and `vercel.md`, applied to the staged copy during the build. Source files are never changed. When the build fails with `patch does not apply`, an upstream edit touched a patched section. Regenerate the patch from the current sources:
+
+```bash
+tmp=$(mktemp -d)
+cp -R skills agents commands vercel.md "$tmp"/
+git -C "$tmp" init -q && git -C "$tmp" add -A
+git -C "$tmp" apply --reject "$PWD/openai/content.patch"  # applies what it can; writes <file>.rej for the rest
+# In $tmp, apply each .rej hunk by hand on top of the upstream change, then delete the .rej files
+git -C "$tmp" diff -U2 > openai/content.patch
+bun run build:openai && bun test tests/build-openai.test.ts
+```
+
+Use the same steps to change an adaptation: apply the patch in `$tmp`, edit the files there, and regenerate. Check that the patched text still matches the upstream change (for example, current CLI syntax).
+
 ## Testing
 
 42 test files across `tests/`. Key categories:

openai/README.md

@@ -0,0 +1,48 @@
+# vercel
+
+This package is generated from [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin) version `{{version}}` for the OpenAI plugin directory.
+
+## What is included
+
+- `skills/`: {{skills}} current skills, including their reference files and Codex display metadata
+- `.mcp.json`: the Vercel MCP server at `https://mcp.vercel.com`
+- `vercel.md`: the Vercel ecosystem reference graph
+- `agents/` and `commands/`: upstream workflow reference content
+- Plugin icons and assets
+
+## OpenAI packaging
+
+The package version is `{{version}}`, matching the upstream source version.
+
+The package uses `.codex-plugin/plugin.json` with the local plugin id `vercel`. Skills are discovered from their `SKILL.md` name, description, and retrieval metadata. The upstream hook runtime is not included.
+
+The runtime skills and supporting references follow upstream, with OpenAI packaging and safety guidance retained. Source-only `overlay.yaml` files and `upstream/` copies are excluded so each skill has one discoverable definition.
+
+The Eve skill uses installed documentation when available and public documentation otherwise. Installing dependencies or scaffolding an Eve project must be part of the user's requested setup.
+
+Deployment examples keep CI credentials away from untrusted PR code and scope protected browser-test authentication to the verified deployment origin. Next.js framework guidance comes from version-matched Next.js documentation and the official Next.js workflow skills instead of bundled Next.js skills.
+
+The Vercel connection is declared as an MCP server rather than an app reference. Connect and authenticate with Vercel through the host's MCP setup before using its tools. MCP supports both reads and writes within your granted permissions. For build output, use `get_deployment_build_logs` or `list_deployment_events`, whichever the connection exposes; `open_deployments` shows a live deployment card when the connection enables it. Digital subscriptions, credits, and add-on purchases are unavailable through MCP; domain registration requires a quote and explicit approval.
+
+## Usage
+
+After installing the plugin, invoke a skill such as `ai-sdk`, `build-agents`, or `deployments-cicd`, or describe the task so the host can choose the relevant skill. The `agents/` and `commands/` files preserve upstream workflows as reference material; they do not register separate Codex agents or slash commands.
+
+## Package layout
+
+```text
+vercel/
+├── .codex-plugin/plugin.json
+├── .mcp.json
+├── skills/
+├── vercel.md
+├── agents/
+├── commands/
+└── assets/
+```
+
+Run `bun run build:openai` in the source repository to generate this package and its submission ZIP. The build includes dotfiles and omits hooks, app manifests, authoring files, and any skills excluded in `openai/config.json`.
+
+## Reporting issues
+
+Report content and OpenAI packaging issues in [vercel/vercel-plugin](https://github.com/vercel/vercel-plugin/issues).

openai/config.json

@@ -0,0 +1,154 @@
+{
+  "excludedSkills": [],
+  "skillInterfaces": {
+    "access-protected-vercel-deployment": {
+      "display_name": "Protected Deployment Access",
+      "short_description": "Reach and test deployments behind Deployment Protection"
+    },
+    "ai-gateway": {
+      "display_name": "AI Gateway",
+      "short_description": "Set up, route, and monitor models with AI Gateway"
+    },
+    "ai-sdk": {
+      "display_name": "AI SDK",
+      "short_description": "Build AI features and agents with the AI SDK"
+    },
+    "auth": {
+      "display_name": "Authentication",
+      "short_description": "Add user auth with Clerk, Better Auth, Auth0, or Descope"
+    },
+    "bootstrap": {
+      "display_name": "Project Bootstrap",
+      "short_description": "Set up repos with Vercel-linked resources in a safe order"
+    },
+    "build-agents": {
+      "display_name": "Build Agents",
+      "short_description": "Plan and build AI agents and agent apps"
+    },
+    "cdn-caching": {
+      "display_name": "CDN Caching",
+      "short_description": "Debug Vercel CDN cache hits, stale content, and ISR"
+    },
+    "chat-sdk": {
+      "display_name": "Chat SDK",
+      "short_description": "Build multi-platform chat bots with Chat SDK"
+    },
+    "create-a-backend": {
+      "display_name": "Vercel Backends",
+      "short_description": "Choose the right Vercel backend products",
+      "default_prompt": "Use $create-a-backend to plan and build a backend on Vercel."
+    },
+    "custom-metrics": {
+      "display_name": "Custom Metrics",
+      "short_description": "Emit and query custom metrics from Vercel Functions"
+    },
+    "daemons": {
+      "display_name": "Vercel Daemons",
+      "short_description": "Run long-running background workers on Vercel"
+    },
+    "deployments-cicd": {
+      "display_name": "Deployments & CI/CD",
+      "short_description": "Show live deployments and build logs; manage CI/CD"
+    },
+    "domains": {
+      "display_name": "Domains & DNS",
+      "short_description": "Search, register, and configure domains and DNS"
+    },
+    "env-vars": {
+      "display_name": "Environment Variables",
+      "short_description": "Manage Vercel environment variables and .env files"
+    },
+    "eve": {
+      "display_name": "eve",
+      "short_description": "Build durable AI agents with the eve framework"
+    },
+    "flags-sdk": {
+      "display_name": "Flags SDK",
+      "short_description": "Add feature flags in code with the Flags SDK"
+    },
+    "is-agentic": {
+      "display_name": "Is Agentic",
+      "short_description": "Score a site's readiness for AI agents"
+    },
+    "knowledge-update": {
+      "display_name": "Vercel Knowledge Update",
+      "short_description": "Corrects outdated LLM knowledge about the Vercel platform"
+    },
+    "marketplace": {
+      "display_name": "Vercel Marketplace",
+      "short_description": "Find, install, and manage Marketplace integrations"
+    },
+    "microfrontends": {
+      "display_name": "Microfrontends",
+      "short_description": "Split one app across Vercel projects with microfrontends"
+    },
+    "offload-to-sandbox": {
+      "display_name": "Offload to Sandbox",
+      "short_description": "Run heavy builds and test suites in Vercel Sandboxes"
+    },
+    "queues": {
+      "display_name": "Vercel Queues",
+      "short_description": "Defer and fan out background work with Vercel Queues"
+    },
+    "react-best-practices": {
+      "display_name": "React Best Practices",
+      "short_description": "Review TSX components against React best practices"
+    },
+    "routing-middleware": {
+      "display_name": "Routing Middleware",
+      "short_description": "Rewrite, redirect, and personalize requests before cache"
+    },
+    "runtime-cache": {
+      "display_name": "Runtime Cache",
+      "short_description": "Cache data per region with tag-based invalidation"
+    },
+    "vercel-agent": {
+      "display_name": "Vercel Agent",
+      "short_description": "Use Vercel Agent for code review and investigations"
+    },
+    "vercel-cli": {
+      "display_name": "Vercel CLI",
+      "short_description": "Deploy, debug, and manage Vercel from the command line"
+    },
+    "vercel-connect": {
+      "display_name": "Vercel Connect",
+      "short_description": "Get scoped third-party credentials for apps and users"
+    },
+    "vercel-firewall": {
+      "display_name": "Vercel Firewall",
+      "short_description": "Configure WAF rules, rate limits, and bot protection"
+    },
+    "vercel-flags": {
+      "display_name": "Vercel Flags",
+      "short_description": "Plan flags, rollouts, and experiments with Vercel Flags"
+    },
+    "vercel-functions": {
+      "display_name": "Vercel Functions",
+      "short_description": "Configure, debug, and optimize Vercel Functions"
+    },
+    "vercel-sandbox": {
+      "display_name": "Vercel Sandbox",
+      "short_description": "Run untrusted code in isolated Vercel Sandbox microVMs"
+    },
+    "vercel-services": {
+      "display_name": "Vercel Services",
+      "short_description": "Deploy multiple services in one Vercel project"
+    },
+    "vercel-storage": {
+      "display_name": "Vercel Storage",
+      "short_description": "Use Vercel Blob, Global Config, and Marketplace storage"
+    },
+    "vercel-tracing": {
+      "display_name": "Vercel Tracing",
+      "short_description": "Instrument and query OpenTelemetry traces on Vercel"
+    },
+    "verification": {
+      "display_name": "End-to-End Verification",
+      "short_description": "Verify the full flow: browser, API, data, and response"
+    },
+    "workflow": {
+      "display_name": "Workflow SDK",
+      "short_description": "Build durable, resumable workflows with Workflow SDK"
+    }
+  }
+}