@jmruthers/pace-core 0.6.9 → 0.6.11

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

@@ -15,7 +15,7 @@ This guide defines the standard project structure and file organization patterns
 ## Table of Contents
 
 1. [Standard Directory Structure](#standard-directory-structure)
-2. [File Organization Patterns](#file-organization-patterns)
+2. [File Organization Standard](#file-organization-standard)
 3. [Naming Conventions](#naming-conventions)
 4. [Import Path Configuration](#import-path-configuration)
 5. [Component Organization](#component-organization)
@@ -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)
@@ -125,11 +142,11 @@ your-app/
 
 ---
 
-## File Organization Patterns
+## File Organization Standard
 
-### Pattern 1: Feature-Based Organization (Recommended for Small-Medium Apps)
+### Feature-Based Organization
 
-Organize components, hooks, and related code by feature/domain:
+**MUST** organize components, hooks, and related code by feature/domain:
 
 ```
 src/
@@ -163,73 +180,11 @@ src/
     └── users.ts
 ```
 
-**When to use:** Small to medium-sized apps (< 20 features)
-
-### Pattern 2: Domain-Driven Organization (Recommended for Large Apps)
-
-For larger applications, organize by domain with internal structure:
-
-```
-src/
-├── domains/
-│   ├── events/
-│   │   ├── components/
-│   │   │   ├── EventCard.tsx
-│   │   │   └── EventList.tsx
-│   │   ├── hooks/
-│   │   │   └── useEventData.ts
-│   │   ├── services/
-│   │   │   └── EventService.ts
-│   │   ├── types.ts
-│   │   └── index.ts              # Domain barrel export
-│   │
-│   └── users/
-│       ├── components/
-│       ├── hooks/
-│       ├── services/
-│       ├── types.ts
-│       └── index.ts
-│
-├── shared/                        # Shared across domains
-│   ├── components/
-│   │   ├── Layout.tsx
-│   │   └── Navigation.tsx
-│   ├── hooks/
-│   │   └── useAppConfig.ts
-│   └── utils/
-│       └── formatDate.ts
-│
-└── pages/
-    ├── events/
-    │   ├── EventsListPage.tsx
-    │   └── EventDetailPage.tsx
-    └── users/
-        └── UsersPage.tsx
-```
-
-**When to use:** Large apps with multiple distinct domains (> 20 features, clear domain boundaries)
-
-### Pattern 3: Hybrid Organization
-
-Combine feature-based and domain-based as needed:
-
-```
-src/
-├── components/
-│   ├── events/                   # Feature-based (simple features)
-│   └── shared/                   # Shared components
-│
-├── domains/
-│   └── complex-feature/          # Domain-based (complex features)
-│       ├── components/
-│       ├── hooks/
-│       └── services/
-│
-└── pages/
-    └── [pages organized by route]
-```
-
-**When to use:** Apps with mixed complexity levels
+**Why feature-based?** Since pace apps are already split by domain, organizing code by feature within each app provides:
+- **Clear boundaries** - Related code stays together
+- **Easy navigation** - Find all code for a feature in one place
+- **Simplified imports** - Consistent path structure
+- **Better maintainability** - Changes to a feature are localized
 
 ---
 
@@ -471,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/
@@ -481,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)
 
@@ -498,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);
 ```
 
 ---
@@ -529,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
 
@@ -582,7 +535,7 @@ src/
 ```
 
 **Migration Steps:**
-1. Group components by feature/domain
+1. Group components by feature
 2. Move to `src/components/[feature]/`
 3. Remove duplicate pace-core components (use pace-core instead)
 4. Update imports to use path aliases
@@ -613,7 +566,7 @@ src/
 ```
 
 **Migration Steps:**
-1. Identify features/domains in your app
+1. Identify features in your app
 2. Reorganize by feature, not type
 3. Use pace-core for UI primitives (Button, Input, Card)
 4. Keep only feature-specific components
@@ -694,7 +647,7 @@ your-app/
    git commit -am "Backup before structure migration"
    ```
 
-3. **Identify Features/Domains**
+3. **Identify Features**
    - List all features in your app
    - Group related components/hooks/utils
    - Identify pace-core duplicates
@@ -766,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
@@ -781,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

package/docs/standards/4-code-quality-standards.md

@@ -10,6 +10,26 @@ This standard defines TypeScript rules, naming conventions, and code style patte
 
 ---
 
+## How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines TypeScript rules, naming conventions, patterns, and accessibility (WCAG 2.1 AA).
+- **Cursor rule:** `04-code-quality.mdc` — AI guidance when editing `src/**/*.{ts,tsx,js,jsx}`; points to this doc.
+- **ESLint:** Rules in `04-code-quality.cjs` (plugin prefix `pace-core-compliance/`): `naming-convention`, `component-naming`, `type-naming`. Run via lint step in CI and locally.
+- **Audit tool:** Standard 4 audit runs as part of `npm run validate`; checks TypeScript config (strict mode), test coverage config (vitest), and excessive/debug console logging. 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                              |
+|----------------------------|------------------------------------------------------|
+| typescriptConfig           | TypeScript Rules (Avoid Implicit any / tsconfig)     |
+| testCoverage               | (Testing standard) / vitest coverage                  |
+| excessiveConsoleLogging   | Forbidden Patterns / code hygiene                   |
+| debugConsoleLogging       | Forbidden Patterns / code hygiene                   |
+
+---
+
 ## TypeScript Rules
 
 ### No `any` Type
@@ -456,7 +476,7 @@ function EventPage({ eventId }: { eventId: string }) {
     // 50+ lines of logic
   }, [eventId]);
   
-  // 200+ lines of JSX
+  // 400+ lines of JSX
   return <div>...</div>;
 }
 
@@ -704,15 +724,15 @@ Before committing code, verify:
 
 ## ESLint Rules
 
-The following ESLint rules enforce code quality standards:
-
-### Naming Conventions
+Rule IDs use the plugin prefix **`pace-core-compliance/`**. The following rules enforce code quality standards:
 
-- **`naming-convention`** - Enforces hook naming (`use*`) and provider naming (`*Provider`)
+- **`pace-core-compliance/naming-convention`** — Enforces hook naming (`use*`) and provider naming (`*Provider`).
+- **`pace-core-compliance/component-naming`** — Enforces component PascalCase.
+- **`pace-core-compliance/type-naming`** — Enforces types and interfaces PascalCase.
 
 These rules are part of the `pace-core-compliance` plugin and are automatically enabled when you extend `@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/5-styling-standards.md

@@ -2,6 +2,8 @@
 
 **🤖 Cursor Rule**: See [05-styling.mdc](../../cursor-rules/05-styling.mdc) for AI-optimized directives that automatically enforce markup quality (this rule is ALWAYS APPLIED).
 
+**🔧 ESLint Rules**: See [05-styling.cjs](../../eslint-rules/rules/05-styling.cjs) for mechanically checkable styling/markup rules.
+
 ## Purpose
 
 This standard defines the **REQUIRED** configuration for consuming apps to properly use pace-core styling. Adhering to this standard ensures:
@@ -11,6 +13,26 @@ This standard defines the **REQUIRED** configuration for consuming apps to prope
 - ✅ Tailwind v4 content scanning works properly
 - ✅ Consistent styling across all PACE suite applications
 
+---
+
+## How each layer enforces this standard
+
+- **Standards (this doc):** Source of truth; defines required CSS setup (app.css, @source, @theme, color palettes), markup/styling rules, and Tailwind v4 usage.
+- **Cursor rule:** `05-styling.mdc` — ALWAYS APPLIED; AI guidance when editing `src/**/*.{ts,tsx,js,jsx}`; points to this doc and CSS checklist.
+- **ESLint:** Rules in `05-styling.cjs` (plugin prefix `pace-core-compliance/`): see ESLint Rules section below. Run via lint step in CI and locally.
+- **Audit tool:** Standard 5 audit runs as part of `npm run validate`; checks app.css existence/structure, required imports, @source directives, @theme and color palettes, and Tailwind v4 plugin in vite.config. 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 |
+|------------------|--------------------------|
+| appCss | Required File: src/app.css; CRITICAL: @source paths; CSS Import Path; Required Color Palettes; Verification Checklist |
+| tailwindConfig | Verification Checklist / Troubleshooting (Tailwind v4) |
+
+---
+
 ## Component & Markup Guidance
 
 - Components should be stateless when possible, fully typed, and accessibility-first.
@@ -215,7 +237,7 @@ When you have additional entry points (storybook, tests, preview servers):
 ## Styling & Markup Rules
 
 - **No inline styles**: Do not use `style={{ ... }}` except when a third-party library strictly requires it. Prefer pace-core variants + Tailwind utilities.
-- **Use theme tokens only**: Avoid arbitrary Tailwind colors (`text-gray-500`, `bg-red-500`) and bracket syntax (`bg-[oklch(...)]`). Use `main-*`, `sec-*`, `acc-*`, or semantic tokens like `text-foreground`.
+- **Use theme tokens only**: Avoid arbitrary Tailwind colors (e.g. standard-named colors) and bracket syntax (`bg-[oklch(...)]`). Use `main-*`, `sec-*`, `acc-*`, or semantic tokens like `text-foreground`.
 - **Semantic-first markup**: Prefer semantic HTML elements. Use `<div>` only when no semantic element fits or when required by a library; otherwise use semantic tags or React fragments.
 - **Minimal wrappers**: Avoid extra wrapper elements just for styling—apply layout classes to existing semantic parents or use pace-core layout components.
 - **Typography**: Rely on pace-core typography defaults; only add utilities when they reference approved theme tokens (e.g., `text-main-700`).
@@ -335,6 +357,18 @@ import './app.css';
 2. **Check build output:** Look for warnings about missing classes
 3. **Verify package version:** Ensure you're using a recent version of pace-core
 
+## ESLint Rules
+
+Rule IDs use the plugin prefix **`pace-core-compliance/`**. The following rules enforce styling and markup standards:
+
+- **`pace-core-compliance/no-inline-styles`** — Disallow `style={{...}}`; use pace-core or Tailwind.
+- **`pace-core-compliance/no-typography-styling`** — Disallow typography/color/spacing classes on typography elements (per standard).
+- **`pace-core-compliance/no-pace-core-style-override`** — Disallow overriding className on pace-core components.
+- **`pace-core-compliance/prefer-semantic-html`** — Prefer semantic elements over `<div>`/`<span>`.
+- **`pace-core-compliance/no-nested-same-type-tags`** — Disallow redundant nesting of same semantic type.
+
+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