vybekiit 0.7.27 → 0.7.29

package/dist/global-skills/vybekiitReferences/backend/platform-skills/extend-capabilities-vybekiit.md

@@ -0,0 +1,127 @@
+# Platform wrapper: extend-capabilities (agent-only)
+
+**Agent-only.** Invoked silently when no `goal-index.md` row and no platform wrapper covers the builder's request. The builder never hears "skill gap" or "extension."
+
+## When to run
+
+1. Read `.vybekiit/agent/goal-index.md` (and `.vybekiit/extensions/goal-index.md` if present).
+2. If a row matches → follow that skill; **stop here**.
+3. If the request is tech-specific → check `@vybekiit/*` `resolve*Provider()` adapters and `.vybekiit/platform-skills/*-vybekiit.md` plus `.vybekiit/extensions/platform-skills/`.
+4. If an existing goal skill can absorb the tech (e.g. new database → `save-data`) → follow that goal skill; **stop here**.
+5. Otherwise → run this workflow.
+
+## Workflow
+
+### 1. Classify the gap
+
+| Kind | Signal | Output |
+|---|---|---|
+| **New builder goal** | Feature or outcome with no goal-index match | Layer A buyer skill |
+| **New tech / provider** | Named framework, DB, language, or tool | Layer B wrapper (+ upstream pin when available) |
+
+Pick a **goal stem** (kebab-case, goal-named for Layer A) or **tech stem** (kebab-case for Layer B).
+
+### 2. Research (tech gaps only)
+
+1. Search skills.sh: `npx skills search <query>`
+2. When an official skill exists: `npx skills add <repo> --skill <name> -y` into project `.agents/skills/`
+3. Note official docs URL for the wrapper header
+4. Check `@vybekiit/*` for an existing provider interface to wire behind
+
+### 3. Draft
+
+Use these shapes (or `vybekiit` templates from `@vybekiit/agent-kit`):
+
+**Layer A (buyer goal)** — mirror `skills/save-data.md`:
+
+- `**Goal:**` one plain sentence
+- `**Contract:**` five rules + `language.md`
+- `## Steps` with `**Verify:**` on each step
+- `## Definition of done`
+- `## After completing this skill`
+
+**Layer B (platform wrapper)** — mirror `platform-skills/mongodb-vybekiit.md`:
+
+- Official docs links
+- `## Kit wiring` (prefer `resolve*Provider()`)
+- `## Verify-before-advance`
+- `## Never say to builder`
+- `## TODO(vybekiit)` when no npm adapter exists yet
+
+**Machine-global** — Agent Skills `SKILL.md` with YAML frontmatter (`name`, `description`).
+
+### 4. Lint (agent-only)
+
+Before saving, run:
+
+```bash
+vybekiit lint-extension-skill <draft-path> --kind=buyer-goal
+# or --kind=platform-wrapper
+# or --kind=agent-skills-global
+```
+
+Fix all issues. Exit code must be `0`. Builder never sees this step.
+
+### 5. Ask scope (plain language only)
+
+Ask exactly once:
+
+> "Should I save this guide just for this project, or for all your projects on this computer?"
+
+| Answer | Persist to |
+|---|---|
+| **This project** | Layer A: `.vybekiit/extensions/skills/<goal>.md` · Layer B: `.vybekiit/extensions/platform-skills/<tech>-vybekiit.md` |
+| **All my projects** | Tool-aware global path (detect active tool first) |
+
+### Tool-aware global paths
+
+| Active tool | Global skill path | skills.sh agent |
+|---|---|---|
+| **Cursor** | `~/.cursor/skills-cursor/<name>/SKILL.md` | `--agent cursor` |
+| **Claude Code** | `~/.claude/skills/<name>/SKILL.md` | `--agent claude-code` |
+| **Codex** | `~/.agents/skills/<name>/SKILL.md` | `--agent codex` |
+| **Fallback** | `~/.agents/skills/<name>/SKILL.md` | omit `--agent` |
+
+Detect tool: Cursor if `.cursor/rules/vybekiit.mdc` exists; else Claude if `CLAUDE.md` session; else Codex via `AGENTS.md`.
+
+Global install via skills.sh when upstream exists:
+
+```bash
+npx skills add <repo> --skill <name> --global --agent <agent> -y
+```
+
+### 6. Persist
+
+**Project-local:**
+
+- Create directories if missing: `.vybekiit/extensions/skills/`, `.vybekiit/extensions/platform-skills/`
+- Write the drafted file
+- **Layer A only:** append a row to `.vybekiit/agent/goal-index.md`:
+
+  `| "<builder phrase>" | \`extensions/skills/<goal>.md\` |`
+
+  Optionally mirror the row in `.vybekiit/extensions/goal-index.md` for backup.
+
+**Machine-global:**
+
+- Write `SKILL.md` to the tool path above
+- Do not edit project `goal-index.md` for global-only skills
+
+### 7. Resume
+
+Immediately follow the new skill as if it always existed. Never tell the builder you "created a skill."
+
+## Verify-before-advance
+
+- Lint passed (`vybekiit lint-extension-skill` exit 0)
+- File exists at chosen path
+- For Layer A: goal-index row present
+- For tech: upstream pin in `.agents/skills/` when available
+
+## Never say to builder
+
+skill gap, extension, Layer A, Layer B, platform wrapper, goal-index, skills.sh, Agent Skills, YAML frontmatter
+
+## Owned vs maintained
+
+`.vybekiit/extensions/**` is **buyer-owned** — `sync-agent-layer` never overwrites it. Extension rows in `goal-index.md` are preserved on kit updates.

package/dist/global-skills/vybekiitReferences/backend/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/backend/platform-skills/mongodb-vybekiit.md

@@ -0,0 +1,34 @@
+# Platform wrapper: MongoDB Atlas (agent/maintainer only)
+
+**Agent-only.** Not invoked by buyer `wire-database`. Use when `.env` already has `DATA_PROVIDER=mongodb`.
+
+## Official upstream
+
+- Docs: https://www.mongodb.com/docs/
+- Node driver: https://www.mongodb.com/docs/drivers/node/current/
+- Agent skills: https://www.mongodb.com/docs/agent-skills/
+- Skills repo: https://github.com/mongodb/agent-skills
+- MCP overview: https://www.mongodb.com/docs/mcp-server/overview/
+- MCP get started: https://www.mongodb.com/docs/mcp-server/get-started/
+
+## Kit wiring
+
+1. Set `DATA_PROVIDER=mongodb`, `MONGODB_URI` (Atlas SRV connection string), and `MONGODB_DB` (database name)
+2. Data access via `@vybekiit/db` → `resolveDataProvider()` in controllers/services — never direct driver in routes
+3. Atlas CLI installed by `vybekiit doctor` when `DATA_PROVIDER=mongodb`
+
+## MCP
+
+Merge `.vybekiit/agent/mcp-mongodb.json` into buyer `.cursor/mcp.json` (see `agent/mcp-setup.md`).
+
+1. Copy `MONGODB_URI` from `.env` into `MDB_MCP_CONNECTION_STRING`
+2. Keep `MDB_MCP_READ_ONLY=true` unless a maintainer explicitly needs write tools
+3. Fallback: `npx mongodb-mcp-server@latest setup` — see official get-started guide
+
+If MCP fails once, run `vybekiit doc-fallback mongodb`.
+
+## Verify-before-advance
+
+- `pingDatabase()` from `@vybekiit/db` succeeds
+- MCP lists collections on the dev cluster (read-only)
+- Never connect MCP to production buyer data without read-only mode

package/dist/global-skills/vybekiitReferences/backend/platform-skills/railway-postgres-vybekiit.md

@@ -0,0 +1,24 @@
+# Platform wrapper: Railway Postgres (coupled stack data)
+
+> Agent-only: follow the Persistent features sequence in `.vybekiit/agent/session-bootstrap.md`. Reuse the relevant catalog presets before adding app-owned extensions, and record structural and behavioral evidence separately.
+
+**Agent-only.** Invoked by buyer skills `save-data`, `doctor`, and prerequisites for `add-signin` when `DATA_PROVIDER=railway`.
+
+## Official upstream
+
+- Docs: https://docs.railway.com/databases/postgresql
+- Agent skill: `use-railway` in `.agents/skills/`
+- MCP: `mcp-railway-local.json` (variables, provisioning) or `mcp-railway-remote.json` (OAuth)
+
+## Kit wiring
+
+1. Set `DATA_PROVIDER=railway` with `HOSTING_PROVIDER=railway` (coupled stack — same Railway project)
+2. Provision Postgres plugin in the linked Railway project via MCP or CLI
+3. Pull `DATABASE_URL` from Railway variables into `.env`
+4. Data access via `@vybekiit/db` → `resolveDataProvider()` — never direct SQL in UI
+5. Auth: `better-auth` uses the same `DATABASE_URL` Postgres binding
+
+## Verify-before-advance
+
+- `pingRailwayDatabase(DATABASE_URL)` or doctor `pingDatabase()` green
+- Railway MCP connected for variable reads in dev/IDE only

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

@@ -0,0 +1,80 @@
+# AGENTS.md — your build agent (read this first)
+
+> **You are talking to a non-technical vibe coder.** They describe what they want; you
+> make every technical decision and translate manual steps into plain, one-at-a-time instructions.
+>
+> Single source of truth. `CLAUDE.md` and `.cursor/rules/vybekiit.mdc` point here;
+> `.cursor/rules/patterns.mdc` summarizes code conventions (not SSOT).
+
+## This is a browser extension — it talks to your backend
+
+Extensions **cannot safely keep private keys**. Sign-in, data, and payments live on the vibe coder's
+**deployed web app**; the extension calls it over HTTPS. Follow `chrome-extension-vybekiit.md` for
+Chrome API facts.
+
+<!-- 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. For Chrome APIs and store publish, read `.vybekiit/platform-skills/chrome-extension-vybekiit.md`.
+3. Grep `TODO(vybekiit)` markers and run each named skill until none remain.
+
+## Planning before big builds
+
+When the vibe coder asks for something **large or vague** 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.
+
+During onboarding, preserve the requested goal. Ask about planning only if a missing product decision blocks the work or the builder asks to plan.
+
+## Conventions (when the extension scaffold ships)
+
+- Use shadcn primitives in `src/components/ui/` and `@vybekiit/tokens` — same rules as web.
+- UI sources: `.vybekiit/agent/ui-sources.md` · normalize-on-import per `ui-consistency-vybekiit.md`.
+- Logging via `src/lib/logger.ts`; error alerts via `track-errors` + `@vybekiit/observability`.
+- Code hygiene: `code-hygiene-vybekiit.md` · `observability-vybekiit.md`.
+- **Never read `.env` values aloud or paste them in chat** — backend secrets stay on the web app.
+  Read `env-secrets-vybekiit.md`.
+- **All user-facing copy** lives in `public/_locales/en/messages.json` and is rendered via `t('key')`
+  from `lib/i18n.ts` — never inline strings in popup UI. See `i18n-vybekiit.md`.
+
+### Before you write code (invisible quality — vibe coder never hears this)
+
+1. **Test as you build** — `pnpm test` green before saying done.
+2. **Format + lint silently** — `pnpm format && pnpm lint` after substantive edits.
+3. **Use kit hooks** when present — read `src/hooks/README.md`.
+4. **Keep functions small** (~5 lines) and props few (~5).
+5. **Mobile-first popup UI** — narrow layout first, then scale up; preview at phone width.
+
+Read `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`) in `.vybekiit/platform-skills/`.
+
+## Wire-up markers
+
+`TODO(vybekiit): … — skill: <name>` in code → run that skill, replace stub, verify, re-grep.

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

@@ -0,0 +1,27 @@
+# Goal index — route the builder's request to a skill (extension)
+
+| The builder says something like… | Use this skill |
+|---|---|
+| "set up my extension", "let's start" | `skills/onboarding.md` |
+| "help me plan", "think it through" | `skills/plan-my-idea.md` |
+| "add payments", "take money" | `skills/setup-payments.md` |
+| "publish", "put it in the store", "make it live" | `skills/publish-extension.md` |
+| "let people sign in / log in" | `skills/connect-account.md` |
+| "save my data", "add a database" | `skills/save-data.md` |
+| "design my database" | `skills/design-my-data.md` |
+| "add images", "app icon" | `skills/add-images.md` |
+| "invite teammates" | `skills/add-teams.md` |
+| "notify users", "analytics" | `skills/add-notifications.md` / `skills/add-analytics.md` |
+| "sign in with Google" | `skills/sign-in-with-google.md` |
+| "update the kit" | `skills/update-kit.md` |
+| "it's broken", "check my extension" | `skills/doctor.md` |
+| "send feedback", "report a kit bug", "the kit is confusing" | `skills/vybekiit-feedback.md` |
+| "am I ready to ship" | `skills/check-safety.md` |
+| "translate my extension" | `skills/add-language.md` |
+| "chrome permissions", "camera", "tabs" | `skills/configure-capabilities.md` |
+
+If sign-in needs a server and none exists, run `vybekiit plan-readiness sign-in extension` — it orchestrates scaffolding `backend/` automatically.
+
+<!-- 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/extension/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/extension/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/extension/agent/mcp-sentry.json

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

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

@@ -0,0 +1,102 @@
+
+## 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" })`
+
+# 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`.
+
+Restart Codex after changes. Run `/mcp` in a session to verify tools are listed.
+
+## Provider snippets (merge one or more)
+
+| When | File | Upstream docs |
+|------|------|---------------|
+| 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 |
+
+### 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.

package/dist/global-skills/vybekiitReferences/extension/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/extension/agent/mcp-twilio-docs.json

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

package/dist/global-skills/vybekiitReferences/extension/agent/session-bootstrap.md

@@ -0,0 +1,44 @@
+# Session bootstrap (agent-only)
+
+<!-- vybekiit:generated:start session-bootstrap -->
+Reuse instructions already loaded in this conversation. Simple questions need brief answers, not setup. Inspect before project-specific claims; execute requests for work.
+
+## Read order (when needed)
+
+1. `AGENTS.md` (contract)
+2. `.vybekiit/agent/session-bootstrap.md` (this file)
+3. `.vybekiit/agent/goal-index.md` → pick the matching skill (merge rows from `.vybekiit/extensions/goal-index.md` when present)
+4. Routine coding needs no new skill. Consult a platform wrapper only for the capability being changed; extend capabilities only for a real uncovered integration.
+5. Follow the skill exactly; use `language.md` for voice
+6. On skill complete: append one entry to `checklist.md` Decision log via `formatChecklistEntry()`
+7. Stuck on an integration after one MCP or debug attempt: `vybekiit doc-fallback <tech-id>` and tell the builder the plain stuck phrase only
+
+## Persistent features
+
+- For booking, payments, membership, and shared information: inspect the app and authorized connection, discover relevant presets, identify only missing behavior, review and apply migrations, wire existing adapters, then verify persistence, authorization, and concurrency.
+- Use the preset catalog matching skills, dependencies, versions, and provider requirements. A missing dedicated skill does not mean a capability is missing: inspect `vybekiit list-presets` before proposing custom storage or a different product. Load relevant manifests once; do not reload the entire catalog or unrelated integrations each turn.
+- Ordinary product intent authorizes ordinary implementation choices. Continue without asking the builder to design tables or reconfirm their request. Ask only for a missing product decision or a genuinely missing access step.
+- Store app-specific manifests and generated SQL under `.vybekiit/extensions/database/`. Use the same preset contract and `apply-preset <id> --manifest=<path>`; register extension table names with the selected relational adapter. Existing generic collections stay unchanged.
+- Read structured upgrade diagnostics before using `--upgrade`. Existing nulls, duplicates, incompatible definitions, or drift block the change. Preserve every existing row; never delete projects to free capacity. Never read or write a preset table before `verify-presets` shows its preset applied.
+- Reuse `booking` for capacity and cancellation and `organizations` for membership. One business owns its schedule: identify its owner with the app's existing admin check, never an organization per account. Only the owner and permitted staff create or change classes; students browse and book without an organization of their own. Call `reserveBooking` and `cancelBooking` through the selected data adapter, supplying the verified session identity from the server. Report what they return: a cancellation that changed nothing is not a success. Show remaining places from every student's active reservations without revealing who booked. Named staff roles are server-controlled permissions stored as memberships of the business's organization: use the tenancy provider's `inviteMember`, `updateMemberRole`, and `listMembers` (`organization_members.role`) and check them on the server next to the admin check. A super moderator is not a database administrator and cannot change roles without an explicit permission.
+- A browser-only or in-memory demonstration is a preview. It cannot complete a shared booking, payment, or membership request. Structural verification is separate from behavioral evidence; test unauthorized access, cross-organization access, duplicate requests, and simultaneous reservations against the running app with separate owner and student sign-ins. Install missing dependencies and start the app yourself, then check every new or changed permission with real sign-ins against the running app. Tests against mocked data are not behavioral evidence.
+- Record preset versions, extension paths, migration checksums, remaining limitations, and verification evidence in checklist.md Progress and Decision log. Resume from that evidence when asked where things stand.
+
+## Quiet process lifecycle
+
+- Execute ordinary commands with your own shell tool. Never open a terminal window or tab, invoke a terminal app, or ask the builder to run a command just to keep work visible.
+- Before starting a server or watcher, check its health URL or port and your current background tasks. Reuse a matching process that is already running.
+- Run long-lived servers and watchers with the agent's native background-task support. Keep the returned task handle and use it to read output, stop, or restart that process.
+- Keep at most one process per app service. Stop the tracked process before replacing it when a real restart is required.
+- Use bounded commands for tests and logs. Do not use watch mode for one-time checks.
+
+## Project skill discovery
+
+- Auto-discovered Agent Skills: `.agents/skills/<goal>/SKILL.md` (Cursor + Claude via `.cursor/skills` / `.claude/skills` symlinks; Codex when project skills are enabled).
+- Authoring fallback: `.vybekiit/skills/<goal>.md` (same body; used when a goal-index row is opened explicitly).
+- First-party MCP catalog (agent-only): `.agents/skills/use-kit-mcp/SKILL.md` and `.vybekiit/platform-skills/mcp-tools-vybekiit.md` — also via MCP `get_skill` / `list_platform_skills` / `search_skills` ("mcp tools").
+- Do not invent skills outside those folders or the buyer-owned `.vybekiit/extensions/` tree.
+
+Buyer-owned files you may append to (never delete): `checklist.md` Decision log, `CONTEXT.md` app glossary, `.vybekiit/extensions/**` (extension skills).
+Machine-global skills live in tool-specific paths (see `extend-capabilities-vybekiit.md`); tools auto-discover them.
+<!-- vybekiit:generated:end session-bootstrap -->

package/dist/global-skills/vybekiitReferences/extension/agent/tech-references.md

@@ -0,0 +1,28 @@
+# Official tech references (agent-only)
+
+<!-- vybekiit:generated:start tech-references -->
+# Official tech references (agent-only)
+
+When MCP or first-pass debug fails, run `vybekiit doc-fallback <id>` and follow these URLs.
+
+| id | Docs | MCP | Env keys |
+|---|---|---|---|
+| better-auth | https://www.better-auth.com/docs | — | AUTH_PROVIDER, BETTER_AUTH_SECRET, BETTER_AUTH_URL, DATABASE_URL |
+| twilio | https://www.twilio.com/docs | https://mcp.twilio.com/docs | TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER, TWILIO_VERIFY_SERVICE_SID |
+| twilio-whatsapp | https://www.twilio.com/docs/whatsapp | https://mcp.twilio.com/docs | TWILIO_WHATSAPP_FROM |
+| supabase | https://supabase.com/docs | — | SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, DATABASE_URL |
+| stripe | https://docs.stripe.com | — | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET |
+| neon | https://neon.tech/docs | — | DATABASE_URL |
+| firebase | https://firebase.google.com/docs | — | — |
+| mongodb | https://www.mongodb.com/docs/ | https://www.mongodb.com/docs/mcp-server/overview/ | DATA_PROVIDER, MONGODB_URI, MONGODB_DB |
+| express | https://expressjs.com | — | — |
+| expo | https://docs.expo.dev | — | — |
+| nextjs | https://nextjs.org/docs | — | — |
+| cloudflare | https://developers.cloudflare.com | — | — |
+| railway | https://docs.railway.com | https://docs.railway.com/ai/mcp-server | HOSTING_PROVIDER, DATA_PROVIDER, DATABASE_URL, RAILWAY_PROJECT_ID, RAILWAY_SERVICE_ID |
+| resend | https://resend.com/docs | — | EMAIL_PROVIDER, RESEND_API_KEY |
+| lemon-squeezy | https://docs.lemonsqueezy.com | — | LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID |
+| sentry | https://docs.sentry.io | https://mcp.sentry.dev/mcp | OBSERVABILITY_PROVIDER, SENTRY_DSN |
+| posthog | https://posthog.com/docs | https://mcp.posthog.com/mcp | ANALYTICS_PROVIDER, POSTHOG_API_KEY, POSTHOG_HOST |
+| plausible | https://plausible.io/docs | — | PLAUSIBLE_DOMAIN, ANALYTICS_PROVIDER |
+<!-- vybekiit:generated:end tech-references -->