@jmruthers/pace-core 0.6.10 → 0.6.12

package/docs/standards/6-security-rbac-standards.md

@@ -2,12 +2,36 @@
 
 **🤖 Cursor Rule**: See [06-security-rbac.mdc](../../cursor-rules/06-security-rbac.mdc) for AI-optimized directives that automatically enforce RBAC contract compliance (ESLint-enforced).
 
+**🔧 ESLint Rules**: See [06-security-rbac.cjs](../../eslint-rules/rules/06-security-rbac.cjs) for mechanically checkable security and RBAC rules.
+
 ## Purpose
 
 Define standards for Row-Level Security (RLS) policies and Role-Based Access Control (RBAC) integration to ensure security, performance, and maintainability.
 
 **Note:** General performance optimization patterns (React, caching, bundle size) are covered in [Operations Standards](./9-operations-standards.md). This document focuses on RLS-specific performance requirements.
 
+---
+
+## How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines RLS policy patterns, helper function requirements (STABLE, SECURITY DEFINER, SET search_path), forbidden/required patterns, Edge Function RBAC (isPermitted/setupRBAC), and security baseline.
+- **Cursor rule:** `06-security-rbac.mdc` — AI guidance when editing `src/**/*.{ts,tsx,js,jsx}` and `supabase/migrations/**/*.sql`; points to this doc and RBAC contract.
+- **ESLint:** Rules in `06-security-rbac.cjs` (plugin prefix `pace-core-compliance/`): see ESLint Rules section below. Run via lint step in CI and locally.
+- **Audit tool:** Standard 6 audit runs as part of `npm run validate`; checks RLS policies in SQL migrations (naming, inline auth, subqueries, helper attributes, SECURITY DEFINER/search_path/schema-qualify/COMMENT), PagePermissionGuard coverage, and Edge Functions RBAC (setupRBAC before isPermitted). Report: `audit/<timestamp>-pace-core-audit.md`. For pace-core development, run `npm run validate` from the repository root.
+
+---
+
+## Audit issue types and where to read
+
+| Audit issue type | See section in this doc |
+|------------------|--------------------------|
+| rlsPolicy | RLS Policy Performance Requirements; Helper Function Requirements; Forbidden/Required Patterns; SECURITY DEFINER Requirements; Security Risks & Mitigations; Policy Naming Convention; RLS Policy Patterns |
+| rbacPageGuard | Security Baseline (page protection) |
+| organisationIdResolution | Organisation context resolution (consuming apps) |
+| edgeFunctionRBAC | Edge Functions and Serverless Functions |
+
+---
+
 ## Principles
 
 - **Performance First**: All RLS policies must use optimized helper functions
@@ -1072,6 +1096,33 @@ USING (organisation_id = get_organisation_context())
 USING (is_public = true AND organisation_id IS NOT NULL)
 ```
 
+## Organisation context resolution (consuming apps)
+
+When a consuming app uses both **selectedOrganisation** (from `useOrganisations()`) and **selectedEvent** (from `useEvents()`), any code that passes organisation context to RPCs or payloads (**p_organisation_id**, **organisation_id**, **selectedOrganisationId**) **MUST** use a **derived organisation ID** that falls back to the event’s organisation when the context selector has no org selected.
+
+**Why:** If the user has selected an event but no organisation in the header, `selectedOrganisation` may be null while `selectedEvent.organisation_id` is set. Passing only `selectedOrganisation?.id` to RPCs then sends `undefined`, breaking data isolation or causing incorrect behaviour.
+
+**✅ CORRECT – derived organisationId:**
+```ts
+const organisationId = useMemo(
+  () =>
+    selectedOrganisation?.id ??
+    (selectedEvent as { organisation_id?: string | null } | undefined)?.organisation_id ??
+    undefined,
+  [selectedOrganisation?.id, selectedEvent]
+);
+// Use organisationId for all p_organisation_id, organisation_id, selectedOrganisationId
+```
+
+**❌ WRONG – using selectedOrganisation?.id when selectedEvent is in scope:**
+```ts
+p_organisation_id: selectedOrganisation?.id,  // undefined when event selected without org
+organisation_id: selectedOrganisation?.id || '',
+selectedOrganisationId: selectedOrganisation?.id,
+```
+
+**Enforcement:** The Standard 6 audit and the ESLint rule `require-derived-organisation-id` flag files that use both `selectedOrganisation` and `selectedEvent` but pass `selectedOrganisation?.id` (or `selectedOrganisation.id`) to organisation context parameters. Fix by deriving `organisationId` as above and using it consistently.
+
 ## App Ownership
 
 Tables are assigned to specific apps for RBAC permission checking:
@@ -1184,6 +1235,21 @@ date +"%Y%m%d%H%M%S"
 3. **Monitor performance** after deployment
 4. **Rollback plan** ready if issues occur
 
+## ESLint Rules
+
+Rule IDs use the plugin prefix **`pace-core-compliance/`**. The following rules enforce security and RBAC standards:
+
+- **`pace-core-compliance/no-direct-supabase-client`** — Require useSecureSupabase from pace-core/rbac; disallow direct createClient from @supabase/supabase-js.
+- **`pace-core-compliance/rbac-permission-loading`** — Enforce loading state handling when using RBAC permission hooks.
+- **`pace-core-compliance/no-direct-rbac-rpc`** — Disallow direct RPC calls to rbac_*; use pace-core RBAC hooks/APIs.
+- **`pace-core-compliance/no-direct-rbac-table`** — Disallow direct queries to RBAC tables; use pace-core APIs.
+- **`pace-core-compliance/no-hardcoded-role-checks`** — Disallow hardcoded role checks; use useAccessLevel/getRoleContext from pace-core/rbac.
+- **`pace-core-compliance/rbac-use-resource-names-constants`** — Require RESOURCE_NAMES constants instead of string literals in useResourcePermissions.
+- **`pace-core-compliance/no-rbac-wrapper-components`** — Disallow wrapper components around pace-core RBAC components.
+- **`pace-core-compliance/no-rbac-wrapper-functions`** — Disallow wrapper functions around pace-core RBAC hooks.
+
+These rules are part of the `pace-core-compliance` plugin and are enabled when extending `@jmruthers/pace-core/eslint-config`.
+
 ## Related Documentation
 
 - [Standards Overview](./0-standards-overview.md) - Standards system overview

package/docs/standards/7-api-tech-stack-standards.md

@@ -10,6 +10,25 @@ This standard defines the required technology stack, API design patterns, and RP
 
 ---
 
+## How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines required tech stack (React 19+, TypeScript, Vite, Tailwind v4, Supabase, TanStack Query, etc.), API/RPC naming (`data_*` / `app_*`), ApiResult shape, RPC rules, Vite/TypeScript config, and deprecation policy.
+- **Cursor rule:** `07-api-tech-stack.mdc` — AI guidance when editing `src/**`, config files, and `supabase/migrations/**/*.sql`; points to this doc.
+- **ESLint:** Rules in `07-api-tech-stack.cjs` (plugin prefix `pace-core-compliance/`): see ESLint Rules section below. Run via lint step in CI and locally.
+- **Audit tool:** Standard 7 audit runs as part of `npm run validate`; checks RPC naming in SQL migrations, tech stack versions (package.json), and Vite configuration (optimizeDeps.exclude, resolve.dedupe). Report: `audit/<timestamp>-pace-core-audit.md`. For pace-core development, run `npm run validate` from the repository root.
+
+---
+
+## Audit issue types and where to read
+
+| Audit issue type | See section in this doc |
+|------------------|--------------------------|
+| rpcNaming | API & RPC Naming Conventions; RPC Naming Pattern; Naming Rules |
+| techStack | Required Tech Stack; Version Requirements |
+| viteConfig | Tech Stack Configuration (Vite Configuration) |
+
+---
+
 ## Required Tech Stack
 
 ### Core Technologies
@@ -717,23 +736,15 @@ Before creating or updating an API/RPC, verify:
 
 ## ESLint Rules
 
-The following ESLint rules enforce API and tech stack standards:
-
-### RPC Naming
-
-- **`rpc-naming-pattern`** - Enforces `data_*` prefix for read operations and `app_*` prefix for write operations
-
-### React 19+ Patterns
-
-- **`no-class-components`** - Disallows React class components (functional components only)
-
-### Environment Variables
+Rule IDs use the plugin prefix **`pace-core-compliance/`**. The following rules enforce API and tech stack standards:
 
-- **`prefer-import-meta-env`** - Enforces `import.meta.env` (Vite) instead of `process.env` in client code
+- **`pace-core-compliance/rpc-naming-pattern`** — Enforces `data_*` prefix for read operations and `app_*` prefix for write operations.
+- **`pace-core-compliance/no-class-components`** — Disallows React class components (functional components only).
+- **`pace-core-compliance/prefer-import-meta-env`** — Enforces `import.meta.env` (Vite) instead of `process.env` in client code.
 
-These rules are part of the `pace-core-compliance` plugin and are automatically enabled when you extend `@jmruthers/pace-core/eslint-config`.
+These rules are part of the `pace-core-compliance` plugin and are enabled when extending `@jmruthers/pace-core/eslint-config`.
 
-**Setup**: Run `node node_modules/@jmruthers/pace-core/scripts/install-eslint-config.cjs` to configure ESLint in your consuming app.
+**Setup**: Run `npm run setup` to configure ESLint (and other pace-core tools) in your consuming app.
 
 ## Related Documentation
 

package/docs/standards/8-testing-documentation-standards.md

@@ -2,12 +2,33 @@
 
 **🤖 Cursor Rule**: See [08-testing-documentation.mdc](../../cursor-rules/08-testing-documentation.mdc) for AI-optimized directives that automatically enforce testing and documentation standards.
 
+**🔧 ESLint Rules**: See [08-testing.cjs](../../eslint-rules/rules/08-testing.cjs) for mechanically checkable testing rules.
+
 ## Purpose
 
 This standard defines testing strategies, documentation requirements, and issue reporting templates to ensure consistent quality, maintainability, and effective communication across pace-core and consuming apps.
 
 ---
 
+## How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines testing strategy (unit/integration/E2E), test structure and naming, testing tools (React Testing Library, userEvent, Vitest), test timeouts, coverage requirements, documentation requirements, and bug/feature request templates.
+- **Cursor rule:** `08-testing-documentation.mdc` — AI guidance when editing test files (`**/*.{test,spec}.{ts,tsx}`) and docs (`**/*.md`, `**/*.mdx`); points to this doc.
+- **ESLint:** Rules in `08-testing.cjs` (plugin prefix `pace-core-compliance/`): see ESLint Rules section below. Run via lint step in CI and locally.
+- **Audit tool:** Standard 8 audit runs as part of `npm run validate`; checks test timeout configuration (vitest.config, package.json scripts), required testing tools (vitest, @testing-library/react, @testing-library/user-event), and test file structure/naming (.test vs .spec). Report: `audit/<timestamp>-pace-core-audit.md`. For pace-core development, run `npm run validate` from the repository root.
+
+---
+
+## Audit issue types and where to read
+
+| Audit issue type | See section in this doc |
+|------------------|--------------------------|
+| testTimeout | Test Timeouts |
+| testingTools | Testing Tools |
+| testStructure | Test Structure; Test File Naming |
+
+---
+
 ## Testing Strategy
 
 ### Test Types
@@ -388,6 +409,16 @@ Before committing code with documentation, verify:
 
 ---
 
+## ESLint Rules
+
+Rule IDs use the plugin prefix **`pace-core-compliance/`**. The following rule enforces testing standards:
+
+- **`pace-core-compliance/test-file-naming`** — Enforce test file naming: `*.test.ts` or `*.test.tsx` (not `*.spec.ts`).
+
+This rule is part of the `pace-core-compliance` plugin and is enabled when extending `@jmruthers/pace-core/eslint-config`.
+
+---
+
 ## Related Documentation
 
 - [Standards Overview](./0-standards-overview.md) - Standards system overview

package/docs/standards/9-operations-standards.md

@@ -10,6 +10,25 @@ This standard defines error handling patterns, performance optimization strategi
 
 ---
 
+## How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines error handling patterns (ApiResult, type guards, user-facing vs logging messages), performance optimization (memoization, code splitting, caching), and CI/CD integration (pipeline stages, required checks, package.json scripts).
+- **Cursor rule:** `09-operations.mdc` — AI guidance when editing `src/**`, config files, and `.github/workflows/**`; points to this doc.
+- **ESLint:** No dedicated Standard 9 rules; error handling and performance patterns are encouraged via the Cursor rule and via overlapping [Code Quality](./4-code-quality-standards.md) / [API & Tech Stack](./7-api-tech-stack-standards.md) rules. Run `npm run lint` as part of CI.
+- **Audit tool:** Standard 9 audit runs as part of `npm run validate`; checks error handling patterns (ApiResult usage), CI/CD configuration (.github/workflows), and error boundary usage. Report: `audit/<timestamp>-pace-core-audit.md`. For pace-core development, run `npm run validate` from the repository root.
+
+---
+
+## Audit issue types and where to read
+
+| Audit issue type | See section in this doc |
+|------------------|--------------------------|
+| errorHandling | Error Handling Patterns; Result Types; API Errors |
+| cicd | CI/CD Integration; Required CI Checks |
+| errorBoundary | Error Handling Patterns (Pattern 3: Error Boundaries) |
+
+---
+
 ## Error Handling Patterns
 
 ### Principles

package/docs/standards/README.md

@@ -1,203 +1,22 @@
 # Pace Standards
 
-This repository defines the **canonical development standards** for **pace-core** and **all consuming applications** in the pace-suite.
-
-These standards are **human-readable first**, but are deliberately structured so they can be **enforced by automation**, including Cursor rules, ESLint, and custom audit tooling.
-
-They are the **single source of truth**.  
-All other quality tools must align *to these standards*, not reinterpret them.
-
----
-
-## How to use these standards
-
-### pace-core
-- Treat these standards as **hard constraints**
-- pace-core sets the bar and defines the contracts
-- Any deviation must be explicitly documented here
-
-### Consuming applications
-- Inherit these standards by default
-- Only diverge where a documented exception exists
-- Consuming apps should never weaken standards silently
-
-### AI agents (Cursor, Codex, etc.)
-- Follow these standards **strictly**
-- Do **not** silence rules to "make things pass"
-- If compliance is unclear, stop and report rather than guessing
-
----
-
-## The Four Layers of Quality Enforcement
-
-The pace-suite uses **four complementary quality layers**, each with a distinct responsibility.  
-They are intentionally overlapping in *coverage*, but **not duplicative in purpose**.
-
-Think of this as *defence in depth*, not redundancy.
-
----
-
-### 1. Standards Documents (Source of Truth)
-
-**What they are**
-- Human-readable `.md` documents
-- Describe *intent*, *principles*, and *expectations*
-- Technology-agnostic where possible
-
-**What they are used for**
-- Defining *what "good" looks like*
-- Onboarding humans and AI agents
-- Resolving ambiguity when tools disagree
-- Designing new rules, lint checks, and audits
-
-**What they are NOT**
-- They are not executable
-- They do not enforce anything by themselves
-- They should not contain implementation hacks
-
-➡️ **If there is a conflict, the standards win.**
-
----
-
-### 2. Cursor Rules (Real-time Guidance)
-
-**What they are**
-- AI-optimised interpretations of the standards
-- Applied while code is being written or modified
-- Prevent mistakes *before* they land
-
-**What they are used for**
-- Steering AI agents toward correct patterns
-- Enforcing architectural intent during development
-- Reducing rework later in linting or audits
-
-**What they are NOT**
-- They are not a replacement for lint or audits
-- They should not invent new standards
-- They should not silence problems "to move on"
-
-➡️ Cursor rules **translate standards into behaviour**, but do not redefine them.
-
----
-
-### 3. ESLint (Fast, Local Static Analysis)
-
-**What it is**
-- Deterministic, file-level static analysis
-- Runs locally and in CI
-- Focused on correctness, safety, and consistency
-
-**What it is used for**
-- Catching obvious issues early (types, hooks, imports, patterns)
-- Enforcing mechanically checkable rules
-- Preventing regressions during refactors
-
-**What it is NOT**
-- ESLint should not encode complex business rules
-- It should not contain subjective or architectural debates
-- It should not be silenced to "get green builds"
-
-➡️ ESLint enforces *how code is written*, not *whether the system is correct*.
-
----
-
-### 4. Audit Tool (Deep, System-Level Analysis)
-
-**What it is**
-- A custom static analysis tool
-- Operates across files, folders, and systems
-- Understands pace-core contracts and invariants
-
-**What it is used for**
-- Validating architectural compliance (RBAC, data access, boundaries)
-- Catching issues ESLint cannot see
-- Providing actionable remediation plans
-
-**What it is NOT**
-- It is not a linter replacement
-- It should not report stylistic issues
-- It should not contradict the standards
-
-➡️ The audit tool answers: *"Is this system actually compliant?"*
-
----
-
-## How the layers work together
-
-| Layer        | Strength                         | Timing          |
-|--------------|----------------------------------|-----------------|
-| Standards    | Intent & clarity                 | Design time     |
-| Cursor rules | Preventive guidance              | Write time      |
-| ESLint       | Fast mechanical enforcement      | Dev / CI        |
-| Audit tool   | Deep architectural verification  | Review / CI     |
-
-No single layer is sufficient on its own.  
-Together, they create a **repeatable, scalable quality system** for both humans and AI.
-
----
-
-## Standards Documents
-
-The standards are organized into **10 files**, each covering a specific domain:
-
-### 0. [Standards Overview](./0-standards-overview.md)
-Entry point, precedence, how standards work, and the four layers of quality enforcement.
-
-### 1. [pace-core Compliance](./1-pace-core-compliance-standards.md)
-pace-core usage patterns, ESLint rules, secure Supabase client requirements, and compliance enforcement.
-
-### 2. [Project Structure](./2-project-structure-standards.md)
-Standard directory structure, file organization patterns, naming conventions, and migration guides.
-
-### 3. [Architecture](./3-architecture-standards.md)
-SOLID principles, component design, API design, and architectural patterns.
-
-### 4. [Code Quality](./4-code-quality-standards.md)
-TypeScript rules, naming conventions, code style patterns, and React patterns.
-
-### 5. [Styling](./5-styling-standards.md)
-**CRITICAL:** Required CSS configuration, Tailwind v4 setup, markup quality, and styling patterns.
-
-### 6. [Security & RBAC](./6-security-rbac-standards.md)
-RLS policy patterns, RBAC integration, helper functions, and security requirements.
-
-### 7. [API & Tech Stack](./7-api-tech-stack-standards.md)
-Required tech stack, API/RPC naming conventions, result shapes, and deprecation policy.
-
-### 8. [Testing & Documentation](./8-testing-documentation-standards.md)
-Testing strategy, documentation requirements, bug report templates, and feature request templates.
-
-### 9. [Operations](./9-operations-standards.md)
-Error handling patterns, performance optimization, caching strategies, and CI/CD integration.
-
----
-
-## Key Principles
-
-- **Do not silence tools** — fix the underlying issue
-- **Do not duplicate rules** — each layer has a purpose
-- **Do not diverge silently** — document exceptions explicitly
-- **Standards always win** — tools must align to them
-
----
-
-## Getting Started
-
-1. **Read the Overview** - Start with [0-standards-overview.md](./0-standards-overview.md) to understand the system
-2. **Review Critical Standards** - Pay special attention to:
-   - [5-styling-standards.md](./5-styling-standards.md) - **CRITICAL CSS configuration**
-   - [1-pace-core-compliance-standards.md](./1-pace-core-compliance-standards.md) - pace-core usage
-   - [6-security-rbac-standards.md](./6-security-rbac-standards.md) - Security and RBAC
-3. **Set Up Quality Enforcement** - Install Cursor rules and ESLint config:
-   - `npm run setup:cursor-rules` - Install Cursor rules for AI-assisted enforcement
-   - `npm run setup:eslint` - Install ESLint config for real-time linting
-4. **Run Audits** - Use the audit tool to validate compliance:
-   - `npm run audit:pace-core` - Run comprehensive audit organized by standards
-5. **Follow the Standards** - Use the standards as your guide for all development work
-6. **Reference When Needed** - Use the standards to resolve conflicts and answer questions
-
----
-
-**Last Updated:** 2025-01-28  
-**Version:** 2.0.0  
-**Applies to:** All pace-core and consuming apps
+This repository defines the **canonical development standards** for **pace-core** and **all consuming applications** in the pace-suite. They are human-readable first and enforced by Cursor rules, ESLint, and the audit tool.
+
+**Entry point:** [0-standards-overview.md](./0-standards-overview.md) — read this first for the four-layer quality system, precedence, and how to use the standards.
+
+## Standards documents (10 files)
+
+| File | Purpose |
+|------|---------|
+| [0-standards-overview.md](./0-standards-overview.md) | Entry point, four layers, precedence, file mapping |
+| [1-pace-core-compliance-standards.md](./1-pace-core-compliance-standards.md) | pace-core usage, ESLint, secure Supabase client |
+| [2-project-structure-standards.md](./2-project-structure-standards.md) | Directory structure, file organization, naming |
+| [3-architecture-standards.md](./3-architecture-standards.md) | SOLID principles, component and API design |
+| [4-code-quality-standards.md](./4-code-quality-standards.md) | TypeScript, naming, code style, React patterns |
+| [5-styling-standards.md](./5-styling-standards.md) | **CRITICAL:** CSS config, Tailwind v4, markup quality |
+| [6-security-rbac-standards.md](./6-security-rbac-standards.md) | RLS, RBAC, security requirements |
+| [7-api-tech-stack-standards.md](./7-api-tech-stack-standards.md) | Tech stack, API/RPC naming, result shapes |
+| [8-testing-documentation-standards.md](./8-testing-documentation-standards.md) | Testing strategy, documentation, templates |
+| [9-operations-standards.md](./9-operations-standards.md) | Error handling, performance, CI/CD |
+
+All other quality tools align to these standards; they are the single source of truth.

package/docs/testing/test-setup-for-consumers.md

@@ -18,6 +18,8 @@ This setup provides:
 - **Mock utilities** for pace-core providers
 - **Consistent test configuration** matching pace-core standards
 
+**Test colocation:** pace-core colocates test files with source files (e.g. `Component.test.tsx` next to `Component.tsx`). Consumers should follow the same pattern per the project structure standard; do not use a dedicated `__tests__/` or `tests/` folder for unit/integration tests. Shared test helpers may live in a single location (e.g. `src/__tests__/helpers`) if needed.
+
 ## Prerequisites
 
 - Node.js 18+ installed

package/docs/troubleshooting/common-issues.md

@@ -321,7 +321,23 @@ export const MyComponent = ({ isOpen, data }: Props) => {
 2. **Call hooks in the same order** - Every render must call the same hooks in the same order
 3. **No early returns before hooks** - All hooks must be called before any conditional returns
 
-### Issue 8: PagePermissionGuard UI Issues
+### Issue 8: Login succeeds but redirect doesn't happen / form resets
+
+**Symptoms:** After entering valid credentials, the login button shows "Signing in…" then the form resets and you stay on the login page.
+
+**Root Cause:** Global auth gate or wrong routing pattern (e.g. wrapping the whole app in a component that redirects to `/login` when `!isAuthenticated`), which races with post-login context updates.
+
+**Solution:** See [Authentication — Critical: Auth routing pattern](../implementation-guides/authentication.md#critical-auth-routing-pattern) and [Redirect not happening after login](../implementation-guides/authentication.md#1-login-not-working). Use a single public `/login` route and wrap all other routes in **ProtectedRoute**; do not wrap `<Routes>` in a component that redirects unauthenticated users to `/login`.
+
+### Issue 9: Logout button does nothing (e.g. 403)
+
+**Symptoms:** Clicking logout has no effect; the UI still shows the user as logged in. Network tab may show `POST .../auth/v1/logout` returning 403.
+
+**Root Cause:** Server-side logout can fail (e.g. cookie/domain); without handling the error, local state stays "logged in".
+
+**Solution:** pace-core clears local user/session on signOut error and falls back to `signOut({ scope: 'local' })`, so the UI should still show logged out. See [Authentication — Logout does nothing / 403 on logout](../implementation-guides/authentication.md#4-logout-does-nothing--403-on-logout). If logout still fails, check cookie domain and CORS.
+
+### Issue 10: PagePermissionGuard UI Issues
 
 **Symptoms:**
 - Access Denied modal persists despite correct permissions

package/docs/troubleshooting/organisation-context-setup.md

@@ -305,6 +305,14 @@ The key is making sure the database has the organisation context functions and y
 3. **Use RLS policies correctly**: Policies should use `auth.uid()` and `organisation_id` columns directly
 4. **No manual context setting**: The secure client handles everything automatically
 
+### Super admin and "All Organizations"
+
+When the user is a **super admin** and no organisation is selected (e.g. "All Organizations"), the secure client from `useSecureSupabase()` is created with `organisationId = null` and `isSuperAdmin: true`. Only in that case may RPCs such as `data_rbac_roles_list` be called without org context (e.g. to load a user's event roles across all orgs). Consuming apps must use the same secure client from the hook so that `isSuperAdmin` is correctly resolved (via `useOrganisationSecurity()`); do not create a separate client or bypass the hook.
+
+### Org from URL (e.g. /users?org=scouts-victoria)
+
+When the app derives "current organisation" from the URL (or another source) but does not set pace-core's `selectedOrganisation`, the secure client may have `organisationId = null`. For **org-scoped table queries** (e.g. listing users in an org), either: (1) keep `selectedOrganisation` in sync with the URL so the secure client has the correct org context, or (2) use the secure client's `withContext({ organisationId: urlOrgId })` to obtain a client scoped to that org for the request. RPCs that accept explicit `p_organisation_id` use the parameter as the source of truth and do not require the header to match.
+
 ## ♿ Accessibility
 
 Organisation context setup doesn't directly impact accessibility, but ensure: