vybekiit 0.7.27 → 0.7.29

package/dist/global-skills/vybekiitReferences/web/platform-skills/sentry-vybekiit.md

@@ -0,0 +1,33 @@
+# Platform wrapper: Sentry (agent-only)
+
+**Agent-only.** Invoked by buyer skill `track-errors` — not a buyer-facing name.
+
+## Official upstream
+
+- Docs: https://docs.sentry.io/platforms/javascript/guides/nextjs/
+- Package: `@vybekiit/observability` (Sentry adapter via `@sentry/core`)
+- Pinned skills: `.agents/skills/sentry-sdk-setup/SKILL.md`, `.agents/skills/sentry-workflow/SKILL.md`
+
+## Kit wiring
+
+1. Set in `.env`:
+   - `OBSERVABILITY_PROVIDER="sentry"`
+   - `SENTRY_DSN="<from Sentry dashboard>"`
+2. Confirm `instrumentation.ts` exists (calls `resolveObservabilityProvider`).
+3. Confirm `src/lib/observability.ts` exports the provider.
+4. Add a dev-only test route or button that throws once; verify alert in Sentry dashboard.
+5. Wire `app/global-error.tsx` or route error boundaries to call `observability.captureException`.
+
+## Builder manual step (one at a time)
+
+1. Open the Sentry project the agent created (or have them sign up at sentry.io).
+2. Copy the **DSN** from Project Settings → Client Keys.
+3. Paste when the agent asks — never paste into chat.
+
+## Verify-before-advance
+
+Trigger test error → Sentry shows the event → tell builder "You'll get an email when something breaks."
+
+## Mobile
+
+Same `@vybekiit/observability` interface; Expo uses Sentry React Native SDK when the mobile track-errors skill runs — follow Expo Sentry docs for native init if needed beyond the headless provider.

package/dist/global-skills/vybekiitReferences/web/platform-skills/seo-vybekiit.md

@@ -0,0 +1,31 @@
+# seo-vybekiit
+
+Use `resolveSeoProvider()` from `@vybekiit/seo` — see package README and ADR-0012.
+
+Canonical GEO/SEO patterns: `docs/positioning/seo-geo-plan.md` (maintainer repo).
+
+## Buyer app wiring
+
+| Surface | Location |
+|---|---|
+| Metadata + OG | `src/lib/seo.ts` → `buildPageMetadata()`, `buildBlogGeo()` |
+| JSON-LD | `src/components/vybe-json-ld.tsx` + `buildJsonLdBlogPosting()` / `buildJsonLdFaq()` |
+| llms.txt | `app/llms.txt/route.ts` → `buildLlmsTxt()` |
+| Sitemap | `app/sitemap.ts` — static paths + CMS blog slugs |
+| Internal links | `suggestInternalLinks(hub, spokes)` — hub `/blog`, spokes per post |
+
+## GEO / answer-engine optimization
+
+Structure pages so ChatGPT, Perplexity, Claude, and Google AI Mode can cite them:
+
+1. **Answer-first** — direct answer in the first 100–150 words before elaboration.
+2. **FAQ blocks** — natural-language H3 questions; emit `FAQPage` JSON-LD via `buildJsonLdFaq()`.
+3. **Article posts** — `type: 'article'` metadata + `BlogPosting` JSON-LD on `/blog/[slug]`.
+4. **llms.txt** — curated page list at `/llms.txt`; pointer to `/llms-full.txt` for extended docs.
+5. **Hub-spoke links** — blog index links to every post with keyword-rich anchors (not "click here").
+6. **Open Graph** — `buildOpenGraph()` + `toNextMetadata()` for share cards and crawler context.
+
+## Maintainer landing only (not buyer template)
+
+- Bing / Brave Webmaster submission — manual, Wave B.
+- Neutral competitor `/compare` spoke pages — marketing content on `apps/landing`.

package/dist/global-skills/vybekiitReferences/web/platform-skills/ses-vybekiit.md

@@ -0,0 +1,19 @@
+# Platform wrapper: AWS SES (opt-in email)
+
+**Agent-only.** Invoked by buyer skill `setup-email` when `EMAIL_PROVIDER=ses`.
+
+## Official upstream
+
+- Docs: https://docs.aws.amazon.com/ses/
+
+## Kit wiring
+
+1. Email via `@vybekiit/email` → `resolveEmailProvider()` when `EMAIL_PROVIDER=ses`
+2. Set AWS credentials and verified sender domain/address in `.env`
+3. Wire sending through the provider interface; hook into sign-in codes, welcome, receipts as needed
+4. Replace any `TODO(vybekiit): … — skill: setup-email` markers
+
+## Verify-before-advance
+
+- Send test email to builder; confirm arrival (check spam)
+- Sender domain verified in the provider console before go-live

package/dist/global-skills/vybekiitReferences/web/platform-skills/shadcn-vybekiit.md

@@ -0,0 +1,25 @@
+# Platform wrapper: shadcn/ui (web template)
+
+**Agent-only.** Invoked when building or editing UI — not a buyer goal skill.
+
+## Official upstream
+
+- Docs: https://ui.shadcn.com
+- MCP: shadcn/ui component search at edit time when available
+- **VybeKiit catalog MCP:** UI catalog tools in `.vybekiit/agent/mcp-agent.json` (server `vybekiit`) — search 474+ mirrored blocks across BundUI, Magic UI, Kokonut, Aceternity, Untitled, Gluestack
+- Block catalog: `.vybekiit/agent/ui-sources.md`
+- Intent routing: `ui-routing-vybekiit.md`
+
+## Kit conventions
+
+- Full shadcn base primitive set is pre-installed in `src/components/ui/` (including sidebar, table, form, etc.)
+- Signed-in dashboard chrome uses shadcn `Sidebar` via `src/components/app-sidebar.tsx` and `dashboard-shell.tsx`
+- Use existing primitives and shared shells — do not add a second design system
+- Read colors/spacing from CSS variables backed by `@vybekiit/tokens`
+- Forms: reuse `FormField` and shared error patterns from the template
+- Third-party blocks: **normalize on import** — see `ui-consistency-vybekiit.md`
+- Mirrored namespaces are read-only upstream copies — refresh with maintainer `pnpm sync:ui`
+
+## Verify-before-advance
+
+Visual change → confirm in dev preview; run component tests if present; grep for raw `<button` outside composed screens.

package/dist/global-skills/vybekiitReferences/web/platform-skills/ship-via-pr-vybekiit.md

@@ -0,0 +1,49 @@
+# Platform wrapper: ship via PR (agent-only)
+
+**Agent-only.** Save work through a safe branch + online checker — use when changes are large or the builder is waiting.
+
+## When
+
+- After meaningful progress and `back-up-my-code` already created a remote
+- Builder is impatient — use a **git worktree** so main stays runnable while you work in parallel
+- Before merging to `main`, CI must be green on all three OS jobs (`ci-vybekiit.md`)
+
+## Flow
+
+1. **Worktree (optional, parallel work):**
+   ```bash
+   git worktree add ../my-app-feature feature/save-progress
+   cd ../my-app-feature
+   ```
+
+2. **Branch + commit:**
+   ```bash
+   git checkout -b feature/save-progress
+   git add -A
+   git commit -m "Save progress"
+   ```
+
+3. **Push + open PR:**
+   ```bash
+   git push -u origin HEAD
+   gh pr create --title "Save progress" --body "Agent checkpoint — checks running."
+   ```
+
+4. **Wait for CI** — all ubuntu/macOS/Windows jobs green (`gh pr checks --watch`).
+
+5. **Merge when green:**
+   ```bash
+   gh pr merge --squash --delete-branch
+   ```
+
+6. Tell the builder in plain words: *"Your latest work is saved and checked."*
+
+## Rules
+
+- Never expose PR, worktree, or branch jargon — see `language.md`.
+- Pre-push hook runs before push; fix locally first.
+- Never merge red CI — fix and push again.
+
+## Verify
+
+PR merged · `main` green on GitHub · builder hears one plain success line

package/dist/global-skills/vybekiitReferences/web/platform-skills/stripe-vybekiit.md

@@ -0,0 +1,26 @@
+# Platform wrapper: Stripe (opt-in payments)
+
+**Agent-only.** Invoked by buyer skill `setup-payments` when `PAYMENTS_PROVIDER=stripe`.
+
+## Official upstream
+
+- Docs: https://docs.stripe.com
+- API reference: https://docs.stripe.com/api
+- Stripe MCP: https://docs.stripe.com/mcp
+- Pinned skill: `.agents/skills/stripe-best-practices/SKILL.md`
+
+## Kit wiring
+
+1. Merge `agent/mcp-stripe.json` into buyer MCP config — see `agent/mcp-setup.md` (Cursor, Claude Desktop, Codex)
+2. Builder completes Stripe OAuth once when prompted by MCP
+3. Agent creates product + price via Stripe MCP write tools; write restricted `STRIPE_SECRET_KEY` and webhook secret to `.env`
+4. Payments via `@vybekiit/payments` → `resolvePaymentProvider()` when `PAYMENTS_PROVIDER=stripe`
+5. Webhook route at `app/api/webhook/route.ts`; fulfillment in `src/lib/fulfillment.ts`
+6. Replace `TODO(vybekiit): … — skill: setup-payments` markers
+7. **Note:** Stripe is not Merchant of Record — explain tax handling in plain words if the builder asks
+
+## Verify-before-advance
+
+- MCP connected; test mode product/price visible in Stripe
+- Test checkout opens; webhook receives `checkout.session.completed` (test mode OK)
+- Order recorded; builder sees success in app

package/dist/global-skills/vybekiitReferences/web/platform-skills/supabase-vybekiit.md

@@ -0,0 +1,31 @@
+# Platform wrapper: Supabase (default data)
+
+> Agent-only: follow the Persistent features sequence in `.vybekiit/agent/session-bootstrap.md`. Reuse the relevant catalog presets before adding app-owned extensions, and record structural and behavioral evidence separately.
+
+**Agent-only.** Invoked by buyer skills `save-data`, `doctor`, and prerequisites for `add-signin`.
+
+## Official upstream
+
+- Docs: https://supabase.com/docs
+- Supabase MCP: https://supabase.com/docs/guides/ai-tools/mcp
+- CLI: `supabase` (installed by `vybekiit doctor`)
+- Pinned skills: `.agents/skills/supabase/SKILL.md`, `.agents/skills/supabase-postgres-best-practices/SKILL.md`
+
+## Kit wiring
+
+1. Merge `agent/mcp-supabase.json` into buyer MCP config — see `agent/mcp-setup.md` (Cursor, Claude Desktop, Codex)
+2. Builder completes Supabase OAuth once when MCP prompts on first use
+3. Data access via `@vybekiit/db` → `resolveDataProvider()` — never direct Supabase client in UI
+4. After `supabase login`, agent runs programmatic project create (see `doctor` / onboarding)
+5. Write `SUPABASE_URL`, `SUPABASE_ANON_KEY`, service role to `.env`
+6. Migrations under `infra/`; RLS reviewed; service role server-side only
+7. For auth: also set `DATABASE_URL` (Postgres connection) for better-auth — see `better-auth-vybekiit.md`
+
+Optional: scope MCP URL with `?project_ref=…&read_only=true` per Supabase security guidance.
+
+## Verify-before-advance
+
+- MCP connected (list tables or run a read query)
+- `supabase projects list` works after login
+- `pingDatabase()` from `@vybekiit/db` succeeds
+- Migration applied; test read/write path green

package/dist/global-skills/vybekiitReferences/web/platform-skills/tenancy-vybekiit.md

@@ -0,0 +1,3 @@
+# tenancy-vybekiit
+
+Use `resolve*Provider()` from `@vybekiit/tenancy` — see package README and ADR-0012.

package/dist/global-skills/vybekiitReferences/web/platform-skills/testing-vybekiit.md

@@ -0,0 +1,33 @@
+# Platform wrapper: testing (agent-only)
+
+**Agent-only.** Run tests with every feature — the builder never hears "vitest" or "unit test."
+
+## When
+
+Every new feature, bug fix, API route change, or hook change.
+
+## How
+
+- **Runner:** `pnpm test` (Vitest)
+- **Web:** React Testing Library for components; test files live in `src/**/__tests__/`
+- **Patterns:** follow existing tests in `src/lib/__tests__/`, `src/hooks/__tests__/`, `src/components/__tests__/`
+
+## Rules
+
+1. Test **behavior users care about** — form submit succeeds, auth error shows, checkout redirects.
+2. No `toBeDefined()` theater — assert outcomes, not existence.
+3. Mock network at the client boundary (`fetch-json`, auth/billing clients), not deep kit internals.
+4. Run `pnpm test` **before** telling the builder something works.
+
+## Also read
+
+- `nextjs-vybekiit.md` — App Router + API route patterns
+- `react-patterns-vybekiit.md` — hooks and forms to test
+
+## Verify
+
+```bash
+pnpm test
+```
+
+Green before "done."

package/dist/global-skills/vybekiitReferences/web/platform-skills/ui-consistency-vybekiit.md

@@ -0,0 +1,34 @@
+# Platform wrapper: UI consistency (agent-only)
+
+**Agent-only.** Professional, symmetric UI — not a buyer goal skill.
+
+## Catalog
+
+Web/extension: `.vybekiit/agent/ui-sources.md` · routing: `ui-routing-vybekiit.md`  
+Mobile: `.vybekiit/agent/ui-sources.mobile.md` · porting: `ui-port-from-web-vybekiit.md`
+
+## Non-negotiable contract
+
+1. **Primitive-first** — `Button`, `Input`, `Card`, … from `src/components/ui/` for standard controls in buyer screens
+2. **Namespace mirrors** — upstream copies live in `bundui/`, `magicui/`, `kokonutui/`, `aceternity/`, `untitled/`, `gluestack/`, `blocks/21st/` — never merge into `ui/` wholesale
+3. **Locked size scale** — `sm | default | lg | icon` only in buyer-facing screens
+4. **Token SSOT** — semantic colors from `@vybekiit/tokens` CSS vars
+5. **Normalize on import** — when composing screens from mirrored blocks, swap controls to kit primitives + token colors
+6. **One visual voice per screen** — one effect-library flavor per marketing page
+7. **No second design system** — HeroUI, MUI, Chakra forbidden; Untitled/Gluestack isolated in their namespaces
+
+## Normalize-on-import workflow
+
+1. Pick block via MCP `suggest_ui_blend` or search local mirror
+2. Copy/adapt into `app/` or `src/components/<feature>/`
+3. `rg '<button|<input' <file>` — replace with kit components
+4. Map colors to CSS variables / theme tokens
+5. Strip conflicting Tailwind size classes
+6. Preview in dev — confirm buttons match existing screens
+7. Run UI checks from `check-safety` step 7
+
+## Cross-refs
+
+- `shadcn-vybekiit.md` — kit component conventions
+- `ui-routing-vybekiit.md` — intent → source mapping
+- `code-hygiene-vybekiit.md` — no duplicate helpers in UI code

package/dist/global-skills/vybekiitReferences/web/platform-skills/ui-routing-vybekiit.md

@@ -0,0 +1,41 @@
+# Platform wrapper: UI routing (agent-only)
+
+**Agent-only.** Maps builder intent → mirrored UI source + normalize workflow.
+
+## Tools
+
+1. **VybeKiit UI catalog MCP** — `suggest_ui_blend`, `search_ui_components`, `get_ui_component`, `list_ui_sources`
+2. **shadcn MCP** — official primitive lookup
+3. **Local index** — `.vybekiit/agent/ui-catalog-index.json` (640+ mirrored components)
+
+## Intent routing
+
+| Builder says… | Primary source | Namespace | Fallback |
+|---|---|---|---|
+| hero / landing / wow effects | Aceternity or Magic UI | `aceternity/`, `magicui/` | `bundui/` hero blocks |
+| bento / features section | Magic UI or Kokonut | `magicui/`, `kokonutui/` | `bundui/` |
+| pricing / testimonials / FAQ | BundUI | `bundui/` | 21st blocks (when authed) |
+| dashboard / KPI / charts | shadcn Charts + Tremor | `ui/chart` | `bundui/`, `untitled/` tables |
+| forms / settings / admin | kit primitives | `ui/` | `bundui/` form variants |
+| AI chat / agent / streaming messages | AI Elements | `ai-elements/` | `kokonutui/` ai-prompt |
+| reasoning / tool calls / citations | AI Elements | `ai-elements/` | normalize to kit forms |
+| kanban / gantt / editor / data viz | Kibo UI | `kibo/` | `bundui/`, `untitled/` |
+| AI chat interface (legacy) | Kokonut / Cult patterns | `kokonutui/` | `ai-elements/` |
+| enterprise / dense admin | Untitled UI | `untitled/` | `bundui/` admin blocks |
+| cross-platform pattern ref | Gluestack (web mirror) | `gluestack/` | mobile StyleSheet port |
+| mobile version of X | Port from web block | mobile kit `ui/` | `building-native-ui` skill |
+
+## Workflow
+
+1. Call `suggest_ui_blend` with the builder's words
+2. Import from the returned namespace path — do not re-fetch upstream unless mirror is stale
+3. Compose in `app/` or feature components — **normalize-on-import** (see `ui-consistency-vybekiit.md`)
+4. One animated/marketing library flavor per page max
+5. Mobile: check `ui-catalog-index.mobile.json` `portable` flag before promising motion parity
+
+## Cross-refs
+
+- `ui-sources.md` — full catalog + registry URLs
+- `ui-consistency-vybekiit.md` — normalize contract
+- `shadcn-vybekiit.md` — kit primitives
+- mobile: `ui-port-from-web-vybekiit.md`

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

@@ -1,10 +1,16 @@
 ---
 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
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/web/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: watch-my-app

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

@@ -1,10 +1,16 @@
 ---
 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
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/backend/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: wire-auth

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

@@ -1,10 +1,16 @@
 ---
 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; book my classes; yoga booking."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/backend/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: wire-database
@@ -14,6 +20,14 @@ metadata:
 
 **Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
 
+## Reuse before implementation
+
+For bookings, class schedules, appointments, and cancellations, discover `booking` through
+`vybekiit list-presets`, then apply its prerequisites and migration. Use its atomic reservation and
+cancellation functions through verified server sessions. Add only missing app-specific fields and
+permissions. Do not substitute selling class packs for a request to book classes.
+For other requests, select matching presets from the catalog before authoring an extension.
+
 ## Steps
 
 1. Run `vybekiit plan-setup database` for the checklist.

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

@@ -1,10 +1,16 @@
 ---
 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
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/backend/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: wire-email

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

@@ -1,10 +1,16 @@
 ---
 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
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/backend/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: wire-payments

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vybekiit",
-  "version": "0.7.27",
+  "version": "0.7.29",
   "description": "Choose your services, sign in, create a VybeKiit app, and open its verified local welcome page.",
   "license": "MIT",
   "publishConfig": {
@@ -25,7 +25,8 @@
     "firebase-admin": "^13.0.2",
     "mongodb": "^7.4.0",
     "open": "11.0.0",
-    "playwright": "^1.61.1"
+    "playwright": "^1.61.1",
+    "pg": "8.22.0"
   },
   "devDependencies": {
     "@types/node": "22.20.0",
@@ -33,13 +34,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.29",
+    "@vybekiit/agent-mcp": "0.7.29",
+    "@vybekiit/core": "0.7.29",
+    "@vybekiit/db": "0.7.29",
+    "@vybekiit/deploy": "0.7.29",
+    "@vybekiit/payments": "0.7.29",
+    "@vybekiit/report-mode": "0.7.29"
   },
   "scripts": {
     "build": "tsup && node scripts/bundleGlobalSkills.mjs",