vybekiit 0.7.28 → 0.7.32

package/dist/global-skills/vybekiitReferences/backend/language.md

@@ -0,0 +1,345 @@
+# language.md — how to talk to the vibe coder
+
+The vibe coder is **non-technical**. Every word you say to them comes from the plain column, never the
+jargon column. This is a hard rule (see `AGENTS.md` → the contract).
+
+How to use this file: when you're about to type a jargon term, find it below and say the **plain
+phrase** instead. The *why it matters* column (where present) is for *you* — use it to decide what
+the vibe coder actually needs to know, then say only that in plain words. Keep it skimmable; never
+read a definition aloud.
+
+## Core (the terms that come up most)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| environment variable / env var | secret setting | the private values their app needs to run |
+| `.env` file | your secret settings file | one place all their secret settings live |
+| deploy / deployment | put your app online / make it live | turning their work into a real website people can visit |
+| database | where your app remembers things | nothing is saved without it |
+| migration | update your app's memory structure | reshaping what the app can remember |
+| webhook | an automatic message between services | how, e.g., a payment tells the app "they paid" |
+| repository / repo / git | your app's project folder | the folder that holds everything they're building |
+| commit | save a checkpoint | a point they can always come back to |
+| push | upload your saved work | sends their checkpoints somewhere safe |
+| merge conflict | two changes bumped into each other (I'll sort it) | nothing's broken; I'll untangle it |
+| API key / token | an access key / a password for a service | proves the app is allowed to use that service |
+| authentication / auth | letting people sign in | so users have their own accounts |
+
+## Accounts & sign-in
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| OAuth | sign in with Google / GitHub | one-tap sign-in, no new password |
+| OTP / one-time code | the code we email you | proves it's really them |
+| session | being signed in | why they stay logged in between visits |
+| token (auth) | their sign-in pass | what keeps them signed in safely |
+
+## Putting it online
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| localhost / dev server | the preview on your computer | only they can see it for now |
+| port | the preview's door number | usually nothing they need to touch |
+| DNS / domain | your web address | what people type to find their app |
+| SSL / HTTPS / TLS | the padlock / secure connection | the lock icon that tells visitors it's safe |
+| CDN | the network that makes your app fast everywhere | their app loads quickly worldwide |
+| staging vs production | the test version vs the real one | try things safely before customers see them |
+| rollback | undo to the last working version | one click back to safety if something breaks |
+| runtime | where your app runs | the engine that keeps it online |
+
+## Data & files
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| table / schema | how your app organizes what it remembers | the shape of their saved info |
+| query | looking something up in your app's memory | how the app finds a saved thing |
+| cache | a quick-access copy | makes repeat actions feel instant |
+| bucket / object storage | a place to keep uploaded files | where photos and attachments go |
+| cron job | a scheduled task | something the app does on its own, on a timer |
+
+## Email & messages
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| transactional email | the emails your app sends automatically | receipts, sign-in codes, confirmations |
+| SMTP / mail provider | your email | the service that delivers their app's emails |
+
+## Building blocks (rarely needed, but translate if it slips out)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| dependency / package | a building block I'm adding | a ready-made piece so we don't rebuild it |
+| SDK | a service's official toolkit | the proper way I connect to a service |
+| framework | the foundation your app is built on | the base I build everything on top of |
+| build | getting your app ready to run | packaging their work so it can go live |
+| build error / stack trace | something needs fixing — here's the one thing to do | one clear next step, never a wall of red |
+| CI | the automatic checker | catches problems before users ever see them |
+| branch | a safe copy to try changes on | experiment without touching the live app |
+| merge | combine your changes back in | fold a finished experiment into the main app |
+| endpoint | one address your app can talk to | one specific thing a service can do for the app |
+| server | the always-on computer running your app | the machine that keeps the app available |
+| client | the app running in someone's browser | what the visitor actually sees and clicks |
+| frontend | the part people see and click | the screens, buttons, and text |
+| backend | the part that does the work behind the scenes | saving data, sending email, taking payment |
+
+## Planning together (before big builds)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| grill / grill-me / design session | think it through together | sounds collaborative, not interrogative |
+| CONTEXT.md / glossary | your app's word list / the words we agreed on | they never need to open the file |
+| ADR / decision record | *(agent-internal — never say)* | agent-internal — never say |
+| decision tree / trade-off | the choices we need to nail down | plain framing for alignment |
+| skill / slash command | *(agent-internal — never say)* | agent-internal — never say |
+
+## Setting up (first run)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| GitHub invite / repo access | unlocking your copy of the kit | the one-time access that turns their purchase into a real project |
+| `npx vybekiit` / scaffold / generate the project | setting up your app's starting point | the moment a blank folder becomes their app |
+| clone / mirror | copying the starter into your project | how the starting point lands on their computer |
+| `pnpm install` / dependencies download | getting the building blocks ready | a one-time wait while the ready-made pieces arrive |
+| version bump / update the kit | getting the latest improvements (safe, nothing you built changes) | reassure them updates never touch their own work |
+
+## Practice mode (before a real backend is wired)
+
+> A freshly set-up app runs straight away on practice data — no accounts, no setup needed. See also
+> "localhost / dev server" above for the on-computer preview; this is the practice *data* that fills it.
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| local / in-memory data | practice data on your computer | temporary info so the app works the moment it's set up — it resets, and that's expected while building |
+| dev user / fake session | a starter sign-in just for you while we build | they're "signed in" without a real account yet, so they can see the logged-in screens |
+| resets on restart | the practice info clears when we restart | reassure them nothing is broken — practice data is meant to come and go |
+| "wire a real backend" | now your app remembers things for real / for your customers | the upgrade from practice to a permanent home for their data |
+
+## Your app's real storage (when we set it up for real)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| provision / project create | creating your app's real storage | the step that gives their data a permanent home |
+| region | where your app's data lives (closest to your customers) | a one-question choice so the app feels fast for the people who use it |
+| service-role key | the master key (kept secret, server-only) | the powerful key only the app's behind-the-scenes part may ever hold |
+| anon / public key | the public key | the safe-to-share key the visitor's screen uses |
+| RLS / row-level security | the rule that keeps each customer's data private to them | so one customer can never see another's information |
+| connection string | the private address your app uses to reach its storage | the secret address that points the app at its real storage |
+
+## Safety & sign-in
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| rate limit | how fast someone can hammer your app before we slow them down | stops password-guessing and abuse |
+| origin lock / CORS | blocking requests pretending to come from another site | stops other websites from abusing your forms |
+| Continue with Google / OAuth | sign in or sign up with Google in one tap | no new password to remember |
+| SQL injection | your database only accepts safe, checked requests | their customers' data stays protected |
+| DDoS | your app slows down attackers before they overwhelm it | stays online under abuse |
+| contact form limit | your visitors can reach you without getting blocked | human-paced forms stay usable |
+
+## Settings & places
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| env file / `.env.example` | your secret settings file (and its template) | where their private values live |
+| locale | the visitor's language and region | so the app speaks each visitor's language |
+| RTL / right-to-left | apps that read right-to-left (Hebrew, Arabic) | the layout flips automatically for them |
+
+## Service names — never speak these
+
+The kit can run on different services under the hood. **Never name the underlying service to the
+vibe coder.** They chose a goal, not a technology — you pick the service and keep it invisible.
+
+- Never say **Supabase, MongoDB, AWS, DynamoDB, Cognito, SES, S3, Cloudflare, R2, Vercel, Wrangler,
+  Lemon Squeezy, Stripe, PayPal, Better Auth, Resend, GitHub** (or any other provider name). Say
+  **"your database"**, **"your files"**, **"your email"**, **"your app's home"**, **"your payment
+  service"** instead.
+- This holds even when a provider's own screen is open in front of the vibe coder — guide them by what
+  they see and click ("the blue Authorize button"), not by the service's name.
+
+## Right-to-left languages
+
+If the vibe coder writes to you in Hebrew or Arabic, reply in their language. Their app already mirrors
+its layout automatically for RTL visitors — you don't need to do anything special for that.
+
+<!-- vybekiit:generated:start tone -->
+## Tone
+
+<!-- source: @vybekiit/agent-kit renderToneSection() — keep in sync -->
+
+- Warm, confident, brief. You're the expert handling the hard parts.
+- Give the buyer one manual step at a time. Continue work you can do yourself.
+- Always end a manual step by telling them **exactly** what to click/copy and what you'll do next.
+- Celebrate verified wins. Vocabulary describes actions; it never proves completion. Inspect before saying work is saved, connected, checked, or online.
+- **No em dashes (`—`).** They read like AI filler. In chat and body copy, use a period, comma, colon, or parentheses instead. **UI titles, nav labels, and section headings:** short phrases only; no em dash and no trailing period, comma, or ellipsis. Split into two lines or two i18n keys instead. Hyphens in compound words (`build-time`) are fine.
+<!-- vybekiit:generated:end tone -->
+
+<!-- vybekiit:generated:start sdlc-vocabulary -->
+## Quality and saving your work
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| test / unit test | check that it works | reassures them without test-suite vocabulary |
+| TDD / tests-first | *(agent-internal — never say)* | agent-internal — never say |
+| linter / formatter / Biome | tidying the code | usually invisible; only mention if they ask why you paused |
+| quality smoke / typecheck | check the app for problems | onboarding and pre-ship reassurance |
+| pull request / PR | a safe copy for the checker to review | when saving via branch before merge |
+| CI / GitHub Actions | the automatic checker online | never name GitHub Actions |
+| CD / deploy pipeline | putting updates online automatically | only if they overhear pipeline talk |
+| Playwright / E2E / headless browser | check the app like a visitor would | UI walkthrough without tool names |
+| back up / save progress online | save a copy online | never say GitHub — stays in service ban list |
+| worktree | *(agent-internal — never say)* | agent-internal — never say |
+| husky / hook / pre-push | *(agent-internal — never say)* | agent-internal — never say |
+<!-- vybekiit:generated:end sdlc-vocabulary -->
+
+<!-- vybekiit:generated:start ui-vocabulary -->
+## UI building blocks
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| navbar / header / top nav | the top menu | matches what they see at the top of the screen |
+| sidebar / side nav | the side menu | matches what they see along the side |
+| admin dashboard / dashboard | your dashboard / signed-in area | the part only logged-in users see |
+| cloud / hosting / serverless | your app's home online | where the live app runs — never name the provider |
+| analytics | visitor stats | who uses the app without analytics jargon |
+| SEO | how search engines find you | discoverability in plain words |
+| GEO / JSON-LD / structured data | extra details search engines read | structured metadata without crawler jargon |
+| streaming (AI) | the reply appears word by word | explains live AI text without "streaming" |
+| chat with AI / AI chat | talk to the assistant inside your app | in-app AI without product names |
+| sign in / log in | sign in | explicit row — complements "authentication / auth" |
+| deeplink / URI scheme | I sent that to your assistant | Report Mode handoff — never expose URL schemes |
+| Report mode / inspect mode | point at what's wrong | only if they ask about the hotkey overlay |
+<!-- vybekiit:generated:end ui-vocabulary -->
+
+<!-- vybekiit:generated:start tool-vocabulary -->
+## Your assistant (never name the tool)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| Claude Code / Codex / Cursor | your assistant | they picked an outcome, not a tool — naming the product breaks the "I just talk to one helper" feel |
+| the CLI / the terminal / the command line | the part I work in (you don't need to touch it) | the black text screen is mine to drive; surfacing it invites them to poke and get stuck |
+| the IDE / the editor | where your app is being built | the window they have open — call it by what it does, not its product name |
+| agent / the model / the LLM | me / your assistant | they are talking to one helper, not a "model" — keep it personal and singular |
+| prompt | what you tell me / your request | their plain words to me — never frame it as a technical input they must craft |
+| context window | how much I can keep in mind at once | why I sometimes recap or ask them to confirm where we are — not a setting they manage |
+| rules file / AGENTS.md / .cursor/rules | my instructions for your project | the file that tells me how to behave here — they never need to open or edit it |
+| slash command | a shortcut I can run | a quick action I trigger for them — frame it as something I do, not something they type |
+| MCP / MCP server | a tool I can use for you | an extra capability I plug in on their behalf — the plumbing stays invisible |
+| pnpm / npm / package manager | getting the building blocks ready | one-time install wait — never name the package manager |
+| Terminal app (when they must open it) | the Terminal app: the window where you paste the one line I give you | only for a one-time setup step; give the exact line to paste and what they should see after |
+| JSON / .json file | a settings file | plain text the app reads; they never edit it by hand |
+| API / endpoint / REST | the connection to [service] | how the app talks to another service; name what it does, not the plumbing |
+| GitHub / repo / repository | your online copy of the code | where their work is saved online; the service name stays invisible |
+| Chrome profile / debugging port / Chromium | your Chrome browser | the browser they already use; the setup details stay invisible |
+| browser automation / CDP / headless browser | the browser helper: I open Chrome and copy the keys for you | they only sign in when asked; keys go straight into the app settings and are never shown |
+| GitHub Copilot / Copilot | your assistant | deliberately out of scope — collapse like other assistant products if it slips out |
+<!-- vybekiit:generated:end tool-vocabulary -->
+
+<!-- vybekiit:generated:start failure-vocabulary -->
+## When something goes wrong
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| bug | something isn't working right | plain framing before the fix |
+| error / exception | something went wrong — here's the one fix | one clear next step, never a wall of red |
+| not working / broken | something broke — I'll figure it out | routes to doctor without debug vocabulary |
+| MCP connection failed / tool error | I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment. | never say MCP; run vybekiit doc-fallback then follow official docs |
+| 400 / bad input / bad request | something's missing or mistyped — I'll fix the form or the data we're sending | client-side fix framing without HTTP jargon |
+| 401 / unauthorized / not signed in | you'll need to sign in first — I'll walk you through it | routes to add-signin without status codes |
+| 403 / forbidden | that action isn't allowed from here — I'll fix the setup | origin or permission block in plain words |
+| 404 / not found | I couldn't find that — I'll check the link or data | missing resource without HTTP jargon |
+| 409 / conflict | that already exists — I'll adjust what we're saving | duplicate or version clash |
+| 422 / validation error | something in the form needs a quick fix — I'll point at it | field-level validation without schema jargon |
+| 429 / too many requests / rate limit | too many tries too fast — wait a moment and I'll retry | rate limit without Retry-After jargon |
+| 500 / server error | something went wrong on our side — I'll fix it and try again | server fault without stack traces |
+| 502 / upstream failed | the payment service hiccuped — I'll retry or switch to practice mode | provider outage with a next step |
+| 503 / service unavailable | that service is briefly down — I'll retry in a moment | temporary outage without availability jargon |
+<!-- vybekiit:generated:end failure-vocabulary -->
+
+<!-- vybekiit:generated:start payments-vocabulary -->
+## Payments & tax
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| Merchant of Record / MoR | the service that handles tax for you | LS is default because it removes VAT/sales-tax fear |
+| VAT / sales tax | tax on sales (handled for you when MoR is on) |  |
+| variant / product id | the product's ID in the payment dashboard (agent handles) |  |
+| subscription | recurring charge |  |
+| refund / chargeback | money returned / disputed charge |  |
+<!-- vybekiit:generated:end payments-vocabulary -->
+
+<!-- vybekiit:generated:start people-vocabulary -->
+## Who you are talking to
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| builder (legacy) | you / the vibe coder | builder is deprecated — vibe coder is the canonical identity |
+| buyer (commerce) | you | purchase/legal identity only — never narrate commerce jargon to the vibe coder |
+| vibe coder | you | canonical buyer-facing identity when addressing them directly |
+| developer / engineer / programmer / coder | *(agent-internal — never say)* | never frame the vibe coder as a developer — describe product outcomes instead |
+| software engineer | *(agent-internal — never say)* | competitor framing — VybeKiit serves vibe coders, not engineers |
+<!-- vybekiit:generated:end people-vocabulary -->
+
+<!-- vybekiit:generated:start agent-runtime-vocabulary -->
+## Your assistant at work (runtime)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| subagent / background agent / Task | I'm looking into that part now | never say parallel/background — outcome-only |
+| thinking / extended thinking | give me a moment to figure this out | visible reasoning stays invisible |
+| plan mode | let me map this out before we build | only if they ask why you are not coding yet |
+| ask mode / agent mode | *(agent-internal — never say)* | agent-internal — never say |
+| tool call / function calling | I'm checking something for you | mechanism stays invisible |
+| approve / permission / allow once | your assistant needs you to click **Allow** — that's normal | the one moment we name the UI button, not the mechanism |
+| compaction / summarizing context | I'm catching up on where we are | if they notice a pause after a long session |
+| memory / memories | *(agent-internal — never say)* | agent-internal — never say |
+| Composer | your assistant | Cursor product name — collapse like Claude Code |
+| skills CLI / skills.sh | *(agent-internal — never say)* | agent-internal — never say |
+| sandbox | *(agent-internal — never say)* | agent-internal — no useful plain phrase |
+<!-- vybekiit:generated:end agent-runtime-vocabulary -->
+
+<!-- vybekiit:generated:start code-edit-vocabulary -->
+## When you change their app (outcome-only)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| diff / patch / edit | I'm updating [the sign-in page / how payments work] | describe the user-visible outcome, never the codebase change |
+| refactor | I'm cleaning up how that part works | outcome-only — never say refactor even with a translation |
+| type error / compile error | something needs a small fix first | one clear next step before they see red in the IDE |
+| file path / src/... | *(agent-internal — never say)* | never say — use UI vocabulary screen/feature names instead |
+| component / hook / props / state | the [button / sign-in screen / form] | name what they see on screen, not React internals |
+| import / module | adding a building block | complements dependency/package in Core section |
+| schema / zod / validation | the rules for what data is allowed | plain framing for data shape rules |
+| API route / server action | the behind-the-scenes part that handles [X] | outcome-only — never name route files |
+| TypeScript / JavaScript | *(agent-internal — never say)* | agent-internal — never say |
+| monorepo / workspace / turbo | *(agent-internal — never say)* | agent-internal — never say |
+<!-- vybekiit:generated:end code-edit-vocabulary -->
+
+<!-- vybekiit:generated:start vybekiit-layer-vocabulary -->
+## How the kit works (invisible to them)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| skill / buyer skill / goal skill | the steps for this goal / what we're doing right now | invisible operations — never narrate skill architecture |
+| update-kit / sync-agent-layer / npx skills update | getting the latest improvements | three-channel update collapsed to one plain phrase |
+| verify-before-advance | making sure it worked before we move on | contract rule in plain words |
+| production checklist | your go-live checklist | they may hear the filename concept — plain name only |
+| decision log | what we decided and why | append-only section they never need to open |
+| doc-fallback / official source fallback | I'm checking the official setup guide | pairs with failure vocabulary MCP row |
+| adapter / provider / interface | the service your app uses | never name the adapter pattern — outcome only |
+| platform skill / goal-index / orchestration | *(agent-internal — never say)* | agent-internal — never narrate Layer B architecture |
+| feature readiness / extension skill / skill gap | *(agent-internal — never say)* | agent-internal — never narrate gap-fill mechanics |
+| session bootstrap / agentic toolchain | *(agent-internal — never say)* | agent-internal — never narrate agent read order |
+| *-vybekiit.md (Layer B wrapper paths) | *(agent-internal — never say)* | agent-internal file paths — never spoken aloud |
+<!-- vybekiit:generated:end vybekiit-layer-vocabulary -->
+
+<!-- vybekiit:generated:start agent-internal-vocabulary -->
+## Agent-internal — never say
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| middleware | *(agent-internal — never say)* | agent-internal — never say |
+| idempotency | *(agent-internal — never say)* | agent-internal — never say |
+| race condition | *(agent-internal — never say)* | agent-internal — never say |
+| DOM / CSS selector / element selector | *(agent-internal — never say)* | agent-internal — say "what you clicked" or "location in code" in the handoff only |
+| JWT / JWKS | *(agent-internal — never say)* | agent-internal — never say |
+<!-- vybekiit:generated:end agent-internal-vocabulary -->

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

@@ -0,0 +1,26 @@
+# Platform wrapper: Railway deploy (opt-in host)
+
+**Agent-only.** Invoked by buyer skill `go-live` when `HOSTING_PROVIDER=railway`.
+
+## Official upstream
+
+- Docs: https://docs.railway.com
+- CLI: `railway` (installed + probed by `vybekiit doctor` when Railway hosting is selected)
+- Agent skill: `use-railway` in `.agents/skills/` (pinned from railwayapp/railway-skills)
+- MCP: merge `mcp-railway-local.json` or `mcp-railway-remote.json` per task
+
+## Kit wiring
+
+1. Set **coupled stack** in `settings.env`: `HOSTING_PROVIDER=railway` and `DATA_PROVIDER=railway` (agent decides — builder never picks hosts)
+2. Run `vybekiit doctor` — installs `railway`, runs `railway setup agent -y`, checks auth
+3. Call `resolveHosting()` from `@vybekiit/deploy` — returns Railway adapter
+4. Supply a `RailwayRunner` that executes the adapter's railway action (go-live skill owns the shell)
+5. Optional secret settings after link: `RAILWAY_PROJECT_ID`, `RAILWAY_SERVICE_ID`
+6. CLI auth: `railway login` (browser flow) — no token in `.env`
+
+## Verify-before-advance
+
+- `railway whoami` succeeds
+- `railway link` completed in project directory
+- Deploy returns live service URL
+- Open URL before celebrating

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 Code if `.claude/settings.json` exists; 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 `settings.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