vybekiit 0.7.28 → 0.7.29

package/dist/global-skills/vybekiitReferences/spa/platform-skills/mcp-tools-vybekiit.md

@@ -0,0 +1,87 @@
+# Platform wrapper: kit MCP tools
+
+**Agent-only.** Catalog of every first-party MCP tool VybeKiit ships. Read this file locally or load via MCP `get_skill` / `list_platform_skills` (`mcp-tools-vybekiit` / `use-kit-mcp`).
+
+Never name MCP, tool ids, or package paths to the builder. Prefer **search → get** (slim pages, then detail).
+
+## Server
+
+| Server key | Package | Bin | Purpose |
+|------------|---------|-----|---------|
+| `vybekiit` | `@vybekiit/agent-mcp` | `vybekiit-agent-mcp` | Skills, CLI catalog, doctor tools, doc-fallback, browser automations, mirrored UI catalog |
+
+Snippet: `.vybekiit/agent/mcp-agent.json`. Setup: `.vybekiit/agent/mcp-setup.md`.
+Auto-discovered skill: `.agents/skills/use-kit-mcp/SKILL.md`.
+
+## Env
+
+| Variable | Meaning |
+|----------|---------|
+| `VYBEKIIT_PROJECT_ROOT` | Project root for skill reads + automation cwd (default cwd) |
+| `VYBEKIIT_UI_CATALOG_PATH` | Path to `ui-catalog-index.json` |
+| `VYBEKIIT_AUTOMATE_BIN` | Optional absolute path to `vybekiit-automate` |
+
+## Context controls
+
+- Cursor pagination: `limit` / `cursor` / response `nextCursor` + `hasMore` + `total`
+- Prefer slim rows; request full detail only when needed (`fields=slim|full` on UI tools)
+- Automations: `run_automation({ dryRun: true })` before a real browser session
+
+## Tools
+
+| Tool | Description | Required | Optional | When to use |
+|------|-------------|----------|----------|-------------|
+| `search_skills` | Fuzzy-search buyer goals/skills (goal-index SSOT). Paginated slim rows. | query | template, limit, cursor | Before opening skill files; empty query lists all goals for the template. |
+| `get_skill` | Load one skill by goal id or stem (excerpt by default). | id | template, excerptLines | After search_skills picks a row; also loads use-kit-mcp / platform wrappers. |
+| `list_platform_skills` | List/search `.vybekiit/platform-skills/*` wrappers (paginated). | — | query, limit, cursor | Find provider wrappers (stripe, railway, mcp-tools-vybekiit, …). |
+| `search_commands` | Fuzzy-search vybekiit CLI verbs. Returns usage — run via shell, not MCP. | query | limit, cursor | Discover CLI verbs (doctor, create app, automate, …). |
+| `get_command` | Get one CLI command by exact name from the catalog. | name | — | After search_commands when you know the exact verb name. |
+| `search_doctor_tools` | List doctor toolchain entries (`vybekiit doctor --ensure <name>`). Does not run doctor. | query | limit, cursor | Before ensuring CLIs (gh, wrangler, supabase, …). |
+| `search_tech_ids` | Fuzzy-search known tech ids before doc_fallback. | query | limit, cursor | Pick a tech id for official docs after one failed MCP/debug attempt. |
+| `doc_fallback` | Official docs + env key hints. Never name MCP to the builder — use builderMessage. | techId | — | MCP or first debug failed once; same as `vybekiit doc-fallback <tech-id>`. |
+| `search_automations` | Fuzzy-search vybekiit-automate browser verbs (ls, cws, nc, …). Paginated. | query | limit, cursor | Before run_automation; empty query lists the catalog. |
+| `get_automation` | Get one automation by domain (+ command) or id (`ls:setup`). | domain | command | Inspect usage string for a known domain/verb. |
+| `run_automation` | Run vybekiit-automate from any project root (resolves bin). Always --json. Prefer dryRun first. Google redirect_uri_mismatch → domain=google command=oauth with --redirect incl. localhost. | domain, command | args, dryRun, yes, cdp, profile, timeoutMs | Execute browser automations anywhere; OAuth 400 redirect_uri_mismatch; dryRun=true to preview argv only. |
+| `search_ui_components` | Fuzzy-search mirrored UI components. Page envelope; default fields=slim. | query | source, limit, cursor, fields | Find blocks by intent/name; slim first, then get_ui_component. |
+| `get_ui_component` | Get one mirrored component by source namespace + slug. | source, name | — | Full detail after search_ui_components. |
+| `suggest_ui_blend` | Ranked multi-source component suggestions for a natural-language UI intent. | intent | limit | Builder wants a composed look (hero + pricing + marquee, …). |
+| `list_ui_sources` | List mirrored UI source namespaces and component counts. | — | — | See which registries are in the local catalog index. |
+
+## Browser automations (from any folder)
+
+```
+search_automations({ query: "lemon squeezy" })
+run_automation({ domain: "ls", command: "setup", dryRun: true })
+run_automation({ domain: "ls", command: "standby" })
+// Google Error 400 redirect_uri_mismatch / Auth.js localhost — args only, no Console babysitting:
+search_automations({ query: "redirect_uri_mismatch" })
+run_automation({ domain: "google", command: "oauth", args: [
+  "--project=my-app", "--app-name=MyApp", "--support-email=you@gmail.com",
+  "--app-url=https://example.com",
+  "--redirect=https://example.com/api/auth/callback/google",
+  "--redirect=http://localhost:3000/api/auth/callback/google",
+]})
+```
+
+Shell equivalent:
+
+```
+vybekiit-automate catalog --json
+vybekiit-automate ls standby --json --yes
+vybekiit-automate google oauth --project=... --app-name=... --support-email=... --app-url=... --redirect=... --json
+```
+
+## Wire-up (agents)
+
+1. `vybekiit setup` registers the `vybekiit` server once at Claude user scope and refreshes it on every rerun.
+2. Start a new Claude session after setup so Claude can approve and discover the global tools.
+3. Cursor receives project `.cursor/mcp.json` files because its setup path remains project-scoped.
+4. `create app` still ships `@vybekiit/agent-mcp` and `@vybekiit/browser-automation` under `packages/` for owned tooling and other MCP clients.
+5. Doctor may merge provider-specific third-party MCPs only when the project needs them.
+
+## Provider / third-party MCP snippets
+
+Not first-party tools — merge only when the builder uses that provider (see `mcp-setup.md`):
+`mcp-supabase`, `mcp-stripe`, `mcp-paypal`, `mcp-neon`, `mcp-firebase`, `mcp-mongodb`, `mcp-railway-*`, `mcp-twilio-*`, `mcp-sentry`, `mcp-posthog`.
+
+If any MCP fails once → `doc_fallback` / `vybekiit doc-fallback <tech-id>`; tell the builder only the plain stuck phrase.

package/dist/global-skills/vybekiitReferences/web/AGENTS.md

@@ -0,0 +1,153 @@
+# AGENTS.md — your build agent (read this first)
+
+> **You are talking to a non-technical vibe coder.** They can describe what they want
+> and follow simple steps, but they do **not** want to understand environment variables, deploys,
+> databases, or git. Your job is to make every technical decision and do the work — and translate
+> the few steps only they can do into plain, one-at-a-time instructions.
+>
+> This is the **single source of truth** for how you behave in this project. Codex reads this file
+> natively; `CLAUDE.md` (Claude Code) and `.cursor/rules/vybekiit.mdc` (Cursor) are thin pointers to
+> it; `.cursor/rules/patterns.mdc` summarizes code conventions (not SSOT). Supported assistants:
+> Claude Code · Codex · Cursor.
+
+<!-- vybekiit:generated:start contract -->
+## The contract: Decide + Guide
+
+A request such as "Can people book my classes?" means build the working feature. Inspect the connected provider and run `vybekiit list-presets` before saying the kit lacks the capability. Reuse the booking and organizations presets, add only app-specific behavior, and verify saved bookings and access rules. Read `.vybekiit/agent/session-bootstrap.md` for the persistence workflow. Continue ordinary authorized work without asking the buyer to reconfirm it.
+
+① **One action at a time** — Give the buyer one manual action at a time. Continue authorized work independently, checking each step until the requested work is complete or blocked. Requests to let people book, pay, or join a team mean implement that behavior; do not replace the requested feature with an easier alternative.
+② **Verify before advancing** — Confirm each step actually worked before moving on, so the vibe coder can't get silently stuck. Shared bookings, payments, and team access need real saved information; a preview does not complete them.
+③ **Plain language** — Translate every technical term using language.md — the vibe coder never has to understand or decide.
+④ **Translate errors** — Turn any failure into "what happened + the one thing to do about it" — never paste a raw stack trace.
+⑤ **Celebrate progress** — Celebrate only verified progress. State whether it works locally, in practice, or online.
+⑥ **Record decisions** — After every completing skill, append one entry to checklist.md Decision log via formatChecklistEntry().
+⑦ **Official source fallback** — If MCP or the first debug attempt fails once, run vybekiit doc-fallback and tell the vibe coder the plain stuck phrase only.
+<!-- vybekiit:generated:end contract -->
+
+## How to work
+
+Simple questions need brief answers, without setup or skill searches. Inspect before making
+project-specific claims. Requests for work mean do the work and verify the requested behavior.
+Reuse instructions already loaded in the conversation. Continue authorized work independently;
+one action at a time limits steps the buyer must take. Prefer this project's skills over global
+copies. Do not use helper agents for simple exchanges.
+
+1. **Find the goal.** Buyer goal skills in `.agents/skills/` (also via `.cursor/skills/` and
+   `.claude/skills/`) load automatically from their descriptions — use the matching skill when the
+   vibe coder's intent fits. If nothing fits or you're unsure, fall back to `.vybekiit/agent/goal-index.md`
+   and read the skill in `.vybekiit/skills/`. Also check `.vybekiit/extensions/goal-index.md` when present.
+   Routine edits need no new skill. Consult `platform-skills/extend-capabilities-vybekiit.md`
+   only for a real uncovered integration.
+2. **One action at a time.** Do a step, then **verify it worked before moving on** (the skills call
+   this *verify-before-advance* — it's what stops a vibe coder getting silently stuck and asking for
+   a refund).
+3. **Translate every error** into "what happened + the one thing to do about it." Never paste a raw
+   stack trace at the vibe coder.
+4. **Celebrate progress.** Celebrate verified behavior and say whether it works locally, in practice, or online.
+5. **Write tests as you build features** and keep them green — that green suite is the vibe coder's
+   safety net and the reason updates are safe to apply.
+
+## Planning before big builds
+
+When the vibe coder asks for something **large or vague** (a whole product shape, "like X but for Y",
+many features at once) and you have not planned together this session:
+
+1. **Offer once** (never force): *"Want to think it through together first? I'll ask one question at
+   a time until we're totally aligned."*
+2. If they **accept** → follow `skills/plan-my-idea.md`.
+3. If they **decline** → build anyway. Impatient vibe coders stay in control.
+
+During onboarding, preserve the requested goal. Ask about planning only if a missing product decision blocks the work or the builder asks to plan.
+
+## What you may decide without asking
+
+Generic coding, design tweaks, data shapes, file structure, and which kit package to use. These
+are **not** skills — just do them well, following the conventions below.
+
+## Conventions (so the code stays clean and updatable)
+
+- The kit's logic lives in `@vybekiit/*` packages (payments, accounts, data). **Use them — don't
+  reinvent them.** They update separately; the vibe coder's customizations stay in this repo.
+- All secret settings live in **one** file: `.env` (documented by `.env.example`). One source of
+  truth. **Never read `.env` values aloud or paste them in chat** — reference keys from
+  `.env.example` only. If the vibe coder pastes a secret in chat, warn them and have them paste into
+  `.env` on their machine instead. Read `env-secrets-vybekiit.md`.
+- Keep components small and readable. Use the kit's UI primitives in `src/components`.
+- Layout uses logical spacing (`ms-`, `me-`, `ps-`, `pe-`, `start-`, `end-`) so the app mirrors
+  automatically for Hebrew/Arabic visitors. Never hard-code `left`/`right`.
+- **All user-facing copy** lives in `messages/en.json` and is rendered via `t('flat.dotted.key')`
+  — never inline strings in JSX. New UI = new keys in the same PR. See `i18n-vybekiit.md`.
+
+### Before you write code (invisible quality — vibe coder never hears this)
+
+1. **Check before create** — search `src/lib/README.md` and `@vybekiit/*` before adding a helper; extend existing code if ≥80% overlap.
+2. **One home per concern** — auth → `auth-client.ts`, billing → `billing-client.ts`, logging → `logger.ts`. Never add a second `utils-*.ts`.
+3. **Use the kit logger** — `import { log } from '@/lib/logger'`; never `console.log` in app/API code (tests may use console).
+4. **KISS** — no one-off wrappers around kit packages; validate API bodies with zod at the route boundary.
+5. **SSOT** — secrets in `.env` only; business constants in one file per domain (e.g. `plans.ts`).
+6. **Test as you build** — add/update tests with every feature; `pnpm test` green before saying done.
+7. **Format + lint silently** — run `pnpm format && pnpm lint` after substantive edits.
+8. **Use kit hooks** — `useAsync` / `useUser` / `useToast` / `FormField`; read `src/hooks/README.md`.
+9. **Keep functions small** (~5 lines) and props few (~5); split rather than grow.
+10. **Mobile-first web** — narrow layout first, then `md:`/`lg:`; preview at phone width (375px).
+
+Read `.vybekiit/platform-skills/code-hygiene-vybekiit.md`, `observability-vybekiit.md`, `testing-vybekiit.md`, `format-lint-vybekiit.md`, `react-patterns-vybekiit.md`, `responsive-vybekiit.md`, `env-secrets-vybekiit.md`, and `planning-vybekiit.md` (when running `plan-my-idea`) for details.
+
+### UI (professional & symmetric — you choose the source)
+
+- Pick blocks from `.vybekiit/agent/ui-sources.md` (shadcn, Magic UI, Kokonut, 21st.dev, etc.) — the vibe coder never chooses.
+- **Always normalize** imports to `src/components/ui/*` and `@vybekiit/tokens` — matching button sizes, token colors, symmetric spacing.
+- Locked button/input sizes: `sm | default | lg | icon` only. No raw `<button>` for standard controls.
+- Read `.vybekiit/platform-skills/ui-consistency-vybekiit.md` before adding marketing or dashboard UI.
+
+## Wire-up markers (how "finish setup" works)
+
+Some files ship as **ready layouts with the logic stubbed**, so the app builds and looks finished
+before any keys exist (the sign-in, sign-up, verify, pricing, and dashboard screens are like this).
+Every unfinished point carries one greppable marker:
+
+```
+TODO(vybekiit): <what to do> — skill: <skill-name>
+```
+
+When the vibe coder says "set it up", "finish setup", "wire it up", or "make it work", list every
+marker and resolve them one at a time:
+
+```
+grep -rn "TODO(vybekiit)" .
+```
+
+Each marker names the skill that completes it (e.g. `add-signin`, `setup-payments`). Run that skill,
+replace the stub, verify, then re-grep — you're done when it comes back empty. The stubs are
+centralized so a skill edits **one** file, not every screen: sign-in lives in
+`src/lib/auth-client.ts`, checkout in `src/lib/billing-client.ts`. Never show the vibe coder a marker or
+the word "stub" — just do the work and tell them what now works.
+
+## Wire-up markers (how "finish setup" works)
+
+Some files ship as **ready layouts with the logic stubbed**, so the app builds and looks finished
+before any keys exist (the sign-in, sign-up, verify, pricing, and dashboard screens are like this).
+Every unfinished point carries one greppable marker:
+
+```
+TODO(vybekiit): <what to do> — skill: <skill-name>
+```
+
+When the vibe coder says "set it up", "finish setup", "wire it up", or "make it work", list every
+marker and resolve them one at a time:
+
+```
+grep -rn "TODO(vybekiit)" .
+```
+
+Each marker names the skill that completes it (e.g. `add-signin`, `setup-payments`). Run that skill,
+replace the stub, verify, then re-grep — you're done when it comes back empty. The stubs are
+centralized so a skill edits **one** file, not every screen: sign-in lives in
+`src/lib/auth-client.ts`, checkout in `src/lib/billing-client.ts`. Never show the vibe coder a marker or
+the word "stub" — just do the work and tell them what now works.
+
+## Boundaries
+
+- You fix and extend **this app**. You don't promise things the kit doesn't do.
+- If the vibe coder asks for something genuinely outside the kit, say so plainly and offer the closest
+  thing the kit supports.

package/dist/global-skills/vybekiitReferences/web/agent/goal-index.md

@@ -0,0 +1,54 @@
+# Goal index — route the builder's request to a skill
+
+The builder speaks in goals, not commands. Match what they say to a skill below and follow it
+exactly. When in doubt between two, pick `onboarding` (it routes onward). Every skill follows the
+shared rules in `AGENTS.md`: one action at a time · verify-before-advance · plain language ·
+translate errors · celebrate.
+
+| The builder says something like… | Use this skill |
+|---|---|
+| "set up my app", "I just bought this", "let's start", "get me going" | `skills/onboarding.md` |
+| "help me plan", "I'm not sure what I want", "think it through with me", "figure out my idea first" | `skills/plan-my-idea.md` |
+| big vague feature ("build me a marketplace", "I want something like Airbnb") before specifics | `skills/plan-my-idea.md` |
+| "add payments", "let me take money", "sell something", "charge people" | `skills/setup-payments.md` |
+| "put it online", "publish", "make it live", "ship it", "deploy" | `skills/go-live.md` |
+| "let people sign in / log in / create accounts / add users" | `skills/add-signin.md` |
+| "I forgot my password", "reset my password" | `skills/reset-password.md` |
+| "email me a link", "sign in without a password" | `skills/sign-in-with-email-link.md` |
+| "sign in with my phone", "text me a code" | `skills/sign-in-with-phone.md` |
+| "set up text messages", "Twilio", "WhatsApp" | `skills/setup-sms.md` |
+| "save my data", "remember this", "store info", "add a database" | `skills/save-data.md` |
+| "what should my app remember", "design my database", "what data do I need", "map my features to data" | `skills/design-my-data.md` |
+| "let users upload", "store files / images / attachments" | `skills/add-files.md` |
+| "add my logo", "hero image", "app icon", "add images", "put my picture" | `skills/add-images.md` |
+| "send emails", "email my users", "set up email" | `skills/setup-email.md` |
+| "invite teammates", "add my team", "work with others", "organizations" | `skills/add-teams.md` |
+| "notify users", "send alerts", "email when something happens" | `skills/add-notifications.md` |
+| "see who uses my app", "visitor stats", "analytics", "track usage" | `skills/add-analytics.md` |
+| "add AI", "smart replies", "chatbot", "AI helper" | `skills/add-ai.md` |
+| "let users search", "find things", "search my data" | `skills/add-search.md` |
+| "live updates", "real-time", "push changes instantly", "refresh without reload" | `skills/add-realtime.md` |
+| "add a blog", "changelog", "write articles on my site" | `skills/add-blog.md` |
+| "AI search", "ChatGPT find my site", "get quoted by Perplexity", "llms.txt", "answer engines" | `skills/add-blog.md` (content + GEO) or `skills/go-live.md` (verify `/llms.txt` live) |
+| "get a domain", "buy a web address", "use my own URL" | `skills/buy-domain.md` |
+| "update the kit", "get the latest", "upgrade" | `skills/update-kit.md` |
+| "it's broken", "nothing works", "I get an error", "check my app" | `skills/doctor.md` |
+| "send feedback", "report a kit bug", "the kit is confusing" | `skills/vybekiit-feedback.md` |
+| "lock down my app", "make it safe", "protect from abuse" | `skills/harden.md` |
+| "sign in with Google", "sign up with Google", "Continue with Google" | `skills/sign-in-with-google.md` |
+| "am I ready to ship", "did we cover security", "is my app safe" | `skills/check-safety.md` |
+| "tell me when things break", "error alerts", "know if my app crashes" | `skills/track-errors.md` |
+| "save my code", "back up my project", "put it on GitHub" | `skills/back-up-my-code.md` |
+| "make it Hebrew", "translate my app", "add Spanish", "speak my language" | `skills/add-language.md` |
+| "set it up", "finish setup", "wire it up", "make it work" | grep `TODO(vybekiit)`, then run each named skill — see `AGENTS.md` → *Wire-up markers* |
+
+Anything else (change the design, add a page, tweak text, general coding) is **not** a skill — just
+do it well per `AGENTS.md`, then offer the next relevant goal above.
+
+> The sign-in, save-data, file-upload, email, domain, and update-the-kit goals are now shipping (no
+> longer "coming soon") — each routes to its skill above. Each one routes to the right service under
+> the hood; never name the service to the builder (see `language.md`).
+
+<!-- vybekiit:generated:start goal-index-validation -->
+<!-- Goal drift: run `vybekiit check-goals` — non-zero exit means fix goal-index or add skills -->
+<!-- vybekiit:generated:end goal-index-validation -->

package/dist/global-skills/vybekiitReferences/web/agent/mcp-agent.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "vybekiit": {
+      "command": "node",
+      "args": [
+        "../../packages/agentMcp/dist/bin.js"
+      ],
+      "env": {
+        "VYBEKIIT_PROJECT_ROOT": ".",
+        "VYBEKIIT_UI_CATALOG_PATH": ".vybekiit/agent/ui-catalog-index.json"
+      }
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-firebase.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "firebase": {
+      "command": "npx",
+      "args": ["-y", "firebase-tools@latest", "mcp"]
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-mongodb.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "mongodb": {
+      "command": "npx",
+      "args": ["-y", "mongodb-mcp-server@latest"],
+      "env": {
+        "MDB_MCP_CONNECTION_STRING": "",
+        "MDB_MCP_READ_ONLY": "true"
+      }
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-neon.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "neon": {
+      "url": "https://mcp.neon.tech/mcp?readonly=true",
+      "headers": {}
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-paypal.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "paypal": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.sandbox.paypal.com/http"]
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-posthog.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "posthog": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "https://mcp.posthog.com/mcp",
+        "--header",
+        "Authorization:${POSTHOG_AUTH_HEADER}"
+      ],
+      "env": {
+        "POSTHOG_AUTH_HEADER": "Bearer ${POSTHOG_API_KEY}"
+      }
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-railway-local.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "railway": {
+      "command": "railway",
+      "args": ["mcp"]
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-railway-remote.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "railway": {
+      "url": "https://mcp.railway.com"
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-sentry.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "sentry": {
+      "url": "https://mcp.sentry.dev/mcp"
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-setup.md

@@ -0,0 +1,165 @@
+# MCP setup — Cursor, Claude Desktop, Codex (agent-only)
+
+Merge provider snippets from `.vybekiit/agent/mcp-*.json` into the buyer's AI client config. **Preserve existing servers** — never replace the whole file.
+
+## Cursor
+
+**Config:** project `.cursor/mcp.json` or global `~/.cursor/mcp.json`
+
+1. Open the config file (create with `{ "mcpServers": {} }` if missing).
+2. Merge each needed fragment's `mcpServers` block into the top-level `mcpServers` object.
+3. Restart Cursor or open **Settings → Tools & MCP** and confirm each server is connected.
+
+## Claude Desktop
+
+**Config (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Same JSON shape as Cursor — merge `mcpServers` entries from the snippets below. Restart Claude Desktop after saving.
+
+## Codex
+
+**Config:** `~/.codex/config.toml` or project `.codex/config.toml` (trusted projects only)
+
+Use `codex mcp add` interactively, or add TOML tables manually:
+
+### HTTP MCP (Stripe, Supabase, Neon)
+
+```toml
+[mcp_servers.stripe]
+url = "https://mcp.stripe.com"
+
+[mcp_servers.supabase]
+url = "https://mcp.supabase.com/mcp"
+
+[mcp_servers.neon]
+url = "https://mcp.neon.tech/mcp?readonly=true"
+```
+
+### Stdio bridge (PayPal remote)
+
+PayPal uses `mcp-remote` because the hosted server requires streamable HTTP via a local bridge:
+
+```toml
+[mcp_servers.paypal]
+command = "npx"
+args = ["-y", "mcp-remote", "https://mcp.sandbox.paypal.com/http"]
+```
+
+Production PayPal: replace sandbox URL with `https://mcp.paypal.com/http`.
+
+### Stdio (Firebase, MongoDB)
+
+```toml
+[mcp_servers.firebase]
+command = "npx"
+args = ["-y", "firebase-tools@latest", "mcp"]
+
+[mcp_servers.mongodb]
+command = "npx"
+args = ["-y", "mongodb-mcp-server@latest"]
+
+[mcp_servers.mongodb.env]
+MDB_MCP_CONNECTION_STRING = "<copy from MONGODB_URI in .env>"
+MDB_MCP_READ_ONLY = "true"
+```
+
+Restart Codex after changes. Run `/mcp` in a session to verify tools are listed.
+
+## VybeKiit first-party MCPs
+
+## Agent skill (read locally or via MCP)
+
+- Auto-discovered: `.agents/skills/use-kit-mcp/SKILL.md`
+- Platform wrapper: `.vybekiit/platform-skills/mcp-tools-vybekiit.md`
+- Via MCP (when `vybekiit` server is connected): `search_skills({ query: "mcp tools" })` then `get_skill({ id: "use-kit-mcp" })` or `list_platform_skills({ query: "mcp" })`
+
+
+
+After `pnpm build` in the monorepo (or a workspace that includes these packages):
+
+| Server | Tools | Context controls |
+|--------|-------|------------------|
+| `vybekiit` (`mcp-agent.json`) | `search_skills`, `get_skill`, `list_platform_skills`, `search_commands`, `get_command`, `search_doctor_tools`, `search_tech_ids`, `doc_fallback`, `search_automations`, `get_automation`, `run_automation`, `search_ui_components`, `get_ui_component`, `suggest_ui_blend`, `list_ui_sources` | Cursor pagination (`limit`/`cursor`/`nextCursor`), slim rows, fuzzy rank; UI tools take `fields=slim\|full` (default slim) |
+
+Env:
+
+- `VYBEKIIT_PROJECT_ROOT` — project root for skill file reads + automation cwd (default `cwd`)
+- `VYBEKIIT_UI_CATALOG_PATH` — path to `ui-catalog-index.json`
+- `VYBEKIIT_AUTOMATE_BIN` — optional absolute path to `vybekiit-automate` (otherwise package bin / monorepo dist / PATH)
+
+Prefer **search → get** (list slim, then detail) so tool responses stay small.
+
+### Browser automations (from any folder)
+
+```
+search_automations({ query: "lemon squeezy" })
+run_automation({ domain: "ls", command: "setup", dryRun: true })   # preview argv
+run_automation({ domain: "ls", command: "standby" })                # real browser
+```
+
+Shell equivalent (anywhere the monorepo or package is installed):
+
+```
+vybekiit-automate catalog --json
+vybekiit-automate ls setup --json --yes --name=Kit --price-cents=2900 --mode=test --webhook-url=…
+```
+
+`run_automation` resolves the bin automatically (env → package → monorepo dist → PATH) and runs with `cwd=VYBEKIIT_PROJECT_ROOT`.
+
+## Provider snippets (merge one or more)
+
+| When | File | Upstream docs |
+|------|------|---------------|
+| VybeKiit agent surface (skills, CLI, doctor, doc-fallback) | `mcp-agent.json` | Local `@vybekiit/agent-mcp` — always merge first |
+| Default data (`DATA_PROVIDER=supabase`) | `mcp-supabase.json` | https://supabase.com/docs/guides/ai-tools/mcp |
+| Stripe payments | `mcp-stripe.json` | https://docs.stripe.com/mcp |
+| PayPal payments | `mcp-paypal.json` | https://docs.paypal.ai/developer/tools/ai/mcp-quickstart |
+| Neon data | `mcp-neon.json` | https://neon.tech/docs/ai/neon-mcp-server |
+| Firebase data | `mcp-firebase.json` | Firebase MCP via `firebase-tools mcp` |
+| Twilio SMS / Verify | `mcp-twilio-docs.json` | https://mcp.twilio.com/docs |
+| Twilio API (optional alpha) | `mcp-twilio-alpha.json` | `@twilio-alpha/mcp` stdio bridge |
+| Sentry error alerts | `mcp-sentry.json` | https://mcp.sentry.dev/mcp |
+| PostHog analytics / flags | `mcp-posthog.json` | https://mcp.posthog.com/mcp |
+| Advanced data (`DATA_PROVIDER=mongodb`, **agent/maintainer only**) | `mcp-mongodb.json` | https://www.mongodb.com/docs/mcp-server/get-started/ |
+| Railway stack (`HOSTING_PROVIDER=railway` and/or `DATA_PROVIDER=railway`) | `mcp-railway-local.json` | https://docs.railway.com/ai/mcp-server |
+| Railway remote MCP (OAuth, no local CLI state) | `mcp-railway-remote.json` | https://docs.railway.com/ai/mcp-server |
+
+**Railway MCP — when to use which**
+
+- **Local** (`mcp-railway-local.json`): repo-linked deploys, `railway up`, variables, logs — shares CLI login. Preferred when `railway` is installed and authed (doctor runs `railway setup agent -y`).
+- **Remote** (`mcp-railway-remote.json`): OAuth at `mcp.railway.com` — project/service discovery, redeploys, `railway-agent` for multi-step ops. Use when local CLI context is unavailable.
+
+### MCP failure → official docs
+
+If an MCP server fails to connect or a tool call errors **once**, do not retry blindly:
+
+1. Run `vybekiit doc-fallback <tech-id>` (e.g. `twilio`, `supabase`, `stripe`).
+2. Follow the returned official URLs and env key hints.
+3. Tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."* Never say MCP, stack trace, or provider jargon aloud.
+
+See `.vybekiit/agent/tech-references.md` for the full id → docs map.
+
+### Supabase optional query params
+
+Append to the URL for tighter scope (recommended for real data):
+
+- `?project_ref=<ref>` — limit to one project
+- `?read_only=true` — Postgres read-only user
+- Combined: `https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true`
+
+OAuth login happens on first use — no PAT required for interactive clients.
+
+### PayPal OAuth
+
+First tool call opens PayPal login in the browser. Use sandbox endpoint until checkout is verified, then switch to production URL in config.
+
+## Advanced (CI / local only)
+
+- **PayPal local:** `npx -y @paypal/mcp --tools=all` with `PAYPAL_ACCESS_TOKEN` — see PayPal MCP quickstart
+- **Supabase CI:** PAT in `Authorization` header — see Supabase MCP security docs
+
+Never connect MCP to production buyer data without `read_only=true` or a dev branch.
+
+### MongoDB (agent/maintainer only)
+
+When `.env` has `DATA_PROVIDER=mongodb`, merge `mcp-mongodb.json` and copy `MONGODB_URI` into `MDB_MCP_CONNECTION_STRING`. Keep `MDB_MCP_READ_ONLY=true` unless a maintainer explicitly needs write tools. Buyers never see provider names — see `BUILDER-VOICE.md`.

package/dist/global-skills/vybekiitReferences/web/agent/mcp-stripe.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "stripe": {
+      "url": "https://mcp.stripe.com"
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-supabase.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "supabase": {
+      "url": "https://mcp.supabase.com/mcp"
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-twilio-alpha.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "twilio-alpha": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@twilio-alpha/mcp",
+        "--services",
+        "api_v2010,messaging_v1,verify_v2"
+      ]
+    }
+  }
+}

package/dist/global-skills/vybekiitReferences/web/agent/mcp-twilio-docs.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "twilio-docs": {
+      "url": "https://mcp.twilio.com/docs"
+    }
+  }
+}