@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/rbac/quick-start.md

@@ -357,15 +357,15 @@ export function Login() {
   }
 
   return (
-    <div className="min-h-screen flex items-center justify-center bg-sec-50">
-      <div className="max-w-md w-full space-y-8">
-        <div>
+    <main className="min-h-screen flex items-center justify-center bg-sec-50">
+      <section className="max-w-md w-full space-y-8">
+        <section>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-sec-900">
             Sign in to your account
           </h2>
-        </div>
+        </section>
         <form className="mt-8 space-y-6" onSubmit={handleLogin}>
-          <div>
+          <section>
             <label htmlFor="email" className="sr-only">
               Email address
             </label>
@@ -379,8 +379,8 @@ export function Login() {
               value={email}
               onChange={(e) => setEmail(e.target.value)}
             />
-          </div>
-          <div>
+          </section>
+          <section>
             <label htmlFor="password" className="sr-only">
               Password
             </label>
@@ -394,8 +394,8 @@ export function Login() {
               value={password}
               onChange={(e) => setPassword(e.target.value)}
             />
-          </div>
-          <div>
+          </section>
+          <section>
             <button
               type="submit"
               disabled={loading}
@@ -403,10 +403,10 @@ export function Login() {
             >
               {loading ? 'Signing in...' : 'Sign in'}
             </button>
-          </div>
+          </section>
         </form>
-      </div>
-    </div>
+      </section>
+    </main>
   )
 }
 ```
@@ -427,18 +427,18 @@ export function Dashboard() {
   const { user, selectedOrganisationId } = useUnifiedAuth()
 
   if (!user) {
-    return <div>Please log in</div>
+    return <p>Please log in</p>
   }
 
   return (
-    <div className="min-h-screen bg-sec-50">
+    <main className="min-h-screen bg-sec-50">
       <nav className="bg-background shadow">
-        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
-          <div className="flex justify-between h-16">
-            <div className="flex items-center">
+        <section className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <section className="flex justify-between h-16">
+            <section className="flex items-center">
               <h1 className="text-xl font-semibold">Dashboard</h1>
-            </div>
-            <div className="flex items-center space-x-4">
+            </section>
+            <section className="flex items-center space-x-4">
               <span className="text-sm text-sec-700">
                 {user.email} | Org: {selectedOrganisationId}
               </span>
@@ -448,39 +448,39 @@ export function Dashboard() {
               >
                 Sign out
               </button>
-            </div>
-          </div>
-        </div>
+            </section>
+          </section>
+        </section>
       </nav>
 
       <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
-        <div className="px-4 py-6 sm:px-0">
-          <div className="border-4 border-dashed border-sec-200 rounded-lg h-96 p-8">
+        <section className="px-4 py-6 sm:px-0">
+          <section className="border-4 border-dashed border-sec-200 rounded-lg h-96 p-8">
             <h2 className="text-2xl font-bold mb-4">Welcome to your Dashboard</h2>
             
             {/* CRITICAL: Use PagePermissionGuard for page-level permissions */}
             <PagePermissionGuard
               pageName="dashboard"
               operation="read"
-              fallback={<div>You don't have permission to view the dashboard</div>}
+              fallback={<p>You don't have permission to view the dashboard</p>}
             >
-              <div className="space-y-4">
+              <section className="space-y-4">
                 <p>You have access to the dashboard!</p>
                 
-                <div className="space-x-4">
+                <section className="space-x-4">
                   <Link 
                     to="/users" 
                     className="bg-main-500 text-main-50 px-4 py-2 rounded hover:bg-main-600"
                   >
                     View Users
                   </Link>
-                </div>
-              </div>
+                </section>
+              </section>
             </PagePermissionGuard>
-          </div>
-        </div>
+          </section>
+        </section>
       </main>
-    </div>
+    </main>
   )
 }
 ```
@@ -501,21 +501,21 @@ export function Users() {
   const { user, selectedOrganisationId } = useUnifiedAuth()
 
   if (!user) {
-    return <div>Please log in</div>
+    return <p>Please log in</p>
   }
 
   return (
-    <div className="min-h-screen bg-sec-50">
+    <main className="min-h-screen bg-sec-50">
       <nav className="bg-background shadow">
-        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
-          <div className="flex justify-between h-16">
-            <div className="flex items-center">
+        <section className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <section className="flex justify-between h-16">
+            <section className="flex items-center">
               <Link to="/" className="text-main-600 hover:text-main-800 mr-4">
                 ← Back to Dashboard
               </Link>
               <h1 className="text-xl font-semibold">Users</h1>
-            </div>
-            <div className="flex items-center space-x-4">
+            </section>
+            <section className="flex items-center space-x-4">
               <span className="text-sm text-sec-700">
                 {user.email} | Org: {selectedOrganisationId}
               </span>
@@ -525,35 +525,35 @@ export function Users() {
               >
                 Sign out
               </button>
-            </div>
-          </div>
-        </div>
+            </section>
+          </section>
+        </section>
       </nav>
 
       <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
-        <div className="px-4 py-6 sm:px-0">
-          <div className="border-4 border-dashed border-sec-200 rounded-lg h-96 p-8">
+        <section className="px-4 py-6 sm:px-0">
+          <section className="border-4 border-dashed border-sec-200 rounded-lg h-96 p-8">
             <h2 className="text-2xl font-bold mb-4">User Management</h2>
             
             {/* CRITICAL: Use PagePermissionGuard for page-level permissions */}
             <PagePermissionGuard
               pageName="users"
               operation="read"
-              fallback={<div>You don't have permission to view users</div>}
+              fallback={<p>You don't have permission to view users</p>}
             >
-              <div className="space-y-4">
+              <section className="space-y-4">
                 <p>You have access to the users page!</p>
                 <p>This means your RBAC system is working correctly.</p>
                 
-                <div className="bg-main-100 border border-main-400 text-main-700 px-4 py-3 rounded">
+                <section className="bg-main-100 border border-main-400 text-main-700 px-4 py-3 rounded">
                   <strong>Success!</strong> Your RBAC setup is working correctly.
-                </div>
-              </div>
+                </section>
+              </section>
             </PagePermissionGuard>
-          </div>
-        </div>
+          </section>
+        </section>
       </main>
-    </div>
+    </main>
   )
 }
 ```

package/docs/rbac/secure-client-protection.md

@@ -134,7 +134,7 @@ function MyComponent() {
   const supabase = useSecureSupabase();
   
   if (!supabase) {
-    return <div>Loading...</div>;
+    return <p>Loading...</p>;
   }
   
   // Organisation context is automatically enforced
@@ -229,38 +229,6 @@ function MyComponent() {
 }
 ```
 
-## Audit Script Detection
-
-The pace-core audit script comprehensively detects insecure client usage:
-
-```bash
-npm run audit
-```
-
-The audit will report violations including:
-- ✅ Direct `createClient` imports from `@supabase/supabase-js`
-- ✅ Direct `createClient()` function calls
-- ✅ Usage of non-secure clients for database queries (`.from()` calls)
-- ✅ Files that import `createClient` but don't use `useSecureSupabase()`
-- ✅ Variables created with `createClient()` that are used for queries
-
-**Example audit output**:
-```
-❌ Direct Supabase client usage detected
-   File: src/components/UserList.tsx
-   Line: 15
-   Variable: supabase
-   Table: users
-   Reason: Direct Supabase client usage detected. Variable 'supabase' is created with createClient() and used for database queries. You MUST use useSecureSupabase() instead to ensure RLS policies and organisation context are enforced.
-   Recommendation: Replace with: import { useSecureSupabase } from '@jmruthers/pace-core/rbac'; const supabase = useSecureSupabase();
-```
-
-The audit tool provides the same level of detection as the ESLint rule, making it useful for:
-- Pre-commit checks
-- CI/CD pipelines
-- Code reviews
-- Migration validation
-
 ## Best Practices
 
 1. **Always use `useSecureSupabase()`** in React components
@@ -268,7 +236,6 @@ The audit tool provides the same level of detection as the ESLint rule, making i
 3. **Never import `createClient`** from `@supabase/supabase-js` in component files
 4. **Verify client security** in critical code paths (optional but recommended)
 5. **Run ESLint** regularly to catch violations early
-6. **Run audit script** before deploying to catch any missed violations
 
 ## Troubleshooting
 
@@ -324,7 +291,6 @@ The protection system provides:
 - ✅ **Runtime warnings** to alert developers in development mode
 - ✅ **Type safety** to verify client security
 - ✅ **Automatic marking** of secure clients
-- ✅ **Audit scripts** to catch violations before deployment
 
 By following these guidelines, you ensure that all database operations respect organisation context and RLS policies, preventing security vulnerabilities and data leakage.
 

package/docs/rbac/troubleshooting.md

@@ -192,7 +192,7 @@ function App() {
 <PagePermissionGuard
   pageName="dashboard"
   operation="read"
-  fallback={<div>Access Denied</div>}
+  fallback={<p>Access Denied</p>}
 >
   <Dashboard />
 </PagePermissionGuard>

package/docs/security/README.md

@@ -126,14 +126,14 @@ function ProtectedComponent() {
   const { user, session, isLoading } = useUnifiedAuth();
 
   if (isLoading) {
-    return <div>Loading...</div>;
+    return <p>Loading...</p>;
   }
 
   if (!user || !session) {
-    return <div>Please log in</div>;
+    return <p>Please log in</p>;
   }
 
-  return <div>Welcome, {user.email}!</div>;
+  return <p>Welcome, {user.email}!</p>;
 }
 ```
 
@@ -672,9 +672,9 @@ test('hides content when user lacks permission', () => {
     <PermissionEnforcer
       operation="read"
       resource="users"
-      fallback={<div>Access denied</div>}
+      fallback={<p>Access denied</p>}
     >
-      <div>User data</div>
+      <section>User data</section>
     </PermissionEnforcer>
   );
 

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

@@ -0,0 +1,220 @@
+# Standards Overview
+
+**🤖 Cursor Rule**: See [00-standards-overview.mdc](../../cursor-rules/00-standards-overview.mdc) for AI-optimized directives that automatically enforce these standards.
+
+## Purpose
+
+This document provides an overview of the pace-core standards system, how it works, and how to use it. These standards are 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
+- Organized by the 10-file standards structure
+
+**What it is used for**
+- Validating architectural compliance (RBAC, data access, boundaries)
+- Catching issues ESLint cannot see (cross-file analysis, configuration validation)
+- Providing actionable remediation plans
+- System-level checks (provider nesting, RLS policies in SQL, project structure)
+
+**What it is NOT**
+- It is not a linter replacement
+- It should not report stylistic issues (handled by ESLint)
+- It should not duplicate ESLint checks (file-level AST analysis)
+- It should not contradict the standards
+
+➡️ 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.
+
+---
+
+## 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.
+
+---
+
+## Precedence Order
+
+When standards conflict, apply this precedence order:
+
+1. **Security** - Security and RBAC standards take highest priority
+2. **API/RPC** - API contracts and RPC standards
+3. **Components & Markup** - Component usage and markup quality
+4. **Code Quality/Style** - TypeScript, naming, code style
+5. **Testing & Documentation** - Testing and documentation requirements
+6. **Consuming App Structure** - Project structure and organization
+
+**Example:** If a component pattern conflicts with a security requirement, security wins.
+
+---
+
+## 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 |
+
+---
+
+## Quick Reference Guide
+
+**New to pace-core?** Start here:
+1. Read [Standards Overview](./0-standards-overview.md) (this file) - Understand the system
+2. Read [Styling Standards](./5-styling-standards.md) - **CRITICAL:** Required CSS setup
+3. Read [pace-core Compliance](./1-pace-core-compliance-standards.md) - How to use pace-core
+4. Read [Project Structure](./2-project-structure-standards.md) - Organize your code
+
+**Common Tasks:**
+- **Setting up a new app?** → [Project Structure](./2-project-structure-standards.md) + [Styling Standards](./5-styling-standards.md)
+- **Writing components?** → [Architecture](./3-architecture-standards.md) + [Code Quality](./4-code-quality-standards.md)
+- **Working with RBAC?** → [Security & RBAC](./6-security-rbac-standards.md)
+- **Creating APIs/RPCs?** → [API & Tech Stack](./7-api-tech-stack-standards.md)
+- **Handling errors?** → [Operations](./9-operations-standards.md)
+- **Writing tests?** → [Testing & Documentation](./8-testing-documentation-standards.md)
+
+---
+
+## 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
+
+---
+
+## Related Documentation
+
+- [pace-core Compliance](./1-pace-core-compliance-standards.md) - pace-core usage patterns
+- [Project Structure](./2-project-structure-standards.md) - Project structure and organization
+- [Architecture](./3-architecture-standards.md) - SOLID architecture principles
+- [Code Quality](./4-code-quality-standards.md) - Code quality and TypeScript standards
+- [Styling](./5-styling-standards.md) - Markup and styling standards
+- [Security & RBAC](./6-security-rbac-standards.md) - RBAC and RLS standards
+- [API & Tech Stack](./7-api-tech-stack-standards.md) - Tech stack and API/RPC standards
+- [Testing & Documentation](./8-testing-documentation-standards.md) - Testing and documentation standards
+- [Operations](./9-operations-standards.md) - Error handling, performance, and CI/CD
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 2.0.0  
+**Applies to:** All pace-core and consuming apps