@jmruthers/pace-core 0.6.9 → 0.6.11

package/docs/implementation-guides/data-tables.md

@@ -38,6 +38,10 @@ The PACE Core DataTable is an enterprise-grade data table component built on Tan
 >
 > The component uses pace-core's internal toast system to provide consistent user feedback. Your `onDeleteRow`, `onDeleteSelected`, `onImport`, and `onExport` handlers should focus on the data operations themselves - the UI feedback is handled for you.
 
+### Bulk delete confirmation
+
+When `deleteSelected` is enabled, a **confirmation dialog** is shown by pace-core before the app's `onDeleteSelected` is called. The dialog displays the number of selected rows and warns that the action cannot be undone. You do not need to show your own confirmation (e.g. `window.confirm`) for the same bulk-delete action. If your app has additional, domain-specific warnings (e.g. "this will also delete related diners and menus"), you may show those after the user has confirmed in the pace-core dialog.
+
 ### Audit Logging
 
 > **ℹ️ Audit Logging**: The DataTable component **does NOT** automatically create audit entries for CRUD operations. Audit logging must be handled by either:
@@ -1985,6 +1989,47 @@ When `export: true` and `import: true` are enabled in features, the DataTable au
 - Case-insensitive header matching
 - Supports both display names and field names
 
+#### Import result contract (required for correct modal summary)
+
+For the Import modal to show accurate success/failed counts, your `onImport` handler **must return** a result in the standard shape. The modal only recognises this contract; it does not accept app-specific or RPC-specific shapes.
+
+**Standard shape** (exported as `ImportSummary` from `@jmruthers/pace-core`):
+
+```ts
+interface ImportSummary {
+  successCount: number;   // number of rows imported successfully
+  totalCount: number;     // total rows in this chunk (or full import)
+  failedCount: number;    // number of rows that failed
+  failedRows?: Array<{ row: number; reason: string }>;  // optional details for failed rows
+}
+```
+
+**Return type**: `onImport` may return `void`, `Promise<void>`, `ImportSummary`, or `Promise<ImportSummary>`. The layout passes your handler's return value through to the modal. If you return anything other than a valid `ImportSummary` (including returning nothing), the modal treats the chunk as fully failed and shows incorrect counts (e.g. 0 successful, all rows failed). For accurate counts and failure details, you **must** return `ImportSummary` per chunk.
+
+**Guidance for consuming apps**:
+
+1. **Return `ImportSummary` from your handler.** After your import logic runs (RPC, API, or local), map the result into `ImportSummary` and return it.
+2. **Chunking**: The DataTable calls `onImport` once per chunk. Return a summary **per chunk** (e.g. `successCount` and `totalCount` for that chunk). The modal merges chunk results automatically.
+3. **Mapping from RPC/app shapes**: If your RPC returns e.g. `{ imported: 48, failed: 0 }` or `{ importedDiners: 100, totalRowsProcessed: 100, skippedRows: [] }`, map it before returning:
+
+   ```ts
+   import type { ImportSummary } from '@jmruthers/pace-core';
+
+   onImport={async (chunk) => {
+     const result = await myRpcOrImport(chunk);  // your app-specific result
+     return {
+       successCount: result.imported ?? result.importedDiners ?? 0,
+       totalCount: result.totalRowsProcessed ?? chunk.length,
+       failedCount: result.failed ?? result.skippedRows?.length ?? 0,
+       failedRows: result.skippedRows?.map(({ row, reason }) => ({ row, reason })),
+     } satisfies ImportSummary;
+   }}
+   ```
+
+4. **Do not return** app-specific shapes (e.g. `importedUnits`, `importedDiners`, RPC table rows) and expect the modal to interpret them. Always map to `ImportSummary` at the boundary.
+5. **Populate `failedRows` from validation and RPC.** Include exact failure reasons from your validation (e.g. "Could not find meal for date X, type Y for the selected event") and from the database/RPC (e.g. per-row error messages). The modal displays these as-is so users can pinpoint issues. Do not replace or correct the summary after the fact; the only source of truth is what your handler returns per chunk.
+6. **Reject invalid rows in validation.** If some rows would be inserted but not visible (e.g. due to event or RLS), reject them in validation with a clear reason so they appear in `failedRows` instead of being inserted and then missing from the list.
+
 ### Export/Import with Reference Fields
 
 For columns that display related data (using `accessorFn` with `editAccessorKey`), the export includes both the display value and the ID value for seamless round-trip import/export.
@@ -2074,6 +2119,136 @@ The import automatically recognizes and maps:
 />
 ```
 
+> **📚 Import result contract**: Ensure your `onImport` handler returns [ImportSummary](#import-result-contract-required-for-correct-modal-summary) so the modal shows correct success/failed counts. Map RPC or app-specific results to that shape at the boundary.
+
+#### Using Bulk Import RPCs
+
+For large imports (100+ rows), use bulk import RPC functions for better performance. CAKE app provides bulk import RPCs that use `SECURITY DEFINER` and automatically retrieve the authenticated user via `auth.uid()`.
+
+**Benefits:**
+- No session timeout issues during long imports (user authentication never expires mid-call)
+- Simplified client code (no need to manage user session state)
+- Better performance (single upfront permission check instead of per-row RLS, 60-70% faster)
+- User-friendly error messages
+
+**Example: Bulk Import Mealplans**
+
+```tsx
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+import type { ImportSummary } from '@jmruthers/pace-core';
+
+function MealplansTable() {
+  const supabase = useSecureSupabase();
+  const { selectedOrganisation } = useOrganisations();
+  const { selectedEvent } = useEvents();
+
+  const handleImport = async (importedData: any[]): Promise<ImportSummary> => {
+    // No need to check user session - auth.uid() handles it automatically
+    const { data, error } = await supabase.rpc('app_cake_mealplans_bulk_import', {
+      p_mealplans_data: importedData,
+      p_organisation_id: selectedOrganisation.id,
+      p_event_id: selectedEvent?.id  // Optional
+    });
+
+    if (error) {
+      // Error messages are user-friendly and specific
+      toast.error(error.message);
+      return {
+        successCount: 0,
+        totalCount: importedData.length,
+        failedCount: importedData.length,
+      };
+    }
+
+    const result = data[0];
+    return {
+      successCount: result.imported,
+      totalCount: importedData.length,
+      failedCount: result.failed,
+      failedRows: result.errors ? JSON.parse(result.errors as string) : [],
+    };
+  };
+
+  return (
+    <DataTable
+      data={mealplans}
+      columns={columns}
+      features={{ import: true }}
+      onImport={handleImport}
+      rbac={{ pageName: 'units' }}  // Mealplans managed through units
+    />
+  );
+}
+```
+
+**Available Bulk Import RPCs:**
+
+| RPC Function | Purpose | Permission Required |
+|-------------|---------|---------------------|
+| `app_cake_mealplans_bulk_import` | Bulk import mealplans | `create:page.units` |
+| `app_cake_units_bulk_import` | Bulk import units | `create:page.units` |
+| `app_cake_diners_bulk_import` | Bulk import diners | `create:page.units` |
+| `app_cake_meals_bulk_import` | Bulk import meals | `create:page.meals` |
+| `app_cake_mealplan_bulk_delete` | Bulk delete mealplans for a unit | `delete:page.units` |
+
+**RPC Parameters (all bulk import functions):**
+
+- `p_[resource]_data` (required): JSONB array of records to import
+- `p_organisation_id` (required): Organisation context UUID
+- `p_event_id` (optional): Event context for additional validation
+
+**Note:** You do **not** need to pass `p_user_id` - authentication is handled automatically via the JWT token in the request. The RPC will:
+1. Verify user is authenticated
+2. Check user has access to the organisation
+3. Verify user has the required permission
+4. Perform the bulk import if all checks pass
+
+This eliminates session timeout issues and simplifies client code.
+
+##### Menus import: why some rows don't appear in the list
+
+The menus list is driven by `data_cake_mealplans_list`, which **filters by event**: it only returns mealplans whose meal's `meal_event_id` matches the **selected event**. If your import handler resolves (Meal Date, Meal Type) to a `meal_id` from a **different event** (e.g. same org, same date/type in another event), those rows are inserted successfully but **never shown** in the list, so the UI shows fewer rows than the import count.
+
+**Required:** When building the payload for `app_cake_mealplans_bulk_import`, resolve `meal_id` using **the selected event**: e.g. look up meal by `(event_id, meal_date, meal_type)` (or equivalent), not by `(meal_date, meal_type)` alone. That way every imported row uses a meal for the current event and will appear in the list.
+
+**To identify which rows are "missing" (inserted but not visible):**
+
+1. **CSV diagnosis:** Run `node scripts/diagnose-menus-import.js "<path-to-menus.csv>"` to confirm row count and check for duplicate (Unit Number, Meal Date, Meal Type, Dish Code) keys.
+2. **DB diagnosis:** In Supabase SQL Editor, run the query in `scripts/sql/mealplans_not_visible_for_event.sql` after replacing `YOUR_EVENT_ID` and the unit_ids array. It returns mealplans for those units whose meal is not in the selected event (the difference between import count and list count).
+
+**Troubleshooting: rows reported as failed (e.g. "Could not find meal" or "Unit not found")**
+
+The import only uses **units, meals and dishes that belong to the event currently selected** in the page header. If the failed-rows table shows reasons like "Could not find meal for date X, type Y for the selected event" or "Unit N not found for the selected event", then:
+
+1. **Confirm the event** – Ensure the correct event is selected in the header before starting the import. The same unit number (e.g. 115) or meal (same date and type) can exist under different events; the import only sees data for the selected event.
+2. **Match CSV to that event** – The CSV Unit Number must match `cake_unit.unit_number` for a unit that has `unit_event_id` = selected event. Meals and dishes are matched by `meal_event_id` / `dish_event_id` = selected event. If the CSV was exported from another event, re-export for the selected event or switch event to match the CSV.
+3. **Meal date and type** – Meal is matched by date (parsed from the CSV Meal Date column, e.g. DD/MM/YYYY → YYYY-MM-DD), meal type name (case-insensitive, from Meal Type column), and event. Ensure the meal exists for that exact date and type for the selected event.
+4. **Dish code** – Dish is matched by code (Dish Code column) and event. Check for typos or extra spaces; the code must exist for the selected event.
+
+#### Advanced Import Configuration
+
+The DataTable import feature supports configuration through the `importModalConfig` prop to customize modal text only. The summary shown in the modal is the merge of the `ImportSummary` values returned by your `onImport` handler per chunk; do not correct or replace it after the fact.
+
+##### Available Configuration Options
+
+```tsx
+interface ImportModalConfig {
+  title?: string;
+  description?: string;
+  uploadText?: string;
+  selectFileButtonText?: string;
+  importButtonText?: string;
+  importButtonProcessingText?: string;
+  cancelButtonText?: string;
+  previewHeaderText?: string;
+  totalRowsText?: string;  // Use {count} as placeholder
+  /** When true, send the entire file in one chunk. Required for handlers that delete-then-insert per unit/entity (e.g. menus), so later chunks do not overwrite earlier ones. */
+  singleChunk?: boolean;
+}
+```
+
+**Menus import:** Use `singleChunk: true` for menus (mealplans) import. The handler deletes all mealplans for each unit then inserts the chunk's rows; with multiple chunks, later chunks would delete and replace earlier chunks' data for the same unit, so the reported count would be wrong and many rows would be missing. With `singleChunk: true`, the whole file is sent in one call and the summary matches the actual result.
+
 ### Custom Export
 
 The export filename is automatically generated from the table `title` prop:
@@ -2189,18 +2364,198 @@ onExport={async (options) => {
 
 ### Import Column Mapping
 
-The import automatically maps CSV columns using this priority:
+The import automatically maps CSV columns using a comprehensive fallback chain that supports flexible column matching. This eliminates the need for manual column mapping in most cases.
 
-1. **Column Header Match** (case-insensitive)
-   - CSV header "Type" → maps to column with `header: "Type"`
-   
-2. **editAccessorKey Match** (for reference fields)
+#### Automatic Mapping Fallback Chain
+
+The import tries multiple matching strategies in order:
+
+1. **Exact Header Match (case-sensitive)**
+   - CSV header "Meal" → maps to column with `header: "Meal"`
+
+2. **Exact Header Match (case-insensitive)**
+   - CSV header "meal" or "MEAL" → maps to column with `header: "Meal"`
+
+3. **AccessorKey Match**
+   - CSV header "meal_display" → maps to column with `accessorKey: "meal_display"`
+   - Works case-insensitively: "Meal_Display" or "MEAL_DISPLAY" also match
+
+4. **Normalized Match**
+   - Handles whitespace and special character variations
+   - CSV header "Meal Date" → matches "MealDate", "meal-date", "meal_date"
+   - Normalization: converts to lowercase, replaces spaces/special chars with underscores
+
+5. **ImportAliases Match**
+   - CSV header matches any value in the column's `importAliases` array
+   - Works case-insensitively and with normalization
+
+6. **editAccessorKey Match** (for reference fields)
    - CSV header "Type" or "Type (ID)" → maps to `editAccessorKey` field
+   - Also matches direct field names: "meal_mealtype_id" → `editAccessorKey: "meal_mealtype_id"`
+
+7. **Use as-is** (fallback)
+   - If no match is found, the CSV column name is used as-is (lowercase)
+   - A warning is logged for unmapped columns
+
+#### Using ImportAliases for Flexible CSV Formats
+
+The `importAliases` property allows you to define alternative CSV headers that should map to a column. This is especially useful when:
+- CSV files use different naming conventions than your table headers
+- CSV files use more descriptive names (e.g., "Meal Date" vs "Meal")
+- You need to support multiple CSV formats
+
+**Example: Column with ImportAliases**
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'meal_display',
+    header: 'Meal',  // Display-friendly header
+    importAliases: ['Meal Date', 'meal_date', 'MealDate'],  // CSV can use these
+  },
+  {
+    accessorKey: 'dish_code',
+    header: 'Dish',  // Display-friendly header
+    importAliases: ['Dish Code', 'dish_code', 'DishCode'],  // CSV can use these
+  },
+  {
+    accessorKey: 'mealtype_name',
+    header: 'Type',
+    editAccessorKey: 'meal_mealtype_id',
+    importAliases: ['Meal Type', 'meal_type', 'MealType'],  // CSV can use these
+  }
+];
+```
+
+**CSV File:**
+```csv
+Unit Number,Meal Date,Meal Type,Dish Code,Dish Name
+1,2025-01-20,Main,ABC123,Spaghetti
+```
+
+**Result:**
+- "Meal Date" maps to `meal_display` (via `importAliases`)
+- "Meal Type" maps to `meal_mealtype_id` (via `importAliases` → `editAccessorKey`)
+- "Dish Code" maps to `dish_code` (via `importAliases`)
+- No warnings generated
+
+#### Best Practices for Column Definitions
+
+To maximize automatic column mapping success:
+
+1. **Use Descriptive AccessorKeys**
+   ```tsx
+   // ✅ Good - accessorKey matches common CSV naming
+   {
+     accessorKey: 'meal_date',
+     header: 'Meal',
+   }
    
-3. **accessorKey/id Match** (fallback)
-   - CSV header matches column `accessorKey` or `id`
+   // CSV "meal_date" or "Meal Date" will match automatically
+   ```
 
-If no match is found, the CSV column name is used as-is (useful for new fields).
+2. **Add ImportAliases for Common Variations**
+   ```tsx
+   {
+     accessorKey: 'meal_display',
+     header: 'Meal',
+     importAliases: ['Meal Date', 'meal_date', 'MealDate', 'Meal Date'],
+   }
+   ```
+
+3. **Document Acceptable CSV Formats**
+   ```tsx
+   {
+     accessorKey: 'dish_code',
+     header: 'Dish',
+     // CSV can use: "Dish", "Dish Code", "dish_code", "DishCode"
+     importAliases: ['Dish Code', 'dish_code', 'DishCode'],
+   }
+   ```
+
+4. **For Reference Fields, Include Both Display and ID Aliases**
+   ```tsx
+   {
+     accessorKey: 'mealtype_name',
+     header: 'Type',
+     editAccessorKey: 'meal_mealtype_id',
+     // CSV can use display name or ID field name
+     importAliases: ['Meal Type', 'meal_type', 'MealType', 'meal_mealtype_id'],
+   }
+   ```
+
+#### Complete Example: Flexible Column Mapping
+
+```tsx
+const columns: DataTableColumn<Meal>[] = [
+  {
+    accessorKey: 'unit_number',
+    header: 'Unit',
+  },
+  {
+    accessorKey: 'meal_display',
+    header: 'Meal',
+    importAliases: ['Meal Date', 'meal_date', 'MealDate'],
+  },
+  {
+    accessorKey: 'mealtype_name',
+    header: 'Type',
+    editAccessorKey: 'meal_mealtype_id',
+    importAliases: ['Meal Type', 'meal_type', 'MealType'],
+  },
+  {
+    accessorKey: 'dish_code',
+    header: 'Dish',
+    importAliases: ['Dish Code', 'dish_code', 'DishCode'],
+  },
+  {
+    accessorKey: 'dish_name',
+    header: 'Dish Name',
+    importAliases: ['Dish Name', 'dish_name', 'DishName'],
+  },
+];
+
+// This CSV will map correctly without warnings:
+// Unit Number,Meal Date,Meal Type,Dish Code,Dish Name
+// 1,2025-01-20,Main,ABC123,Spaghetti
+```
+
+#### Troubleshooting Column Mapping
+
+**Issue: Getting warnings for columns that should map**
+
+**Solution 1: Add ImportAliases**
+```tsx
+{
+  accessorKey: 'meal_display',
+  header: 'Meal',
+  importAliases: ['Meal Date'],  // Add the CSV header here
+}
+```
+
+**Solution 2: Check AccessorKey Format**
+- Ensure `accessorKey` uses snake_case or matches CSV format
+- CSV "Meal Date" will normalize to "meal_date"
+- If your `accessorKey` is "mealDisplay", add "meal_display" to `importAliases`
+
+**Solution 3: Verify Column Definition**
+- Ensure column has either `accessorKey` or `id`
+- Ensure column has `header` property
+- Check that `editAccessorKey` is set for reference fields
+
+**Issue: Reference fields not mapping correctly**
+
+**Solution:**
+- Ensure `editAccessorKey` is set
+- Add both display name and ID to `importAliases`:
+  ```tsx
+  {
+    accessorKey: 'mealtype_name',
+    header: 'Type',
+    editAccessorKey: 'meal_mealtype_id',
+    importAliases: ['Meal Type', 'meal_mealtype_id'],  // Both variations
+  }
+  ```
 
 ### Form Integration
 
@@ -2278,7 +2633,7 @@ function UserForm({ user, onSubmit, onCancel }) {
         <button
           type="submit"
           disabled={isSubmitting}
-          className="px-4 py-2 bg-main-600 text-white rounded hover:bg-main-700 disabled:opacity-50"
+          className="px-4 py-2 bg-main-600 text-main-50 rounded hover:bg-main-700 disabled:opacity-50"
         >
           {isSubmitting ? 'Saving...' : 'Save'}
         </button>
@@ -2333,7 +2688,7 @@ function UserForm({ user, onSubmit, onCancel }) {
 
 #### 7. Delete selected rows not working
 - **Check feature configuration**: Ensure `features={{ selection: true, deletion: true, deleteSelected: true }}`
-- **Provide onDeleteSelected callback**: Implement the callback to handle bulk deletion
+- **Provide onDeleteSelected callback**: Implement the callback to handle bulk deletion. A confirmation dialog is shown by pace-core before your handler is called; do not add a separate confirm step for the same action.
 - **Verify getRowId function**: Ensure you provide a `getRowId` function that returns unique IDs
 - **Check button visibility**: The delete button only appears when all three features are enabled and rows are selected
 - **Debug selection state**: Add console logs to verify `onRowSelectionChange` is being called with correct data

package/docs/migration/ApiResult-migration.md

@@ -0,0 +1,25 @@
+# ApiResult migration
+
+Async API-style functions in `@jmruthers/pace-core` now return a consistent **`ApiResult<T>`** shape instead of throwing or returning raw values. This document points to the CHANGELOG and standards for the type and migration.
+
+## Summary
+
+- **Type**: `ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }`
+- **Error type**: `ApiError = { code: string; message: string; details?: object }`
+- **Helpers**: `ok(data)`, `err(error)`, `isOk(result)`, `isErr(result)` — exported from the package.
+
+## Where to look
+
+1. **CHANGELOG** — [packages/core/CHANGELOG.md](../../CHANGELOG.md) (Unreleased → Breaking Changes → “Async API-style functions now return ApiResult<T>”) for the list of affected surfaces and a short before/after.
+2. **Standards** — [7-api-tech-stack-standards.md](../standards/7-api-tech-stack-standards.md) and [3-architecture-standards.md](../standards/3-architecture-standards.md) for the ApiResult contract and usage.
+
+## Affected surfaces
+
+- RBAC (e.g. `isPermitted`, `getAccessLevel`, audit, eventContext)
+- Auth (auth-utils, `IAuthService` / `AuthService`)
+- File-reference service and storage helpers (`extractFileMetadata`, `getSignedUrl`, `listFiles`, `downloadFile`, `generateFileUrlsBatch`, etc.)
+- Context and app utilities (`organisationContext`, `appIdResolver`)
+- Google Places and CSRF
+- Security (`validateUserSession`, etc.)
+
+At each call site, check `result.ok` and use `result.data` or `result.error` accordingly.

package/docs/rbac/RBAC_CONTRACT.md

@@ -629,18 +629,6 @@ The following ESLint rules enforce this contract (all as **ERROR** severity):
 7. **`no-resource-permission-string-literals`** - Detects string literals in `useResourcePermissions` calls
 8. **`no-permission-wrapper-functions`** - Detects wrapper functions around pace-core permission hooks
 
-### Runtime Compliance
-
-Use runtime compliance checking in development:
-
-```tsx
-import { checkRuntimeCompliance } from '@jmruthers/pace-core/rbac/compliance';
-
-// In development mode
-if (import.meta.env.DEV) {
-  checkRuntimeCompliance();
-}
-```
 
 ## enforcePermissions Configuration
 

package/docs/rbac/api-reference.md

@@ -514,41 +514,41 @@ SELECT revoke_global_role(
 
 ### Event-App Role Management
 
-#### grant_event_app_role()
+#### rbac_role_grant (event-app)
 
-Grants an event-app specific role to a user.
+Grants an event-app role to a user. Use the same RPC `rbac_role_grant` with `p_role_type = 'event_app'` and `p_context_id` in the form `'<event_id>:<app_id>'`.
+
+**RPC name:** `rbac_role_grant`
 
 **Signature:**
 ```sql
-grant_event_app_role(
-    p_user_id UUID,
-    p_event_id UUID,
-    p_app_id UUID,
-    p_role TEXT,
-    p_granted_by UUID DEFAULT auth.uid(),
-    p_notes TEXT DEFAULT NULL
-) RETURNS UUID
+public.rbac_role_grant(
+  p_user_id uuid,
+  p_role_type text,   -- 'event_app' for event-app roles
+  p_role_name text,
+  p_context_id text DEFAULT NULL::text,  -- '<event_id>:<app_id>' for event_app
+  p_granted_by uuid DEFAULT auth.uid()
+)
+RETURNS TABLE(success boolean, message text, role_id uuid, error_code text)
 ```
 
-**Parameters:**
+**Parameters (event-app):**
 - `p_user_id`: The user to grant the role to
-- `p_event_id`: The event context
-- `p_app_id`: The application context
-- `p_role`: Event-app role ('viewer', 'participant', 'planner', 'event_admin')
-- `p_granted_by`: User granting the role (defaults to current user)
-- `p_notes`: Optional notes about the role grant
+- `p_role_type`: `'event_app'` for event-app roles
+- `p_role_name`: Event-app role (`'viewer'`, `'participant'`, `'planner'`, `'event_admin'`)
+- `p_context_id`: `'<event_id>:<app_id>'` (e.g. event code or UUID, then app UUID as text)
+- `p_granted_by`: Optional; user granting the role (defaults to current user)
 
-**Example:**
-```sql
--- Grant event_admin role for specific event and app
-SELECT grant_event_app_role(
-    'user-123'::UUID,
-    'event-789'::UUID,
-    'app-101'::UUID,
-    'event_admin',
-    'admin-user-789'::UUID,
-    'Assigned as event administrator'
-);
+**Example (application code):**
+```typescript
+const { data, error } = await supabase.rpc('rbac_role_grant', {
+  p_user_id: userId,
+  p_role_type: 'event_app',
+  p_role_name: 'event_admin',
+  p_context_id: `${eventId}:${appId}`,
+  p_granted_by: grantedBy ?? undefined,
+});
+// data is array of { success, message, role_id, error_code }
 ```
 
 #### revoke_event_app_role()
@@ -622,13 +622,15 @@ import { createClient } from '@supabase/supabase-js';
 
 const supabase = createClient(url, key);
 
-// Grant organisation role
-const { data: roleId, error: grantError } = await supabase.rpc('rbac_role_grant', {
+// Grant organisation role (organisation context)
+const { data: grantData, error: grantError } = await supabase.rpc('rbac_role_grant', {
   p_user_id: 'user-123',
-  p_organisation_id: 'org-456',
+  p_role_type: 'organisation',
   p_role_name: 'org_admin',
-  p_notes: 'Promoted to administrator'
+  p_context_id: 'org-456',  // organisation_id for organisation roles
+  p_granted_by: currentUserId,
 });
+// Grant event-app role: use p_role_type: 'event_app', p_context_id: `${eventId}:${appId}`
 
 if (grantError) {
   console.error('Failed to grant role:', grantError);

package/docs/standards/0-standards-overview.md

@@ -42,6 +42,17 @@ They are intentionally overlapping in *coverage*, but **not duplicative in purpo
 
 Think of this as *defence in depth*, not redundancy.
 
+```mermaid
+flowchart LR
+  Standards[Standards]
+  CursorRules[Cursor Rules]
+  ESLint[ESLint]
+  AuditTool[Audit Tool]
+  Standards -->|"Write time"| CursorRules
+  Standards -->|"Dev / CI"| ESLint
+  Standards -->|"Review / CI"| AuditTool
+```
+
 ### 1. Standards Documents (Source of Truth)
 
 **What they are**
@@ -64,6 +75,8 @@ Think of this as *defence in depth*, not redundancy.
 
 ### 2. Cursor Rules (Real-time Guidance)
 
+Cursor rules live in the package under `cursor-rules/`. Consuming apps copy them into `.cursor/rules/` via `npm run setup` (see [pace-core Compliance](./1-pace-core-compliance-standards.md) for setup steps).
+
 **What they are**
 - AI-optimised interpretations of the standards
 - Applied while code is being written or modified
@@ -122,7 +135,7 @@ Think of this as *defence in depth*, not redundancy.
 
 ➡️ The audit tool answers: *"Is this system actually compliant?"*
 
-**Usage**: Run `npm run audit:pace-core` in your consuming app to generate a comprehensive audit report organized by standard.
+**Usage:** In a consuming app (or from the repo root with pace-core available), run `npm run validate`. This runs type-check, lint, build, tests, and the pace-core audit. The pace-core audit report is written to `audit/<timestamp>-pace-core-audit.md`; ESLint output is written to `audit/<timestamp>-eslint-report.md` when the lint step runs.
 
 ---
 
@@ -135,9 +148,22 @@ Think of this as *defence in depth*, not redundancy.
 | ESLint       | Fast mechanical enforcement      | Dev / CI        |
 | Audit tool   | Deep architectural verification  | Review / CI     |
 
+| Layer        | Out of scope |
+|--------------|--------------|
+| Standards    | Not executable; do not enforce by themselves |
+| Cursor rules | Not a replacement for lint or audits |
+| ESLint       | Not system-level correctness; not complex business rules |
+| Audit tool   | Not stylistic issues; not file-level AST duplication |
+
 No single layer is sufficient on its own.  
 Together, they create a **repeatable, scalable quality system** for both humans and AI.
 
+### Traceability
+
+- **From audit report to standard:** Each audit section links to the corresponding standard doc (via the report; links are generated in the audit tool).
+- **From ESLint rule to standard:** ESLint rules are grouped by standard (e.g. `01-pace-core-compliance`, `06-security-rbac`); rule names or plugin metadata map to the standard doc.
+- **Principle:** When fixing a finding, open the referenced standard for intent and examples; fix the cause, do not silence the tool.
+
 ---
 
 ## Precedence Order
@@ -153,24 +179,31 @@ When standards conflict, apply this precedence order:
 
 **Example:** If a component pattern conflicts with a security requirement, security wins.
 
+### When tools disagree
+
+- Treat the **standards document** as the arbiter. If the standard is clear, the tool that matches it is correct; fix the other or fix the code.
+- If the standard is ambiguous, **update the standard first** (with rationale), then align the tool(s).
+- Do not silence a tool to get a green build; fix the underlying issue or document an explicit, approved exception in the standard.
+- **Remediation:** When the audit (or lint) fails in CI, use the generated report and the linked standard doc to fix issues, then re-run `npm run validate`.
+
 ---
 
 ## Standards File Mapping
 
-The standards are organized into 10 files, each covering a specific domain:
-
-| File | Standard | Cursor Rule | Purpose |
-|------|----------|------------|---------|
-| `0-standards-overview.md` | Overview | `00-standards-overview.mdc` | This file - entry point and system overview |
-| `1-pace-core-compliance-standards.md` | pace-core Compliance | `01-pace-core-compliance.mdc` | Enforce pace-core usage patterns |
-| `2-project-structure-standards.md` | Project Structure | `02-project-structure.mdc` | Define standard folder structure |
-| `3-architecture-standards.md` | Architecture | `03-architecture.mdc` | Enforce SOLID architecture principles |
-| `4-code-quality-standards.md` | Code Quality | `04-code-quality.mdc` | Enforce code quality standards |
-| `5-styling-standards.md` | Styling | `05-styling.mdc` | Enforce clean markup and styling standards |
-| `6-security-rbac-standards.md` | Security & RBAC | `06-security-rbac.mdc` | Enforce RBAC contract and security |
-| `7-api-tech-stack-standards.md` | API & Tech Stack | `07-api-tech-stack.mdc` | Enforce tech stack versions and API standards |
-| `8-testing-documentation-standards.md` | Testing & Documentation | `08-testing-documentation.mdc` | Enforce testing and documentation standards |
-| `9-operations-standards.md` | Operations | `09-operations.mdc` | Enforce error handling, performance, and CI/CD |
+The standards are organized into 10 files, each covering a specific domain. ESLint rule files are prefixed by standard (e.g. `01-pace-core-compliance`, `06-security-rbac`).
+
+| File | Standard | Cursor Rule | ESLint | Audit | Purpose |
+|------|----------|------------|--------|-------|---------|
+| `0-standards-overview.md` | Overview | `00-standards-overview.mdc` | — | — | This file - entry point and system overview |
+| `1-pace-core-compliance-standards.md` | pace-core Compliance | `01-pace-core-compliance.mdc` | Yes | Yes | Enforce pace-core usage patterns |
+| `2-project-structure-standards.md` | Project Structure | `02-project-structure.mdc` | — | Yes | Define standard folder structure |
+| `3-architecture-standards.md` | Architecture | `03-architecture.mdc` | — | Yes | Enforce SOLID architecture principles |
+| `4-code-quality-standards.md` | Code Quality | `04-code-quality.mdc` | Yes | Yes | Enforce code quality standards |
+| `5-styling-standards.md` | Styling | `05-styling.mdc` | Yes | Yes | Enforce clean markup and styling standards |
+| `6-security-rbac-standards.md` | Security & RBAC | `06-security-rbac.mdc` | Yes | Yes | Enforce RBAC contract and security |
+| `7-api-tech-stack-standards.md` | API & Tech Stack | `07-api-tech-stack.mdc` | Yes | Yes | Enforce tech stack versions and API standards |
+| `8-testing-documentation-standards.md` | Testing & Documentation | `08-testing-documentation.mdc` | Yes | Yes | Enforce testing and documentation standards |
+| `9-operations-standards.md` | Operations | `09-operations.mdc` | — | Yes | Enforce error handling, performance, and CI/CD |
 
 ---
 
@@ -218,3 +251,5 @@ The standards are organized into 10 files, each covering a specific domain:
 **Last Updated:** 2025-01-28  
 **Version:** 2.0.0  
 **Applies to:** All pace-core and consuming apps
+
+The standards version (e.g. 2.0.0) is updated when the standards system, precedence, or four-layer model changes; it is independent of the pace-core package version.