@jmruthers/pace-core 0.6.10 → 0.6.11

package/docs/rbac/api-reference.md

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

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

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

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

@@ -65,12 +65,12 @@ npm install @jmruthers/pace-core
 
 **Automated Setup (Easiest)**
 
-Use the installation script to set up ESLint:
+Use the combined setup script to set up ESLint (and other pace-core tools):
 
 ```bash
-npm run setup:eslint
-# or
-node node_modules/@jmruthers/pace-core/scripts/install-eslint-config.cjs
+npm run setup
+# or to force update existing configs
+npm run setup -- --force
 ```
 
 This script will:
@@ -147,12 +147,12 @@ export default tseslint.config(
 
 **Automated Setup (Easiest)**
 
-Use the installation script to set up Cursor rules:
+Use the combined setup script to set up Cursor rules (and other pace-core tools):
 
 ```bash
-npm run setup:cursor-rules
-# or
-node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+npm run setup
+# or to force update existing configs
+npm run setup -- --force
 ```
 
 This script will:
@@ -233,6 +233,8 @@ Rules are organized in `packages/core/eslint-rules/rules/`:
 - `07-api-tech-stack.cjs` - RPC naming, React 19+, import.meta.env
 - `08-testing.cjs` - Test file naming
 
+Rule IDs are under the plugin prefix `pace-core-compliance/` (e.g. `pace-core-compliance/prefer-pace-core-components`). Use this prefix when configuring overrides or looking up rules in IDE/CI output.
+
 ### Detailed Rule Descriptions
 
 #### Import Rules
@@ -565,43 +567,21 @@ function YourComponent() {
 }
 ```
 
-## Static Analysis Script
-
-The static analysis script provides a comprehensive scan of your codebase and generates a detailed compliance report.
-
-### Running the Script
-
-```bash
-# From your consuming app root
-node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
-```
-
-Or add it to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "check:pace-core": "node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs"
-  }
-}
-```
-
-### What It Checks
+## Compliance validation
 
-1. **Restricted Imports** - Scans for direct imports of wrapped libraries
-2. **Duplicate Components** - Finds local components matching pace-core names
-3. **Duplicate Hooks** - Finds local hooks matching pace-core hooks
-4. **Duplicate Utils** - Finds local utils matching pace-core utils
-5. **Suggestions** - Recommends pace-core alternatives for native HTML elements
+Compliance is validated by **ESLint** (during development) and the **pace-core Audit** step (when you run `npm run validate`).
 
-### Report Output
+**Run validation:** From the consuming app root (or repository root for pace-core development), run `npm run validate`. The pace-core audit report is written to `audit/<timestamp>-pace-core-audit.md`. For pace-core development, run `npm run validate` from the repository root; the audit runs against the current directory.
 
-The script generates a color-coded terminal report showing:
+**What the Standard 1 audit checks:**
 
-- ❌ **Errors** - Critical violations that must be fixed
-- ⚠️ **Warnings** - Issues that should be addressed
-- 💡 **Suggestions** - Recommendations for improvement
-- ✅ **Summary** - Overall compliance status
+- Provider nesting order in `main.tsx` (QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider)
+- Core styles import chain (app.css: tailwindcss, pace-core core.css, @source directives)
+- RBAC setup (`setupRBAC()` called before rendering)
+- Vite aliases (no aliases that bypass pace-core exports)
+- Secure Supabase client location (`createClient()` only in main.tsx or lib/supabase.ts)
+- Cursor rules present (`.cursor/rules/` with pace-core rules)
+- ESLint config includes pace-core config
 
 ## Best Practices
 
@@ -707,6 +687,16 @@ createRoot(document.getElementById("root")!).render(
 - ❌ `UnifiedAuthProvider` wrapping `BrowserRouter` (causes context errors)
 - ❌ Missing `BrowserRouter` (causes `useNavigate` errors)
 
+## MUST: Auth routing
+
+**MUST** protect routes with pace-core **ProtectedRoute**. Use a single public `/login` route and wrap all other routes in `<Route element={<ProtectedRoute />}>` (or `requireEvent={false}` variant for apps that do not require an event).
+
+**MUST NOT** implement a global auth gate that wraps the entire route tree and redirects unauthenticated users to `/login` when `!isAuthenticated`. That pattern races with post-login context updates and can cause "login succeeds but redirect doesn't happen" or the login form to reset.
+
+**SHOULD NOT** use React Router `BrowserRouter` `future` flags (e.g. `v7_startTransition`, `v7_relativeSplatPath`) unless login and logout have been verified with that configuration; use plain `<BrowserRouter>` by default.
+
+See [Authentication implementation guide](../../implementation-guides/authentication.md#critical-auth-routing-pattern) for the full auth routing pattern and checklist.
+
 ## MUST: Vite Configuration
 
 **⚠️ CRITICAL: Vite configuration prevents React context mismatches!**
@@ -844,7 +834,7 @@ function useSecureSupabase(
 
 ### Acceptable Exceptions
 
-**The ONLY acceptable use of `createClient()` in consuming app code is:**
+**The ONLY acceptable uses of `createClient()` in consuming app code are:**
 
 1. **Creating the base client for `UnifiedAuthProvider`** - This MUST be in one of these files:
    - `src/main.tsx` (or `main.jsx`)
@@ -862,13 +852,15 @@ function useSecureSupabase(
   const supabase = createClient(...);
   ```
 
+2. **PublicPageProvider (pace-core)** - `PublicPageProvider` may create a client for unauthenticated public pages only; that client must not be used for authenticated or organisation-scoped data.
+
 **NO OTHER EXCEPTIONS ARE PERMITTED** - All other uses of `createClient()` are security violations and MUST be fixed.
 
 ### Detection / Audit Tool
 
-The audit tool (`npm run audit:pace-core`) performs comprehensive system-level analysis organized by standards:
+The pace-core Audit step (run via `npm run validate`) performs comprehensive system-level analysis organized by standards:
 
-- **Standard 1 (pace-core Compliance)**: Provider nesting, core styles import, RBAC setup, Vite aliases, secure Supabase client location, Cursor rules, ESLint config
+- **Standard 1 (pace-core Compliance)**: Provider nesting, core styles import, RBAC setup, Vite aliases, secure Supabase client location, **auth routing (no global auth gate)**, Cursor rules, ESLint config
 - **Standard 2 (Project Structure)**: Directory structure, config files, import paths, test colocation, Supabase structure
 - **Standard 3 (Architecture)**: Component boundaries, ApiResult usage
 - **Standard 4 (Code Quality)**: TypeScript config, test coverage config
@@ -880,6 +872,26 @@ The audit tool (`npm run audit:pace-core`) performs comprehensive system-level a
 
 **Reference**: See [packages/core/audit-tool/](../../audit-tool/) for audit tool implementation.
 
+### How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines MUST/SHOULD and exceptions.
+- **Cursor rule:** `01-pace-core-compliance.mdc` — AI guidance when editing `src/**/*.{ts,tsx,js,jsx}`; points to this doc and ESLint.
+- **ESLint:** Rules in `01-pace-core-compliance.cjs` (plugin prefix `pace-core-compliance/`): prefer-pace-core-components, prefer-pace-core-hooks, prefer-pace-core-utils, no-local-component-duplication, no-inline-styles, prefer-pace-core-form; plus no-restricted-imports and RBAC rules from Standard 6. Run via lint step in CI and locally.
+- **Audit tool:** Standard 1 audit runs as part of `npm run validate`; checks provider nesting, core styles import, RBAC setup, Vite aliases, secure Supabase client location, **auth routing pattern (flags files that redirect to `/login` when `!isAuthenticated`, which indicates a global auth gate)**, Cursor rules presence, ESLint config. Report: `audit/<timestamp>-pace-core-audit.md`. ESLint does not currently enforce auth routing; use the audit and the [Authentication implementation guide](../../implementation-guides/authentication.md#critical-auth-routing-pattern) to avoid the global auth gate pattern.
+
+### Audit issue types and where to read
+
+| Audit issue type | See section in this doc |
+|------------------|--------------------------|
+| providerNesting | MUST: Provider Nesting Order |
+| coreStyles | (Styling standard) / app.css |
+| rbacSetup | MUST: Setup RBAC Before Use (Cursor rule); Detection / Audit Tool |
+| viteAlias | MUST: Vite Configuration |
+| supabaseClient | MUST: Use Secure Supabase Client |
+| authRouting | MUST: Auth routing (no global auth gate); [Authentication guide](../../implementation-guides/authentication.md#critical-auth-routing-pattern) |
+| cursorRules | Step 3: Setup Cursor Rules |
+| eslintConfig | Step 2: Setup ESLint |
+
 ### Detection / Audit (Legacy)
 
 - `rg "createClient\(" src` must return **exactly ONE match** in the file that creates the base client for `UnifiedAuthProvider`.
@@ -934,17 +946,19 @@ During audits, documented exceptions will be:
 
 **Invalid exceptions** (undocumented, unnecessary, or security-related) will be flagged as violations requiring remediation.
 
+Documented exceptions are not yet detected automatically by the audit tool; they are tracked manually or via review. Future versions may report them as informational.
+
 ## Troubleshooting
 
 ### ESLint Setup Issues
 
 **Error: "Could not find 'no-restricted-imports' in plugin 'pace-core-compliance'"**
 - **Cause**: This rule was removed from the plugin (it's now handled by standard ESLint `no-restricted-imports`)
-- **Fix**: Update to the latest version of `@jmruthers/pace-core` and run `npm run setup:eslint --force`
+- **Fix**: Update to the latest version of `@jmruthers/pace-core` and run `npm run setup -- --force`
 
 **Error: "TypeError: Unexpected array" when using `tseslint.config()`**
 - **Cause**: Incorrect spreading of `paceCoreConfig` in `tseslint.config()` wrapper
-- **Fix**: Run `npm run setup:eslint --force` to fix the config structure, or manually ensure `paceCoreConfig` is spread correctly:
+- **Fix**: Run `npm run setup -- --force` to fix the config structure, or manually ensure `paceCoreConfig` is spread correctly:
   ```javascript
   import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
   
@@ -959,7 +973,7 @@ During audits, documented exceptions will be:
 - **Fix**: 
   1. Ensure `@jmruthers/pace-core` is built: `npm run build` in pace-core
   2. Check that `node_modules/@jmruthers/pace-core/dist/eslint-rules/` exists
-  3. Run `npm run setup:eslint --force` to regenerate config
+  3. Run `npm run setup -- --force` to regenerate config
 
 ### ESLint Rules Not Working
 
@@ -970,12 +984,6 @@ During audits, documented exceptions will be:
 5. **Verify rules are available**: Check that the rules file exists
 6. **Check rule count**: Verify all rules are loaded
 
-### Static Analysis Script Errors
-
-1. **Manifest not found**: Ensure `core-usage-manifest.json` exists in pace-core package
-2. **No files scanned**: Check that you're running from the project root
-3. **Permission errors**: Ensure script has read access to source files
-
 ### False Positives
 
 If you encounter false positives:
@@ -1004,10 +1012,7 @@ After setting up the ESLint config, verify it's working:
    ```
    Run ESLint and verify it reports the violation.
 
-3. **Run static analysis**: Use the compliance script to get a full report:
-   ```bash
-   npm run check:pace-core
-   ```
+3. **Run full validation**: Run `npm run validate` and review `audit/<timestamp>-pace-core-audit.md` for Standard 1 issues.
 
 ## Related Documentation
 

package/docs/standards/2-project-structure-standards.md

@@ -25,6 +25,23 @@ This guide defines the standard project structure and file organization patterns
 9. [Migration from Existing Projects](#migration-from-existing-projects)
 10. [Structure Checklist](#structure-checklist)
 
+### How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines MUST/SHOULD for structure, naming, imports, and config.
+- **Cursor rule:** `02-project-structure.mdc` — AI guidance when creating or organizing files (`**/*.{ts,tsx,js,jsx,md}`, `src/**`); points to this doc.
+- **ESLint:** No project-structure rules; structure is enforced by the Cursor rule and the audit tool only.
+- **Audit tool:** Standard 2 audit runs as part of `npm run validate`; checks directory structure, config files, import paths (tsconfig), test colocation, feature-based organization (no type-based or domain-based). 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                        |
+|---------------------|------------------------------------------------|
+| directoryStructure  | Standard Directory Structure                   |
+| configFiles         | Configuration Files                           |
+| importPaths         | Import Path Configuration                     |
+| testColocation      | Testing Structure (Test Colocation)           |
+| organizationPattern | Component Organization / File Organization Standard |
+
 ---
 
 ## Standard Directory Structure
@@ -95,7 +112,7 @@ your-app/
 │   └── audit-*.md
 │
 ├── .gitignore
-├── .eslintrc.js                  # ESLint config (or eslint.config.js)
+├── eslint.config.js               # ESLint config (flat config; or .eslintrc.js / eslint.config.cjs)
 ├── package.json
 ├── tsconfig.json                 # TypeScript config
 ├── tsconfig.app.json             # App-specific TS config (if needed)
@@ -409,7 +426,7 @@ describe('EventCard', () => {
 
 ### Migration Files
 
-**MUST** place all migrations in `supabase/migrations/`:
+**If the app has app-owned migrations:** they **MUST** be in `supabase/migrations/` with the naming convention `YYYYMMDDHHMMSS_description.sql`:
 
 ```
 supabase/
@@ -419,7 +436,7 @@ supabase/
     └── 20250117150000_add_rls_policies.sql
 ```
 
-**MUST** follow naming convention: `YYYYMMDDHHMMSS_description.sql`
+**If the app has no app-owned migrations** (e.g. shared DB managed elsewhere): **MUST** add `supabase/README.md` explaining where migrations/RLS are managed and whether the app will add migrations in the future.
 
 ### Edge Functions (if used)
 
@@ -436,20 +453,18 @@ supabase/
 
 ### Supabase Client Setup
 
-**MUST** place Supabase client in `src/lib/supabase.ts`:
+**MUST** place the base Supabase client in `main.tsx`, `App.tsx`, or (if in a separate file) `src/lib/supabase.ts`. If in a separate file, the base client **MUST NOT** be exported for general use; it must only be passed to `UnifiedAuthProvider`. Components **MUST** use `useSecureSupabase()` from pace-core for queries. See [pace-core Compliance](./1-pace-core-compliance-standards.md) for security requirements.
 
 ```typescript
-// src/lib/supabase.ts
+// src/lib/supabase.ts — base client for UnifiedAuthProvider only; DO NOT import elsewhere
 import { createClient } from '@supabase/supabase-js';
 import type { Database } from '@/types/database';
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
 const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;
 
-export const supabaseClient = createClient<Database>(
-  supabaseUrl,
-  supabaseAnonKey
-);
+// Used only by main.tsx/App.tsx for UnifiedAuthProvider; components use useSecureSupabase()
+export const supabaseClient = createClient<Database>(supabaseUrl, supabaseAnonKey);
 ```
 
 ---
@@ -467,7 +482,7 @@ export const supabaseClient = createClient<Database>(
 | `vite.config.ts` | Vite build configuration | ✅ Yes |
 | `vitest.config.ts` | Vitest test configuration | ✅ Yes |
 | `.gitignore` | Git ignore patterns | ✅ Yes |
-| `.eslintrc.js` or `eslint.config.js` | ESLint configuration | ✅ Yes |
+| `eslint.config.js` (or `.eslintrc.js` / `eslint.config.cjs`) | ESLint configuration | ✅ Yes |
 
 ### Root Directory Rules
 
@@ -704,9 +719,10 @@ your-app/
 
 1. **Remove Duplicate pace-core Components**
    ```bash
-   # Check for pace-core duplicates
-   node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+   # Run full validation (includes pace-core audit)
+   npm run validate
    ```
+   Review `audit/<timestamp>-pace-core-audit.md` for Standard 1 and project structure issues.
 
 2. **Remove Empty Directories**
    ```bash
@@ -719,16 +735,17 @@ your-app/
 
 #### Phase 5: Verification
 
-1. **Install Cursor Rules**
+1. **Run Setup**
    ```bash
-   node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+   npm run setup
    ```
 
 2. **Run Compliance Checks**
    ```bash
-   # Check pace-core compliance
-   node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+   # Run full validation (includes pace-core audit)
+   npm run validate
    ```
+   Review `audit/<timestamp>-pace-core-audit.md` for compliance and structure issues.
 
 3. **Verify Build**
    ```bash

package/docs/standards/3-architecture-standards.md

@@ -6,6 +6,20 @@
 
 Define the core architectural principles and SOLID expectations for pace-core and consuming apps so components, APIs, and utilities evolve consistently and sustainably.
 
+### How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines SOLID, component design, API design, and boundaries.
+- **Cursor rule:** `03-architecture.mdc` — AI guidance when editing `src/**/*.{ts,tsx}`; points to this doc.
+- **ESLint:** SRP proxies only: `max-lines-per-function`, `complexity`, `max-lines` (on `src/**` and, in the monorepo, `packages/core/src/**`). Other architecture enforcement is via the Cursor rule and the audit tool.
+- **Audit tool:** Standard 3 audit runs as part of `npm run validate`; checks component boundaries (data fetching in components, complex business logic in components) and ApiResult shape 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                                        |
+|--------------------|----------------------------------------------------------------|
+| componentBoundary  | Component Design Principles / SOLID (Single Responsibility)    |
+| apiResult          | API Design Principles (Type-Safe Results)                      |
+
 ---
 
 ## Architectural Principles
@@ -164,6 +178,32 @@ const supabaseService: DataService = { /* ... */ };
 const mockService: DataService = { /* ... */ };
 ```
 
+### How we check SOLID
+
+Each principle is enforced by one or more layers. The table below shows which layer(s) check what.
+
+| Principle | Standards | Cursor rule | ESLint | Audit tool |
+|-----------|-----------|-------------|--------|------------|
+| **SRP** | Defined (this doc) | Guidance: extract logic to hooks/services | Proxies: `max-lines-per-function`, `max-lines` (1000), `complexity` (on `src/**`, `packages/core/src/**`) | componentBoundary: data fetching in components, complex business logic (no line or named-export checks; those are in ESLint) |
+| **OCP** | Defined (this doc) | Guidance: composition over modification | — | — |
+| **LSP** | Defined (this doc) | Guidance: maintain interface contracts | — | — |
+| **ISP** | Defined (this doc) | Guidance: focused interfaces | — | Optional: large interface/props count heuristic |
+| **DIP** | Defined (this doc) | Guidance: depend on abstractions | — | Partly covered by componentBoundary (data in components) |
+
+**Limitations:** OCP, LSP, ISP, and DIP are enforced by standards and cursor rules only; there are no mechanical checks for them. SRP is partially checked: the audit flags component-boundary violations (data/business logic in components), and ESLint uses length/complexity as proxies for “single reason to change.” Full SRP adherence is not mechanically decidable.
+
+### Size limits (SRP proxies)
+
+**Line-related limits** are enforced only by **ESLint** (single source; audit does not report line counts):
+
+| What | Limit | Enforced by | Why |
+|------|-------|--------------|-----|
+| **Lines per function** | 400 | ESLint `max-lines-per-function` | Same. |
+| **Lines per file** | 1000 | ESLint `max-lines` | Same. |
+| **Named exports per file** | 10 | ESLint `pace-core-compliance/max-named-exports` | Same. |
+
+All SRP size limits (lines and named exports) are enforced only by ESLint; the audit does not report them.
+
 ---
 
 ## Component Design Principles
@@ -194,7 +234,7 @@ function Counter() {
 
 ### Accessible by Default
 
-**Components must be accessible with correct roles, keyboard support, and visible focus.**
+**Components must be accessible with correct roles, keyboard support, and visible focus.** Prefer pace-core `Button` when available; it provides built-in accessibility. This example illustrates accessibility attributes when building a custom primitive.
 
 ```tsx
 // ✅ CORRECT - Accessible component