@jmruthers/pace-core 0.6.10 → 0.6.11

package/docs/api-reference/rpc-functions.md

@@ -146,7 +146,7 @@ Documented in [RBAC API Reference](../rbac/api-reference.md):
 **Data Access (RBAC-protected):**
 - `data_user_organisations_get` - Get all organisations for a user
 - `data_user_organisation_roles_get` - Get user roles in organisations
-- `get_organisation_members` - (exception to naming standard) Returns distinct active organisation role assignments for dashboard statistics. Enforces `check_user_organisation_access` so only super admins or organisation members can call it.
+- `data_rbac_roles_list` - List all roles (global, organisation, event-app) for a user. **Explicit parameters are the source of truth:** the function uses only `p_user_id`, `p_organisation_id`, `p_event_id`, `p_app_id`; it does **not** use `x-organisation-id` or request/session org. RLS on `rbac_organisation_roles` and `rbac_event_app_roles` uses caller identity (JWT) via `app.current_user_id` set by the RPC. **Note:** This RPC returns roles for **one** user (the caller when `p_user_id` is null, or the given `p_user_id`). It does **not** return `user_id` and does **not** support "list all users in org X". For that, see "User list for one organisation" below.
 - `data_user_events_get` - Get events accessible to a user
 - `data_cake_meals_get` - Get cake meals for an event (application-specific, RBAC-protected)
 
@@ -168,6 +168,16 @@ Documented in [RBAC API Reference](../rbac/api-reference.md):
 
 **Note**: For public event access, use `usePublicEvent()` hook from pace-core, which handles direct table queries internally.
 
+### User list for one organisation
+
+Apps that need to show **all users (or user IDs) in a given organisation** have two options:
+
+1. **Direct query (recommended):** Query the `rbac_organisation_roles` table with a filter on `organisation_id`. Use the secure client from `useSecureSupabase()`. When the "current org" is derived from the URL (e.g. `/users?org=scouts-victoria`), ensure the secure client has that organisation context for the request (e.g. keep `selectedOrganisation` in sync with the URL, or use a client created with that org via `withContext({ organisationId: urlOrgId })`). The caller must have access to that org (or be a super admin). Select distinct `user_id` (and optionally `role`, etc.) as needed.
+
+2. **Alternative:** If pace-core adds a dedicated RPC that returns `(user_id, role, ...)` for a given `p_organisation_id`, use that and pass the org ID explicitly; such an RPC would use only explicit parameters and caller auth/RLS.
+
+**Not supported:** Calling `data_rbac_roles_list` with only `p_organisation_id` does **not** return "all users in the org". It returns the **caller's** roles in that org (when `p_user_id` is null), and the return type has no `user_id` column.
+
 ## Removed Legacy RPC Functions
 
 The following RPC functions have been **removed** in v0.6.x. All consuming apps have been migrated to modern alternatives.
@@ -233,8 +243,7 @@ These functions are used internally by pace-core and should **NOT** be called di
 - ~~`get_organisation_context`~~ - **REMOVED** - No longer needed
 - ~~`get_page_scope_type`~~ - **REMOVED** - Replaced with direct table queries
 
-**Active Functions** (pace-core internal, do not call directly):
-- `grant_event_app_role` - Used by `useRoleManagement` hook (use hook instead)
+**Event-app role grants:** Use `rbac_role_grant` with `p_role_type: 'event_app'` and `p_context_id: '<event_id>:<app_id>'`. The `useRoleManagement().grantEventAppRole` hook calls this RPC.
 
 **Note**: The removed functions have been replaced with direct table queries or are no longer needed. Organisation context is automatically handled by the secure Supabase client from `useSecureSupabase()` hook.
 

package/docs/core-concepts/rbac-system.md

@@ -236,6 +236,14 @@ SELECT rbac_role_grant(
 
 For complete documentation on role management functions, see **[Role Management Functions](../rbac/role-management-functions.md)**.
 
+### Required migrations for role management
+
+Granting roles (including event-app roles) requires the **`rbac_role_grant`** RPC to exist in the database. The Supabase project must have the migration that creates or updates this function applied.
+
+- **Migration:** `20260109112708_fix_rbac_role_grant_reactivate_inactive_roles.sql` (or a later migration that defines `public.rbac_role_grant`).
+- **Symptom:** If `POST …/rest/v1/rpc/rbac_role_grant` returns **404**, the function is missing — apply pending Supabase migrations to the project.
+- Consuming apps (e.g. pace-admin) that use `useRoleManagement().grantEventAppRole` call this RPC; ensure the project’s migrations are applied before using role grant features.
+
 ## RBAC Compliance & Recent Changes
 
 ### Database-Driven Permissions

package/docs/getting-started/cursor-rules.md

@@ -18,26 +18,21 @@ npm install @jmruthers/pace-core
 
 ### Step 2: Install Cursor Rules
 
-Run the installation script from your app root:
+Run the combined setup script from your app root:
 
 ```bash
-node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+npm run setup
 ```
 
-Or add to your `package.json`:
+This will install:
+- Cursor rules for AI-assisted enforcement
+- ESLint configuration for real-time linting
+- Standards documentation to `docs/standards/`
 
-```json
-{
-  "scripts": {
-    "setup:cursor-rules": "node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs"
-  }
-}
-```
-
-Then run:
+Or to force update existing configs:
 
 ```bash
-npm run setup:cursor-rules
+npm run setup -- --force
 ```
 
 The script will:
@@ -131,18 +126,20 @@ Content with examples and guidelines.
 
 ### Compliance Check
 
-For a quick compliance check:
+For full validation including the pace-core audit:
 
 ```bash
-node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+npm run validate
 ```
 
+Review `audit/<timestamp>-pace-core-audit.md` for pace-core compliance and other standards.
+
 ## Updating Rules
 
-When pace-core is updated, run the installation script again:
+When pace-core is updated, run the setup script again:
 
 ```bash
-npm run setup:cursor-rules
+npm run setup
 ```
 
 The script will:
@@ -155,7 +152,7 @@ The script will:
 To force update all rules (even when versions match):
 
 ```bash
-node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs --force
+npm run setup -- --force
 ```
 
 **Note**: Normally, pace-core rules are automatically updated when they change. The `--force` flag forces an update even when versions match (useful if content changed but version metadata wasn't updated).
@@ -210,7 +207,7 @@ Each app maintains its own `.cursor/rules/` directory.
 1. **Initial Setup:**
    ```bash
    npm install @jmruthers/pace-core
-   npm run setup:cursor-rules
+   npm run setup
    ```
 
 2. **Daily Development:**
@@ -225,7 +222,7 @@ Each app maintains its own `.cursor/rules/` directory.
 4. **After pace-core Updates:**
    ```bash
    npm update @jmruthers/pace-core
-   npm run setup:cursor-rules
+   npm run setup
    ```
 
 ## Related Documentation

package/docs/getting-started/dependencies.md

@@ -48,7 +48,7 @@ reviewedBy: dependency-clarity-audit
 - Validation runs automatically before publishing via `prepublishOnly` hook
 
 **For consuming apps:**
-- Use the audit tool (`npm run audit:pace-core`) to check your dependencies
+- Use the pace-core Audit step in `npm run validate` to check your dependencies
 - The audit tool reads the current `package.json` from the installed pace-core package
 - Version requirements shown by the audit tool come directly from `package.json`
 

package/docs/getting-started/setup.md

@@ -0,0 +1,235 @@
+# pace-core Setup Guide
+
+This guide explains how to set up pace-core in your consuming app with a single command.
+
+## Quick Start
+
+After installing `@jmruthers/pace-core`, run:
+
+```bash
+npm run setup
+```
+
+This single command will:
+- ✅ Set up ESLint configuration for real-time compliance checking
+- ✅ Install Cursor rules for AI-assisted enforcement
+- ✅ Copy standards documentation to `docs/standards/`
+
+## Installation
+
+### Step 1: Install pace-core
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### Step 2: Add Setup Scripts to package.json
+
+**Important:** Add the setup and validate scripts to your consuming app's `package.json`. Do NOT create local script files.
+
+```json
+{
+  "scripts": {
+    "setup": "node node_modules/@jmruthers/pace-core/scripts/setup.cjs",
+    "validate": "node node_modules/@jmruthers/pace-core/scripts/validate.cjs"
+  }
+}
+```
+
+**Note:** These scripts come from the `@jmruthers/pace-core` package, not from your local project. Make sure you're pointing to `node_modules/@jmruthers/pace-core/scripts/`.
+
+### Step 3: Run Setup
+
+```bash
+npm run setup
+```
+
+That's it! All pace-core tools are now configured.
+
+### Step 4: Run Validation (Optional)
+
+After setup, you can run quick validation checks:
+
+```bash
+npm run validate
+```
+
+This runs (in order, when the corresponding script exists):
+- **Type check** – summary in terminal
+- **Lint** – summary in terminal, full output in `audit/<timestamp>-eslint-report.md`
+- **Build** – summary in terminal
+- **Tests** – summary in terminal (runs `test:coverage` if present, otherwise `test`; add `test:coverage` to generate `coverage/index.html`)
+- **pace-core Audit** – standards audit; report in `audit/<timestamp>-pace-core-audit.md`
+
+Reports are written to the `audit/` directory. To get a coverage report during validate, add a `test:coverage` script to your `package.json` (e.g. with Vitest: `vitest run --coverage`).
+
+## What Gets Set Up
+
+### 1. ESLint Configuration
+
+The setup script automatically:
+- Finds your ESLint config file (supports `.js`, `.cjs`, `.mjs`, `.json`, `.yaml`, `.yml`)
+- Adds pace-core ESLint rules to your config
+- Creates a backup of your existing config
+- Handles both ES modules and CommonJS formats
+- Supports `tseslint.config()` wrapper
+
+### 2. Cursor Rules
+
+The setup script:
+- Creates `.cursor/rules/` directory if it doesn't exist
+- Copies all pace-core rules (00-09) to your project
+- **Automatically updates** pace-core rules when they change
+- Preserves your custom rules (50+)
+- Skips files that are already up to date
+
+### 3. Standards Documentation
+
+The setup script:
+- Copies `packages/core/docs/standards/` to `docs/standards/` in your app
+- Provides offline access to all pace-core standards
+- Updates when you run setup again
+
+## Force Update
+
+To force update all configurations (overwrites existing):
+
+```bash
+npm run setup -- --force
+```
+
+Use this when:
+- You want to update to the latest pace-core rules
+- Your ESLint config needs to be regenerated
+- You want to refresh the standards documentation
+
+## Manual Setup
+
+The setup script handles all three tasks (ESLint, Cursor rules, and standards docs) in one command. There are no separate scripts for individual components - use `npm run setup` for everything.
+
+## Verification
+
+After running setup, verify everything is working:
+
+### Run Validation
+
+The easiest way to verify everything is working:
+
+```bash
+npm run validate
+```
+
+This runs all available checks (type-check, lint, tests, pace-core audit).
+
+### Manual Verification
+
+You can also check individual components:
+
+**Check ESLint:**
+```bash
+npm run lint
+```
+
+**Check Cursor Rules:**
+1. Restart Cursor
+2. Open a file that matches the rule patterns
+3. Rules should be automatically loaded
+
+**Check Standards:**
+```bash
+ls docs/standards/
+```
+
+You should see all the standards markdown files.
+
+## Troubleshooting
+
+### Error: Cannot find module 'scripts/setup.cjs'
+
+**Problem:** Your `package.json` has a `setup` script pointing to a local file that doesn't exist:
+```json
+{
+  "scripts": {
+    "setup": "node scripts/setup.cjs"  // ❌ WRONG - This file doesn't exist in consuming apps
+  }
+}
+```
+
+**Solution:** Update your `package.json` to use the script from the pace-core package:
+```json
+{
+  "scripts": {
+    "setup": "node node_modules/@jmruthers/pace-core/scripts/setup.cjs"  // ✅ CORRECT
+  }
+}
+```
+
+**Important:** The setup script comes from `@jmruthers/pace-core`, not from your local project. You should NOT create a local `scripts/setup.cjs` file.
+
+### Setup Script Not Found
+
+If you get an error that the script can't be found:
+
+1. Verify pace-core is installed:
+   ```bash
+   npm list @jmruthers/pace-core
+   ```
+
+2. Check the script path:
+   ```bash
+   ls node_modules/@jmruthers/pace-core/scripts/setup.cjs
+   ```
+
+3. If the file doesn't exist, you may need to update pace-core:
+   ```bash
+   npm update @jmruthers/pace-core
+   ```
+
+4. Make sure your `package.json` script points to `node_modules/@jmruthers/pace-core/scripts/setup.cjs`, not a local `scripts/setup.cjs`
+
+### ESLint Config Issues
+
+If ESLint setup fails:
+
+1. Check your ESLint config file exists
+2. Try with `--force` flag:
+   ```bash
+   npm run setup -- --force
+   ```
+3. Check the backup file created (`.backup.{timestamp}`)
+4. See [ESLint Setup Troubleshooting](../standards/1-pace-core-compliance-standards.md#eslint-setup-issues)
+
+### Cursor Rules Not Loading
+
+1. Verify rules are in `.cursor/rules/` directory
+2. Check file extensions are `.mdc`
+3. Restart Cursor
+4. Check rule frontmatter is valid YAML
+
+### Standards Not Copied
+
+If standards aren't copied:
+
+1. Check pace-core package has docs:
+   ```bash
+   ls node_modules/@jmruthers/pace-core/docs/standards/
+   ```
+2. Try with `--force` flag:
+   ```bash
+   npm run setup -- --force
+   ```
+
+## Next Steps
+
+After setup:
+
+1. **Restart Cursor** to load the new rules
+2. **Run validation**: `npm run validate` (type-check, lint, build, tests, pace-core audit; reports in `audit/`)
+3. **Review standards** in `docs/standards/` for complete documentation
+
+## Related Documentation
+
+- [Cursor Rules Guide](./cursor-rules.md) - Using Cursor rules effectively
+- [Standards Documentation](../standards/README.md) - Complete standards reference
+- [pace-core Compliance](../standards/1-pace-core-compliance-standards.md) - Compliance requirements
+- [Local Development](./local-development.md) - Using pace-core locally

package/docs/implementation-guides/authentication.md

@@ -263,6 +263,22 @@ function App() {
 
 **Important:** The `ProtectedRoute` component solves the common chicken-and-egg problem where apps check for `selectedEvent` before rendering, which blocks the event selector (typically in the `PaceAppLayout` header) from being visible. The component allows rendering when events exist but none is selected, enabling users to see and use the event selector dropdown.
 
+### Critical: Auth routing pattern
+
+To avoid "login succeeds but redirect doesn't happen" or the login form resetting after submit, follow this pattern:
+
+- **MUST** use a single public `/login` route and wrap all other routes in **ProtectedRoute**. Do not wrap the whole app in a custom "auth gate" that redirects when `!isAuthenticated`.
+- **MUST NOT** wrap `<Routes>` in a component that, when `!isAuthenticated`, renders `<Navigate to="/login" />` for non-login paths. That races with post-login context updates and can send the user back to the login page with a reset form.
+- **SHOULD** avoid `BrowserRouter` `future: { v7_startTransition: true, v7_relativeSplatPath: true }` until compatibility with auth context updates is verified; use plain `<BrowserRouter>`.
+
+See [Redirect not happening after login](#1-login-not-working) in Troubleshooting if you see this behaviour.
+
+**Auth and routing checklist (new apps):**
+- [ ] `/login` is a public route; all other routes are under `<Route element={<ProtectedRoute />}>` (or `requireEvent={false}` variant).
+- [ ] No wrapper component that redirects to `/login` when `!isAuthenticated` for the whole app.
+- [ ] `BrowserRouter` used without `future` flags (or login and logout verified if using them).
+- [ ] Verify login and logout in the app after setup.
+
 ## Configuration Options
 
 ### UnifiedAuthProvider Props
@@ -801,6 +817,7 @@ function App() {
 - [ ] User credentials are valid in Supabase
 - [ ] Network connectivity working
 - [ ] Browser not blocking cookies
+- [ ] **Auth routing pattern**: You use a public `/login` route and wrap other routes in `ProtectedRoute`; you do not use a global auth gate that redirects to `/login` when `!isAuthenticated`. See [Critical: Auth routing pattern](#critical-auth-routing-pattern) above.
 
 #### 2. Session Not Persisting
 
@@ -858,6 +875,16 @@ function AuthTest() {
 }
 ```
 
+#### 4. Logout does nothing / 403 on logout
+
+**Symptoms:**
+- Logout button does nothing; user stays on the app
+- Network tab shows `POST .../auth/v1/logout` returning 403
+
+**Cause:** Supabase sign-out with default (global) scope can return 403 in some environments (e.g. cookie domain, CORS). pace-core handles this by clearing local auth state and calling `signOut({ scope: 'local' })`, so the UI should still show the user as logged out and redirect to login.
+
+**If logout still does nothing:** Check cookie domain and CORS for your Supabase project and app origin. The app should still clear local state; if it does not, ensure you are on a version of pace-core that includes the signOut error-handling fix.
+
 ### Detailed Solutions
 
 #### Wrong Supabase Configuration

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,7 +2119,135 @@ The import automatically recognizes and maps:
 />
 ```
 
-> **📚 Import Function Guide**: For detailed guidance on implementing performant, reliable `onImport` handlers, see the [DataTable Import Function Guide](./data-table-import-guide.md). This guide covers batch operations, error handling, validation, performance optimization, and best practices for large imports.
+> **📚 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
 
@@ -2460,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>
@@ -2515,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.