vybekiit 0.7.27 → 0.7.29

package/dist/global-skills/vybekiitReferences/extension/agent/ui-sources.md

@@ -0,0 +1,30 @@
+# UI source catalog — extension (agent-only)
+
+Same catalog and rules as the web template — WXT + shadcn + `@vybekiit/tokens`.
+
+Read `../web/.vybekiit/agent/ui-sources.md` for the full approved source table, mirrored namespaces, and the VybeKiit UI catalog tools (in `mcp-agent.json`, server `vybekiit`).
+
+Popup/options UI uses `src/components/ui/*` when the extension scaffold ships. Normalize every third-party block before merge.
+
+<!-- vybekiit:generated:start web-ui-sources -->
+# Approved UI block sources
+
+| Source | Best for | Install | Notes |
+|---|---|---|---|
+| [shadcn/ui](https://ui.shadcn.com) | Core primitives, forms, dialogs | npx shadcn@latest add <component> | Default foundation — always prefer over duplicates |
+| [BundUI / Shadcn UI Kit](https://shadcnuikit.com/components) | 503+ free shadcn variants, blocks, admin patterns | npx shadcn@latest add @bundui/<name> | Mirror in components/bundui/; normalize controls to kit primitives |
+| [Magic UI](https://magicui.design) | Animated marketing, marquees, beams, bento | npx shadcn@latest add @magicui/<name> | Mirror in components/magicui/; normalize buttons/inputs to kit primitives |
+| [Kokonut UI](https://kokonutui.com) | Interactive marketing, modern layouts | npx shadcn@latest add @kokonutui/<name> | Mirror in components/kokonutui/; shadcn + Motion; strip custom button sizes |
+| [21st.dev](https://21st.dev) | Community blocks, agent templates | npx shadcn add <registry-url> | Mirror curated blocks in components/blocks/21st/; reject blocks that bypass primitives |
+| [Origin UI](https://originui.com) | Extra shadcn-style primitives | Registry CLI | Merge into src/components/ui/ once |
+| [Aceternity UI](https://ui.aceternity.com) | High-motion landing sections | npx shadcn@latest add https://ui.aceternity.com/registry/<name>.json | Mirror in components/aceternity/; free tier only; no OSS GitHub |
+| [Untitled UI React](https://www.untitledui.com/react) | Enterprise admin, dense application UI | npx untitledui@latest add <name> | Mirror in components/untitled/; React Aria — never merge into ui/ |
+| [Gluestack UI](https://gluestack.io/ui) | Cross-platform patterns (web mirror only in VybeKiit) | npx gluestack-ui@latest add <name> | Mirror web subset in components/gluestack/; mobile ports via kit StyleSheet only |
+| [Cult UI](https://cult-ui.com) | AI chat / agent UI patterns | Copy-paste / registry | Map to kit forms |
+| [Tailark](https://tailark.com) | Marketing blocks, conversion layouts | Copy-paste / registry | Keep token colors |
+| [Tremor](https://tremor.so) | Dashboards, KPI cards, charts | npm @tremor/react or blocks | Dashboard-only; wrap in kit Card |
+| [shadcn/ui Charts](https://ui.shadcn.com/charts) | Charts (Recharts) | npx shadcn@latest add chart | Preferred over random chart libs |
+| [shadcn.io blocks](https://shadcn.io/blocks) | Large block marketplace | Registry browse | Normalize before merge |
+| [Shadcnblocks](https://shadcnblocks.com) | Figma-aligned blocks | Registry / copy | Free blocks OK; paid agent-only |
+| [ReUI / Skiper UI / MynaUI](https://reui.io) | Additional shadcn-style sets | Registry | Secondary when official shadcn lacks a pattern |
+<!-- vybekiit:generated:end web-ui-sources -->

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

@@ -0,0 +1,433 @@
+# 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 the backend needs (not in the add-on) |
+| `.env` file | your secret settings file (on the backend) | secrets live on the web app, not in the browser add-on |
+| backend / API | your web app / your app's online brain | where sign-in, data, and payments actually happen |
+| deploy / deployment | put your app online / make it live | the web app must be live before the add-on can talk to it |
+| database | where your app remembers things | nothing is saved without the backend |
+| webhook | an automatic message between services | how a payment tells the app "they paid" |
+| repository / repo / git | your project's 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 |
+| API key / token | an access key / a password for a service | proves the backend is allowed to use a service |
+| authentication / auth | letting people sign in | so users have their own accounts |
+| dependency / package | a building block I'm adding | a ready-made piece so we don't rebuild it |
+
+## The browser add-on
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| Chrome extension / browser extension | the browser add-on | what people install in their browser |
+| manifest | the add-on's ID card | tells the browser what the add-on can do |
+| permissions | what the add-on is allowed to touch | you explain each in plain words before asking |
+| popup | the little window when they click the icon | the main screen of the add-on |
+| side panel | the panel that slides in from the side | another way to show the add-on's UI |
+| content script | the part that runs on web pages | lets the add-on read or change a page when needed |
+| background / service worker | the part that runs in the background | keeps the add-on working even when closed |
+| unpacked / load unpacked | preview / try it locally | load the add-on on their computer for testing |
+| extension store / Chrome Web Store | the extension store | where people find and install add-ons |
+| developer registration | your extension-store account | the account required to publish (the agent handles setup) |
+| MV3 / Manifest V3 | (don't say — use "browser add-on") | internal version label — invisible to the vibe coder |
+
+## 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 |
+
+## Money
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| checkout | the payment page | where the customer actually pays (on the backend) |
+| hosted checkout | the secure payment page we open in the browser | the simplest, safest way to take money |
+| Merchant of Record / MoR | the service that handles tax for you | removes VAT/sales-tax fear |
+| 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 |
+
+## Data & files (on the backend)
+
+| 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 |
+| transactional email | the emails your app sends automatically | receipts, sign-in codes, confirmations |
+
+## Building blocks (rarely needed, but translate if it slips out)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| SDK | a service's official toolkit | the proper way I connect to a service |
+| framework | the foundation your add-on is built on | the base I build everything on top of |
+| build | getting your add-on ready to preview | packaging their work so the browser can load it |
+| 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 |
+| endpoint | one address your backend can talk to | one specific thing the web app can do |
+| client | the add-on running in someone's browser | what the user actually sees and clicks |
+| frontend | the part people see and click | the popup, panel, and pages |
+| server | the always-on backend running your web app | where data and sign-in live |
+
+## 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 add-on's starting point | the moment a blank folder becomes their add-on |
+| 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 project runs straight away on practice data — no accounts, no setup needed. The
+> practice data lives on the web app behind the add-on, the same place a real one will later.
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| local / in-memory data | practice data on your computer | temporary info so things work 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 signed-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)
+
+> This lives on the web app behind the add-on (the add-on never holds secrets — see "Core" above).
+
+| 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 things feel fast for the people who use it |
+| service-role key | the master key (kept secret, server-only) | the powerful key only the web app's behind-the-scenes part may ever hold |
+| anon / public key | the public key | the safe-to-share key the add-on's screens use |
+| 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 web app at its real storage |
+
+## Safety & sign-in
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| chrome.identity | Chrome handles your Google login | the browser's built-in sign-in |
+| Continue with Google | sign in or sign up with Google | one tap from the extension |
+| rate limit | protection on your backend | the extension talks to a protected server |
+
+## 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) | on the backend project, not in the add-on |
+| locale | the user's language and region | so the add-on speaks each person'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 add-on 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
+builder.** They chose a goal, not a technology — you pick the service and keep it invisible.
+
+- Never say **Chrome, WXT, MV3, Google, Supabase, MongoDB, AWS, Cloudflare, Vercel, Wrangler,
+  Stripe, PayPal, Lemon Squeezy, Better Auth, Resend, GitHub** (or any other provider name). Say
+  **"the browser add-on"**, **"the extension store"**, **"your web app"**, **"your database"**,
+  **"your email"**, **"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 add-on already
+mirrors its layout automatically for RTL users — you don't need to do anything special for that.
+
+<!-- vybekiit:generated:start tone -->
+## Tone
+
+<!-- source: @vybekiit/agent-kit renderToneSection() — keep in sync -->
+
+- Warm, confident, brief. You're the expert handling the hard parts.
+- Give the buyer one manual step at a time. Continue work you can do yourself.
+- Always end a manual step by telling them **exactly** what to click/copy and what you'll do next.
+- Celebrate verified wins. Vocabulary describes actions; it never proves completion. Inspect before saying work is saved, connected, checked, or online.
+- **No em dashes (`—`).** They read like AI filler. In chat and body copy, use a period, comma, colon, or parentheses instead. **UI titles, nav labels, and section headings:** short phrases only; no em dash and no trailing period, comma, or ellipsis. Split into two lines or two i18n keys instead. Hyphens in compound words (`build-time`) are fine.
+<!-- vybekiit:generated:end tone -->
+
+<!-- vybekiit:generated:start sdlc-vocabulary -->
+## Quality and saving your work
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| test / unit test | check that it works | reassures them without test-suite vocabulary |
+| TDD / tests-first | *(agent-internal — never say)* | agent-internal — never say |
+| linter / formatter / Biome | tidying the code | usually invisible; only mention if they ask why you paused |
+| quality smoke / typecheck | check the app for problems | onboarding and pre-ship reassurance |
+| pull request / PR | a safe copy for the checker to review | when saving via branch before merge |
+| CI / GitHub Actions | the automatic checker online | never name GitHub Actions |
+| CD / deploy pipeline | putting updates online automatically | only if they overhear pipeline talk |
+| Playwright / E2E / headless browser | check the app like a visitor would | UI walkthrough without tool names |
+| back up / save progress online | save a copy online | never say GitHub — stays in service ban list |
+| worktree | *(agent-internal — never say)* | agent-internal — never say |
+| husky / hook / pre-push | *(agent-internal — never say)* | agent-internal — never say |
+<!-- vybekiit:generated:end sdlc-vocabulary -->
+
+<!-- vybekiit:generated:start ui-vocabulary -->
+## UI building blocks
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| navbar / header / top nav | the top menu | matches what they see at the top of the screen |
+| sidebar / side nav | the side menu | matches what they see along the side |
+| admin dashboard / dashboard | your dashboard / signed-in area | the part only logged-in users see |
+| cloud / hosting / serverless | your app's home online | where the live app runs — never name the provider |
+| analytics | visitor stats | who uses the app without analytics jargon |
+| SEO | how search engines find you | discoverability in plain words |
+| GEO / JSON-LD / structured data | extra details search engines read | structured metadata without crawler jargon |
+| streaming (AI) | the reply appears word by word | explains live AI text without "streaming" |
+| chat with AI / AI chat | talk to the assistant inside your app | in-app AI without product names |
+| sign in / log in | sign in | explicit row — complements "authentication / auth" |
+| deeplink / URI scheme | I sent that to your assistant | Report Mode handoff — never expose URL schemes |
+| Report mode / inspect mode | point at what's wrong | only if they ask about the hotkey overlay |
+<!-- vybekiit:generated:end ui-vocabulary -->
+
+<!-- vybekiit:generated:start tool-vocabulary -->
+## Your assistant (never name the tool)
+
+| Don't say (jargon) | Say instead (plain) | Why it matters to them |
+|---|---|---|
+| Claude Code / Codex / Cursor | your assistant | they picked an outcome, not a tool — naming the product breaks the "I just talk to one helper" feel |
+| the CLI / the terminal / the command line | the part I work in (you don't need to touch it) | the black text screen is mine to drive; surfacing it invites them to poke and get stuck |
+| the IDE / the editor | where your app is being built | the window they have open — call it by what it does, not its product name |
+| agent / the model / the LLM | me / your assistant | they are talking to one helper, not a "model" — keep it personal and singular |
+| prompt | what you tell me / your request | their plain words to me — never frame it as a technical input they must craft |
+| context window | how much I can keep in mind at once | why I sometimes recap or ask them to confirm where we are — not a setting they manage |
+| rules file / AGENTS.md / 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/vybekiitReferences/extension/platform-skills/README.md

@@ -0,0 +1,32 @@
+# Platform skills — extension template (agent-only)
+
+Layer B execution knowledge. Chrome Extension API docs are source of truth — no custom WXT skill yet.
+
+## Official upstream
+
+- Chrome Extension APIs: https://developer.chrome.com/docs/extensions
+- Manifest V3: https://developer.chrome.com/docs/extensions/mv3/intro/
+- Chrome Web Store: https://developer.chrome.com/docs/webstore
+- WXT (framework): https://wxt.dev — reference only in wrapper until official skills exist
+- Publish automation: `@vybekiit/browser-automation` (`extension` / `cws` domain)
+
+## Wrapper index
+
+| Wrapper | Invoked by buyer skill |
+|---|---|
+| `chrome-extension-vybekiit.md` | all extension work + `publish-extension` |
+| `code-hygiene-vybekiit.md` | generic coding (invisible) |
+| `planning-vybekiit.md` | `plan-my-idea` |
+| `observability-vybekiit.md` | generic coding + `track-errors` |
+| `sentry-vybekiit.md` | `track-errors` |
+| `ui-consistency-vybekiit.md` | generic UI work |
+| `testing-vybekiit.md` | generic coding (invisible) |
+| `format-lint-vybekiit.md` | generic coding (invisible) |
+| `react-patterns-vybekiit.md` | generic coding (invisible) |
+| `responsive-vybekiit.md` | popup / options UI layouts |
+| `github-vybekiit.md` | `back-up-my-code` |
+| `playwright-vybekiit.md` | UI walkthrough (when scaffold ships) |
+| `ci-vybekiit.md` | push / PR flow (invisible) |
+| `ship-via-pr-vybekiit.md` | save progress |
+| `i18n-vybekiit.md` | generic UI / `add-language` | Chrome `_locales/` + `lib/i18n.ts` |
+| `env-secrets-vybekiit.md` | secret handling |

package/dist/global-skills/vybekiitReferences/extension/platform-skills/browser-automation-vybekiit.md

@@ -0,0 +1,36 @@
+# Platform wrapper: browser automation
+
+**Agent-only.** Dashboard Playwright CLI for providers without API or MCP coverage.
+
+## Package
+
+`@vybekiit/browser-automation` — bin: **`vybekiit-automate`**
+
+| Target | Profile | Purpose |
+|--------|---------|---------|
+| `ls` | `$HOME/.ls-chrome-profile` | Lemon Squeezy (fresh-squeezy) |
+| `cws` | `$HOME/.cws-chrome-profile` | Chrome Web Store extension publish |
+
+## CLI modes
+
+**Agent mode** — non-interactive, structured stdout:
+
+```bash
+vybekiit-automate ls setup --json --name "Pro" --price-cents 2900 --mode test --webhook-url "https://…"
+vybekiit-automate ls standby --json
+vybekiit-automate cws publish --json   # CWS verbs also exported programmatically
+```
+
+Flags: `--json` (never prompt), `--yes` (skip confirms), `CI=1` or non-TTY requires all flags.
+
+**Wizard mode** — TTY + missing flags → `@clack/prompts` interactive flow.
+
+## Rules
+
+- **Blind navigation only** — selectors/DOM; never send dashboard screenshots to the model
+- Builder **signs in only** for LS; agent runs all other steps
+- Never say "Playwright", "DOM", "browser automation", or "fresh-squeezy" to the builder
+
+## Legacy
+
+None — `@vybekiit/browser-automation` is the sole SSOT.

package/dist/global-skills/vybekiitReferences/extension/platform-skills/chrome-extension-vybekiit.md

@@ -0,0 +1,28 @@
+# Platform wrapper: Chrome extension (WXT + MV3)
+
+**Agent-only.** Follow for all extension implementation and `publish-extension` buyer skill steps.
+
+## Official upstream (source of truth — prefer over training data)
+
+- Extension platform: https://developer.chrome.com/docs/extensions
+- Manifest V3: https://developer.chrome.com/docs/extensions/mv3/intro/
+- Permissions: https://developer.chrome.com/docs/extensions/mv3/declare_permissions/ — **least privilege**
+- Messaging: https://developer.chrome.com/docs/extensions/mv3/messaging/
+- Chrome Web Store publish: https://developer.chrome.com/docs/webstore/publish/
+- WXT framework docs: https://wxt.dev (scaffold/build only — API facts from Chrome docs)
+
+## Kit wiring
+
+1. Template uses **WXT + shadcn** (shared with web); UI reads `@vybekiit/tokens`
+2. Request **minimum host permissions** — default template uses narrow patterns only
+3. Sign-in, data, payments: extension calls the builder's **backend web app** (same as mobile) — no secrets in the extension bundle
+4. **Google sign-in:** use [`chrome.identity`](https://developer.chrome.com/docs/extensions/reference/api/identity) — `getAuthToken` or `launchWebAuthFlow`. OAuth client id in manifest [`oauth2`](https://developer.chrome.com/docs/extensions/mv3/manifest/oauth2/) — never secrets in code
+5. Store publish: `@vybekiit/browser-automation` + `vybekiit-automate extension …` + listing SSOT in `.vybekiit/store/extension/cws-listing.ts`
+6. Re-sync live store: `vybekiit-automate extension import --json` after setting `chromeWebStoreId` in `.vybekiit/store/extension/cws.json`
+7. Capabilities: run `configure-capabilities` skill when adding features — least privilege, invisible to builder
+
+## Verify-before-advance
+
+- Extension loads unpacked in Chrome without console errors
+- Permissions match declared manifest only
+- After publish verb: listing visible in CWS developer dashboard

package/dist/global-skills/vybekiitReferences/extension/platform-skills/ci-vybekiit.md

@@ -0,0 +1,26 @@
+# Platform wrapper: online checker / CI (agent-only)
+
+**Agent-only.** The buyer repo's GitHub Actions workflow — builder hears *"the automatic checker online"*.
+
+## What runs
+
+File: `.github/workflows/ci.yml`
+
+- **Matrix:** ubuntu-latest, macos-latest, windows-latest
+- **Steps:** `pnpm install --frozen-lockfile` → `pnpm verify` (same as local pre-push)
+- **Playwright:** ubuntu job only, when the template ships UI walkthrough tests
+- **Cache:** `setup-node` with `cache: pnpm` — key includes lockfile hash automatically
+
+## Agent responsibilities
+
+1. Fix red CI before merging a PR — never tell the builder to read workflow logs; translate to one plain fix.
+2. When opening PRs (`ship-via-pr-vybekiit.md`), wait for all three OS jobs green before `gh pr merge`.
+3. Optional: enable branch protection requiring CI pass — use `gh` if the builder's account allows.
+
+## Pre-push alignment
+
+Local `.husky/pre-push` runs the same `pnpm verify` (+ optional e2e) so pushes rarely fail CI.
+
+## Verify
+
+All matrix jobs green on the PR before merge.

package/dist/global-skills/vybekiitReferences/extension/platform-skills/client-state-vybekiit.md

@@ -0,0 +1,25 @@
+# Platform wrapper: client state (agent-only)
+
+**Templates use `@vybekiit/client-state` for all server-backed reads/writes on the client.**
+
+## Surfaces
+
+| Surface | API cache | UI-only prefs |
+|---------|-----------|---------------|
+| web | TanStack Query | Zustand via `createUiStore()` |
+| mobile | TanStack Query + optional MMKV persist | MMKV via `useStorage` |
+| extension | TanStack Query | Zustand / localStorage |
+
+## Rules
+
+- **Do:** `useQuery` / `useMutation` for API data; `useStorage` for wizard step, sidebar, drafts
+- **Don't:** raw `fetch` + `useState` for server records; Zustand/MMKV for server data
+- **Don't:** Redis or server-side cache for buyers — client cache handles UX
+
+## Config (agent-only)
+
+`CLIENT_STATE_PERSIST=on|off`, `CLIENT_STATE_QUERY_STALE_SECONDS` — read silently from `.env`.
+
+## Bootstrap
+
+Each template wraps root layout with `ClientStateProvider` from `src/lib/client-state.tsx`.