@jmruthers/pace-core 0.6.10 → 0.6.12

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:
@@ -46,6 +50,14 @@ The PACE Core DataTable is an enterprise-grade data table component built on Tan
 >
 > The DataTable simply calls your provided handlers (`onDeleteRow`, `onEditRow`, `onCreateRow`) - it does not intercept or modify them to add audit logging.
 
+### Organisation and event context (edit/delete buttons)
+
+DataTable permission checks (and thus visibility of edit/delete/import buttons) depend on **RBAC scope**: organisation and, for event-scoped pages, **event** must be available when the table mounts.
+
+- **If organisation or event is set asynchronously** (e.g. after navigation or from a restored session), the first render may have no scope or incomplete scope, so permission checks return "no access" and buttons stay hidden. After a **refresh**, context is often already in state, so scope is ready and buttons appear.
+- **Fix in the app:** Ensure organisation and, for event-scoped pages, event are set **before** or **as** the user reaches the page (e.g. from URL, storage, or a layout that sets context on load). That way scope is ready when the DataTable runs its permission checks and edit/delete/import buttons show without needing a refresh.
+- **Event-scoped pages (e.g. CAKE units/menus):** The selected **event** must be in scope. If the user navigates to the page without an event selected, scope is incomplete and buttons will not show until context is set (or the page is refreshed with event in state).
+
 ## Basic Usage
 
 ### Simple Data Table
@@ -1985,6 +1997,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 +2127,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 +2641,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 +2696,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/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/rbac/getting-started.md

@@ -837,6 +837,13 @@ function AdaptiveComponent({ appId }) {
 }
 ```
 
+### Page permissions and scope
+
+For page permission checks that use a **page name** (e.g. `useCan(userId, scope, 'read:page.items', 'items')`), the backend can only return **event-role** permissions when the scope includes both `eventId` and `appId`. For event-scoped pages, include both in scope so the RPC considers event roles (e.g. `planner`, `event_admin`).
+
+- **Scope:** When calling `useCan` for event-scoped page permissions, pass a scope that includes `eventId` and `appId` (and `organisationId` when required). The library may resolve `appId` from the current app name when `eventId` is present but `appId` is missing, so you can pass `{ organisationId, eventId }` and pace-core will resolve `appId` before calling the backend.
+- **useResolvedScope:** For event-scoped pages, you can use the `useResolvedScope` hook to obtain a scope with `organisationId`, `eventId`, and `appId` resolved from the current app and selection context.
+
 ## Next Steps
 
 - [API Reference](./api-reference.md) - Complete API documentation

package/docs/rbac/troubleshooting.md

@@ -143,9 +143,13 @@ setupRBAC(supabase, {
 - Console shows `scope: { organisationId: "...", eventId: "..." }` (missing `appId`)
 - All permission checks return `false`
 
-**Root Cause:** App name not being set globally for RBAC resolution
+**Root Cause:** For page permission checks with a page name, the backend returns event-role permissions only when both `eventId` and `appId` are provided. If scope is missing `appId`, event-scoped page checks may deny. App name may also not be set globally for RBAC resolution.
 
 **Fix:**
+
+For **event-scoped page checks**, scope should include both `eventId` and `appId`. pace-core can resolve `appId` from the current app name when `eventId` is present (so passing `{ organisationId, eventId }` is enough in that case). Alternatively, use the `useResolvedScope` hook to obtain a scope with `organisationId`, `eventId`, and `appId` before calling `useCan`.
+
+**Fix (app name not set):**
 ```typescript
 // ❌ WRONG - Missing setRBACAppName call
 import { UnifiedAuthProvider } from '@jmruthers/pace-core/providers'