@jmruthers/pace-core 0.5.67 → 0.5.69

package/docs/{INDEX.md → documentation-index.md}

@@ -1,20 +1,23 @@
 # PACE Core Documentation Index
 
-> **📚 Complete Documentation Reference** | [Quick Start](./getting-started/quick-start.md) | [API Reference](./api-reference/components.md) | [Troubleshooting](./troubleshooting/README.md)
+> **📚 Complete Documentation Reference** | [Quick Start](./getting-started/quick-start.md) | [API Reference](./api-reference/components.md) | [Troubleshooting](./troubleshooting/README.md) | [← Back to Docs](./README.md)
 
 Complete index of all PACE Core documentation organized by topic and use case.
 
+---
+
+**Last Updated:** 2025-01-XX | **Version:** v0.5.65+
+
 ## 🚀 Getting Started
 
 ### First Time Users
-- **[Installation](./getting-started/installation.md)** - Package installation and basic setup
+- **[Installation](./getting-started/installation-guide.md)** - Package installation and basic setup (START HERE)
 - **[Quick Start](./getting-started/quick-start.md)** - Build your first app in 10 minutes
 - **[Examples](./getting-started/examples/README.md)** - Complete working examples
+- **[FAQ](./faq.md)** - Common questions and quick answers
 
 ### Configuration
 - **[Vite Configuration](./consuming-app-vite-config.md)** - **CRITICAL** Tailwind v4 setup
-- **[Environment Setup](./getting-started/environment-setup.md)** - Environment variables
-- **[Build Configuration](./getting-started/build-configuration.md)** - Build tool setup
 
 ## 🏗️ Core Features
 
@@ -28,8 +31,8 @@ Complete index of all PACE Core documentation organized by topic and use case.
 - **[Data Tables](./implementation-guides/data-tables.md)** - Interactive data management
 - **[Forms](./implementation-guides/forms.md)** - Form handling and validation
 - **[File Upload & Storage](./implementation-guides/file-upload-storage.md)** - **NEW** Complete file management system
-- **[Event Management](./core-concepts/event-management.md)** - Event selection and context
-- **[Organisation Management](./core-concepts/organisation-management.md)** - Multi-tenant support
+- **[Events](./core-concepts/events.md)** - Event management
+- **[Organisations](./core-concepts/organisations.md)** - Multi-tenant support
 - **[Public Pages](./implementation-guides/public-pages.md)** - Public pages without authentication
 - **[Public Pages Advanced](./implementation-guides/public-pages-advanced.md)** - **NEW** Advanced public page patterns
 
@@ -42,14 +45,11 @@ Complete index of all PACE Core documentation organized by topic and use case.
 
 ### Design System
 - **[Styling Overview](./styles/README.md)** - Complete design system
-- **[Color Palettes](./styles/color-palettes.md)** - Main, secondary, accent colors
-- **[Typography](./styles/typography.md)** - Font families and text styles
-- **[Component Styling](./styles/component-styling.md)** - How components are styled
 
-### Customization
-- **[Custom Themes](./styles/custom-themes.md)** - Creating custom themes
-- **[Dynamic Theming](./styles/dynamic-theming.md)** - Runtime theme switching
-- **[CSS Architecture](./styles/css-architecture.md)** - Single-file CSS approach
+## 🚨 Important Notices
+
+### Breaking Changes
+- **[Breaking Changes](./breaking-changes.md)** - All breaking changes (CRITICAL - read before upgrading)
 
 ## 🔧 API Reference
 
@@ -82,12 +82,9 @@ Complete index of all PACE Core documentation organized by topic and use case.
 - **[Troubleshooting Overview](./troubleshooting/README.md)** - Complete guide
 - **[Common Issues](./troubleshooting/common-issues.md)** - Frequent problems
 - **[Styling Issues](./troubleshooting/styling-issues.md)** - Component styling
-- **[Authentication Issues](./troubleshooting/authentication-issues.md)** - Auth problems
 
 ### Debugging
 - **[Debugging Guide](./troubleshooting/debugging.md)** - Debug techniques
-- **[Performance Issues](./troubleshooting/performance-issues.md)** - Performance problems
-- **[Build Issues](./troubleshooting/build-issues.md)** - Build and deployment
 
 ## 🔄 Migration & Updates
 
@@ -99,68 +96,58 @@ Complete index of all PACE Core documentation organized by topic and use case.
 - **[v0.4.15 Tailwind Scanning](./migration/v0.4.15-tailwind-scanning.md)** - Legacy approach
 
 ### Breaking Changes
-- **[v0.x to v1.x](./migration/v0-to-v1.md)** - Major version upgrade
 - **[RBAC Migration](./migration/rbac-migration.md)** - RBAC system updates
-- **[Component Updates](./migration/component-updates.md)** - Component API changes
 
 ## 📖 Core Concepts
 
 ### Understanding PACE Core
 - **[Architecture](./architecture/README.md)** - System architecture
-- **[Design Principles](./core-concepts/design-principles.md)** - Core design philosophy
-- **[Security Model](./core-concepts/security-model.md)** - Security architecture
-- **[Performance Model](./core-concepts/performance-model.md)** - Performance considerations
 
 ### Key Concepts
+- **[Authentication](./core-concepts/authentication.md)** - User management and sessions
 - **[Permissions](./core-concepts/permissions.md)** - Permission system
 - **[Events](./core-concepts/events.md)** - Event management
 - **[Organisations](./core-concepts/organisations.md)** - Multi-tenancy
-- **[Context Management](./core-concepts/context-management.md)** - React context usage
 
 ## 🛠️ Implementation Guides
 
 ### Application Structure
 - **[App Layout](./implementation-guides/app-layout.md)** - Layout patterns
 - **[Navigation](./implementation-guides/navigation.md)** - Navigation systems
-- **[Routing](./implementation-guides/routing.md)** - URL routing
-- **[State Management](./implementation-guides/state-management.md)** - Application state
 
 ### Data & Forms
 - **[Data Tables](./implementation-guides/data-tables.md)** - Data management
 - **[Forms](./implementation-guides/forms.md)** - Form implementation
-- **[Validation](./implementation-guides/validation.md)** - Input validation
-- **[File Upload](./implementation-guides/file-upload.md)** - File handling
+- **[File Upload & Storage](./implementation-guides/file-upload-storage.md)** - File handling
 
 ### Advanced Features
 - **[Permission Enforcement](./implementation-guides/permission-enforcement.md)** - Security implementation
 - **[Inactivity Tracking](./implementation-guides/inactivity-tracking.md)** - **NEW** User session management
 - **[Organisation Security](./implementation-guides/organisation-security.md)** - **NEW** Advanced security patterns
-- **[Event Management](./implementation-guides/event-management.md)** - Event handling
-- **[Organisation Management](./implementation-guides/organisation-management.md)** - Multi-tenancy
+- **[Public Pages](./implementation-guides/public-pages.md)** - Public pages without authentication
+- **[Public Pages Advanced](./implementation-guides/public-pages-advanced.md)** - **NEW** Advanced public page patterns
 
 ## 🎨 Styling Guides
 
 ### Design System
-- **[Design Tokens](./styles/design-tokens.md)** - Design system tokens
-- **[Color System](./styles/color-system.md)** - Color management
-- **[Typography](./styles/typography.md)** - Text styling
-- **[Spacing](./styles/spacing.md)** - Layout spacing
+- **[Styling Overview](./styles/README.md)** - Complete design system
+
+## 🎯 Common Patterns
 
-### Customization
-- **[Theme Customization](./styles/theme-customization.md)** - Custom themes
-- **[Component Customization](./styles/component-customization.md)** - Styling components
-- **[CSS Architecture](./styles/css-architecture.md)** - CSS organization
-- **[Responsive Design](./styles/responsive-design.md)** - Mobile-first approach
+- **[Common Patterns](./common-patterns.md)** - Reusable code patterns and best practices
 
 ## 🔍 Search by Use Case
 
 ### I want to...
 - **Build a new app** → [Quick Start](./getting-started/quick-start.md)
+- **See code patterns** → [Common Patterns](./common-patterns.md)
 - **Add authentication** → [Authentication Guide](./core-concepts/authentication.md)
 - **Implement permissions** → [RBAC System](./rbac/README.md)
 - **Create data tables** → [Data Tables Guide](./implementation-guides/data-tables.md)
 - **Style my app** → [Styling Overview](./styles/README.md)
 - **Fix styling issues** → [Troubleshooting - Styling](./troubleshooting/styling-issues.md)
+- **Find quick answers** → [FAQ](./faq.md)
+- **Check breaking changes** → [Breaking Changes](./breaking-changes.md)
 - **Optimize performance** → [Performance Best Practices](./best-practices/performance.md)
 - **Deploy to production** → [Deployment Guide](./best-practices/deployment.md)
 - **Migrate from v0.x** → [Migration Guide](./migration/README.md)
@@ -173,6 +160,7 @@ Complete index of all PACE Core documentation organized by topic and use case.
 - **Best practices** → [Best Practices](./best-practices/README.md)
 - **Security guidelines** → [Security Best Practices](./best-practices/security.md)
 - **Performance tips** → [Performance Best Practices](./best-practices/performance.md)
+- **Deployment guide** → [Deployment Best Practices](./best-practices/deployment.md)
 - **Testing strategies** → [Testing Best Practices](./best-practices/testing.md)
 
 ## 📚 Additional Resources
@@ -187,7 +175,7 @@ Complete index of all PACE Core documentation organized by topic and use case.
 - **[GitHub Repository](https://github.com/jmruthers/pace-core)** - Source code
 - **[Issue Tracker](https://github.com/jmruthers/pace-core/issues)** - Bug reports
 - **[Discussions](https://github.com/jmruthers/pace-core/discussions)** - Community help
-- **[Changelog](./CHANGELOG.md)** - Version history
+- **[Migration Guides](./migration/MIGRATION_GUIDE.md)** - Version history and migration info
 
 ---
 

package/docs/faq.md

@@ -0,0 +1,286 @@
+# PACE Core FAQ
+
+> **📚 Frequently Asked Questions** | [← Back to Documentation](./README.md)
+
+Common questions and quick answers about PACE Core.
+
+## Installation & Setup
+
+### How do I install PACE Core?
+
+See the [Installation Guide](./getting-started/installation-guide.md) for complete step-by-step instructions.
+
+**Quick answer:**
+```bash
+npm install @jmruthers/pace-core
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+# Then import CSS in your app
+import '@jmruthers/pace-core/src/styles/core.css';
+```
+
+### Why aren't my components styled?
+
+This is the most common issue. Ensure you have:
+
+1. **Proper Vite configuration** - Include pace-core source files:
+   ```typescript
+   content: [
+     './src/**/*.{js,ts,jsx,tsx}',
+     './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+   ]
+   ```
+
+2. **CSS imported** in your entry point:
+   ```tsx
+   import '@jmruthers/pace-core/src/styles/core.css';
+   ```
+
+3. **Using Tailwind v4** (not v3)
+
+See [Styling Issues](./troubleshooting/styling-issues.md) for detailed help.
+
+### What version of Tailwind do I need?
+
+You need **Tailwind CSS v4** with the Vite plugin. Tailwind v3 will not work.
+
+```bash
+# Correct version
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+
+# Remove v3 if installed
+npm uninstall tailwindcss@^3.0.0
+```
+
+See [Installation Guide](./getting-started/installation-guide.md) for details.
+
+### Do I need a tailwind.config.js file?
+
+**No.** With the CSS-first approach in v0.4.17+, you don't need a config file. The configuration is handled via CSS imports and Vite plugin.
+
+## Authentication & RBAC
+
+### How do I set up authentication?
+
+Wrap your app with `UnifiedAuthProvider`:
+
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}
+  warnBeforeMs={5 * 60 * 1000}
+  onIdleLogout={() => window.location.href = '/login'}
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+See [Authentication Guide](./core-concepts/authentication.md) for details.
+
+### How do I use RBAC permissions?
+
+Use the `useCan` hook or `PagePermissionGuard` component:
+
+```tsx
+import { useCan } from '@jmruthers/pace-core';
+
+const { hasPermission } = useCan();
+
+if (hasPermission('update:users', { organisationId })) {
+  // Show edit button
+}
+```
+
+See [RBAC Guide](./rbac/README.md) for details.
+
+### What's the permission format?
+
+Permissions use colon-separated format: `{operation}:{resource}`
+
+Examples:
+- `read:users`
+- `update:events`  
+- `delete:organisations`
+
+See [Permissions Guide](./core-concepts/permissions.md) for details.
+
+### Why is my permission check always returning false?
+
+Common causes:
+
+1. **Missing organisation context** - Always include `organisationId` in scope
+2. **User not authenticated** - Check authentication status
+3. **Permission format incorrect** - Use colon format, not space
+
+See [Permission Troubleshooting](./troubleshooting/organisation-context-setup.md) for help.
+
+## Breaking Changes
+
+### What changed in v0.5.65?
+
+Mandatory inactivity timeouts in `UnifiedAuthProvider`. You must now provide:
+- `idleTimeoutMs` - When to logout
+- `warnBeforeMs` - When to warn user
+- `onIdleLogout` - Callback on logout
+
+See [Breaking Changes](./breaking-changes.md) for details.
+
+### How do I migrate from v0.4.x to v0.5.65?
+
+Add the required inactivity timeout props:
+
+```tsx
+// Old (broken)
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+
+// New (required)
+<UnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}
+  warnBeforeMs={5 * 60 * 1000}
+  onIdleLogout={() => window.location.href = '/login'}
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+See [Migration Guide](./migration-guides/unified-auth-provider-mandatory-timeouts.md).
+
+## Troubleshooting
+
+### My components look unstyled
+
+**Quick Checklist:**
+- [ ] CSS file imported: `import '@jmruthers/pace-core/src/styles/core.css'`
+- [ ] Vite config includes pace-core source files
+- [ ] Using Tailwind v4
+- [ ] Dev server restarted after config changes
+
+See [Styling Issues](./troubleshooting/styling-issues.md) for detailed help.
+
+### I'm getting TypeScript errors
+
+**Common causes:**
+
+1. **Missing props** - Check breaking changes for new required props
+2. **Wrong imports** - Use `@jmruthers/pace-core` (with @)
+3. **Version mismatch** - Update peer dependencies
+
+See [Common Issues](./troubleshooting/common-issues.md) for help.
+
+### Permission checks aren't working
+
+**Check these:**
+1. User is authenticated
+2. Organisation context is set
+3. Permission format is correct (`operation:resource`)
+4. User has the permission in database
+
+See [RBAC Troubleshooting](./rbac/troubleshooting.md) for help.
+
+## Best Practices
+
+### What are the coding standards?
+
+Follow the [Style Guide](./style-guide.md) for:
+- Code example standards
+- Terminology usage
+- Documentation structure
+- Import patterns
+
+### Should I use the service architecture?
+
+The service architecture is optional. Existing code using `UnifiedAuthProvider` continues to work. New projects may benefit from the cleaner architecture.
+
+See [Service Architecture](./architecture/services.md) for details.
+
+## Common Patterns
+
+### How do I fetch data with permissions?
+
+```tsx
+import { useCan } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { hasPermission, isLoading } = useCan();
+  const [data, setData] = useState([]);
+
+  useEffect(() => {
+    if (hasPermission('read:data', { organisationId })) {
+      fetchData().then(setData);
+    }
+  }, [hasPermission, organisationId]);
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return <DataTable data={data} />;
+}
+```
+
+### How do I handle file uploads?
+
+Use the FileUpload component and hooks:
+
+```tsx
+import { FileUpload, useFileReference } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { uploadFile } = useFileReference(supabase);
+
+  const handleUpload = async (file: File) => {
+    await uploadFile(file, { 
+      organisationId: currentOrg.id 
+    });
+  };
+
+  return <FileUpload onUpload={handleUpload} />;
+}
+```
+
+See [File Upload Guide](./implementation-guides/file-upload-storage.md).
+
+### How do I create a public page?
+
+Use Public page components:
+
+```tsx
+import { PublicPageLayout, usePublicEvent } from '@jmruthers/pace-core';
+
+function PublicPage({ eventSlug }) {
+  const { event, loading } = usePublicEvent(eventSlug);
+
+  if (loading) return <PublicLoadingSpinner />;
+
+  return (
+    <PublicPageLayout event={event}>
+      {/* Public content */}
+    </PublicPageLayout>
+  );
+}
+```
+
+See [Public Pages Guide](./implementation-guides/public-pages.md).
+
+## Performance
+
+### How do I optimize performance?
+
+1. Use permission caching (automatic)
+2. Implement code splitting
+3. Use React.memo for expensive components
+4. Optimize data table rendering
+
+See [Performance Guide](./best-practices/performance.md).
+
+## Still Have Questions?
+
+- Check [Troubleshooting](./troubleshooting/README.md)
+- See [Common Issues](./troubleshooting/common-issues.md)
+- Review [Examples](./getting-started/examples/)
+- [Ask for Help](https://github.com/jmruthers/pace-core/issues)
+

package/docs/{FILE_REFERENCE_SYSTEM.md → file-reference-system.md}

@@ -33,7 +33,7 @@ CREATE TABLE file_references (
 
 ### Storage Structure
 
-**Organization-First Structure:**
+**Organisation-First Structure:**
 ```
 {bucket}/{orgId}/{category}/{filename}