vybekiit 0.7.28 → 0.7.29

package/dist/global-skills/vybekiitReferences/extension/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/extension/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`. MongoDB and AWS are advanced (maintainer docs only).

package/dist/global-skills/vybekiitReferences/extension/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/extension/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/extension/platform-skills/format-lint-vybekiit.md

@@ -0,0 +1,33 @@
+# Platform wrapper: format + lint (agent-only)
+
+**Agent-only.** Keep the codebase tidy — the builder never runs the linter or formatter.
+
+## When
+
+After every substantive edit; once after first `pnpm install` during onboarding (quality smoke).
+
+## How
+
+```bash
+pnpm format    # biome check --write .
+pnpm lint      # biome check .
+```
+
+Or the full loop:
+
+```bash
+pnpm verify   # format → lint → typecheck → test
+```
+
+Optional agent wrapper: `node scripts/checkQuality.mjs`
+
+## Rules
+
+1. **Never ask the builder** to run lint or format — you do it silently.
+2. Biome **warn** rules (function length, complexity) are soft — fix obvious ones; don't block ship on style warnings unless egregious.
+3. If lint fails on a real error, fix it and re-run. Translate one plain fix if you must mention something to the builder (rare).
+4. **Pre-push only** — buyer templates ship an identical husky **pre-push** hook (not pre-commit). The builder never pushes; the agent does. The hook runs `pnpm verify` before push succeeds.
+
+## Verify
+
+`pnpm lint` exits 0 (warnings OK). Full smoke: `pnpm verify`.

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

@@ -0,0 +1,47 @@
+# Platform wrapper: GitHub backup (agent-only)
+
+**Agent-only.** Save the builder's project on GitHub — invoked by buyer skill `back-up-my-code`, not by git jargon.
+
+## Prerequisites
+
+- `gh` CLI installed (`vybekiit doctor` checks this)
+- Builder has a **GitHub account** — `gh` does **not** create accounts. If they don't have one, walk them through signup at github.com one step at a time in plain language.
+
+## Sign in
+
+If doctor reports not signed in:
+
+```bash
+gh auth login --web
+```
+
+Browser opens → builder clicks approve.
+
+## Backup flow
+
+1. `git init` (if no repo yet) — `.gitignore` already ships
+2. Stage all project files (never commit `.env` — it's gitignored)
+3. First commit with a plain message, e.g. "Initial save"
+4. Create **private** repo and push:
+
+```bash
+gh repo create <repo-name> --private --source=. --remote=origin --push
+```
+
+5. Open `https://github.com/<user>/<repo>` and confirm files are there
+6. Give the builder the link in plain words — *"Your project is saved online here."*
+
+## Later saves (PR flow)
+
+For ongoing work after the first backup, use `ship-via-pr-vybekiit.md` — branch, push, wait for the **online checker** on all three operating systems, then merge. The builder hears *"Your latest work is saved and checked."*
+
+## Rules
+
+- Default to **private** repos unless the builder explicitly wants public
+- Never paste secrets into commits or chat
+- Never claim backup worked without verifying on github.com
+- Do not run this in doctor by default — only when the builder asks or after meaningful progress (optional nudge in onboarding)
+
+## Verify
+
+`gh repo view` shows the remote · latest commit visible on GitHub · builder has the URL

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

@@ -0,0 +1,39 @@
+# Platform wrapper: i18n (extension template)
+
+**Agent-only.** Invoked by generic coding and the `add-language` buyer skill.
+
+## Official upstream
+
+- Chrome i18n API: https://developer.chrome.com/docs/extensions/reference/i18n/
+- WXT types: `.wxt/types/i18n.d.ts` (regenerated on build)
+
+## Shared conventions
+
+- **Never hardcode user-facing strings** — use `t('key')` from `@/lib/i18n`.
+- **Flat-dotted keys** in Chrome `messages.json` format (`message` + optional `placeholders`).
+- **Manifest strings:** `__MSG_ext.name__`, `__MSG_ext.description__` in `wxt.config.ts`.
+- **RTL:** `dir={localeToDirection(getActiveLocale())}` on popup root; logical Tailwind spacing.
+
+## Extension stack
+
+| Piece | Location |
+|---|---|
+| Catalog | `public/_locales/{locale}/messages.json` |
+| Helper | `lib/i18n.ts` — `t()`, `getActiveLocale()`, `localeToDirection()` |
+| Manifest | `wxt.config.ts` — `default_locale: 'en'` |
+
+## Adding a locale
+
+1. Copy `public/_locales/en/messages.json` → `public/_locales/{locale}/messages.json`.
+2. Translate `message` fields; keep keys identical.
+3. Rebuild — `pnpm build` bundles `_locales/` into output.
+4. RTL: set `dir` on popup `<main>`; test with Chrome locale override.
+5. Run `pnpm test` — `lib/__tests__/i18n.test.ts` green.
+
+## Key namespace
+
+Extension-specific: `ext.*` (manifest), `popup.*` (UI). No web/mobile parity required for popup copy.
+
+## Verify-before-advance
+
+`pnpm verify` green; reload extension in Chrome; confirm popup + manifest name in new language.

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

@@ -0,0 +1,87 @@
+# Platform wrapper: kit MCP tools
+
+**Agent-only.** Catalog of every first-party MCP tool VybeKiit ships. Read this file locally or load via MCP `get_skill` / `list_platform_skills` (`mcp-tools-vybekiit` / `use-kit-mcp`).
+
+Never name MCP, tool ids, or package paths to the builder. Prefer **search → get** (slim pages, then detail).
+
+## Server
+
+| Server key | Package | Bin | Purpose |
+|------------|---------|-----|---------|
+| `vybekiit` | `@vybekiit/agent-mcp` | `vybekiit-agent-mcp` | Skills, CLI catalog, doctor tools, doc-fallback, browser automations, mirrored UI catalog |
+
+Snippet: `.vybekiit/agent/mcp-agent.json`. Setup: `.vybekiit/agent/mcp-setup.md`.
+Auto-discovered skill: `.agents/skills/use-kit-mcp/SKILL.md`.
+
+## Env
+
+| Variable | Meaning |
+|----------|---------|
+| `VYBEKIIT_PROJECT_ROOT` | Project root for skill reads + automation cwd (default cwd) |
+| `VYBEKIIT_UI_CATALOG_PATH` | Path to `ui-catalog-index.json` |
+| `VYBEKIIT_AUTOMATE_BIN` | Optional absolute path to `vybekiit-automate` |
+
+## Context controls
+
+- Cursor pagination: `limit` / `cursor` / response `nextCursor` + `hasMore` + `total`
+- Prefer slim rows; request full detail only when needed (`fields=slim|full` on UI tools)
+- Automations: `run_automation({ dryRun: true })` before a real browser session
+
+## Tools
+
+| Tool | Description | Required | Optional | When to use |
+|------|-------------|----------|----------|-------------|
+| `search_skills` | Fuzzy-search buyer goals/skills (goal-index SSOT). Paginated slim rows. | query | template, limit, cursor | Before opening skill files; empty query lists all goals for the template. |
+| `get_skill` | Load one skill by goal id or stem (excerpt by default). | id | template, excerptLines | After search_skills picks a row; also loads use-kit-mcp / platform wrappers. |
+| `list_platform_skills` | List/search `.vybekiit/platform-skills/*` wrappers (paginated). | — | query, limit, cursor | Find provider wrappers (stripe, railway, mcp-tools-vybekiit, …). |
+| `search_commands` | Fuzzy-search vybekiit CLI verbs. Returns usage — run via shell, not MCP. | query | limit, cursor | Discover CLI verbs (doctor, create app, automate, …). |
+| `get_command` | Get one CLI command by exact name from the catalog. | name | — | After search_commands when you know the exact verb name. |
+| `search_doctor_tools` | List doctor toolchain entries (`vybekiit doctor --ensure <name>`). Does not run doctor. | query | limit, cursor | Before ensuring CLIs (gh, wrangler, supabase, …). |
+| `search_tech_ids` | Fuzzy-search known tech ids before doc_fallback. | query | limit, cursor | Pick a tech id for official docs after one failed MCP/debug attempt. |
+| `doc_fallback` | Official docs + env key hints. Never name MCP to the builder — use builderMessage. | techId | — | MCP or first debug failed once; same as `vybekiit doc-fallback <tech-id>`. |
+| `search_automations` | Fuzzy-search vybekiit-automate browser verbs (ls, cws, nc, …). Paginated. | query | limit, cursor | Before run_automation; empty query lists the catalog. |
+| `get_automation` | Get one automation by domain (+ command) or id (`ls:setup`). | domain | command | Inspect usage string for a known domain/verb. |
+| `run_automation` | Run vybekiit-automate from any project root (resolves bin). Always --json. Prefer dryRun first. Google redirect_uri_mismatch → domain=google command=oauth with --redirect incl. localhost. | domain, command | args, dryRun, yes, cdp, profile, timeoutMs | Execute browser automations anywhere; OAuth 400 redirect_uri_mismatch; dryRun=true to preview argv only. |
+| `search_ui_components` | Fuzzy-search mirrored UI components. Page envelope; default fields=slim. | query | source, limit, cursor, fields | Find blocks by intent/name; slim first, then get_ui_component. |
+| `get_ui_component` | Get one mirrored component by source namespace + slug. | source, name | — | Full detail after search_ui_components. |
+| `suggest_ui_blend` | Ranked multi-source component suggestions for a natural-language UI intent. | intent | limit | Builder wants a composed look (hero + pricing + marquee, …). |
+| `list_ui_sources` | List mirrored UI source namespaces and component counts. | — | — | See which registries are in the local catalog index. |
+
+## Browser automations (from any folder)
+
+```
+search_automations({ query: "lemon squeezy" })
+run_automation({ domain: "ls", command: "setup", dryRun: true })
+run_automation({ domain: "ls", command: "standby" })
+// Google Error 400 redirect_uri_mismatch / Auth.js localhost — args only, no Console babysitting:
+search_automations({ query: "redirect_uri_mismatch" })
+run_automation({ domain: "google", command: "oauth", args: [
+  "--project=my-app", "--app-name=MyApp", "--support-email=you@gmail.com",
+  "--app-url=https://example.com",
+  "--redirect=https://example.com/api/auth/callback/google",
+  "--redirect=http://localhost:3000/api/auth/callback/google",
+]})
+```
+
+Shell equivalent:
+
+```
+vybekiit-automate catalog --json
+vybekiit-automate ls standby --json --yes
+vybekiit-automate google oauth --project=... --app-name=... --support-email=... --app-url=... --redirect=... --json
+```
+
+## Wire-up (agents)
+
+1. `vybekiit setup` registers the `vybekiit` server once at Claude user scope and refreshes it on every rerun.
+2. Start a new Claude session after setup so Claude can approve and discover the global tools.
+3. Cursor receives project `.cursor/mcp.json` files because its setup path remains project-scoped.
+4. `create app` still ships `@vybekiit/agent-mcp` and `@vybekiit/browser-automation` under `packages/` for owned tooling and other MCP clients.
+5. Doctor may merge provider-specific third-party MCPs only when the project needs them.
+
+## Provider / third-party MCP snippets
+
+Not first-party tools — merge only when the builder uses that provider (see `mcp-setup.md`):
+`mcp-supabase`, `mcp-stripe`, `mcp-paypal`, `mcp-neon`, `mcp-firebase`, `mcp-mongodb`, `mcp-railway-*`, `mcp-twilio-*`, `mcp-sentry`, `mcp-posthog`.
+
+If any MCP fails once → `doc_fallback` / `vybekiit doc-fallback <tech-id>`; tell the builder only the plain stuck phrase.

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

@@ -0,0 +1,36 @@
+# Platform wrapper: observability (agent-only)
+
+**Agent-only.** Logging and error tracking wiring — not a buyer goal skill.
+
+## Structured logging
+
+- Import `log` from `src/lib/logger.ts` (wraps `@vybekiit/core` `createLogger`).
+- **Development:** `debug` and `info` print automatically.
+- **Production:** only `warn` and `error` print — no builder configuration needed.
+- Optional override: `LOG_LEVEL` in `.env` (agent-only; never ask the builder to set it).
+- API routes: `const routeLog = log.child({ requestId })` when correlating a request.
+
+```ts
+import { log } from '@/lib/logger';
+
+log.info('Contact form accepted', { email: parsed.data.email });
+log.error('Checkout failed', err);
+```
+
+Never use bare `console.log` in `app/` or `src/` (tests excluded).
+
+## Error tracking
+
+- Buyer skill: `track-errors` — wires `@vybekiit/observability`.
+- Server entry: `instrumentation.ts` calls `resolveObservabilityProvider`.
+- App code: `import { observability } from '@/lib/observability'` then `observability.captureException(err)`.
+- Platform wrapper: `sentry-vybekiit.md` for Sentry dashboard steps.
+
+## Pre-ship checks
+
+```bash
+node scripts/checkNoConsole.mjs
+rg "from '@/lib/logger'" app/api/
+```
+
+See `check-safety` step 6 (code readiness) and `go-live` pre-flight.

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

@@ -0,0 +1,59 @@
+# planning-vybekiit.md — agent-only planning mechanics
+
+Used by `plan-my-idea.md`. The builder never sees this file or its vocabulary.
+
+## CONTEXT.md format
+
+Single context at repo root (`CONTEXT.md`). Create lazily when the first term resolves.
+
+```md
+# {App name or domain}
+
+{One or two sentences: what this app is and who it's for.}
+
+## Language
+
+**{Canonical term}**:
+{A one or two sentence definition of what it IS, not what it does.}
+_Avoid_: alias1, alias2
+```
+
+### Rules
+
+- **Be opinionated.** Pick one canonical word; list alternatives under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max.
+- **App-specific only.** No general programming terms (API, timeout, cache, component).
+- **Group under subheadings** when clusters emerge (e.g. `## People`, `## Money`).
+- **Update inline** during the session — never batch at the end.
+- **No implementation details** in `CONTEXT.md` — glossary only, not a spec.
+
+### No ADRs for buyers
+
+Do not create `docs/adr/` or decision-record files. Capture agreed language in `CONTEXT.md` only.
+
+## During a planning session
+
+### Challenge against the glossary
+
+When the builder uses a term that conflicts with `CONTEXT.md`, reconcile immediately: *"Last time we
+said X means … — is that still right?"*
+
+### Sharpen fuzzy language
+
+When they say "account", "user", "order", "save" without precision, propose a canonical term and ask
+which they mean.
+
+### Cross-reference with code
+
+When they state how something works, check the code. If it contradicts them, surface it plainly and
+ask which is right before continuing.
+
+### Concrete scenarios
+
+Once the shape emerges, invent one realistic edge-case scenario (*"Sarah tries to… what happens?"*) to
+expose gaps before building.
+
+## After planning
+
+Reference `CONTEXT.md` during later feature work so wording stays consistent. Do not overwrite buyer
+entries during `update-kit` sync — `CONTEXT.md` is buyer-owned.

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

@@ -0,0 +1,42 @@
+# Platform wrapper: Playwright UI tests (agent-only)
+
+**Agent-only.** Walk through the app like a visitor — the builder hears *"I checked it on screen"*, not Playwright.
+
+## When
+
+Before calling a page done (web/extension with UI); in pre-push when `PLAYWRIGHT_ENABLED=true`; on CI (ubuntu job).
+
+## Configure (`.env`)
+
+```env
+PLAYWRIGHT_ENABLED="true"      # turn on locally
+PLAYWRIGHT_HEADLESS="true"     # false to watch the browser
+PLAYWRIGHT_BASE_URL="http://localhost:3000"
+```
+
+## Install browsers (once per machine)
+
+```bash
+pnpm exec playwright install chromium
+```
+
+Doctor/onboarding: agent runs this silently when enabling UI walkthrough tests.
+
+## Run
+
+```bash
+pnpm test:e2e
+# or: PLAYWRIGHT_ENABLED=true pnpm test:e2e
+```
+
+Pre-push runs `pnpm test:e2e` automatically when `PLAYWRIGHT_ENABLED=true`.
+
+## Rules
+
+1. Never say "Playwright", "E2E", or "headless" to the builder — use `language.md`.
+2. Fix failing walkthrough tests before telling the builder the page works.
+3. Keep smoke tests short — one happy path per critical screen.
+
+## Verify
+
+`pnpm test:e2e` green with dev server reachable at `PLAYWRIGHT_BASE_URL`.

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

@@ -0,0 +1,45 @@
+# Platform wrapper: React patterns (agent-only)
+
+**Agent-only.** Kit primitives and soft limits — the builder never hears "props" limits or "split the component."
+
+## Kit primitives (required)
+
+| Concern | Use | Never |
+|---|---|---|
+| Server / API data | TanStack Query via `@vybekiit/client-state` (`useQuery`, `useMutation`) | Raw `fetch` + `useState` for server records |
+| Async UI state | `useAsync` from `@/hooks/use-async` | Hand-rolled fetch for data that belongs in query cache |
+| User / session | `useUser` from `@/hooks/use-user` | Duplicate session logic in pages |
+| Client-only prefs | `useStorage` from `@/hooks/use-storage` | Zustand/MMKV for server data |
+| Toasts | `useToast` from `@/hooks/use-toast` | `alert()` or ad-hoc snackbars |
+| Forms | `FormField` + zod at submit boundary | Inline validation scattered in JSX |
+
+Read `client-state-vybekiit.md` and `src/hooks/README.md` before adding hooks.
+
+## Soft limits (agent + Biome warn)
+
+| Rule | Target | Enforcement |
+|---|---|---|
+| Function body length | ~5 lines ideal; split if longer | Agent convention + Biome warn |
+| Component props | ~5 max; use composition or a small options object | Agent convention |
+| Folders | See `src/README.md` | Required |
+
+## Forms
+
+- Use `FormField` for labels, errors, and inputs.
+- Validate with zod **once** at submit — not on every keystroke unless UX requires it.
+- API routes validate again with zod at the boundary.
+
+## Folders
+
+```
+app/                 routes + API (Next.js App Router)
+src/components/ui/   kit primitives — do not duplicate
+src/components/    app-specific composed UI
+src/hooks/           shared React hooks (see README)
+src/lib/             headless clients + utils (see README)
+```
+
+## Verify
+
+- New screens use kit hooks · forms use `FormField` · no duplicate helpers in `src/lib/`
+- `pnpm test` green after changes

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

@@ -0,0 +1,27 @@
+# Platform wrapper: responsive layout (agent-only)
+
+**Agent-only.** Mobile-first web layout — the builder hears "looks good on phone and desktop," not breakpoints.
+
+## Mobile-first
+
+- Base styles = phone (narrow). Scale up with `sm:` / `md:` / `lg:`.
+- Default page padding: `px-4 md:px-6`
+- Max content width: `max-w-lg mx-auto` (forms/auth) or `max-w-6xl` (marketing/dashboard)
+- Touch targets: kit `Button` sizes `default` or `lg` — never tiny custom tap areas
+
+## RTL
+
+Complements logical properties in `AGENTS.md` — use `ms-`/`me-`/`ps-`/`pe-`/`start-`/`end-`, not `left`/`right`.
+
+## Before calling a page done
+
+Preview at **375px** width in dev tools. Fix overflow, cramped buttons, and unreadable text before showing the builder.
+
+## Also read
+
+- `ui-consistency-vybekiit.md` — primitives and spacing tokens
+- `shadcn-vybekiit.md` — layout blocks from the UI catalog
+
+## Verify
+
+Page usable at 375px and desktop without horizontal scroll on main content.