@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/getting-started/installation-guide.md

@@ -36,10 +36,23 @@ npm install @jmruthers/pace-core
 
 **Required Peer Dependencies:**
 ```bash
-npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
+npm install react react-dom @tanstack/react-query @tanstack/react-table clsx date-fns date-fns-tz react-day-picker react-hook-form react-router-dom tailwind-merge tailwindcss zod
 ```
 
-**Note**: `@supabase/supabase-js` and `@tanstack/react-query` are included as dependencies and do not need to be installed separately.
+> **📦 Complete Dependencies Reference**: See [Dependencies Guide](./dependencies.md) for a detailed breakdown of:
+> - ✅ Which packages are **already included** (don't install)
+> - ⚠️ Which packages are **required peer dependencies** (must install)
+> - ❌ Common mistakes to avoid
+> - 🔍 How to verify your installation
+
+**Note**: The following packages are **included dependencies** - **DO NOT install them**, use pace-core exports instead:
+- `@supabase/supabase-js` - Use `createBaseClient()` from `@jmruthers/pace-core` (security enforcement)
+- `@radix-ui/*` packages - Use pace-core components (consistency enforcement)
+- `lucide-react` - Use `@jmruthers/pace-core/icons` (consistency enforcement)
+
+The following packages are **peer dependencies** and **MUST be installed**:
+- `@tanstack/react-query` - Required for `QueryClient`, `QueryClientProvider`, and React Query hooks
+- `date-fns` and `date-fns-tz` - Required for date formatting (apps may use date-fns functions directly)
 
 ### Step 2: Install Tailwind CSS v4
 
@@ -286,19 +299,19 @@ export default App;
 
 If you're using PACE Core's authentication features:
 
-```bash
-npm install @supabase/supabase-js
-```
+**⚠️ Important**: `@supabase/supabase-js` is **included** in pace-core - you do NOT need to install it separately. Use `createBaseClient()` from pace-core instead.
 
 Create `src/lib/supabase.ts`:
 
 ```typescript
-import { createClient } from '@supabase/supabase-js'
+import { createBaseClient } from '@jmruthers/pace-core'
 
+// Base Supabase client for UnifiedAuthProvider only
+// DO NOT use this client directly - use useSecureSupabase() instead
 const supabaseUrl = process.env.VITE_SUPABASE_URL!
 const supabasePublishableKey = process.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+export const supabase = createBaseClient(supabaseUrl, supabasePublishableKey)
 ```
 
 Set environment variables in `.env.local`:

package/docs/getting-started/quick-start.md

@@ -29,20 +29,29 @@ npm install
 
 ## Step 2: Install PACE Core
 
+> **📦 Dependencies Guide**: See [Dependencies Guide](./dependencies.md) for complete details on which packages to install and which are already included.
+
 ```bash
-# Install PACE Core and required peer dependencies
-npm install @jmruthers/pace-core \
-  @supabase/supabase-js \
-  @tanstack/react-query @tanstack/react-table \
-  @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog \
-  @radix-ui/react-label @radix-ui/react-slot \
-  @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip \
-  clsx lucide-react react-day-picker react-hook-form react-router-dom tailwind-merge zod
-
-# Install Tailwind v4
-npm install -D tailwindcss@^4.0.0 @tailwindcss/vite
+# Install PACE Core
+npm install @jmruthers/pace-core
+
+# Install required peer dependencies
+npm install react react-dom @tanstack/react-query @tanstack/react-table \
+  clsx date-fns date-fns-tz react-day-picker react-hook-form react-router-dom tailwind-merge tailwindcss zod
+
+# Install Tailwind v4 (dev dependency)
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
 ```
 
+**⚠️ Important**: 
+- ❌ **DO NOT install** `@supabase/supabase-js`, `@radix-ui/*`, or `lucide-react` - they're included in pace-core. Use pace-core exports instead:
+  - `createBaseClient()` from `@jmruthers/pace-core` (instead of `createClient` from `@supabase/supabase-js`)
+  - pace-core components (instead of `@radix-ui/*` primitives)
+  - `@jmruthers/pace-core/icons` (instead of `lucide-react`)
+- ⚠️ `@tanstack/react-query` is a **peer dependency** - you MUST install it (required for QueryClient configuration)
+- ⚠️ All listed packages above are **required peer dependencies** - you must install them
+- See [Dependencies Guide](./dependencies.md) for the complete breakdown
+
 ## Step 3: Configure Vite
 
 **⚠️ CRITICAL**: This configuration prevents React context and Router context errors.
@@ -120,9 +129,11 @@ import { createClient } from '@supabase/supabase-js';
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL!;
 const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!;
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+export const supabase = createClient(supabaseUrl, supabasePublishableKey);
 ```
 
+**Note**: `@supabase/supabase-js` is already included in pace-core, so you don't need to install it separately. Just import it directly.
+
 ## Step 6: Set Up Your Database
 
 In your Supabase dashboard, run this SQL to create a simple `tasks` table:

package/docs/implementation-guides/permission-enforcement.md

@@ -49,12 +49,16 @@ setupRBAC(supabase);
 
 ## Layout-Level Permission Enforcement
 
+> **📋 Contract Reference**: See [RBAC Contract](../rbac/RBAC_CONTRACT.md#enforcepermissions-configuration) for when to use `enforcePermissions={true}` vs `enforcePermissions={false}`.
+
 ### Why Layout-Level Enforcement?
 
 Layout-level enforcement provides a safety net that prevents consuming apps from forgetting to implement permission checks. It ensures that every route is automatically validated for permissions.
 
 **Note:** Super admins automatically bypass all permission checks in PaceAppLayout. The component checks super admin status before enforcing permissions, ensuring super admins can access any route without violations.
 
+**⚠️ Important**: For event-based apps, set `enforcePermissions={false}` because pages handle their own checks via `PagePermissionGuard`. For organisation-based apps, set `enforcePermissions={true}` to enable layout-level checks.
+
 ### Basic Implementation
 
 ```tsx