@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/standards/00-pace-core-compliance.md

@@ -0,0 +1,967 @@
+# pace-core Compliance Enforcement
+
+**🤖 Cursor Rule**: See [00-pace-core-compliance.mdc](../../cursor-rules/00-pace-core-compliance.mdc) for AI-optimized directives that automatically enforce these standards.
+
+This guide explains how to enforce pace-core usage patterns in consuming apps to ensure consistent design, reduce duplication, and maintain high code quality.
+
+## Overview
+
+pace-core provides a comprehensive enforcement system that includes:
+
+1. **ESLint Rules** - Real-time linting during development (15 rules)
+2. **Static Analysis Script** - Comprehensive codebase scanning for file-system and config checks
+3. **ESLint Config Preset** - Easy setup for consuming apps
+4. **Cursor Rules Integration** - AI-assisted enforcement via Cursor IDE
+
+### ESLint vs Audit Scripts
+
+**ESLint Rules** (Real-time, AST-based):
+- ✅ Run automatically in your IDE
+- ✅ Provide immediate feedback during development
+- ✅ Check single files using AST analysis
+- ✅ Can be auto-fixed in many cases
+- ✅ Integrated with your development workflow
+
+**Audit Scripts** (Comprehensive, file-system based):
+- ✅ Scan entire codebase
+- ✅ Check file structure and configuration
+- ✅ Cross-file analysis (e.g., provider nesting)
+- ✅ Generate detailed reports
+- ✅ Check setup files (main.tsx, app.css, etc.)
+
+**What's in ESLint vs Audit Scripts**:
+
+| Check | ESLint | Audit Script |
+|-------|--------|--------------|
+| Restricted imports | ✅ | ✅ (reference) |
+| Native HTML elements | ✅ | ✅ (reference) |
+| Custom hooks/utils | ✅ | ✅ (reference) |
+| Inline styles | ✅ | ✅ (reference) |
+| Plain form tags | ✅ | ✅ (reference) |
+| Direct Supabase client | ✅ | ✅ (file location) |
+| RBAC permission loading | ✅ | ✅ (reference) |
+| Direct RBAC RPC/table | ✅ | ✅ (reference) |
+| Hardcoded role checks | ✅ | ✅ (reference) |
+| RESOURCE_NAMES constants | ✅ | ✅ (reference) |
+| RBAC wrapper components | ✅ | ✅ (reference) |
+| RBAC wrapper functions | ✅ | ✅ (reference) |
+| RBAC setup (main.tsx) | ❌ | ✅ |
+| Provider nesting | ❌ | ✅ |
+| Core styles import chain | ❌ | ✅ |
+| PagePermissionGuard coverage | ❌ | ✅ |
+| Edge Functions RBAC | ❌ | ✅ |
+
+**Note**: Many checks have been migrated from audit scripts to ESLint for real-time feedback. The audit scripts now focus on file-system and configuration checks that require cross-file analysis.
+
+## Quick Start
+
+### Step 1: Install pace-core
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### Step 2: Setup ESLint (Recommended)
+
+**Option A: Automated Setup (Easiest)**
+
+Use the installation script to set up both Cursor rules and ESLint:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+```
+
+This script will:
+- ✅ Install Cursor rules to `.cursor/rules/`
+- ✅ Configure ESLint to use pace-core rules
+- ✅ Create `eslint.config.js` if it doesn't exist
+- ✅ Add pace-core config to existing ESLint config
+- ✅ Create backups before modifying files
+
+**Options:**
+- `--force` - Force update even if already configured
+- `--skip-cursor` - Skip Cursor rules installation
+- `--skip-eslint` - Skip ESLint config setup
+
+**Option B: Manual Setup**
+
+The easiest way to enable compliance checking is to use the shareable ESLint config. The config is CommonJS but works with both ES module and CommonJS ESLint configs:
+
+**For ES Module ESLint Config (eslint.config.js):**
+```javascript
+// eslint.config.js (ES modules)
+import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+
+export default [
+  ...paceCoreConfig,
+  // your other config
+];
+```
+
+**For CommonJS ESLint Config (.eslintrc.js or eslint.config.cjs):**
+```javascript
+// eslint.config.cjs (CommonJS)
+const paceCoreConfig = require('@jmruthers/pace-core/eslint-config');
+
+module.exports = [
+  ...paceCoreConfig,
+  // your other config
+];
+```
+
+**Complete Example (ESLint 9 flat config):**
+```javascript
+// eslint.config.js
+import js from '@eslint/js';
+import reactHooks from 'eslint-plugin-react-hooks';
+import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+
+export default [
+  js.configs.recommended,
+  ...paceCoreConfig, // pace-core rules
+  {
+    files: ['**/*.{ts,tsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      // Your other rules
+    },
+  },
+];
+```
+
+### Step 3: Setup Cursor Rules (Optional but Recommended)
+
+To enable AI-assisted enforcement in Cursor IDE, copy the pace-core cursor rules to your project:
+
+```bash
+# Create .cursor/rules directory if it doesn't exist
+mkdir -p .cursor/rules
+
+# Copy pace-core cursor rules
+cp node_modules/@jmruthers/pace-core/cursor-rules/*.mdc .cursor/rules/
+```
+
+Or manually create `.cursor/rules/00-pace-core-compliance.mdc` and reference the pace-core rules:
+
+```markdown
+---
+description: Enforce pace-core usage patterns
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: false
+---
+
+# pace-core Compliance
+
+**📚 Full Documentation**: See [pace-core compliance docs](node_modules/@jmruthers/pace-core/docs/standards/00-pace-core-compliance.md)
+
+**🔧 ESLint Setup**: Ensure ESLint is configured with `@jmruthers/pace-core/eslint-config`
+
+This rule enforces pace-core usage patterns. ESLint provides real-time feedback, while this Cursor rule provides AI-assisted guidance.
+
+## Key Requirements
+
+- Use pace-core components instead of native HTML or custom implementations
+- Use pace-core hooks instead of custom hooks
+- Use pace-core utilities instead of custom utilities
+- Use `useSecureSupabase()` instead of direct Supabase client creation
+- Follow RBAC patterns from pace-core
+- Use RESOURCE_NAMES constants instead of string literals
+
+See the full documentation for complete rules and examples.
+```
+
+**Benefits of Cursor Rules Integration**:
+- AI assistant (like me!) will automatically suggest pace-core alternatives
+- Context-aware suggestions during code writing
+- Works alongside ESLint for comprehensive enforcement
+- Provides explanations and examples in real-time
+
+### Option 2: Manual ESLint Rules Setup
+
+If you prefer more control, you can import the rules directly. Note: The rules are CommonJS, so use `createRequire` in ES modules:
+
+**For ES Module ESLint Config:**
+```javascript
+// eslint.config.js
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const paceCoreRules = require('@jmruthers/pace-core/eslint-rules').rules;
+
+export default [
+  {
+    plugins: {
+      'pace-core-compliance': {
+        rules: paceCoreRules
+      }
+    },
+    rules: {
+      'pace-core-compliance/no-restricted-imports': 'error',
+      'pace-core-compliance/prefer-pace-core-components': 'warn',
+      'pace-core-compliance/prefer-pace-core-hooks': 'warn',
+      'pace-core-compliance/prefer-pace-core-utils': 'warn',
+      'pace-core-compliance/no-local-component-duplication': 'error'
+    }
+  }
+];
+```
+
+**For CommonJS ESLint Config:**
+```javascript
+// eslint.config.cjs
+const paceCoreRules = require('@jmruthers/pace-core/eslint-rules').rules;
+
+module.exports = [
+  {
+    plugins: {
+      'pace-core-compliance': {
+        rules: paceCoreRules
+      }
+    },
+    rules: {
+      'pace-core-compliance/no-restricted-imports': 'error',
+      'pace-core-compliance/prefer-pace-core-components': 'warn',
+      'pace-core-compliance/prefer-pace-core-hooks': 'warn',
+      'pace-core-compliance/prefer-pace-core-utils': 'warn',
+      'pace-core-compliance/no-local-component-duplication': 'error'
+    }
+  }
+];
+```
+
+## ESLint Rules
+
+pace-core provides **15 ESLint rules** organized into four categories:
+
+### Import Rules
+
+#### no-restricted-imports
+
+**Severity**: Error
+
+Blocks direct imports of libraries that pace-core wraps and standardizes.
+
+**Restricted Libraries**:
+- `@radix-ui/*` - All Radix UI packages (use pace-core components instead)
+- `lucide-react` - Icons (import from `@jmruthers/pace-core/icons` instead)
+- `react-day-picker` - Use `Calendar` from pace-core
+- `@tanstack/react-table` - Use `DataTable` from pace-core
+- `react-hook-form` - Use `Form` and `useZodForm` from pace-core
+- `zod` - Use validation utilities from pace-core
+
+**Example Violation**:
+```typescript
+// ❌ Bad
+import { Dialog } from '@radix-ui/react-dialog';
+import { ChevronDown, Edit, Trash } from 'lucide-react';
+
+// ✅ Good
+import { Dialog } from '@jmruthers/pace-core';
+import { ChevronDown, Edit, Trash } from '@jmruthers/pace-core/icons';
+```
+
+### Compliance Rules
+
+#### prefer-pace-core-components
+
+**Severity**: Warning
+
+Suggests using pace-core components instead of native HTML elements.
+
+**Detected Patterns**:
+- `<button>` → Use `Button` from pace-core
+- `<input>` → Use `Input` from pace-core
+- `<textarea>` → Use `Textarea` from pace-core
+- `<label>` → Use `Label` from pace-core
+
+**Example**:
+```tsx
+// ⚠️ Warning
+<button onClick={handleClick}>Click me</button>
+
+// ✅ Recommended
+import { Button } from '@jmruthers/pace-core';
+<Button onClick={handleClick}>Click me</Button>
+```
+
+#### prefer-pace-core-hooks
+
+**Severity**: Warning
+
+Detects custom hooks that duplicate pace-core functionality.
+
+**Common Patterns Detected**:
+- `useToast`, `useNotification` → Use `useToast` from pace-core
+- `useDebounce`, `useDebounced` → Use `useDebounce` from pace-core
+- `useAuth`, `useAuthentication` → Use `useUnifiedAuth` from pace-core
+- `useForm`, `useZodForm` → Use `useZodForm` from pace-core
+
+**Example**:
+```typescript
+// ⚠️ Warning
+function useToast() {
+  // custom implementation
+}
+
+// ✅ Recommended
+import { useToast } from '@jmruthers/pace-core';
+```
+
+#### prefer-pace-core-utils
+
+**Severity**: Warning
+
+Detects utility functions that duplicate pace-core functionality.
+
+**Common Patterns Detected**:
+- `formatDate`, `dateFormat` → Use `formatDate` from pace-core
+- `formatCurrency`, `formatMoney` → Use `formatCurrency` from pace-core
+- `cn`, `classNames`, `clsx` → Use `cn` from pace-core
+- `validate`, `validateInput` → Use `validateUserInput` from pace-core
+
+**Example**:
+```typescript
+// ⚠️ Warning
+function formatDate(date: Date): string {
+  // custom implementation
+}
+
+// ✅ Recommended
+import { formatDate } from '@jmruthers/pace-core';
+```
+
+#### no-local-component-duplication
+
+**Severity**: Error
+
+Prevents creating local components with names matching pace-core components.
+
+**Example Violation**:
+```
+// ❌ Error: components/Button.tsx
+export function Button() { ... }
+
+// pace-core already provides Button component
+```
+
+**Fix**: Remove the local component and import from pace-core:
+```typescript
+import { Button } from '@jmruthers/pace-core';
+```
+
+#### no-inline-styles
+
+**Severity**: Error
+
+Disallows inline styles. Use pace-core components or Tailwind classes instead.
+
+**Example Violation**:
+```tsx
+// ❌ Error
+<div style={{ color: 'red', padding: '10px' }}>Content</div>
+
+// ✅ Good
+<div className="text-acc-500 p-4">Content</div>
+// Or use pace-core components with built-in styling
+```
+
+### Component Rules
+
+#### prefer-pace-core-form
+
+**Severity**: Error
+
+Disallows plain `<form>` tags and direct `react-hook-form` imports. Use pace-core `Form` component instead.
+
+**Detected Patterns**:
+- Plain `<form>` tags
+- Direct imports from `react-hook-form` (except `useFormContext` when using pace-core `Form`)
+
+**Example Violation**:
+```tsx
+// ❌ Error
+import { useForm, FormProvider } from 'react-hook-form';
+<form onSubmit={handleSubmit}>...</form>
+
+// ✅ Good
+import { Form, useZodForm } from '@jmruthers/pace-core';
+<Form form={form} onSubmit={handleSubmit}>...</Form>
+```
+
+**Exception**: `useFormContext` is allowed when `Form` is imported from pace-core:
+```tsx
+// ✅ Allowed
+import { Form } from '@jmruthers/pace-core';
+import { useFormContext } from 'react-hook-form'; // OK when using pace-core Form
+```
+
+### RBAC Rules
+
+#### no-direct-supabase-client
+
+**Severity**: Error
+
+Disallows direct `createClient()` calls from `@supabase/supabase-js`. Use `useSecureSupabase()` from pace-core instead.
+
+**Why**: Direct client creation bypasses organisation context and RLS policies, leading to security vulnerabilities.
+
+**Example Violation**:
+```typescript
+// ❌ Error
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(url, key);
+
+// ✅ Good
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+const secureSupabase = useSecureSupabase();
+```
+
+**Exception**: Creating the base client for `UnifiedAuthProvider` in `main.tsx` or `App.tsx` is allowed.
+
+#### rbac-permission-loading
+
+**Severity**: Error
+
+Requires `isLoading` extraction from `useResourcePermissions` and checking it before permission calls in mutations.
+
+**Why**: Permission checks may fail if scope resolution is still in progress.
+
+**Example Violation**:
+```typescript
+// ❌ Error
+const { canCreate, canUpdate } = useResourcePermissions(RESOURCE_NAMES.EVENTS);
+// Missing isLoading extraction
+
+// In mutation:
+if (canCreate(event)) { ... } // May fail if permissions still loading
+
+// ✅ Good
+const { canCreate, canUpdate, isLoading: permissionsLoading } = useResourcePermissions(RESOURCE_NAMES.EVENTS);
+
+// In mutation:
+if (permissionsLoading) {
+  throw new Error('Permission check in progress. Please wait...');
+}
+if (!canCreate(event)) {
+  throw new Error('Insufficient permissions');
+}
+```
+
+#### no-direct-rbac-rpc
+
+**Severity**: Error
+
+Disallows direct RPC calls to RBAC functions (e.g., `rbac_check_permission_simplified`). Use pace-core RBAC hooks instead.
+
+**Example Violation**:
+```typescript
+// ❌ Error
+const { data } = await supabase.rpc('rbac_check_permission_simplified', {...});
+
+// ✅ Good
+import { isPermitted } from '@jmruthers/pace-core/rbac';
+const hasPermission = await isPermitted({...});
+```
+
+#### no-direct-rbac-table
+
+**Severity**: Error
+
+Disallows direct queries to RBAC tables. Use `useSecureSupabase()` hook or pace-core RBAC API functions instead.
+
+**RBAC Tables**:
+- `rbac_organisation_roles`
+- `rbac_event_app_roles`
+- `rbac_global_roles`
+- `rbac_apps`
+- `rbac_app_pages`
+- `rbac_page_permissions`
+- `rbac_user_profiles`
+
+**Example Violation**:
+```typescript
+// ❌ Error
+const { data } = await supabase.from('rbac_organisation_roles').select('*');
+
+// ✅ Good
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+const secureSupabase = useSecureSupabase();
+const { data } = await secureSupabase.from('rbac_organisation_roles').select('*');
+```
+
+#### no-hardcoded-role-checks
+
+**Severity**: Error
+
+Disallows hardcoded role checks. Use `useAccessLevel` hook or `getRoleContext` API from pace-core instead.
+
+**Example Violation**:
+```typescript
+// ❌ Error
+if (user.role === 'admin') { ... }
+if (currentRole === 'org_admin') { ... }
+
+// ✅ Good
+import { useAccessLevel } from '@jmruthers/pace-core/rbac';
+const { accessLevel } = useAccessLevel();
+if (accessLevel === 'admin') { ... }
+```
+
+#### rbac-use-resource-names-constants
+
+**Severity**: Error
+
+Requires `RESOURCE_NAMES` constants instead of string literals in `useResourcePermissions` calls.
+
+**Example Violation**:
+```typescript
+// ❌ Error
+const permissions = useResourcePermissions('organisations');
+
+// ✅ Good
+import { RESOURCE_NAMES } from '@/config/resource-names';
+const permissions = useResourcePermissions(RESOURCE_NAMES.ORGANISATIONS);
+```
+
+#### no-rbac-wrapper-components
+
+**Severity**: Error
+
+Disallows wrapper components around `PagePermissionGuard`. Use `PagePermissionGuard` directly.
+
+**Example Violation**:
+```tsx
+// ❌ Error
+function ProtectedPage({ pageName, children }) {
+  return <PagePermissionGuard pageName={pageName}>{children}</PagePermissionGuard>;
+}
+
+// ✅ Good
+<PagePermissionGuard pageName="events" operation="read">
+  <YourPageContent />
+</PagePermissionGuard>
+```
+
+#### no-rbac-wrapper-functions
+
+**Severity**: Error
+
+Disallows wrapper functions around pace-core permission hooks. Use hooks directly in components.
+
+**Example Violation**:
+```typescript
+// ❌ Error
+function canEditEvent(eventId: string) {
+  const { canUpdate } = useResourcePermissions(RESOURCE_NAMES.EVENTS);
+  return canUpdate(eventId) && someOtherCondition;
+}
+
+// ✅ Good
+function YourComponent() {
+  const { canUpdate } = useResourcePermissions(RESOURCE_NAMES.EVENTS);
+  // Use canUpdate directly in component logic
+}
+```
+
+## Static Analysis Script
+
+The static analysis script provides a comprehensive scan of your codebase and generates a detailed compliance report.
+
+### Running the Script
+
+```bash
+# From your consuming app root
+node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+```
+
+Or add it to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "check:pace-core": "node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs"
+  }
+}
+```
+
+### What It Checks
+
+1. **Restricted Imports** - Scans for direct imports of wrapped libraries
+2. **Duplicate Components** - Finds local components matching pace-core names
+3. **Duplicate Hooks** - Finds local hooks matching pace-core hooks
+4. **Duplicate Utils** - Finds local utils matching pace-core utils
+5. **Suggestions** - Recommends pace-core alternatives for native HTML elements
+
+### Report Output
+
+The script generates a color-coded terminal report showing:
+
+- ❌ **Errors** - Critical violations that must be fixed
+- ⚠️ **Warnings** - Issues that should be addressed
+- 💡 **Suggestions** - Recommendations for improvement
+- ✅ **Summary** - Overall compliance status
+
+Example output:
+```
+═══════════════════════════════════════════════════════════
+  pace-core Compliance Report
+═══════════════════════════════════════════════════════════
+
+❌ Restricted Imports Found: 3
+
+  • src/components/CustomDialog.tsx:5
+    Import: @radix-ui/react-dialog
+    Reason: Use Dialog component from pace-core instead
+
+Summary:
+  Total Issues: 3
+  - Restricted Imports: 3
+  - Duplicate Components/Hooks/Utils: 0
+  - Suggestions: 0
+```
+
+## Best Practices
+
+### 1. Always Import from pace-core
+
+```typescript
+// ✅ Good
+import { Button, Card, Dialog } from '@jmruthers/pace-core';
+import { useToast, useDebounce } from '@jmruthers/pace-core';
+import { formatDate, formatCurrency } from '@jmruthers/pace-core';
+```
+
+### 2. Use pace-core Components for UI
+
+Avoid native HTML elements when pace-core provides a component:
+
+```tsx
+// ❌ Avoid
+<button className="btn">Click</button>
+
+// ✅ Use pace-core
+<Button>Click</Button>
+```
+
+### 3. Leverage pace-core Hooks
+
+Don't recreate hooks that pace-core already provides:
+
+```typescript
+// ❌ Avoid
+const [debouncedValue, setDebouncedValue] = useState(value);
+useEffect(() => {
+  const timer = setTimeout(() => setDebouncedValue(value), 500);
+  return () => clearTimeout(timer);
+}, [value]);
+
+// ✅ Use pace-core
+import { useDebounce } from '@jmruthers/pace-core';
+const debouncedValue = useDebounce(value, 500);
+```
+
+### 4. Use pace-core Utilities
+
+Leverage formatting, validation, and other utilities from pace-core:
+
+```typescript
+// ❌ Avoid
+const formatted = new Intl.DateTimeFormat('en-US').format(date);
+
+// ✅ Use pace-core
+import { formatDate } from '@jmruthers/pace-core';
+const formatted = formatDate(date);
+```
+
+### 5. Check Before Creating New Components
+
+Before creating a new component, check if pace-core already provides it:
+
+1. Review the [pace-core documentation](https://github.com/your-org/pace-core)
+2. Check `core-usage-manifest.json` for available components
+3. Search pace-core exports
+
+## Troubleshooting
+
+### ESLint Rules Not Working
+
+1. **Verify plugin is loaded**: Check that the config is imported correctly:
+   ```javascript
+   // In your eslint.config.js, add temporarily:
+   import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+   console.log('Config:', paceCoreConfig);
+   console.log('Has plugins:', paceCoreConfig[0]?.plugins);
+   ```
+
+2. **Check rule names**: Rules must be prefixed with `pace-core-compliance/`
+
+3. **Verify manifest exists**: Rules load from `core-usage-manifest.json` in the pace-core package
+
+4. **CommonJS/ES Module issues**: If you're using ES modules and rules aren't loading:
+   - Ensure you're using the config preset (Option 1) which handles this automatically
+   - Or use `createRequire` when importing rules directly (Option 2)
+
+5. **Verify rules are available**: Check that the rules file exists:
+   ```bash
+   ls node_modules/@jmruthers/pace-core/dist/eslint-rules/index.cjs
+   ```
+
+6. **Check rule count**: Verify all 15 rules are loaded:
+   ```bash
+   node -e "const rules = require('@jmruthers/pace-core/eslint-rules'); console.log('Rules:', Object.keys(rules.rules).length);"
+   ```
+   Should output: `Rules: 15`
+
+### Static Analysis Script Errors
+
+1. **Manifest not found**: Ensure `core-usage-manifest.json` exists in pace-core package
+2. **No files scanned**: Check that you're running from the project root
+3. **Permission errors**: Ensure script has read access to source files
+
+### False Positives
+
+If you encounter false positives:
+
+1. **Component name conflicts**: If you have a legitimate reason to create a local component with a pace-core name, consider:
+   - Renaming your component
+   - Using a namespace/prefix
+   - Documenting why pace-core doesn't meet your needs
+
+2. **Hook/Util patterns**: The pattern matching may flag similar names. Review the suggestion and decide if migration makes sense.
+
+## Integration with CI/CD
+
+While CI/CD integration is not included in the initial release, you can easily add it:
+
+```yaml
+# .github/workflows/pace-core-compliance.yml
+name: pace-core Compliance
+
+on: [push, pull_request]
+
+jobs:
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npm run check:pace-core
+      - run: npm run lint
+```
+
+## Verification
+
+After setting up the ESLint config, verify it's working:
+
+1. **Check ESLint can load the config**:
+   ```bash
+   npx eslint --print-config src/App.tsx
+   ```
+   Look for `pace-core-compliance` in the plugins section.
+
+2. **Test with a violation**: Create a test file that imports a restricted library:
+   ```typescript
+   // test-violation.ts
+   import { Dialog } from '@radix-ui/react-dialog'; // Should trigger error
+   ```
+   Run ESLint and verify it reports the violation.
+
+3. **Run static analysis**: Use the compliance script to get a full report:
+   ```bash
+   npm run check:pace-core
+   ```
+
+## Getting Help
+
+- **Documentation**: See [pace-core docs](../README.md)
+- **Issues**: Report false positives or rule issues
+- **Manifest**: Check `core-usage-manifest.json` for available exports
+- **ESLint Config**: The config file is at `@jmruthers/pace-core/eslint-config` (CommonJS)
+- **ESLint Rules**: The rules are at `@jmruthers/pace-core/eslint-rules` (CommonJS)
+
+## File Locations
+
+When installed in a consuming app, the compliance tools are available at:
+
+- **ESLint Config**: `node_modules/@jmruthers/pace-core/eslint-config-pace-core.cjs`
+- **ESLint Rules**: `node_modules/@jmruthers/pace-core/dist/eslint-rules/index.cjs`
+- **Rule Modules**: `node_modules/@jmruthers/pace-core/dist/eslint-rules/rules/*.cjs`
+- **Rule Utils**: `node_modules/@jmruthers/pace-core/dist/eslint-rules/utils/*.cjs`
+- **Static Analysis Script**: `node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs`
+- **Manifest**: `node_modules/@jmruthers/pace-core/core-usage-manifest.json`
+- **Cursor Rules**: `node_modules/@jmruthers/pace-core/cursor-rules/*.mdc`
+
+## MUST: Use Secure Supabase Client
+
+**All database operations MUST use `useSecureSupabase()` (or the contract-approved pace-core secure client wrapper).**
+Consuming apps **MUST NOT** use the base Supabase client directly for queries.
+
+### Hard Requirements
+
+- **MUST NOT** import or call `createClient()` from `@supabase/supabase-js` in consuming app code **except** for creating the base client passed to `UnifiedAuthProvider`.
+- **MUST NOT** export, pass, or store an insecure Supabase client instance for general use.
+- **MUST** perform all `.from(...)`, `.rpc(...)`, `.auth.*`, and storage operations via the secure client returned by `useSecureSupabase()` (or the approved pace-core equivalent).
+- **MUST** create the base Supabase client ONCE and pass it to `UnifiedAuthProvider` as `supabaseClient` prop.
+- **MUST** call `useSecureSupabase()` without parameters - it automatically uses the base client from `useUnifiedAuth()` provider layer.
+- **MUST NOT** pass a base client directly to `useSecureSupabase()` - the hook gets it from the provider automatically.
+
+### Why this is critical
+
+Using `createClient()` directly for queries can bypass organisation context enforcement and RLS policies, leading to:
+- Cross-organisation data access
+- Security vulnerabilities
+- Data leakage between organisations
+
+### Correct Pattern
+
+```tsx
+// ✅ CORRECT: Create base client ONCE for UnifiedAuthProvider
+// main.tsx or App.tsx
+import { createClient } from '@supabase/supabase-js';
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+);
+
+function App() {
+  return (
+    <UnifiedAuthProvider 
+      supabaseClient={supabase}  // Pass base client to provider
+      appName="YourApp"
+      // ... other props
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+
+// ✅ CORRECT: Use secure client in components (no parameters needed)
+// YourComponent.tsx
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+
+function YourComponent() {
+  const secureSupabase = useSecureSupabase(); // Gets client from provider automatically
+  
+  if (!secureSupabase) {
+    return <div>Loading...</div>;
+  }
+  
+  // Use secureSupabase for all queries
+  const { data } = await secureSupabase.from('users').select('*');
+}
+```
+
+### Incorrect Patterns
+
+```tsx
+// ❌ FORBIDDEN: Creating client in component or service
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(url, key); // Don't do this for queries
+
+// ❌ FORBIDDEN: Passing base client to useSecureSupabase
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+import { supabase } from './supabase'; // Don't export base client
+const secureSupabase = useSecureSupabase(supabase); // Don't pass it
+
+// ❌ FORBIDDEN: Using base client directly for queries
+const { data } = await supabase.from('users').select('*'); // Bypasses RLS
+```
+
+### Hook Signature
+
+The `useSecureSupabase()` hook signature is:
+
+```typescript
+function useSecureSupabase(
+  baseClient?: SupabaseClient<Database> | null
+): SupabaseClient<Database> | null
+```
+
+**Important**: The `baseClient` parameter is **optional**. The hook automatically gets the base client from `useUnifiedAuth()` provider layer. You should **NOT** pass a base client parameter - call `useSecureSupabase()` without arguments.
+
+### Acceptable Exceptions
+
+**The ONLY acceptable use of `createClient()` in consuming app code is:**
+
+1. **Creating the base client for `UnifiedAuthProvider`** - This MUST be in one of these files:
+   - `src/main.tsx` (or `main.jsx`)
+   - `src/App.tsx` (or `App.jsx`)
+   - `src/lib/supabase.ts` (or `supabase.js`) - ONLY if this file is ONLY used to create the base client for the provider
+
+**The file containing the base client creation MUST:**
+- Be clearly named (e.g., `supabase.ts`, `main.tsx`)
+- Only create the client once
+- Pass it directly to `UnifiedAuthProvider` (not export it for general use)
+- Include a comment explaining it's the base client for the provider:
+  ```tsx
+  // Base Supabase client for UnifiedAuthProvider only
+  // DO NOT use this client directly - use useSecureSupabase() instead
+  const supabase = createClient(...);
+  ```
+
+**NO OTHER EXCEPTIONS ARE PERMITTED** - All other uses of `createClient()` are security violations and MUST be fixed.
+
+### Detection / Audit
+
+- `rg "createClient\(" src` must return **exactly ONE match** in the file that creates the base client for `UnifiedAuthProvider`.
+- That file MUST be one of: `main.tsx`, `App.tsx`, or `lib/supabase.ts` (or `.jsx`/`.js` equivalents).
+- No `.from(` / `.rpc(` calls may be performed on an insecure client reference.
+- All `useSecureSupabase()` calls should be without parameters.
+
+## Compliance Exceptions
+
+**In general, pace-core compliance rules do NOT allow exceptions.** The rules are designed to ensure security, consistency, and maintainability across the PACE suite.
+
+### When Exceptions Are NOT Allowed
+
+- **Security rules** (e.g., `createClient()` usage) - NO exceptions except the one documented above
+- **RBAC rules** - NO exceptions
+- **Component usage** - NO exceptions (use pace-core components)
+- **Hook usage** - NO exceptions (use pace-core hooks)
+
+### Documenting Legitimate Edge Cases
+
+If you encounter a situation where a rule seems to conflict with a legitimate requirement:
+
+1. **First**: Verify that pace-core doesn't provide a solution
+2. **Second**: Check if the requirement should be added to pace-core
+3. **Third**: If truly unavoidable, document the case clearly:
+   - Add a comment explaining why the exception is necessary
+   - Include a reference to this standard
+   - Consider opening an issue to add the missing functionality to pace-core
+
+**Example of proper documentation:**
+```tsx
+// @pace-core-compliance-exception: Legacy integration requires direct Supabase client
+// TODO: Migrate to useSecureSupabase() when legacy system is updated
+// See: https://github.com/your-org/pace-core/issues/123
+const legacyClient = createClient(...);
+```
+
+**Note**: Even with documentation, exceptions should be:
+- Temporary (with a plan to remove them)
+- Rare (only when absolutely necessary)
+- Reviewed and approved by the team
+- Tracked for eventual removal
+
+### Audit Handling of Exceptions
+
+During audits, documented exceptions will be:
+- **Verified** - Confirmed that the exception is legitimate and properly documented
+- **Categorized** - Marked as "Acceptable Exception" if valid, or flagged for remediation if not
+- **Tracked** - Included in the audit report with a recommendation to remove when possible
+
+**Invalid exceptions** (undocumented, unnecessary, or security-related) will be flagged as violations requiring remediation.
+
+## Related Documentation
+
+- [Component Standards](./03-component-standard.md)
+- [API & RPC Standards](./02-api-and-rpc-standard.md)
+- [Getting Started Guide](../getting-started/README.md)
+- [RBAC Getting Started](../rbac/getting-started.md) - Secure client usage
+