vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/supabase-postgres-best-practices/references/security-privileges.md

@@ -0,0 +1,54 @@
+---
+title: Apply Principle of Least Privilege
+impact: MEDIUM
+impactDescription: Reduced attack surface, better audit trail
+tags: privileges, security, roles, permissions
+---
+
+## Apply Principle of Least Privilege
+
+Grant only the minimum permissions required. Never use superuser for application queries.
+
+**Incorrect (overly broad permissions):**
+
+```sql
+-- Application uses superuser connection
+-- Or grants ALL to application role
+grant all privileges on all tables in schema public to app_user;
+grant all privileges on all sequences in schema public to app_user;
+
+-- Any SQL injection becomes catastrophic
+-- drop table users; cascades to everything
+```
+
+**Correct (minimal, specific grants):**
+
+```sql
+-- Create role with no default privileges
+create role app_readonly nologin;
+
+-- Grant only SELECT on specific tables
+grant usage on schema public to app_readonly;
+grant select on public.products, public.categories to app_readonly;
+
+-- Create role for writes with limited scope
+create role app_writer nologin;
+grant usage on schema public to app_writer;
+grant select, insert, update on public.orders to app_writer;
+grant usage on sequence orders_id_seq to app_writer;
+-- No DELETE permission
+
+-- Login role inherits from these
+create role app_user login password 'xxx';
+grant app_writer to app_user;
+```
+
+Revoke public defaults:
+
+```sql
+-- Revoke default public access
+revoke all on schema public from public;
+revoke all on all tables in schema public from public;
+```
+
+Reference: [Roles and Privileges](https://supabase.com/blog/postgres-roles-and-privileges)

package/dist/global-skills/supabase-postgres-best-practices/references/security-rls-basics.md

@@ -0,0 +1,50 @@
+---
+title: Enable Row Level Security for Multi-Tenant Data
+impact: CRITICAL
+impactDescription: Database-enforced tenant isolation, prevent data leaks
+tags: rls, row-level-security, multi-tenant, security
+---
+
+## Enable Row Level Security for Multi-Tenant Data
+
+Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
+
+**Incorrect (application-level filtering only):**
+
+```sql
+-- Relying only on application to filter
+select * from orders where user_id = $current_user_id;
+
+-- Bug or bypass means all data is exposed!
+select * from orders;  -- Returns ALL orders
+```
+
+**Correct (database-enforced RLS):**
+
+```sql
+-- Enable RLS on the table
+alter table orders enable row level security;
+
+-- Create policy for users to see only their orders
+create policy orders_user_policy on orders
+  for all
+  using (user_id = current_setting('app.current_user_id')::bigint);
+
+-- Force RLS even for table owners
+alter table orders force row level security;
+
+-- Set user context and query
+set app.current_user_id = '123';
+select * from orders;  -- Only returns orders for user 123
+```
+
+Policy for authenticated role:
+
+```sql
+create policy orders_user_policy on orders
+  for all
+  to authenticated
+  using (user_id = auth.uid());
+```
+
+Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)

package/dist/global-skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -0,0 +1,63 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+
+```sql
+-- Create helper function in a private schema
+create or replace function private.is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    -- always check the calling user's identity inside the function
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Revoke direct execution from public roles
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select private.is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/dist/global-skills/track-errors/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: track-errors
+description: the builder gets alerted when something breaks in their live app — without watching logs themselves. Use when the builder says something like: tell me when things break; error alerts; app crashes.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: track-errors
+
+**Goal:** the builder gets alerted when something breaks in their live app — without watching logs themselves.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You set up alerts; the builder only pastes one key when asked.
+
+> (Under the hood — agent-only) Wire `@vybekiit/observability` via `resolveObservabilityProvider()`.
+> Default is silent no-op (`OBSERVABILITY_PROVIDER=local`). This skill switches to Sentry and proves
+> an alert fires. Follow `sentry-vybekiit.md`. Never say "Sentry" unless they ask — say "error alerts."
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/SystemHealthPage.tsx` export `SystemHealthPage` into the buyer app at route `/admin/health`.
+   Recipe id: `system-health`. Presets: none.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('track-errors')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Explain in one line.** *"I'm going to set up alerts so you know when something breaks in your live app."*
+
+2. **Create or open the alert project.** Sign in to the error-tracking dashboard (Sentry free tier) and
+   create a project for this app. Copy the **DSN** (connection string) from project settings.
+   **Verify:** you have a DSN ready — do not paste it in chat.
+
+3. **Wire it in.** Set in `.env`:
+   - `OBSERVABILITY_PROVIDER="sentry"`
+   - `SENTRY_DSN="<paste from dashboard>"`
+   Confirm `instrumentation.ts` and `src/lib/observability.ts` exist and import `@vybekiit/observability`.
+   **Verify:** app builds; provider resolves without error.
+
+4. **Prove it works.** Trigger a deliberate test error (dev-only button or one-time API call). Confirm
+   the event appears in the dashboard within a minute.
+   **Verify:** show the builder the alert entry in plain words ("Your test error showed up — alerts work.").
+
+5. **Protect live users.** Ensure production errors call `observability.captureException` from error
+   boundaries or API catch blocks — not bare `console.error` only.
+   **Verify:** one real code path uses `observability.captureException`.
+
+6. **Celebrate.** 🎉 *"You're covered — if something breaks online, you'll know."*
+
+## If anything breaks
+
+Run `doctor`. Most failures are a missing or wrong DSN — re-copy from the dashboard into `.env` only
+(never chat). If MCP fails once, run `vybekiit doc-fallback sentry`.
+
+## Definition of done
+
+`OBSERVABILITY_PROVIDER=sentry`, DSN set, test alert received, and the builder knows they'll be notified when things break.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/update-kit/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: update-kit
+description: get the latest kit improvements safely, without breaking the builder's app. Use when the builder says something like: update the kit; get the latest; upgrade.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: update-kit
+
+**Goal:** get the latest kit improvements safely, without breaking the builder's app.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You do the whole update; the builder just watches and confirms.
+
+> (Under the hood — agent-only) Updates run through **three channels** inside this one skill:
+> npm package bumps (`@vybekiit/*`), agent-layer refresh from the template mirror, and platform
+> instruction files pinned in `.agents/skills/`. The builder's own app code is never touched — only
+> maintained kit files listed in ADR-0007. Use `planKitUpdate()` from `@vybekiit/agent-kit` for
+> channel 1; `vybekiit sync-agent-layer` for channel 2; `npx skills update -y` for channel 3 when
+> `skills-lock.json` exists.
+
+## Steps
+
+1. **Run the tests first — the safety net.** Run the project's tests and make sure they're green
+   before changing anything. This is the before-picture you'll compare against.
+   **Verify:** all tests pass. If any are red, fix those first — never update on top of a broken app.
+
+2. **Explain in one line.** *"I'm going to pull in the latest improvements — the kit packages and
+   my latest instructions. Your own work won't be touched, and I'll test everything after."*
+
+3. **Update all three channels** (same plain sentence to the builder for each — never name tools):
+
+   **3a — Kit packages.** Bump the `@vybekiit/*` packages to their latest versions (use
+   `planKitUpdate()` to decide what to bump).
+   **Verify:** the install finishes cleanly.
+
+   **3b — Agent instructions.** Run `vybekiit sync-agent-layer` (or pass `web` if detection fails).
+   Regenerates vocabulary/contract sections from agent-kit. Optionally run `vybekiit render-agent-layer`
+   after local edits to maintained renderers.
+   Tell the builder: *"I'm refreshing my latest instructions for your project."*
+   **Verify:** command exits 0; allowlisted paths copied (`.vybekiit/`, `AGENTS.md`, `language.md`,
+   etc.). Buyer-owned `.vybekiit/extensions/**` and extension rows in `goal-index.md` are never
+   overwritten.
+
+   **3c — Platform instructions.** If `skills-lock.json` exists, run `npx skills update -y`.
+   Use the same plain sentence — never name Expo, Vercel, or the skills CLI.
+   **Verify:** update completes or report a plain-language retry later.
+
+4. **Re-run the tests.** Run the full suite again.
+   **Verify:** still green. If something broke, fix it — or roll back to the previous versions and
+   tell the builder, in plain words, what happened. Never leave them on a broken version.
+
+5. **Try the app for real.** Start it and click through the main things (sign-in, a purchase, saving
+   data — whatever they use).
+   **Verify:** the app still works.
+   🎉 *Celebrate* — they're on the latest, and nothing broke.
+
+## If anything breaks
+
+Run `doctor`. If a new version doesn't get along with their app and you can't fix it quickly, roll
+the kit packages back to the last working versions — the app keeps working while you sort it out.
+
+## Definition of done
+
+The kit packages are on their latest working versions, agent instructions are refreshed, platform
+skills are updated when pinned, the tests are green, the app still works, and none of the builder's
+own app files were changed.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/upgrading-expo/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: upgrading-expo
+description: Guidelines for upgrading Expo SDK versions and fixing dependency issues
+version: 1.0.0
+license: MIT
+---
+
+## References
+
+- ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
+- ./references/new-architecture.md -- SDK +53: New Architecture migration guide
+- ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide
+- ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.\*)
+- ./references/expo-av-to-audio.md -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio
+- ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video
+- ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate `@react-navigation/*` imports to `expo-router` entry points (codemod + manual mapping)
+
+## Beta/Preview Releases
+
+Beta versions use `.preview` suffix (e.g., `55.0.0-preview.2`), published under `@next` tag.
+
+Check if latest is beta: https://exp.host/--/api/v2/versions (look for `-preview` in `expoVersion`)
+
+```bash
+npx expo install expo@next --fix  # install beta
+```
+
+## Step-by-Step Upgrade Process
+
+1. Upgrade Expo and dependencies
+
+```bash
+npx expo install expo@latest
+npx expo install --fix
+```
+
+2. Run diagnostics: `npx expo-doctor`
+
+3. Clear caches and reinstall
+
+```bash
+npx expo export -p ios --clear
+rm -rf node_modules .expo
+watchman watch-del-all
+```
+
+## Breaking Changes Checklist
+
+- Check for removed APIs in release notes
+- Update import paths for moved modules
+- Review native module changes requiring prebuild
+- Test all camera, audio, and video features
+- Verify navigation still works correctly
+
+## Prebuild for Native Changes
+
+**First check if `ios/` and `android/` directories exist in the project.** If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.
+
+If upgrading requires native changes:
+
+```bash
+npx expo prebuild --clean
+```
+
+This regenerates the `ios` and `android` directories. Ensure the project is not a bare workflow app before running this command.
+
+## Clear caches for bare workflow
+
+These steps only apply when `ios/` and/or `android/` directories exist in the project:
+
+- Clear the cocoapods cache for iOS: `cd ios && pod install --repo-update`
+- Clear derived data for Xcode: `npx expo run:ios --no-build-cache`
+- Clear the Gradle cache for Android: `cd android && ./gradlew clean`
+
+## Housekeeping
+
+- Review release notes for the target SDK version at https://expo.dev/changelog
+- If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
+- Enable React Compiler in SDK 54+ by adding `"experiments": { "reactCompiler": true }` to app.json — it's stable and recommended
+- Delete sdkVersion from `app.json` to let Expo manage it automatically
+- Remove implicit packages from `package.json`: `@babel/core`, `babel-preset-expo`, `expo-constants`.
+- If the babel.config.js only contains 'babel-preset-expo', delete the file
+- If the metro.config.js only contains expo defaults, delete the file
+
+## Deprecated Packages
+
+| Old Package          | Replacement                                          |
+| -------------------- | ---------------------------------------------------- |
+| `expo-av`            | `expo-audio` and `expo-video`                        |
+| `expo-permissions`   | Individual package permission APIs                   |
+| `@expo/vector-icons` | `expo-symbols` (for SF Symbols)                      |
+| `AsyncStorage`       | `expo-sqlite/localStorage/install`                   |
+| `expo-app-loading`   | `expo-splash-screen`                                 |
+| expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |
+
+When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.
+
+## expo.install.exclude
+
+Check if package.json has excluded packages:
+
+```json
+{
+  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
+}
+```
+
+Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.
+## Removing patches
+
+Check if there are any outdated patches in the `patches/` directory. Remove them if they are no longer needed.
+
+## Postcss
+
+- `autoprefixer` isn't needed in SDK +53. Remove it from dependencies and check `postcss.config.js` or `postcss.config.mjs` to remove it from the plugins list.
+- Use `postcss.config.mjs` in SDK +53.
+
+## Metro
+
+Remove redundant metro config options:
+
+- resolver.unstable_enablePackageExports is enabled by default in SDK +53.
+- `experimentalImportSupport` is enabled by default in SDK +54.
+- `EXPO_USE_FAST_RESOLVER=1` is removed in SDK +54.
+- cjs and mjs extensions are supported by default in SDK +50.
+- Expo webpack is deprecated, migrate to [Expo Router and Metro web](https://docs.expo.dev/router/migrate/from-expo-webpack/).
+
+## Hermes engine v1
+
+Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting `useHermesV1: true` in the `expo-build-properties` config plugin, and may require a specific version of the `hermes-compiler` npm package. Hermes v1 will become a default in some future SDK release.
+
+## New Architecture
+
+The new architecture is enabled by default, the app.json field `"newArchEnabled": true` is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.

package/dist/global-skills/upgrading-expo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Upgrading Expo"
+  short_description: "Upgrade Expo SDKs, fix dependencies, adopt React 19 / React Compiler, and migrate deprecated Expo packages"
+  default_prompt: "Use $upgrading-expo to upgrade an Expo SDK, run diagnostics, fix dependency conflicts, decide whether prebuild/cache clearing applies, and migrate away from deprecated Expo packages."

package/dist/global-skills/upgrading-expo/references/expo-av-to-audio.md

@@ -0,0 +1,132 @@
+# Migrating from expo-av to expo-audio
+
+## Imports
+
+```tsx
+// Before
+import { Audio } from 'expo-av';
+
+// After
+import { useAudioPlayer, useAudioRecorder, RecordingPresets, AudioModule, setAudioModeAsync } from 'expo-audio';
+```
+
+## Audio Playback
+
+### Before (expo-av)
+
+```tsx
+const [sound, setSound] = useState<Audio.Sound>();
+
+async function playSound() {
+  const { sound } = await Audio.Sound.createAsync(require('./audio.mp3'));
+  setSound(sound);
+  await sound.playAsync();
+}
+
+useEffect(() => {
+  return sound ? () => { sound.unloadAsync(); } : undefined;
+}, [sound]);
+```
+
+### After (expo-audio)
+
+```tsx
+const player = useAudioPlayer(require('./audio.mp3'));
+
+// Play
+player.play();
+```
+
+## Audio Recording
+
+### Before (expo-av)
+
+```tsx
+const [recording, setRecording] = useState<Audio.Recording>();
+
+async function startRecording() {
+  await Audio.requestPermissionsAsync();
+  await Audio.setAudioModeAsync({ allowsRecordingIOS: true, playsInSilentModeIOS: true });
+  const { recording } = await Audio.Recording.createAsync(Audio.RecordingOptionsPresets.HIGH_QUALITY);
+  setRecording(recording);
+}
+
+async function stopRecording() {
+  await recording?.stopAndUnloadAsync();
+  const uri = recording?.getURI();
+}
+```
+
+### After (expo-audio)
+
+```tsx
+const recorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
+
+async function startRecording() {
+  await AudioModule.requestRecordingPermissionsAsync();
+  await recorder.prepareToRecordAsync();
+  recorder.record();
+}
+
+async function stopRecording() {
+  await recorder.stop();
+  const uri = recorder.uri;
+}
+```
+
+## Audio Mode
+
+### Before (expo-av)
+
+```tsx
+await Audio.setAudioModeAsync({
+  allowsRecordingIOS: true,
+  playsInSilentModeIOS: true,
+  staysActiveInBackground: true,
+  interruptionModeIOS: InterruptionModeIOS.DoNotMix,
+});
+```
+
+### After (expo-audio)
+
+```tsx
+await setAudioModeAsync({
+  playsInSilentMode: true,
+  shouldPlayInBackground: true,
+  interruptionMode: 'doNotMix',
+});
+```
+
+## API Mapping
+
+| expo-av | expo-audio |
+|---------|------------|
+| `Audio.Sound.createAsync()` | `useAudioPlayer(source)` |
+| `sound.playAsync()` | `player.play()` |
+| `sound.pauseAsync()` | `player.pause()` |
+| `sound.setPositionAsync(ms)` | `player.seekTo(seconds)` |
+| `sound.setVolumeAsync(vol)` | `player.volume = vol` |
+| `sound.setRateAsync(rate)` | `player.playbackRate = rate` |
+| `sound.setIsLoopingAsync(loop)` | `player.loop = loop` |
+| `sound.unloadAsync()` | Automatic via hook |
+| `playbackStatus.positionMillis` | `player.currentTime` (seconds) |
+| `playbackStatus.durationMillis` | `player.duration` (seconds) |
+| `playbackStatus.isPlaying` | `player.playing` |
+| `Audio.Recording.createAsync()` | `useAudioRecorder(preset)` |
+| `Audio.RecordingOptionsPresets.*` | `RecordingPresets.*` |
+| `recording.stopAndUnloadAsync()` | `recorder.stop()` |
+| `recording.getURI()` | `recorder.uri` |
+| `Audio.requestPermissionsAsync()` | `AudioModule.requestRecordingPermissionsAsync()` |
+
+## Key Differences
+
+- **No auto-reset on finish**: After `play()` completes, the player stays paused at the end. To replay, call `player.seekTo(0)` then `play()`
+- **Time in seconds**: expo-audio uses seconds, not milliseconds (matching web standards)
+- **Immediate loading**: Audio loads immediately when the hook mounts—no explicit preloading needed
+- **Automatic cleanup**: No need to call `unloadAsync()`, hooks handle resource cleanup on unmount
+- **Multiple players**: Create multiple `useAudioPlayer` instances and store them—all load immediately
+- **Direct property access**: Set volume, rate, loop directly on the player object (`player.volume = 0.5`)
+
+## API Reference
+
+https://docs.expo.dev/versions/latest/sdk/audio/