vybekiit 0.7.27 → 0.7.29

package/dist/global-skills/vybekiitReferences/mobile/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/mobile/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/mobile/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/mobile/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/mobile/platform-skills/i18n-vybekiit.md

@@ -0,0 +1,41 @@
+# Platform wrapper: i18n (mobile template)
+
+**Agent-only.** Invoked by generic coding and the `add-language` buyer skill.
+
+## Official upstream
+
+- expo-localization: https://docs.expo.dev/versions/latest/sdk/localization/
+- i18n-js: https://github.com/fnando/i18n-js
+
+## Shared conventions
+
+- **Never hardcode user-facing strings** — use `t('flat.dotted.key')` via `useTranslations()` or `@/lib/i18n`.
+- **Flat-dotted keys** in `messages/en.json` (converted to nested scopes for i18n-js internally).
+- **Default locale:** `en`; device locale detected via `expo-localization`, fallback `en`.
+- **RTL:** `applyRtlForLocale()` in `src/lib/direction.ts` (I18nManager, per ADR-0004).
+
+## Mobile stack
+
+| Piece | Location |
+|---|---|
+| Catalog | `messages/{locale}.json` |
+| Init + `t()` | `src/lib/i18n.ts` — call `initI18n()` from `app/_layout.tsx` |
+| Hook | `src/hooks/use-translations.ts` |
+| RTL | `src/lib/direction.ts` |
+
+## Adding a locale
+
+1. Copy `messages/en.json` → `messages/{locale}.json`; translate values.
+2. Register in `src/lib/i18n.ts` via `registerLocale(locale, messages)`.
+3. Add to `flatCatalogs` / device resolution if needed.
+4. RTL locales: confirm layout mirrors after reload.
+5. Run `pnpm test` — `src/lib/__tests__/i18n.test.ts` green.
+
+## Cross-platform keys
+
+Mirror web keys where surfaces match: `home.hero.*`, `auth.*`, `pricing.*`, `dashboard.*`.
+Mobile-only: `navigation.screen.*`, `common.close`.
+
+## Verify-before-advance
+
+`pnpm verify` green; reload app and confirm stack titles + one screen in the new language.

package/dist/global-skills/vybekiitReferences/mobile/platform-skills/launch-store-vybekiit.md

@@ -0,0 +1,26 @@
+# Platform wrapper: launch-store (mobile publish)
+
+**Agent-only.** Invoked by buyer skill `publish-app`.
+
+## Official upstream
+
+- CLI: `launch-store` (global npm; `doctor` installs as `launch`)
+- Build engine: EAS — prefer pinned `.agents/skills/expo-deployment` and `expo-cicd-workflows`
+- Docs: https://docs.expo.dev/submit/introduction/
+
+## Kit wiring
+
+1. App identity in `app.json`; listing in `launch.config.ts` (`buildEngine: 'eas'`)
+2. Resolve `TODO(vybekiit): … — skill: publish-app` markers first
+3. `launch build <ios|android>` — cloud build + test track upload
+4. `launch release <ios|android>` — public store submit
+5. `launch status` — review state
+6. `launch ai screenshots` — installed Genshot companion prepares store pictures from real screens
+7. Mobile app talks to **backend API** for auth/data/payments — never direct DB keys in the app
+
+## Verify-before-advance
+
+- `eas whoami` + `launch --version` via `doctor`
+- Build completes green before submit
+- `launch plan screenshots` shows approved store pictures before upload
+- Store confirms submission received

package/dist/global-skills/vybekiitReferences/mobile/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/mobile/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/mobile/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/mobile/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/mobile/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/mobile/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/mobile/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