vybekiit 0.7.27 → 0.7.28

package/dist/bin.js

@@ -6147,10 +6147,16 @@ var BACKEND_CLI_COMMANDS = {
 // ../packages/agentKit/src/catalogs/buyerGuidance.ts
 var BUYER_GUIDANCE = `# Build with VybeKiit
 
-For app-building tasks, use the relevant VybeKiit skill before implementing. Inspect the
-current project and respect its instructions and the builder's explicit choices.
+You are building with a vibe coder: someone who describes the product in plain words and never
+reads diffs or runs git or hosting commands. Address them as "you". For app-building tasks, use
+the relevant VybeKiit skill before implementing. Inspect the current project and respect its
+instructions and the vibe coder's explicit choices.
 
-1. Understand the goal in the builder's words. Ask only for missing product decisions.
+Speak in plain words. Before you say a technical term to the vibe coder, look it up in the
+project's language.md, or in ~/.vybekiit/language.md when the project has none, and say the
+plain phrase instead. When a skill says language.md, it means that same file.
+
+1. Understand the goal in the vibe coder's words. Ask only for missing product decisions.
 2. Discover the matching goal skill through VybeKiit's search_skills and get_skill tools,
    or read the installed skill and the project's goal-index.md when tools are unavailable.
 3. Inspect existing kit capabilities before creating UI, schemas, migrations, server routes,
@@ -6159,20 +6165,20 @@ current project and respect its instructions and the builder's explicit choices.
 4. In a kit project, follow its CODE-STYLE.md, settings contracts, maintained package boundaries,
    and existing patterns. Customize buyer-owned screens and flows. Do not copy maintained logic
    into the app or create duplicate wrappers. In another project, preserve its architecture.
-5. Explain the chosen ready pieces briefly in plain language, then do the work. Give only one
+5. Explain the chosen ready pieces briefly in plain words, then do the work. Give only one
    manual action at a time and verify it before advancing. Verify changed behavior with tests
    and a real preview. Never present practice payments or local data as connected services.
 6. When the kit cannot meet the goal, describe the concrete gap, implement the smallest
    appropriate extension, and offer kit feedback. Do not invent ready features or providers.
 7. Use /vybekiit-feedback for kit feedback. Check vybekiit feedback status first. Automatic
-   reports require the buyer's saved opt-in; explicit requests authorize that report only.
+   reports require the vibe coder's saved opt-in; explicit requests authorize that report only.
    Send only the feedback skill's sanitized fields, never code or conversation transcripts.
 8. Keep checklist.md progress current in kit projects. Claim completion only for behavior
-   verified in the environment the builder asked for.
+   verified in the environment the vibe coder asked for.
 
 For a new app, use the onboarding skill and the existing kit scaffold. For an existing app,
 inspect before changing it. These are defaults for relevant building work, not instructions
-to replace the builder's unrelated projects or override their choices.
+to replace the vibe coder's unrelated projects or override their choices.
 `;
 
 // ../packages/agentKit/src/catalogs/goalCatalog.ts
@@ -7610,7 +7616,7 @@ var sanitizeDescriptionLine = (text3) => text3.replace(WHITESPACE_PATTERN, " ").
 var renderBuyerSkillDescription = (skillStem, goalText, template) => {
   const goal = sanitizeDescriptionLine(goalText.replace(TRAILING_PERIOD_PATTERN, ""));
   const phrases = lookupBuyerSkillTriggerPhrases(skillStem, template);
-  const when = phrases.length > 0 ? ` Use when the builder says something like: ${phrases.slice(0, 6).join("; ")}.` : "";
+  const when = phrases.length > 0 ? ` Use when the vibe coder says something like: ${phrases.slice(0, 6).join("; ")}.` : "";
   const description = `${goal}.${when}`;
   return description.length <= MAX_DESCRIPTION ? description : `${description.slice(0, MAX_DESCRIPTION - 1)}\u2026`;
 };
@@ -31392,7 +31398,8 @@ var globalInstallPaths = (configDir = claudeConfigDir()) => ({
   settingsFile: join50(configDir, "settings.json"),
   // At runtime this module is inlined into dist/bin.js, so MODULE_DIR is <install>/dist
   // and the payload sits beside it at dist/global-skills.
-  bundledSkillsDir: join50(MODULE_DIR, "global-skills")
+  bundledSkillsDir: join50(MODULE_DIR, "global-skills"),
+  bundledLanguageGuide: join50(MODULE_DIR, "global-guidance", "language.md")
 });
 
 // src/global/globalStatus.ts
@@ -33120,7 +33127,9 @@ var AgentInstallationSettings = Schema20.Struct({
   homeDirectory: Schema20.NonEmptyString,
   claudeDirectory: Schema20.NonEmptyString,
   codexDirectory: Schema20.NonEmptyString,
-  executablePath: Schema20.String
+  executablePath: Schema20.String,
+  /** The plain-language guide bundled with the CLI (the web template's language.md). */
+  plainLanguageGuide: Schema20.NonEmptyString
 });
 var AgentInstallationError = class extends Data13.TaggedError("AgentInstallationError") {
 };
@@ -33203,12 +33212,21 @@ var installAgentGuidance = (settings, agents, canonicalSkills, managedSkills, ve
       })
     )
   );
+  const plainLanguageGuide = yield* Effect39.tryPromise({
+    try: () => readFile31(settings.plainLanguageGuide, "utf8"),
+    catch: (cause) => new AgentInstallationError({
+      message: "The plain-language guide is missing. No instructions were changed.",
+      cause
+    })
+  });
   const guidanceDirectory = join61(settings.homeDirectory, ".vybekiit");
   const guidancePath = join61(guidanceDirectory, "agent-guidance.md");
+  const languagePath = join61(guidanceDirectory, "language.md");
   yield* Effect39.tryPromise({
     try: async () => {
       await mkdir18(guidanceDirectory, { recursive: true });
       await writeFile22(guidancePath, BUYER_GUIDANCE, "utf8");
+      await writeFile22(languagePath, plainLanguageGuide, "utf8");
     },
     catch: (cause) => new AgentInstallationError({ message: "Could not install the building guidance.", cause })
   });
@@ -33230,6 +33248,7 @@ var installAgentGuidance = (settings, agents, canonicalSkills, managedSkills, ve
             const guidancePointer = agent.agent === "claude" ? "@~/.vybekiit/agent-guidance.md" : `For app-building tasks, read ${JSON.stringify(guidancePath)} before choosing an approach.`;
             const instruction = `${guidancePointer}
 Use its matching VybeKiit skills and reuse the kit's UI, schemas, server and client code.
+Speak to the vibe coder in plain words: translate every technical term with the project's language.md, or ${JSON.stringify(languagePath)} when the project has none.
 Skills: ${JSON.stringify(agent.skills)}. Installed instructions require a fresh agent session.`;
             const nextInstruction = updateAgentInstruction(previousInstruction, instruction);
             await mkdir18(dirname21(instructionPath), { recursive: true });
@@ -33761,7 +33780,8 @@ var runGlobalInstall = async (args, gate = checkEntitlement) => {
     homeDirectory: homedir9(),
     claudeDirectory: paths.configDir,
     codexDirectory: process30.env.CODEX_HOME || join64(homedir9(), ".codex"),
-    executablePath: process30.env.PATH || ""
+    executablePath: process30.env.PATH || "",
+    plainLanguageGuide: paths.bundledLanguageGuide
   });
   const detectedAgents = agentInstallationTargets(agentSettings);
   if (!detectedAgents.some((agent) => agent.detected)) {

package/dist/global-guidance/language.md

@@ -0,0 +1,443 @@
+# 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 |
+| compute quota / free tier limit | your app's free allowance | how much running time the free plan includes before needing an upgrade |
+| fire-and-forget / un-awaited background work | background work that might get cut off | the app tried to do something after responding but the server shut down too early |
+| waitUntil / background task API | keep-alive for background work | tells the server "don't shut down yet, I'm still finishing something" |
+
+## 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 |
+
+## 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 | removes VAT/sales-tax fear — the default handles it |
+| VAT / sales tax | tax on sales (handled for you when MoR is on) | they never need to file tax themselves on the default path |
+| variant / product id | the product's ID in the payment dashboard (agent handles) | they pick a price; you wire the id |
+| subscription | recurring charge | money that repeats on a schedule |
+| refund / chargeback | money returned / disputed charge | when a customer gets money back or disputes a charge |
+
+## 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 |
+
+## Quality and saving your work
+
+<!-- source: @vybekiit/agent-kit renderSdlcVocabularyTable() — keep in sync -->
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| test / unit test | I checked it still 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 | everything checks out | 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 | I walked through your app like a visitor would | UI walkthrough without tool names |
+| back up / save progress online | I saved your progress 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 |
+
+## 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 |
+
+## Your app's layout
+
+<!-- source: @vybekiit/agent-kit renderUiVocabularyTable() — keep in sync -->
+
+| 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 |
+
+## When something breaks
+
+<!-- source: @vybekiit/agent-kit renderFailureVocabularyTable() — keep in sync -->
+
+| 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 |
+
+## Agent-internal — never say
+
+<!-- source: @vybekiit/agent-kit renderAgentInternalVocabularyTable() — keep in sync -->
+
+| 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" to the vibe coder |
+
+## Talking about the tools themselves
+
+The vibe coder also overhears you reasoning about your own tooling. Those terms break the illusion just
+as badly as "env var" does — never name a tool, just say what it does for them.
+
+<!-- source: @vybekiit/agent-kit renderToolVocabularyTable() — keep in sync -->
+
+| 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 / CLAUDE.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 |
+
+## 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.
+
+## Tone
+
+<!-- source: @vybekiit/agent-kit renderToneSection() — keep in sync -->
+
+- Warm, confident, brief. You're the expert handling the hard parts.
+- One step at a time. Never a wall of instructions.
+- Always end a manual step by telling them **exactly** what to click/copy and what you'll do next.
+- Celebrate wins.
+- **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.
+
+## 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.
+- One step at a time. Never a wall of instructions.
+- Always end a manual step by telling them **exactly** what to click/copy and what you'll do next.
+- Celebrate wins.
+- **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 | I checked it still 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 | everything checks out | 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 | I walked through your app like a visitor would | UI walkthrough without tool names |
+| back up / save progress online | I saved your progress 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 / CLAUDE.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 |
+| 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 |
+| sandbox | *(agent-internal — never say)* | agent-internal — never say |
+| ask mode / agent mode | *(agent-internal — never say)* | agent-internal — never say |
+| skills CLI / skills.sh | *(agent-internal — never say)* | agent-internal — never say |
+| *-vybekiit.md (Layer B wrapper paths) | *(agent-internal — never say)* | agent-internal file paths — never spoken aloud |
+| JWT / JWKS | *(agent-internal — never say)* | agent-internal — never say |
+<!-- vybekiit:generated:end agent-internal-vocabulary -->

package/dist/global-skills/add-ai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-ai
-description: "the builder wants smart replies or another AI feature in their app. Use when the builder says something like: add ai; chatbot; smart replies."
+description: "the builder wants smart replies or another AI feature in their app. Use when the vibe coder says something like: add ai; chatbot; smart replies."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-analytics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-analytics
-description: "the builder can see who uses their app — visitor stats in plain language. Use when the builder says something like: visitor stats; analytics; track usage."
+description: "the builder can see who uses their app — visitor stats in plain language. Use when the vibe coder says something like: visitor stats; analytics; track usage."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-blog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-blog
-description: "the builder wants a blog or changelog on their site. Use when the builder says something like: add a blog; write articles; changelog."
+description: "the builder wants a blog or changelog on their site. Use when the vibe coder says something like: add a blog; write articles; changelog."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-crud/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-crud
-description: "scaffold create/read/update/delete routes for a resource. Use when the builder says something like: crud; create read update delete."
+description: "scaffold create/read/update/delete routes for a resource. Use when the vibe coder says something like: crud; create read update delete."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-files/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-files
-description: "users can upload files and images, and see them back in the app. Use when the builder says something like: upload; store files; attachments."
+description: "users can upload files and images, and see them back in the app. Use when the vibe coder says something like: upload; store files; attachments."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-images/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-images
-description: "add logos, hero images, icons, and other pictures that ship with the app (not user uploads). Use when the builder says something like: add my logo; hero image; app icon; add images."
+description: "add logos, hero images, icons, and other pictures that ship with the app (not user uploads). Use when the vibe coder says something like: add my logo; hero image; app icon; add images."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-language/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-language
-description: "make the app speak another language — the builder asks in plain words (\"make it Hebrew\",. Use when the builder says something like: translate my app; add spanish; make it hebrew."
+description: "make the app speak another language — the builder asks in plain words (\"make it Hebrew\",. Use when the vibe coder says something like: translate my app; add spanish; make it hebrew."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-notifications/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-notifications
-description: "the builder's users get notified — by email first; push can come later. Use when the builder says something like: notify users; send alerts."
+description: "the builder's users get notified — by email first; push can come later. Use when the vibe coder says something like: notify users; send alerts."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-realtime/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-realtime
-description: "the builder's app can push live updates to signed-in users. Use when the builder says something like: live updates; real-time; push changes instantly; refresh without reload."
+description: "the builder's app can push live updates to signed-in users. Use when the vibe coder says something like: live updates; real-time; push changes instantly; refresh without reload."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-route
-description: "add a new API endpoint without hand-writing boilerplate. Use when the builder says something like: add an endpoint; add api; new route."
+description: "add a new API endpoint without hand-writing boilerplate. Use when the vibe coder says something like: add an endpoint; add api; new route."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-search
-description: "users can search the builder's data in plain language. Use when the builder says something like: let users search; find things; search my data."
+description: "users can search the builder's data in plain language. Use when the vibe coder says something like: let users search; find things; search my data."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-signin/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-signin
-description: "people can create accounts and log in to the builder's app. Use when the builder says something like: sign in; log in; create accounts; add users."
+description: "people can create accounts and log in to the builder's app. Use when the vibe coder says something like: sign in; log in; create accounts; add users."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-teams/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-teams
-description: "the builder can invite teammates and work in shared organizations. Use when the builder says something like: invite teammates; add my team; organizations."
+description: "the builder can invite teammates and work in shared organizations. Use when the vibe coder says something like: invite teammates; add my team; organizations."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/add-upload/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-upload
-description: "let clients upload files safely. Use when the builder says something like: upload; store files; attachments; file upload endpoint."
+description: "let clients upload files safely. Use when the vibe coder says something like: upload; store files; attachments; file upload endpoint."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/back-up-my-code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: back-up-my-code
-description: "the builder's project is saved on GitHub so they never lose work. Use when the builder says something like: save my code; back up; put it on github."
+description: "the builder's project is saved on GitHub so they never lose work. Use when the vibe coder says something like: save my code; back up; put it on github."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/buy-domain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: buy-domain
-description: "the app uses the builder's own web address instead of a temporary one. Use when the builder says something like: get a domain; buy a web address; my own url."
+description: "the app uses the builder's own web address instead of a temporary one. Use when the vibe coder says something like: get a domain; buy a web address; my own url."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/check-safety/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-safety
-description: "confirm the app is protected end-to-end before ship — abuse, database safety, and every. Use when the builder says something like: am i ready to ship; is my app safe; did we cover security."
+description: "confirm the app is protected end-to-end before ship — abuse, database safety, and every. Use when the vibe coder says something like: am i ready to ship; is my app safe; did we cover security."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/configure-capabilities/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configure-capabilities
-description: "the app has **only the permissions it needs** — the builder never thinks about Info.plist, Android manifest, or Expo plugins. Use when the builder says something like: camera; location permission; notifications permission."
+description: "the app has **only the permissions it needs** — the builder never thinks about Info.plist, Android manifest, or Expo plugins. Use when the vibe coder says something like: camera; location permission; notifications permission."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/connect-account/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: connect-account
-description: "people can create accounts and sign in **inside the app**. Use when the builder says something like: sign in; log in; create accounts; add users; forgot password; reset password."
+description: "people can create accounts and sign in **inside the app**. Use when the vibe coder says something like: sign in; log in; create accounts; add users; forgot password; reset password."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/connect-account-backend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: connect-account-backend
-description: "people can sign in from the phone app or extension. Use when the builder says something like: connect account backend."
+description: "people can sign in from the phone app or extension. Use when the vibe coder says something like: connect account backend."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/design-my-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-my-data
-description: "figure out what the app should remember before wiring storage. Use when the builder says something like: design my database; what data do i need; what should my app remember."
+description: "figure out what the app should remember before wiring storage. Use when the vibe coder says something like: design my database; what data do i need; what should my app remember."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor
-description: "find out why something isn't working and fix it — without making the builder debug. Use when the builder says something like: it's broken; nothing works; get an error; check my app."
+description: "find out why something isn't working and fix it — without making the builder debug. Use when the vibe coder says something like: it's broken; nothing works; get an error; check my app."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/go-live/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: go-live
-description: "the builder's app is online at a real web address that anyone can open. Use when the builder says something like: put it online; publish; make it live; ship it; deploy."
+description: "the builder's app is online at a real web address that anyone can open. Use when the vibe coder says something like: put it online; publish; make it live; ship it; deploy."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/harden/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: harden
-description: "the builder's app is protected against the common attacks every app faces — someone. Use when the builder says something like: lock down; make it safe; protect from abuse."
+description: "the builder's app is protected against the common attacks every app faces — someone. Use when the vibe coder says something like: lock down; make it safe; protect from abuse."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/onboarding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboarding
-description: "take the builder from \"I just bought this\" to **their app running and visible in front of. Use when the builder says something like: set up my app; let's start; get me going; just bought."
+description: "take the vibe coder from \"I just bought this\" to **their app running and visible in front of. Use when the vibe coder says something like: set up my app; let's start; get me going; just bought."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---
@@ -9,7 +9,7 @@ metadata:
 
 # Skill: onboarding
 
-**Goal:** take the builder from "I just bought this" to **their app running and visible in front of
+**Goal:** take the vibe coder from "I just bought this" to **their app running and visible in front of
 them** in this one session. This is the keystone — the moment that proves the purchase was worth it.
 
 **Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
@@ -18,16 +18,16 @@ translate every error · celebrate. Decide all technical choices yourself.
 ## Steps
 
 <!-- vybekiit:page-recipe-install -->
-0. **Install the end-user onboarding recipe when the builder wants a first-run wizard (catalog SSOT — Option C).**
+0. **Install the end-user onboarding recipe when the vibe coder wants a first-run wizard (catalog SSOT — Option C).**
    Copy `apps/componentLibrary/src/pageRecipes/OnboardingPage.tsx` export `OnboardingPage` into the buyer app at route `/onboarding`.
    Recipe id: `onboarding`. Presets: none.
    Keep every `TODO:` in the recipe and wire each one after the route renders.
-   Skip this step if the builder only needs *their* kit setup (steps 1–5 below) and not a product wizard for their users.
+   Skip this step if the vibe coder only needs *their* kit setup (steps 1–5 below) and not a product wizard for their users.
    Also reference `packages/agentKit` `getPageRecipeInstall('onboarding')` / page-recipe-manifest.json.
    **Verify:** if installed, `/onboarding` builds with practice UI.
 
 1. **Welcome + ask the one thing that matters.**
-   Greet warmly. If the builder already described their app, use that description. Otherwise ask:
+   Greet warmly. If the vibe coder already described their app, use that description. Otherwise ask:
    *"In one sentence, what do you want to build?"* Use their answer to tailor the starter page later.
    Keep the conversation about their idea.
 
@@ -41,7 +41,7 @@ translate every error · celebrate. Decide all technical choices yourself.
 
 2. **Set up the tools, then get the preview running.**
    First run `vybekiit doctor` — it installs the tools the app will need (for the database and for
-   putting the app online) so the builder never configures anything. It may say a tool "isn't signed
+   putting the app online) so the vibe coder never configures anything. It may say a tool "isn't signed
    in yet" — that's fine for now; sign-in happens later, only when a step needs it (one browser click
    each). Then install the project's building blocks. Check the URL printed by setup and the
    project's running processes. Reuse a preview only after confirming it serves this app.
@@ -52,7 +52,7 @@ translate every error · celebrate. Decide all technical choices yourself.
    After dependencies install, run **quality smoke** yourself: `pnpm verify` (format, lint, typecheck,
    tests). Confirm `.cursorignore` hides `.env` (doctor checks this). Optionally install UI walkthrough
    browsers: `pnpm exec playwright install chromium` (agent-only — see `playwright-vybekiit.md`).
-   Fix anything red before showing the preview. The builder hears: *"Everything checks out."*
+   Fix anything red before showing the preview. The vibe coder hears: *"Everything checks out."*
    **Verify:** the dev server is up with no errors. If it fails → run `doctor`.
 
    > (Agent-only) **Database MCP tier:** Supabase, Neon, and Firebase use login-once MCP configs
@@ -87,7 +87,7 @@ Stop the steps and run `doctor`. Never show a raw error — say what happened an
 
 ## Definition of done
 
-The builder has seen their own app running and personalized, and knows the next thing they can ask
+The vibe coder has seen their own app running and personalized, and knows the next thing they can ask
 for. Save progress for them (don't make them think about it).
 
 ## After completing this skill
@@ -104,4 +104,4 @@ Update checklist.md Progress (mark done, note next). If checklist.md doesn't exi
 
 Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
 
-If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and 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."*
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the vibe coder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/plan-my-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-my-idea
-description: "help the builder figure out exactly what they want **before** you build — so the first. Use when the builder says something like: help me plan; figure out my idea; think it through; marketplace; like airbnb."
+description: "help the builder figure out exactly what they want **before** you build — so the first. Use when the vibe coder says something like: help me plan; figure out my idea; think it through; marketplace; like airbnb."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/publish-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: publish-app
-description: "the builder's app is **in the App Store and Google Play** for anyone to download. This is. Use when the builder says something like: put it online; publish; make it live; ship it; deploy; publish app."
+description: "the builder's app is **in the App Store and Google Play** for anyone to download. This is. Use when the vibe coder says something like: put it online; publish; make it live; ship it; deploy; publish app."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/publish-extension/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: publish-extension
-description: "the builder's extension is **listed in the Chrome Web Store** for anyone to install. Use when the builder says something like: put it online; publish; make it live; ship it; deploy; chrome store."
+description: "the builder's extension is **listed in the Chrome Web Store** for anyone to install. Use when the vibe coder says something like: put it online; publish; make it live; ship it; deploy; chrome store."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/reset-password/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reset-password
-description: "people who forgot their password can get a reset link and set a new one. Use when the builder says something like: forgot password; reset password; lost password; change password email."
+description: "people who forgot their password can get a reset link and set a new one. Use when the vibe coder says something like: forgot password; reset password; lost password; change password email."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/save-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: save-data
-description: "the app can remember things — save information and read it back later. Use when the builder says something like: save my data; remember this; store info; add a database."
+description: "the app can remember things — save information and read it back later. Use when the vibe coder says something like: save my data; remember this; store info; add a database."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/setup-email/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-email
-description: "the app can send emails — welcome notes, receipts, and sign-in codes. Use when the builder says something like: send emails; email my users; set up email."
+description: "the app can send emails — welcome notes, receipts, and sign-in codes. Use when the vibe coder says something like: send emails; email my users; set up email."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/setup-payments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-payments
-description: "the builder can take real money. By the end, a test purchase succeeds end-to-end. Use when the builder says something like: add payments; take money; sell something; charge people."
+description: "the builder can take real money. By the end, a test purchase succeeds end-to-end. Use when the vibe coder says something like: add payments; take money; sell something; charge people."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/setup-sms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-sms
-description: "text messages (and optional WhatsApp) work for sign-in codes and alerts. Use when the builder says something like: set up sms; text messages; twilio; whatsapp messages; send texts."
+description: "text messages (and optional WhatsApp) work for sign-in codes and alerts. Use when the vibe coder says something like: set up sms; text messages; twilio; whatsapp messages; send texts."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/sign-in-with-email-link/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sign-in-with-email-link
-description: "people can sign in with a one-click email link (no password). Use when the builder says something like: magic link; email link sign in; sign in without password; passwordless email."
+description: "people can sign in with a one-click email link (no password). Use when the vibe coder says something like: magic link; email link sign in; sign in without password; passwordless email."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/sign-in-with-google/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sign-in-with-google
-description: "people can tap **Continue with Google** — one button that signs them in **or** creates. Use when the builder says something like: sign in with google; continue with google."
+description: "people can tap **Continue with Google** — one button that signs them in **or** creates. Use when the vibe coder says something like: sign in with google; continue with google."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/sign-in-with-phone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sign-in-with-phone
-description: "people can sign in with a text message code. Use when the builder says something like: sign in with phone; text me a code; sms login; phone number login."
+description: "people can sign in with a text message code. Use when the vibe coder says something like: sign in with phone; text me a code; sms login; phone number login."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/track-errors/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: track-errors
-description: "the builder gets alerted when something breaks in their live app — without watching logs themselves. Use when the builder says something like: tell me when things break; error alerts; app crashes."
+description: "the builder gets alerted when something breaks in their live app — without watching logs themselves. Use when the vibe coder says something like: tell me when things break; error alerts; app crashes."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/update-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update-kit
-description: "get the latest kit improvements safely, without breaking the builder's app. Use when the builder says something like: update the kit; get the latest; upgrade."
+description: "get the latest kit improvements safely, without breaking the builder's app. Use when the vibe coder says something like: update the kit; get the latest; upgrade."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/validate-my-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: validate-my-idea
-description: "test whether people want an offer before building the full product. Use when the builder says something like: validate my idea; test demand; start a waitlist; test my offer."
+description: "test whether people want an offer before building the full product. Use when the vibe coder says something like: validate my idea; test demand; start a waitlist; test my offer."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/vybekiit-feedback/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vybekiit-feedback
-description: "send a private note about VybeKiit so the team can improve the kit. Use when the builder says something like: send feedback; report a kit bug; suggest a kit improvement; the kit is confusing."
+description: "send a private note about VybeKiit so the team can improve the kit. Use when the vibe coder says something like: send feedback; report a kit bug; suggest a kit improvement; the kit is confusing."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/watch-my-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: watch-my-app
-description: "the builder knows whether their online app is healthy and gets a safe repair note when it is not. Use when the builder says something like: watch my app; check if my app is working; tell me when my app is down."
+description: "the builder knows whether their online app is healthy and gets a safe repair note when it is not. Use when the vibe coder says something like: watch my app; check if my app is working; tell me when my app is down."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/wire-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wire-auth
-description: "people can sign in through this API (mobile/extension clients call these routes). Use when the builder says something like: sign in; log in; create accounts; add users; wire auth."
+description: "people can sign in through this API (mobile/extension clients call these routes). Use when the vibe coder says something like: sign in; log in; create accounts; add users; wire auth."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/wire-database/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wire-database
-description: "the server remembers things persistently. Use when the builder says something like: save my data; remember this; store info; add a database; wire database."
+description: "the server remembers things persistently. Use when the vibe coder says something like: save my data; remember this; store info; add a database; wire database."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/wire-email/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wire-email
-description: "send emails from the API. Use when the builder says something like: send emails; email my users; set up email; wire email."
+description: "send emails from the API. Use when the vibe coder says something like: send emails; email my users; set up email; wire email."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/wire-payments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wire-payments
-description: "the API can process payments for mobile/extension clients. Use when the builder says something like: add payments; take money; sell something; charge people; wire payments."
+description: "the API can process payments for mobile/extension clients. Use when the vibe coder says something like: add payments; take money; sell something; charge people; wire payments."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vybekiit",
-  "version": "0.7.27",
+  "version": "0.7.28",
   "description": "Choose your services, sign in, create a VybeKiit app, and open its verified local welcome page.",
   "license": "MIT",
   "publishConfig": {
@@ -33,13 +33,13 @@
     "typescript": "5.7.2",
     "vitest": "3.2.6",
     "@effect/vitest": "0.29.0",
-    "@vybekiit/agent-mcp": "0.7.27",
-    "@vybekiit/agent-kit": "0.7.27",
-    "@vybekiit/db": "0.7.27",
-    "@vybekiit/core": "0.7.27",
-    "@vybekiit/deploy": "0.7.27",
-    "@vybekiit/report-mode": "0.7.27",
-    "@vybekiit/payments": "0.7.27"
+    "@vybekiit/agent-kit": "0.7.28",
+    "@vybekiit/core": "0.7.28",
+    "@vybekiit/deploy": "0.7.28",
+    "@vybekiit/agent-mcp": "0.7.28",
+    "@vybekiit/payments": "0.7.28",
+    "@vybekiit/db": "0.7.28",
+    "@vybekiit/report-mode": "0.7.28"
   },
   "scripts": {
     "build": "tsup && node scripts/bundleGlobalSkills.mjs",