@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/rbac/getting-started.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC Getting Started Guide
@@ -411,7 +411,6 @@ function Navigation({ userId, organisationId }) {
    <UnifiedAuthProvider 
      supabaseClient={supabase} 
      appName="your-app"
-     enableRBAC={true}
      requireOrganisationContext={true}
    >
      <OrganisationProvider>
@@ -721,6 +720,66 @@ function AdaptiveComponent({ appId }) {
 - [Troubleshooting](./troubleshooting.md) - Common issues and solutions
 - [Migration Guide](../migration/rbac-migration.md) - Migrating from legacy RBAC
 
+## ♿ Accessibility
+
+RBAC components are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All RBAC components meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during permission checks and loading states
+- **Error Announcements** - Permission errors are clearly communicated
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements for permission-protected content
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied states
+3. **Announce permission changes** - Use ARIA live regions for dynamic permission updates
+4. **Test with screen readers** - Verify permission operations work with assistive technologies
+5. **Ensure keyboard access** - All permission-protected content should be keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Permission Changes During Session
+
+When user permissions change during active session:
+- Permission checks update automatically via cache invalidation
+- Protected content appears/disappears dynamically
+- No page refresh required
+- Clear feedback explains permission changes
+
+### Missing Permission Data
+
+When permission data is missing or unavailable:
+- System fails securely (denies access by default)
+- Clear error messages explain the issue
+- Fallback UI is shown when appropriate
+- User-friendly error messages guide recovery
+
+### Network Failures During Permission Checks
+
+When network fails during permission validation:
+- Operations fail securely (deny by default)
+- Cached permissions may be used when available
+- Error messages clearly explain the issue
+- Retry mechanisms are available
+
+### Invalid Permission Scopes
+
+When invalid permission scopes are provided:
+- Validation errors are clearly displayed
+- Operations fail gracefully
+- No unauthorized data access
+- User-friendly error messages guide correction
+
+### RPC Call Timeouts
+
+When RPC calls timeout:
+- System fails securely (denies access by default)
+- Clear error messages explain the timeout
+- Retry mechanisms are available
+- Check database connection and performance
+
 ## Need Help?
 
 - Check the [Troubleshooting Guide](./troubleshooting.md)

package/docs/rbac/quick-start.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC Quick Start
@@ -432,7 +432,7 @@ export function Dashboard() {
 
   return (
     <div className="min-h-screen bg-sec-50">
-      <nav className="bg-white shadow">
+      <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">
@@ -506,7 +506,7 @@ export function Users() {
 
   return (
     <div className="min-h-screen bg-sec-50">
-      <nav className="bg-white shadow">
+      <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">
@@ -752,3 +752,55 @@ If you're still having problems after following this guide exactly:
 4. **Check that your user has the correct roles** in the database
 
 This guide is designed to be foolproof - if you follow it exactly, your RBAC system will work correctly.
+
+## ♿ Accessibility
+
+The RBAC system you've built includes accessibility features:
+
+- **WCAG 2.1 AA compliant** - All RBAC components meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during permission checks
+- **Error Announcements** - Permission errors are clearly communicated
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements in your components
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied
+3. **Test with screen readers** - Verify your app works with assistive technologies
+4. **Ensure keyboard access** - All interactive elements should be keyboard accessible
+5. **Announce permission changes** - Use ARIA live regions for dynamic updates
+
+## ⚠️ Edge Cases
+
+### Database Setup Failures
+
+When database setup fails:
+- Verify SQL commands are executed correctly
+- Check that all tables exist and have correct structure
+- Ensure user has proper database permissions
+- Review error messages for specific issues
+
+### Permission Check Failures
+
+When permission checks fail:
+- Verify `setupRBAC()` was called before using RBAC
+- Check that app name matches exactly (case-sensitive)
+- Ensure user has organisation role assigned
+- Verify page permissions exist in database
+
+### Provider Setup Issues
+
+When providers aren't set up correctly:
+- Verify provider order: UnifiedAuthProvider → OrganisationProvider
+- Check that all required props are provided
+- Ensure providers wrap all RBAC-protected content
+- Review error messages for specific issues
+
+### Environment Variable Issues
+
+When environment variables are incorrect:
+- Verify `VITE_APP_NAME` matches database app name exactly
+- Check that Supabase URL and keys are correct
+- Ensure environment variables are loaded before app starts
+- Restart dev server after changing environment variables

package/docs/rbac/rbac-rls-integration.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC-RLS Integration: Dynamic Permission Enforcement
@@ -297,6 +297,28 @@ SELECT check_rbac_permission_with_context(
 
 ## Examples
 
+### React Component Usage
+
+```tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function MealsPage() {
+  return (
+    <div>
+      <PagePermissionGuard
+        pageName="meals"
+        operation="delete"
+        fallback={<div>You don't have permission to delete meals</div>}
+      >
+        <button onClick={handleDeleteMeal}>
+          Delete Selected Meal
+        </button>
+      </PagePermissionGuard>
+    </div>
+  );
+}
+```
+
 ### Complete Table Migration
 
 ```sql
@@ -318,10 +340,10 @@ SELECT * FROM check_rbac_policy_health()
 WHERE table_name = 'cake_meal';
 ```
 
-### Dynamic Permission Testing
+### Database Permission Testing
 
 ```sql
--- Test different scenarios
+-- Test different permission scenarios
 SELECT 
   'planner delete meals' as test_case,
   check_rbac_permission_with_context('delete', 'meals', 'org-uuid', 'event-123', 'CAKE') as result
@@ -335,6 +357,19 @@ SELECT
   check_rbac_permission_with_context('delete', 'deliveries', 'org-uuid', 'event-123', 'CAKE');
 ```
 
+### Dynamic Permission Changes
+
+```sql
+-- Change permissions in real-time
+UPDATE rbac_page_permissions 
+SET allowed = false 
+WHERE app_page_id = 'page-meals-id' 
+  AND role_name = 'planner' 
+  AND operation = 'delete';
+
+-- Policies automatically update to reflect the change!
+```
+
 ## Monitoring and Maintenance
 
 ### Regular Health Checks
@@ -380,4 +415,31 @@ The RBAC-RLS integration provides a robust, dynamic permission enforcement syste
 4. **Enables flexibility** - Organisations can configure permissions without code changes
 5. **Ensures consistency** - RBAC and RLS are always in sync
 
-This system solves the critical architectural issue and provides a foundation for scalable, maintainable permission management across the entire pace suite.
+This integration solves the fundamental disconnect between configurable RBAC permissions and hardcoded RLS policies, ensuring that:
+- Organisations have true control over their permission systems
+- Developers can rely on consistent behavior across all operations
+- Users get the functionality they expect based on their assigned roles
+- The system is maintainable and auditable with clear change tracking
+
+This integration is not just a bug fix - it's a fundamental improvement to the pace-core architecture that will benefit all current and future applications in the suite.
+
+## Support
+
+### Getting Help
+1. Check the troubleshooting section above
+2. Review the audit log for error details
+3. Use the SQL functions for debugging
+4. Check the health monitoring views
+
+### Reporting Issues
+When reporting issues, please include:
+- The specific error message
+- Relevant audit log entries
+- Health check results
+- Steps to reproduce the issue
+
+## Related Documentation
+
+- **[RLS Integration Example](./examples/rbac-rls-integration-example.md)** - Practical usage examples
+- **[API Reference](./api-reference.md)** - Complete function reference
+- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions

package/docs/rbac/super-admin-guide.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Super Admin Access Guide
@@ -582,3 +582,47 @@ Super admin access in @jmruthers/pace-core provides:
 - **Comprehensive audit logging**
 
 Use the provided hooks and components to implement super admin access in your consuming applications. This guide includes both implementation patterns and practical examples to help you get started quickly.
+
+## ♿ Accessibility
+
+Super admin components are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All super admin components meet accessibility standards
+- **Screen Reader Support** - Super admin status and actions are properly announced
+- **Keyboard Navigation** - All super admin interfaces are keyboard accessible
+- **Focus Management** - Proper focus handling during super admin operations
+- **Status Indicators** - Super admin status is clearly communicated
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements for super admin interfaces
+2. **Label super admin controls clearly** - Use descriptive labels for all super admin actions
+3. **Announce privilege changes** - Use ARIA live regions for dynamic privilege updates
+4. **Test with screen readers** - Verify super admin operations work with assistive technologies
+5. **Ensure keyboard access** - All super admin actions should be keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Super Admin Access Revocation
+
+When super admin access is revoked:
+- Current session may continue with elevated privileges
+- New operations respect revoked status
+- Audit logs track all super admin actions
+- Clear warnings indicate privilege changes
+
+### Concurrent Super Admin Operations
+
+When multiple super admin operations occur simultaneously:
+- Operations are queued and processed in order
+- Security checks prevent conflicts
+- Audit logging tracks all operations
+- Data consistency is maintained
+
+### Super Admin Bypass Failures
+
+When super admin bypass doesn't work:
+- Verify super admin status is correctly detected
+- Check that bypass logic is properly implemented
+- Ensure audit logging is working
+- Review error messages for specific issues

package/docs/rbac/troubleshooting.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC Troubleshooting Guide

package/docs/security/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T18:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Security Guide
@@ -747,3 +747,68 @@ Conduct regular security reviews:
 - **Dependency reviews** - Review third-party dependencies
 
 This security guide provides a comprehensive overview of security considerations when using PACE Core. Always follow security best practices and stay updated with the latest security recommendations.
+
+## ♿ Accessibility
+
+Security implementations should maintain accessibility:
+
+- **Security forms are keyboard accessible** - All authentication and security forms should support keyboard navigation
+- **Error messages are accessible** - Security errors should be clearly communicated to assistive technologies
+- **Screen reader support** - Security messages and warnings should be properly announced
+- **Focus management** - Ensure focus is properly managed during security operations
+- **Timeouts are announced** - Session timeouts and security warnings should be accessible
+
+### Accessibility Best Practices
+
+1. **Test authentication flows with screen readers** - Verify login and security flows work with assistive technologies
+2. **Ensure keyboard access** - All security forms should be keyboard accessible
+3. **Provide clear error messages** - Security errors should be descriptive without exposing vulnerabilities
+4. **Announce security state changes** - Use ARIA live regions for security status updates
+5. **Test with assistive technologies** - Verify all security features work with screen readers
+
+## ⚠️ Edge Cases
+
+### Security vs Usability Conflicts
+
+When security measures impact usability:
+- Find balance between security and user experience
+- Provide clear guidance for security requirements
+- Implement security transparently
+- Test with real users to ensure usability
+- Document security decisions
+
+### Authentication Failures
+
+When authentication fails:
+- Provide clear error messages without exposing system details
+- Handle rate limiting gracefully
+- Ensure error messages are accessible
+- Test with different authentication scenarios
+- Monitor authentication failures for security threats
+
+### Permission Check Failures
+
+When permission checks fail:
+- Verify RLS policies are correctly configured
+- Check organisation context is properly set
+- Ensure user has required roles assigned
+- Review audit logs for permission denials
+- Test with different user roles
+
+### Session Management Edge Cases
+
+When session management fails:
+- Handle session expiration gracefully
+- Provide clear messages for session issues
+- Ensure proper cleanup on session end
+- Test with multiple concurrent sessions
+- Verify session security across devices
+
+### Security Configuration Issues
+
+When security configuration is incorrect:
+- Verify environment variables are set correctly
+- Check security policies are properly configured
+- Ensure RLS policies are enabled
+- Review security configuration documentation
+- Test with minimal security configuration

package/docs/security/checklist.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T18:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Security Checklist
@@ -347,3 +347,50 @@ Comprehensive security checklist for PACE Core applications before going to prod
 - **Approved By**: [Name]
 
 Remember: **Security is everyone's responsibility!**
+
+## ♿ Accessibility
+
+Security checklist items should consider accessibility:
+
+- **Security forms are keyboard accessible** - Verify all authentication forms support keyboard navigation
+- **Error messages are accessible** - Ensure security error messages are properly announced
+- **Screen reader support** - Verify security warnings and messages work with screen readers
+- **Focus management** - Ensure focus is properly managed during security operations
+- **Accessibility testing included** - Include accessibility testing in security checklist
+
+### Accessibility Checklist Items
+
+- [ ] All security forms are keyboard accessible
+- [ ] Security error messages are properly announced
+- [ ] Security warnings work with screen readers
+- [ ] Focus management is correct during security operations
+- [ ] Accessibility testing is included in security testing
+
+## ⚠️ Edge Cases
+
+### Checklist Items Not Applicable
+
+When checklist items don't apply:
+- Document why items are not applicable
+- Provide alternative security measures
+- Review with security team
+- Update checklist for your specific use case
+- Maintain security standards even when items don't apply
+
+### Partial Compliance
+
+When only partial compliance is possible:
+- Document compliance gaps
+- Create remediation plan
+- Prioritize critical security items
+- Set timeline for full compliance
+- Monitor compliance progress
+
+### Environment-Specific Security
+
+When security requirements vary by environment:
+- Document environment-specific requirements
+- Verify security measures for each environment
+- Test security in all environments
+- Maintain security standards across environments
+- Review environment-specific configurations

package/docs/standards/01-architecture-standard.md

@@ -0,0 +1,39 @@
+# Architecture Standard
+
+## Purpose
+Define the core architectural principles for pace-core so that components, APIs, RPCs, utilities, and documentation evolve consistently and sustainably.
+
+## Principles
+- Composition over complexity
+- Separation of concerns
+- Domain-agnostic
+- Extensible, stable APIs
+- Secure by default
+- Performance-conscious
+
+## Boundaries
+### In scope
+- UI primitives
+- Generic hooks
+- Shared API patterns
+- Error-handling conventions
+- RPC shape conventions
+
+### Out of scope
+- App-specific domain logic
+- App-specific styling
+- Business workflows
+
+## Precedence
+1. Security Standard
+2. API & RPC Standard
+3. Component Standard
+4. Code Style Standard
+5. Testing Standard
+6. Documentation Standard
+
+## Cursor Checklist
+- Ensure changes fit boundaries
+- Do not introduce domain logic
+- Follow precedence ordering
+- Prefer additive changes

package/docs/standards/02-api-and-rpc-standard.md

@@ -0,0 +1,39 @@
+# API & RPC Standard
+
+## Naming
+- `<family>_<domain>_<verb>` pattern (e.g., `data_cake_dishes_list`, `app_cake_dish_create`)
+- `data_*` prefix for read operations (e.g., `data_file_reference_list`)
+- `app_*` prefix for write operations (e.g., `app_cake_dish_create`)
+- CRUD verbs only: create, read, update, delete, list, get
+- Bulk operations use `_bulk` suffix (e.g., `app_cake_dish_create_bulk`)
+
+## Result Shape
+```ts
+type ApiResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: ApiError };
+
+type ApiError = {
+  code: string;
+  message: string;
+  details?: object;
+};
+```
+
+## RPC Rules
+- Read RPCs never mutate
+- Write RPCs should be idempotent when possible
+- Never accept dynamic SQL
+- Must enforce RLS + tenant boundaries
+- Errors must be user-safe
+
+## Deprecation Rules
+- Mark outdated RPCs with @deprecated
+- Retirement window: 2 stable releases
+
+## Cursor Checklist
+- Enforce ApiResult shape
+- Follow naming rules
+- Do not bypass RLS
+- Avoid overlapping or redundant RPCs
+- Ensure idempotency for writes

package/docs/standards/03-component-standard.md

@@ -0,0 +1,32 @@
+# Component Development Standard
+
+## Principles
+- Stateless when possible
+- Composable structure
+- Accessible by default
+- Fully typed
+- Small surface area
+
+## Architecture
+- UI primitives only
+- Never add domain logic
+- No data fetching inside components
+- Support controlled + uncontrolled usage
+
+## Accessibility Checklist
+- Keyboard operable
+- Correct ARIA roles
+- Visible focus states
+- No inaccessible interactions
+
+## Testing Requirements
+- Use React Testing Library
+- Test key interactions
+- Snapshot tests only for simple components
+
+## Cursor Checklist
+- Do not add domain logic
+- Validate accessibility rules
+- Keep components small
+- Move non-UI logic to hooks
+- Enforce strict typings

package/docs/standards/04-code-style-standard.md

@@ -0,0 +1,32 @@
+# TypeScript & Code Style Standard
+
+## TypeScript Rules
+- No any
+- Prefer discriminated unions
+- Avoid assertions unless in escape hatches
+- Use ReadonlyArray where possible
+- Avoid boolean mode flags
+
+## Naming Conventions
+- Hooks: useSomething
+- Providers: SomethingProvider
+- Utilities: camelCase
+- Components: PascalCase
+
+## Preferred Patterns
+- Pure functions
+- Composition over inheritance
+- Early returns
+- Small private helpers
+
+## Forbidden
+- Implicit any
+- Bloated components
+- Domain-specific types in pace-core
+
+## Cursor Checklist
+- No any / unknown / unnecessary assertions
+- Convert flags into unions
+- Enforce naming rules
+- Extract large functions into helpers
+- Prevent domain types from leaking in

package/docs/standards/05-security-standard.md

@@ -0,0 +1,30 @@
+# Security Standard
+
+## Threat Model
+- Multi-tenant SaaS
+- Untrusted browser environment
+- Supabase backend
+- Risks: RLS gaps, injection, unsafe logging, leaking PII
+
+## Security Rules
+- Never bypass RLS
+- Validate all inputs
+- Sanitize logs
+- Never store secrets in code
+- Use safe error messaging
+
+## Logging Rules
+Allowed:
+- IDs
+- Non-PII metadata
+
+Forbidden:
+- Passwords
+- Tokens
+- Sensitive data
+
+## Cursor Checklist
+- Confirm RLS is enforced
+- Ensure no sensitive logs
+- Replace raw errors with ApiError
+- Validate input shapes

package/docs/standards/06-testing-and-docs-standard.md

@@ -0,0 +1,29 @@
+# Testing & Documentation Standard
+
+## Testing Strategy
+- Unit tests for utils & hooks
+- Integration tests for components
+- Few meaningful E2E tests (in consuming apps)
+- Coverage: ≥90% utils, ≥70% components
+
+## Test Structure
+- Colocated tests (*.test.ts/tsx)
+- Use RTL + userEvent
+- Avoid unnecessary mocks
+
+## Documentation Requirements
+- Component READMEs
+- API docs
+- Standards directory
+
+## Required Sections
+- Overview
+- API/Props
+- Examples
+- A11y notes
+- Edge cases
+
+## Cursor Checklist
+- Update docs after API changes
+- Ensure tests cover critical paths
+- Use RTL patterns only