vybekiit 0.7.26 → 0.7.28

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
 ---