vybekiit 0.7.27 → 0.7.29

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

@@ -0,0 +1,20 @@
+# Platform wrapper: Analytics (PostHog / Plausible opt-in)
+
+**Agent-only.** Invoked when `ANALYTICS_PROVIDER` is set.
+
+## Official upstream
+
+- PostHog docs: https://posthog.com/docs
+- PostHog MCP: merge `agent/mcp-posthog.json` when `ANALYTICS_PROVIDER=posthog`
+- Pinned skills (PostHog): `.agents/skills/instrument-product-analytics/SKILL.md`, `.agents/skills/instrument-feature-flags/SKILL.md`
+- Plausible: docs-only — https://plausible.io/docs (no vendor skills.sh repo)
+
+## Kit wiring
+
+1. Analytics via `@vybekiit/analytics` → `resolveAnalyticsProvider()`
+2. PostHog: set `POSTHOG_API_KEY`, `POSTHOG_HOST` in `.env`; use pinned skills + MCP for instrumentation
+3. Plausible: script tag / API per docs; no pinned upstream skills
+
+## Verify-before-advance
+
+- Test event appears in dashboard (PostHog live events or Plausible realtime)

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

@@ -0,0 +1,31 @@
+# Platform wrapper: asset optimization + CDN (ADR-0010)
+
+**Agent-only.** Used by `add-images`, `add-files`, build hooks, and `VybeImage`.
+
+## Kit wiring
+
+1. **Build-time:** `resolveAssetDelivery().optimizeForBuild({ sourceDir })` — sharp + SVGO
+2. **Runtime URLs:** `resolveAssetDelivery().url(src, { width, format })` — CDN transforms
+3. **Display:** `VybeImage` in `src/components/vybe-image.tsx`
+4. **Storage:** `resolveStorageProvider()` for uploads; doctor provisions R2 on Cloudflare default
+
+## Provider derivation (no new env knob)
+
+| HOSTING | STORAGE | Delivery |
+|---|---|---|
+| cloudflare | r2 | CF Pages + R2 + Image Resizing |
+| cloudflare | supabase | CF Pages + Supabase URL + CF resize |
+| vercel | any | Vercel Image Optimization |
+| aws | s3 | CloudFront + S3 URLs |
+
+## Cloudflare R2
+
+- Doctor: `vybekiit doctor` creates bucket + API token, writes `.env`
+- Docs: https://developers.cloudflare.com/r2/
+- Image Resizing: https://developers.cloudflare.com/images/image-resizing/
+
+## Verify
+
+- `node scripts/optimizeAssets.mjs` succeeds
+- Upload test file → `url()` returns CDN transform URL
+- Images load fast in browser / on device

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

@@ -0,0 +1,25 @@
+# Platform wrapper: AWS (Agent Toolkit + existing adapters)
+
+**Agent-only.** Supports `@vybekiit/db` (`DATA_PROVIDER=aws` DynamoDB) and `@vybekiit/deploy` AWS hosting.
+
+## Official upstream
+
+- Agent Toolkit skills: https://docs.aws.amazon.com/agent-toolkit/latest/userguide/skills.html
+- Install: `npx skills add aws/agent-toolkit-for-aws/skills`
+- AWS MCP Server: authenticated API access + runtime skill retrieval
+
+## Kit wiring
+
+1. Data: `DATA_PROVIDER=aws` with `AWS_REGION` (+ optional keys or instance role)
+2. Hosting: `HOSTING_PROVIDER=aws` with Amplify app id when provisioned
+3. Skills assist console/API work the agent absorbs — builder never sees AWS console
+
+## Verify-before-advance
+
+- Ask: "What AWS skills do you have available?"
+- Run `vybekiit doctor` — platform-skills report lists pinned AWS toolkit skills
+- Local AWS credentials profile for MCP (never commit keys)
+
+## Security
+
+MCP uses the developer's local AWS profile only. No AWS secrets in the repo.

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

@@ -0,0 +1,21 @@
+# Platform wrapper: better-auth (default auth)
+
+**Agent-only.** Invoked by buyer skill `add-signin`.
+
+## Official upstream
+
+- Docs: https://www.better-auth.com/docs
+- Pinned skills: `.agents/skills/better-auth-best-practices/SKILL.md`, `.agents/skills/create-auth-skill/SKILL.md`, `.agents/skills/better-auth-security-best-practices/SKILL.md`
+
+## Kit wiring
+
+1. Requires database first — run `save-data` / `supabase-vybekiit.md` if not ready
+2. Auth via `@vybekiit/auth` → `resolveAuthProvider()` (better-auth when `AUTH_PROVIDER` default)
+3. Set `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `DATABASE_URL` in `.env` (agent generates secrets)
+4. Mount handler at `app/api/auth/[...all]/route.ts`
+5. Wire `src/lib/auth-client.ts` stubs marked `TODO(vybekiit): … — skill: add-signin`
+
+## Verify-before-advance
+
+- Sign-up → verify (OTP) → dashboard path works in browser
+- Tests for auth client green

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

@@ -0,0 +1,40 @@
+# 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 |
+| `nc` | `$HOME/.nc-chrome-profile` | Namecheap API key setup |
+| `gd` | `$HOME/.gd-chrome-profile` | GoDaddy API key setup |
+
+## 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 nc setup --json
+vybekiit-automate gd setup --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/web/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/web/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`.

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

@@ -0,0 +1,42 @@
+# Platform wrapper: Cloudflare email (default sender)
+
+**Agent-only.** Invoked by buyer skill `setup-email` when `EMAIL_PROVIDER=cloudflare` (default).
+
+## Official upstream
+
+- Docs: https://developers.cloudflare.com/email-service/
+- Pinned skills: `.agents/skills/wrangler/SKILL.md`, `.agents/skills/cloudflare-email-service/SKILL.md`
+
+## Kit wiring
+
+1. Email via `@vybekiit/email` → `resolveEmailProvider()` when `EMAIL_PROVIDER=cloudflare`
+2. Deploy the Cloudflare email worker (a small `fetch` handler that receives the POST from
+   `createCloudflareEmail` and calls the Email Sending binding); point `CLOUDFLARE_EMAIL_ENDPOINT` at it
+3. Root `.env` keys:
+
+   ```bash
+   EMAIL_WORKER_SECRET=              # wrangler secret on the worker
+   CLOUDFLARE_EMAIL_ENDPOINT=        # https://<worker>.workers.dev/send
+   EMAIL_FROM=hello@yourdomain.com
+   EMAIL_FROM_NAME=Your App
+   CLOUDFLARE_ACCOUNT_ID=
+   CLOUDFLARE_API_TOKEN=             # deploy + zone provisioning only
+   ```
+
+4. Optional Namecheap automation (registrar NS update):
+
+   ```bash
+   NAMECHEAP_API_USER=
+   NAMECHEAP_API_KEY=
+   NAMECHEAP_CLIENT_IP=
+   ```
+
+5. Domain provisioning: `DOMAIN=yourdomain.com node infra/scripts/provisionDomain.mjs`
+6. Enable sending: `npx wrangler email sending enable yourdomain.com`
+7. Test: trigger a real send from the app (e.g. a sign-in email) and confirm it arrives
+
+## Verify-before-advance
+
+- `vybekiit doctor` — Namecheap + email worker health when configured
+- Test email arrives (check spam)
+- Apps call `resolveEmailProvider()` — never POST to the worker directly

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

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

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

@@ -0,0 +1,38 @@
+# Platform wrapper: code hygiene (agent-only)
+
+**Agent-only.** Invisible guardrails for every coding task — not a buyer goal skill.
+
+## Before you write code
+
+1. **Check before create** — search `src/lib/` and `@vybekiit/*` before adding a helper; extend existing code if ≥80% overlap.
+2. **One home per concern** — auth → `auth-client.ts`, billing → `billing-client.ts`, HTTP → `fetch-json.ts`, logging → `logger.ts`. Never add `utils-foo.ts`.
+3. **Use the kit logger** — `import { log } from '@/lib/logger'` (web) or `@/lib/logger` (mobile). Never `console.log` in app/API code (tests may use console).
+4. **KISS** — no one-off wrappers around kit packages; validate API bodies with zod at the route boundary only.
+5. **SSOT** — secrets in `.env` only; business constants in one file per domain (e.g. `plans.ts`).
+
+Read `src/lib/README.md` for the utility registry.
+
+## Duplicate detection
+
+Before adding a function:
+
+```bash
+rg "function <name>" src/lib/ app/
+rg "export (async )?function" src/lib/
+```
+
+Flag and merge when the same name or a 10+ line block appears twice. Consolidate validation into shared zod schemas, not copy-pasted checks in routes.
+
+## Forbidden
+
+- Second auth/billing/fetch wrapper
+- Inline date/currency formatters in components (add to an existing lib file)
+- Raw SQL or string-built queries (use `@vybekiit/db`)
+
+## React-specific
+
+Follow pinned `vercel-react-best-practices` for event-listener dedup, RSC prop dedup, and effect placement.
+
+## Verify
+
+After refactors: tests green · `node scripts/checkNoConsole.mjs` (web) · no duplicate function names in `src/lib/`.

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

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

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

@@ -0,0 +1,29 @@
+# Platform wrapper: data modeling (agent-only)
+
+**Invoked by:** `design-my-data` buyer skill · inline from `save-data` for trivial cases.
+
+## When to use
+
+| Situation | Action |
+|-----------|--------|
+| Multiple entities or relationships | Run `design-my-data` first |
+| Single simple list/table | Inline `planDataModel()` in `save-data` |
+| Builder already agreed on shape | Jump to `save-data` |
+
+## Workflow
+
+1. Infer entities from product language (customers, orders, posts, etc.)
+2. `planDataModel(entities, DATA_PROVIDER)` — PK/FK stay in agent output only
+3. Read `buyerSummary` to builder; confirm
+4. `save-data` provisions via MCP path for active provider (merge via `agent/mcp-setup.md`):
+   - Supabase → `mcp-supabase.json` + Supabase CLI
+   - Neon → `mcp-neon.json`
+   - Firebase → `mcp-firebase.json`
+
+## Never say to builder
+
+primary key, foreign key, migration, schema, normalization, SQL, NoSQL
+
+## MCP tier
+
+Document login-once paths in `onboarding.md`. Supabase, Neon, and Firebase are buyer-facing MCP tiers. MongoDB: agent-only via `mongodb-vybekiit.md` when `DATA_PROVIDER=mongodb` (not buyer-facing). AWS remains advanced (maintainer docs only).

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

@@ -0,0 +1,46 @@
+# Platform: DB feature presets
+
+Agent-only. Applies composable SaaS table bundles from `@vybekiit/db` presets.
+
+## When to use
+
+- A buyer skill needs kit-owned tables (orders, teams, search, AI, audit).
+- `vybekiit doctor` reports missing DB presets.
+- Before wiring `@vybekiit/*` package code that expects preset collections.
+
+## Commands
+
+```bash
+vybekiit list-presets
+vybekiit apply-preset <feature> [--provider=supabase|neon|railway] [--dry-run]
+vybekiit verify-presets [--fix]
+```
+
+## Skill → preset map
+
+| Skill | Presets |
+|---|---|
+| `add-signin` | `auth-bridge` |
+| `setup-payments` | `orders`, `webhook_events` |
+| `add-teams` | `organizations` |
+| `add-search` | `search_documents` |
+| `add-ai` | `embeddings`, `ai_conversations` |
+| `add-realtime` | `realtime_publications` |
+| `add-notifications` | `notifications_log` |
+| `add-files` | `file_metadata` |
+| `harden` | `audit_log` |
+| `go-live` | `job_runs` |
+
+## Verify-before-advance
+
+After each `apply-preset`, run `vybekiit verify-presets <feature>` (or `--fix` from doctor).
+Translate errors to plain language — never say "migration" or "RLS" to the builder.
+
+## Postgres providers
+
+Full SQL + indexes for `supabase`, `neon`, `railway`. Requires `DATABASE_URL`.
+
+## NoSQL (v1.1)
+
+`renderPreset` emits collection/index notes for `mongodb`, `firebase`, `aws` — apply manually
+via provider CLI until v1.1 renderers ship.

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

@@ -0,0 +1,22 @@
+# Platform wrapper: Cloudflare deploy (default host)
+
+**Agent-only.** Invoked by buyer skill `go-live` when `HOSTING_PROVIDER=cloudflare` (default).
+
+## Official upstream
+
+- Docs: https://developers.cloudflare.com
+- CLI: `wrangler` (installed + probed by `vybekiit doctor`)
+- Pinned skills: `.agents/skills/wrangler/SKILL.md`, `.agents/skills/workers-best-practices/SKILL.md`
+
+## Kit wiring
+
+1. Call `resolveHosting()` from `@vybekiit/deploy` — returns Cloudflare adapter
+2. Supply a `CloudflareRunner` that executes the adapter's wrangler action (go-live skill owns the shell)
+3. Secret settings: `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN` in `.env`
+4. CLI auth: `wrangler login` (browser once) — probed by `doctor`, not stored in `.env`
+
+## Verify-before-advance
+
+- `wrangler whoami` succeeds
+- `resolveHosting().deploy({ outputDir, projectName })` returns a live URL
+- Open the URL in browser before celebrating

package/dist/global-skills/vybekiitReferences/web/platform-skills/deploy-github-pages-vybekiit.md

@@ -0,0 +1,25 @@
+# Platform wrapper: GitHub Pages deploy (free static host)
+
+**Agent-only.** Invoked by buyer skill `go-live` when `HOSTING_PROVIDER=github-pages` (ADR-0040).
+The free, zero-cold-start static host tied to the buyer's own repo — best for the spa, extension
+popup, and static web targets. Static only: no SSR/backend (use cloudflare or deno-deploy for those).
+
+## Official upstream
+
+- Docs: https://docs.github.com/en/pages
+- CLI: `gh` (installed + probed by `vybekiit doctor`) — GitHub Pages needs no extra host CLI
+- Auth: `gh auth login` (browser once) or `GITHUB_TOKEN`/`GH_TOKEN` in CI — never stored in `.env` (ADR-0001)
+
+## Kit wiring
+
+1. Call `resolveHosting()` from `@vybekiit/deploy` — returns the GitHub Pages adapter
+2. `deploy({ outputDir, projectName })` publishes a public repo + enables Pages and returns the live
+   URL (delegates to the shared Live-work provision path — one code path for buyer + dogfood)
+3. Optional setting: `GITHUB_PAGES_OWNER` — owner/org login; defaults to the authenticated GitHub login
+4. Token: from `gh auth token` / `GITHUB_TOKEN`, read at deploy time and never printed
+
+## Verify-before-advance
+
+- `gh auth status` succeeds
+- `resolveHosting().deploy({ outputDir, projectName })` returns a live `*.github.io` URL
+- Open the URL in the browser before celebrating (the first Pages build can take a moment)

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

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

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

@@ -0,0 +1,23 @@
+# Platform wrapper: Vercel deploy (opt-in host)
+
+**Agent-only.** Invoked by buyer skill `go-live` when `HOSTING_PROVIDER=vercel`.
+
+## Official upstream
+
+- Docs: https://vercel.com/docs
+- CLI: `vercel` (installed + probed by `vybekiit doctor` when Vercel hosting is selected)
+- Pinned Next.js skills in `.agents/skills/` cover App Router patterns (not deploy CLI details)
+
+## Kit wiring
+
+1. Set `HOSTING_PROVIDER=vercel` in `.env` (agent decides — builder never picks hosts)
+2. Call `resolveHosting()` from `@vybekiit/deploy` — returns Vercel adapter
+3. Supply a `VercelRunner` that executes the adapter's vercel action (go-live skill owns the shell)
+4. Secret settings: `VERCEL_TOKEN` in `.env`; optional `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` after link
+5. CLI auth: token-based (`VERCEL_TOKEN`) or `vercel login` for interactive link — see ADR-0006
+
+## Verify-before-advance
+
+- `vercel whoami` succeeds (or token validates)
+- Deploy returns production URL
+- Open URL before celebrating

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

@@ -0,0 +1,20 @@
+# Platform wrapper: secret settings / `.env` (agent-only)
+
+**Agent-only.** Keep secret values invisible — the builder never hears key names as passwords in chat.
+
+## Hard rules
+
+1. **Never read `.env` aloud** or paste its values into chat, commits, or PR descriptions.
+2. **Reference keys from `.env.example` only** — say *"the payment key in your secret settings file"* using the plain label from `.env.example` comments, not the raw value.
+3. **If the builder pastes a secret in chat**, warn once: *"Don't paste secrets here — paste it into your secret settings file on your machine instead."* Then guide them to open `.env` locally.
+4. **Doctor must pass** `.cursorignore` listing `.env` — run `vybekiit doctor` if unsure.
+
+## What agents can see
+
+Cursor, Claude Code, and Codex may still read `.env` if ignore rules fail — treat every value as redacted even when visible. Never reproduce secret strings; use `••••••` or *"already set"* when confirming.
+
+## Verify
+
+- `.cursorignore` includes `.env`
+- `.gitignore` includes `.env`
+- `git status` never shows `.env` staged

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

@@ -0,0 +1,127 @@
+# Platform wrapper: extend-capabilities (agent-only)
+
+**Agent-only.** Invoked silently when no `goal-index.md` row and no platform wrapper covers the builder's request. The builder never hears "skill gap" or "extension."
+
+## When to run
+
+1. Read `.vybekiit/agent/goal-index.md` (and `.vybekiit/extensions/goal-index.md` if present).
+2. If a row matches → follow that skill; **stop here**.
+3. If the request is tech-specific → check `@vybekiit/*` `resolve*Provider()` adapters and `.vybekiit/platform-skills/*-vybekiit.md` plus `.vybekiit/extensions/platform-skills/`.
+4. If an existing goal skill can absorb the tech (e.g. new database → `save-data`) → follow that goal skill; **stop here**.
+5. Otherwise → run this workflow.
+
+## Workflow
+
+### 1. Classify the gap
+
+| Kind | Signal | Output |
+|---|---|---|
+| **New builder goal** | Feature or outcome with no goal-index match | Layer A buyer skill |
+| **New tech / provider** | Named framework, DB, language, or tool | Layer B wrapper (+ upstream pin when available) |
+
+Pick a **goal stem** (kebab-case, goal-named for Layer A) or **tech stem** (kebab-case for Layer B).
+
+### 2. Research (tech gaps only)
+
+1. Search skills.sh: `npx skills search <query>`
+2. When an official skill exists: `npx skills add <repo> --skill <name> -y` into project `.agents/skills/`
+3. Note official docs URL for the wrapper header
+4. Check `@vybekiit/*` for an existing provider interface to wire behind
+
+### 3. Draft
+
+Use these shapes (or `vybekiit` templates from `@vybekiit/agent-kit`):
+
+**Layer A (buyer goal)** — mirror `skills/save-data.md`:
+
+- `**Goal:**` one plain sentence
+- `**Contract:**` five rules + `language.md`
+- `## Steps` with `**Verify:**` on each step
+- `## Definition of done`
+- `## After completing this skill`
+
+**Layer B (platform wrapper)** — mirror `platform-skills/mongodb-vybekiit.md`:
+
+- Official docs links
+- `## Kit wiring` (prefer `resolve*Provider()`)
+- `## Verify-before-advance`
+- `## Never say to builder`
+- `## TODO(vybekiit)` when no npm adapter exists yet
+
+**Machine-global** — Agent Skills `SKILL.md` with YAML frontmatter (`name`, `description`).
+
+### 4. Lint (agent-only)
+
+Before saving, run:
+
+```bash
+vybekiit lint-extension-skill <draft-path> --kind=buyer-goal
+# or --kind=platform-wrapper
+# or --kind=agent-skills-global
+```
+
+Fix all issues. Exit code must be `0`. Builder never sees this step.
+
+### 5. Ask scope (plain language only)
+
+Ask exactly once:
+
+> "Should I save this guide just for this project, or for all your projects on this computer?"
+
+| Answer | Persist to |
+|---|---|
+| **This project** | Layer A: `.vybekiit/extensions/skills/<goal>.md` · Layer B: `.vybekiit/extensions/platform-skills/<tech>-vybekiit.md` |
+| **All my projects** | Tool-aware global path (detect active tool first) |
+
+### Tool-aware global paths
+
+| Active tool | Global skill path | skills.sh agent |
+|---|---|---|
+| **Cursor** | `~/.cursor/skills-cursor/<name>/SKILL.md` | `--agent cursor` |
+| **Claude Code** | `~/.claude/skills/<name>/SKILL.md` | `--agent claude-code` |
+| **Codex** | `~/.agents/skills/<name>/SKILL.md` | `--agent codex` |
+| **Fallback** | `~/.agents/skills/<name>/SKILL.md` | omit `--agent` |
+
+Detect tool: Cursor if `.cursor/rules/vybekiit.mdc` exists; else Claude if `CLAUDE.md` session; else Codex via `AGENTS.md`.
+
+Global install via skills.sh when upstream exists:
+
+```bash
+npx skills add <repo> --skill <name> --global --agent <agent> -y
+```
+
+### 6. Persist
+
+**Project-local:**
+
+- Create directories if missing: `.vybekiit/extensions/skills/`, `.vybekiit/extensions/platform-skills/`
+- Write the drafted file
+- **Layer A only:** append a row to `.vybekiit/agent/goal-index.md`:
+
+  `| "<builder phrase>" | \`extensions/skills/<goal>.md\` |`
+
+  Optionally mirror the row in `.vybekiit/extensions/goal-index.md` for backup.
+
+**Machine-global:**
+
+- Write `SKILL.md` to the tool path above
+- Do not edit project `goal-index.md` for global-only skills
+
+### 7. Resume
+
+Immediately follow the new skill as if it always existed. Never tell the builder you "created a skill."
+
+## Verify-before-advance
+
+- Lint passed (`vybekiit lint-extension-skill` exit 0)
+- File exists at chosen path
+- For Layer A: goal-index row present
+- For tech: upstream pin in `.agents/skills/` when available
+
+## Never say to builder
+
+skill gap, extension, Layer A, Layer B, platform wrapper, goal-index, skills.sh, Agent Skills, YAML frontmatter
+
+## Owned vs maintained
+
+`.vybekiit/extensions/**` is **buyer-owned** — `sync-agent-layer` never overwrites it. Extension rows in `goal-index.md` are preserved on kit updates.

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

@@ -0,0 +1,27 @@
+# Platform wrapper: Firebase (Firestore)
+
+**Agent-only.** Invoked by buyer skills `save-data` and `doctor`.
+
+## Official upstream
+
+- Agent skills: https://firebase.google.com/docs/ai-assistance/agent-skills
+- MCP server: `npx -y firebase-tools@latest mcp`
+- Install skills: `npx skills add firebase/agent-skills --agent=cursor`
+
+## Kit wiring
+
+1. Set `DATA_PROVIDER=firebase`, `FIREBASE_PROJECT_ID`, and credentials (`FIREBASE_SERVICE_ACCOUNT_JSON` or `GOOGLE_APPLICATION_CREDENTIALS`)
+2. Data via `@vybekiit/db` → `resolveDataProvider()` — never raw Firestore in UI
+3. Firebase Auth is a follow-up skill; default auth remains `better-auth` unless agent wires Firebase Auth
+4. Storage stays on `STORAGE_PROVIDER=supabase|r2|s3` (Firebase Storage not in v1)
+
+## MCP
+
+Merge `.vybekiit/agent/mcp-firebase.json` alongside `mcp-agent.json` in `.cursor/mcp.json`.
+
+Skills + MCP are complementary: skills teach how; MCP executes.
+
+## Verify-before-advance
+
+- `pingFirebaseDatabase()` green via doctor
+- Firebase CLI authenticated locally for MCP (`firebase login`)