@jmruthers/pace-core 0.6.1 → 0.6.2

package/docs/architecture/database-schema-requirements.md

@@ -123,6 +123,167 @@ The RBAC system uses a **single source of truth** approach:
 - All functions use `rbac_organisation_roles` table for role management
 - Views inherit RLS policies from the underlying `rbac_organisation_roles` table
 
+## App Access Tables Architecture
+
+The system uses three complementary tables to manage app availability and user permissions:
+
+### Table Relationship Overview
+
+| Table | Purpose | Question It Answers |
+|-------|---------|-------------------|
+| `core_organisation_app_access` | Organisation-level app configuration | "Is this app available for this organisation?" |
+| `core_event_app_access` | Event-level app availability | "Is this app available for this event?" |
+| `rbac_event_app_roles` | User-specific role grants | "Who can do what for this event-app?" |
+
+### 1. `core_organisation_app_access`
+
+**Purpose:** Organisation-level app configuration and feature flags.
+
+**Schema:**
+```sql
+CREATE TABLE core_organisation_app_access (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id) ON DELETE CASCADE,
+    app_id UUID NOT NULL REFERENCES rbac_apps(id),
+    is_enabled BOOLEAN DEFAULT true,
+    settings JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    created_by UUID REFERENCES auth.users(id),
+    updated_by UUID REFERENCES auth.users(id)
+);
+```
+
+**Use Cases:**
+- Enable/disable apps at the organisation level
+- Store organisation-specific app settings (e.g., feature flags, configuration)
+- Control which apps are available to an organisation
+
+**Key Characteristics:**
+- Organisation-scoped (one record per organisation-app combination)
+- Contains `is_enabled` flag for feature toggling
+- Contains `settings` JSONB field for app-specific configuration
+
+### 2. `core_event_app_access`
+
+**Purpose:** Event-level app availability flag.
+
+**Schema:**
+```sql
+CREATE TABLE core_event_app_access (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    event_id VARCHAR NOT NULL REFERENCES core_events(event_id),
+    app_id UUID NOT NULL REFERENCES rbac_apps(id) ON DELETE CASCADE,
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id),
+    created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+    updated_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+    created_by UUID REFERENCES auth.users(id),
+    updated_by UUID REFERENCES auth.users(id),
+    CONSTRAINT core_event_app_access_unique UNIQUE (event_id, app_id, organisation_id)
+);
+```
+
+**Use Cases:**
+- Enable an app for a specific event
+- Track which apps are available for each event
+- Quick check: "Is this app enabled for this event?"
+
+**Key Characteristics:**
+- Event-scoped (one record per event-app-organisation combination)
+- Unique constraint prevents duplicate entries
+- Simple boolean flag (existence = enabled)
+
+### 3. `rbac_event_app_roles`
+
+**Purpose:** User-specific role grants for event-app combinations.
+
+**Schema:**
+```sql
+CREATE TABLE rbac_event_app_roles (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    event_id VARCHAR NOT NULL REFERENCES core_events(event_id) ON DELETE CASCADE,
+    app_id UUID NOT NULL REFERENCES rbac_apps(id),
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id),
+    role rbac_event_app_role NOT NULL, -- ENUM: 'viewer', 'participant', 'planner', 'event_admin'
+    status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'inactive', 'suspended')),
+    granted_at TIMESTAMPTZ DEFAULT NOW(),
+    granted_by UUID REFERENCES auth.users(id),
+    valid_from TIMESTAMPTZ DEFAULT NOW(),
+    valid_to TIMESTAMPTZ,
+    CONSTRAINT rbac_event_app_roles_unique UNIQUE (user_id, event_id, app_id, role)
+);
+```
+
+**Use Cases:**
+- Grant specific roles to users for event-app combinations
+- Control what users can do (viewer, participant, planner, event_admin)
+- Time-based role validity (valid_from, valid_to)
+- Role status management (active, inactive, suspended)
+
+**Key Characteristics:**
+- User-scoped (one record per user-event-app-role combination)
+- Includes role hierarchy and permissions
+- Time-based validity support
+- Status tracking for role lifecycle
+
+### Relationship Summary
+
+**Access Tables = "Is this app available?"**
+- `core_organisation_app_access`: Organisation-level availability and settings
+- `core_event_app_access`: Event-level availability flag
+
+**Roles Table = "Who can do what?"**
+- `rbac_event_app_roles`: User-specific role grants with permissions
+
+### Important Notes
+
+1. **Separation of Concerns:**
+   - Access tables handle **configuration** (feature flags, availability)
+   - Roles table handles **authorization** (user permissions)
+
+2. **Independence:**
+   - Access records can exist without roles (app enabled, no users yet)
+   - Roles can exist without access records (legacy data or data inconsistency)
+   - These are intentionally independent to allow flexible configuration
+
+3. **Performance:**
+   - Access tables provide fast feature flag checks without querying user roles
+   - Roles table provides detailed permission information when needed
+
+4. **Data Integrity:**
+   - `core_event_app_access` has unique constraint on `(event_id, app_id, organisation_id)`
+   - `rbac_event_app_roles` has unique constraint on `(user_id, event_id, app_id, role)`
+
+### Example Usage Patterns
+
+```sql
+-- Check if app is available for an event (configuration check)
+SELECT EXISTS (
+    SELECT 1 FROM core_event_app_access
+    WHERE event_id = 'event-123'
+    AND app_id = 'app-456'
+    AND organisation_id = 'org-789'
+);
+
+-- Check if user has access to an event-app (authorization check)
+SELECT EXISTS (
+    SELECT 1 FROM rbac_event_app_roles
+    WHERE user_id = 'user-abc'
+    AND event_id = 'event-123'
+    AND app_id = 'app-456'
+    AND status = 'active'
+    AND valid_from <= NOW()
+    AND (valid_to IS NULL OR valid_to > NOW())
+);
+
+-- Get organisation-level app settings
+SELECT settings FROM core_organisation_app_access
+WHERE organisation_id = 'org-789'
+AND app_id = 'app-456'
+AND is_enabled = true;
+```
+
 ## Required RPC Functions
 
 The following RPC functions are required and should be updated to use the correct tables/views:

package/docs/core-concepts/rbac-system.md

@@ -10,7 +10,7 @@ reviewedBy: documentation-standards-audit
 
 PACE Core provides a comprehensive Role-Based Access Control (RBAC) system that manages user permissions through roles, ensuring secure and scalable access control across your application.
 
-> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/rbac-migration.md) for step-by-step instructions.
+> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/V0.4.0_rbac-migration.md) for step-by-step instructions.
 
 > **⚠️ IMPORTANT**: You **must** call `setupRBAC()` before using any RBAC features. See the [Quick Start Guide](../rbac/quick-start.md) for setup instructions.
 
@@ -278,7 +278,7 @@ If you're upgrading from a system with hardcoded permissions:
 3. **Replace 'manage' Operations** - Use specific CRUD operations instead
 4. **Enable Cache Invalidation** - Ensure realtime subscriptions are active
 
-For detailed migration instructions, see the **[RBAC Migration Guide](../migration/rbac-migration.md)**.
+For detailed migration instructions, see the **[RBAC Migration Guide](../migration/V0.4.0_rbac-migration.md)**.
 
 ## What's Next?
 
@@ -286,7 +286,7 @@ For detailed migration instructions, see the **[RBAC Migration Guide](../migrati
 - **[RBAC Quick Start](../rbac/quick-start.md)** - Build your first RBAC-enabled app
 - **[RBAC API Reference](../rbac/api-reference.md)** - Complete API documentation
 - **[RBAC Examples](../rbac/examples.md)** - Practical usage examples
-- **[Migration Guide](../migration/rbac-migration.md)** - Migrate from legacy RBAC
+- **[Migration Guide](../migration/V0.4.0_rbac-migration.md)** - Migrate from legacy RBAC
 - **[Installation](../getting-started/installation-guide.md)** - Get PACE Core set up
 - **[Authentication](./authentication.md)** - Understand authentication system
 - **[Organisations](./organisations.md)** - Learn about multi-tenancy

package/docs/documentation-index.md

@@ -96,10 +96,8 @@ This index mirrors the folder layout in `packages/core/docs/` so teams can quick
 
 - [Migration overview](./migration/README.md)
 - [Unified migration guide](./migration/MIGRATION_GUIDE.md)
-- [Quick migration guide](./migration/quick-migration-guide.md)
-- [Organisation context timing fix](./migration/organisation-context-timing-fix.md)
-- [Service architecture changes](./migration/service-architecture.md)
-- [RBAC migration](./migration/rbac-migration.md)
+- [Organisation context timing fix](./migration/V0.3.44_organisation-context-timing-fix.md)
+- [RBAC migration](./migration/V0.4.0_rbac-migration.md)
 - [Tailwind scanning updates](./migration/v0.4.15-tailwind-scanning.md)
 - [CSS-first migration (v0.4.16)](./migration/v0.4.16-css-first-approach.md)
 - [Source path fix (v0.4.17)](./migration/v0.4.17-source-path-fix.md)

package/docs/getting-started/cursor-rules.md

@@ -42,7 +42,7 @@ npm run setup:cursor-rules
 
 The script will:
 - Create `.cursor/rules/` directory if it doesn't exist
-- Copy all pace-core rules (00-07) to your project
+- Copy all pace-core rules (00-08) to your project
 - **Automatically update** pace-core rules (00-09) if they've changed
 - Preserve any existing custom rules (50+)
 - Skip files that are already up to date
@@ -67,6 +67,7 @@ The installed rules are numbered for ordering:
 - **05-bug-reports-and-features.mdc** - Templates for bug reports (guidance-only)
 - **06-code-quality.mdc** - Enforce code quality standards
 - **07-tech-stack-compliance.mdc** - Enforce tech stack versions and patterns
+- **08-markup-quality.mdc** - Enforce clean markup standards, semantic HTML usage, and pace-core component patterns
 
 ## Using Rules with Cursor
 

package/docs/migration/DOCUMENTATION_STRUCTURE.md

@@ -0,0 +1,441 @@
+# Documentation Structure Guidelines
+
+**Purpose:** Define clear structure and responsibilities for CHANGELOG.md and migration documentation to prevent overlap and maintain single source of truth.
+
+## Documentation Hierarchy
+
+```
+CHANGELOG.md (High-level announcements, links to detailed guides)
+├── docs/migration/README.md (Index/navigation)
+├── docs/migration/MIGRATION_GUIDE.md (General migration patterns)
+├── docs/migration/V0.X_TO_V0.Y_MIGRATION.md (Version-specific migrations)
+├── docs/migration/V0.6.0_REACT_19_MIGRATION.md (Feature-specific migrations)
+├── docs/migration/database-changes-december-2025.md (Database-specific)
+└── docs/migration/V0.5.190_person-scoped-profiles-migration-guide.md (Feature-specific)
+```
+
+## CHANGELOG.md Responsibilities
+
+### ✅ What CHANGELOG.md SHOULD Include
+
+1. **High-Level Announcements**
+   - Breaking changes summary
+   - New features summary
+   - Deprecations summary
+   - Bug fixes summary
+
+2. **Brief Summaries**
+   - One-line descriptions of changes
+   - Key impact statements
+   - Version numbers and dates
+
+3. **Links to Detailed Guides**
+   - Links to migration guides for breaking changes
+   - Links to feature documentation
+   - Links to troubleshooting guides
+
+4. **Quick Migration Notes**
+   - Brief "what changed" statements
+   - Links to detailed migration guides
+   - Critical warnings (e.g., "⚠️ CRITICAL: Database migrations required")
+
+### ❌ What CHANGELOG.md SHOULD NOT Include
+
+1. **Detailed Migration Steps**
+   - Step-by-step instructions
+   - Code examples (unless very brief)
+   - Configuration file examples
+   - Troubleshooting details
+
+2. **Duplicate Content**
+   - Content that exists in migration guides
+   - Detailed explanations already in docs
+   - Long code blocks
+
+3. **Version-Specific Details**
+   - Detailed version upgrade paths
+   - Specific migration commands
+   - Database migration file names (unless critical)
+
+## Migration Documentation Responsibilities
+
+### ✅ What Migration Docs SHOULD Include
+
+1. **Step-by-Step Instructions**
+   - Detailed migration steps
+   - Code examples (before/after)
+   - Configuration changes
+   - Command-line instructions
+
+2. **Code Examples**
+   - Before/after code comparisons
+   - Complete working examples
+   - Common patterns and anti-patterns
+
+3. **Troubleshooting**
+   - Common issues and solutions
+   - Error messages and fixes
+   - Edge cases
+
+4. **Complete Context**
+   - Why changes were made
+   - Impact analysis
+   - Migration timeline
+   - Testing checklists
+
+### ❌ What Migration Docs SHOULD NOT Include
+
+1. **High-Level Summaries**
+   - Brief announcements (that's CHANGELOG's job)
+   - Marketing-style descriptions
+   - Non-actionable information
+
+2. **Duplicate Content**
+   - Content duplicated from other migration guides
+   - Content that should be in CHANGELOG
+
+## Content Strategy by Type
+
+### Breaking Changes
+
+**CHANGELOG.md:**
+```markdown
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+- **BREAKING**: Database schema changes (table naming standardization)
+
+### Migration Notes
+- **React 19 Upgrade**: See [React 19 Migration Guide](./docs/migration/V0.6.0_REACT_19_MIGRATION.md)
+- **Database Changes**: See [v0.5.190 → v0.6.1 Migration Guide](./docs/migration/V0.5.190_TO_V0.6.1_MIGRATION.md)
+```
+
+**Migration Doc:**
+```markdown
+# React 19 Migration Guide
+
+## Step 1: Update Dependencies
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+```
+
+## Step 2: Update Vite Configuration
+
+```typescript
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+})
+```
+
+[... detailed steps ...]
+```
+
+### New Features
+
+**CHANGELOG.md:**
+```markdown
+### Added
+- **useFormDialog Hook**: Generic React hook for managing form dialog state
+- **DateTimeField Component**: Form input component for datetime values with automatic UTC ↔ timezone conversion
+```
+
+**Migration Doc (if needed):**
+```markdown
+# Using New Features
+
+## useFormDialog Hook
+
+```tsx
+import { useFormDialog } from '@jmruthers/pace-core';
+
+const formDialog = useFormDialog<FormData>({
+  defaultValues: { name: '', email: '' }
+});
+```
+
+[... usage examples ...]
+```
+
+### Minor Version Changes
+
+**CHANGELOG.md:**
+```markdown
+## [0.5.109] - 2025-11-03
+
+### Changed
+- **Session Tracking Hook API**: Removed `trackLogin()` and `trackLogout()` methods
+
+### Migration Guide
+
+### Upgrading from 0.5.108 to 0.5.109
+
+**Breaking Change**: The `useSessionTracking` hook no longer provides `trackLogin()` and `trackLogout()` methods.
+
+**Migration Steps:**
+1. Remove manual tracking calls
+2. Keep event switch tracking
+3. Apply database migrations
+
+[... brief migration guide ...]
+```
+
+**Note:** For minor versions, it's acceptable to include brief migration guides directly in CHANGELOG if they're simple. For complex migrations, create a dedicated migration guide.
+
+## File Naming Conventions
+
+### Migration Guides
+
+All migration guides should include version or date stamps in their filenames for clarity:
+
+- **Version-specific**: `V0.X_TO_V0.Y_MIGRATION.md`
+  - Example: `V0.5.190_TO_V0.6.1_MIGRATION.md`
+  - ✅ Already includes version numbers
+
+- **Feature-specific**: `V{VERSION}_{FEATURE}-migration.md` or `V{VERSION}_{FEATURE}-migration-guide.md`
+  - Example: `V0.6.0_REACT_19_MIGRATION.md` (introduced in v0.6.0)
+  - Example: `V0.5.190_person-scoped-profiles-migration-guide.md` (introduced in v0.5.190)
+  - **Rationale**: Version at start ensures chronological sorting and makes it clear which version introduced the feature
+
+- **Database-specific**: `database-changes-{DATE}.md` or `database-changes-{DATE}-V{VERSION}.md`
+  - Example: `database-changes-december-2025.md` (date-based, already in use)
+  - Example: `database-changes-december-2025-V0.5.190.md` (if version context needed)
+  - **Rationale**: Dates are clear for database changes, but version can help if needed
+
+- **General/Topic-specific**: `V{VERSION}_{TOPIC}-migration.md` or `{DATE}_{TOPIC}-migration.md`
+  - Example: `V0.4.0_rbac-migration.md` (if version-specific)
+  - Example: `V0.3.44_organisation-context-timing-fix.md` (if version-specific)
+  - **Rationale**: Version at start ensures chronological sorting. Use version if tied to specific release, date if it's a fix/change
+
+### Naming Rules
+
+1. **Always include version or date** - Makes it clear when/what the migration relates to
+2. **Version at the start** - Put version number at the beginning of filename for chronological sorting
+3. **Use version for feature migrations** - Tied to specific release
+4. **Use date for database changes** - Clear chronological reference
+5. **Use version for fixes** - Tied to specific release
+6. **Be consistent** - Follow the pattern once established
+
+### Documentation Files (No Version Needed)
+
+These are general documentation files that don't need version stamps:
+
+- **Index**: `README.md`
+- **General Guide**: `MIGRATION_GUIDE.md` (includes quick reference table)
+- **Structure Guidelines**: `DOCUMENTATION_STRUCTURE.md`
+
+### Migration Guides (Version Required)
+
+**All migration guides must include version or date stamps:**
+
+- ✅ `V0.6.0_REACT_19_MIGRATION.md` - Feature migration with version at start
+- ✅ `V0.5.190_person-scoped-profiles-migration-guide.md` - Feature migration with version at start
+- ✅ `V0.3.44_organisation-context-timing-fix.md` - Fix migration with version at start
+- ✅ `V0.5.190_TO_V0.6.1_MIGRATION.md` - Version-specific migration
+- ✅ `database-changes-december-2025.md` - Database changes with date
+- ✅ `V0.4.0_rbac-migration.md` - RBAC migration (introduced in v0.4.0)
+- ✅ Service architecture documentation is in `/docs/architecture/services.md` (not a migration guide)
+
+## Link Strategy
+
+### From CHANGELOG to Migration Docs
+
+Always use relative paths:
+```markdown
+- See [React 19 Migration Guide](./docs/migration/REACT_19_MIGRATION_V0.6.0.md)
+```
+
+### Between Migration Docs
+
+Use relative paths:
+```markdown
+- See [Database Changes December 2025](./database-changes-december-2025.md)
+- See [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md)
+```
+
+### From Migration Docs to CHANGELOG
+
+Use relative paths:
+```markdown
+- See [CHANGELOG.md](../../CHANGELOG.md) for version history
+```
+
+## Version-Specific Migration Guides
+
+### When to Create a Version-Specific Guide
+
+Create a dedicated migration guide when:
+- ✅ Major version upgrade (e.g., 0.5.x → 0.6.x)
+- ✅ Multiple breaking changes in one version
+- ✅ Complex migration requiring multiple steps
+- ✅ Database migrations required
+- ✅ Significant API changes
+
+### When to Keep in CHANGELOG
+
+Keep migration guide in CHANGELOG when:
+- ✅ Minor version upgrade with simple changes
+- ✅ Single breaking change that's straightforward
+- ✅ No database migrations required
+- ✅ Simple code updates only
+
+## Review Checklist
+
+Before adding content to CHANGELOG or migration docs:
+
+### CHANGELOG Review
+
+- [ ] Is this a high-level announcement?
+- [ ] Is this a brief summary (not detailed steps)?
+- [ ] Are detailed migration steps linked to migration docs?
+- [ ] Is there duplicate content in migration docs?
+- [ ] Are all links working and pointing to correct files?
+
+### Migration Doc Review
+
+- [ ] Are step-by-step instructions included?
+- [ ] Are code examples provided?
+- [ ] Is troubleshooting information included?
+- [ ] Are links to related docs included?
+- [ ] Is there duplicate content from CHANGELOG?
+- [ ] Is there duplicate content from other migration docs?
+
+## Maintenance Guidelines
+
+### Regular Reviews
+
+1. **After Each Release**
+   - Review CHANGELOG for duplicate content
+   - Verify all links work
+   - Check migration docs are referenced correctly
+
+2. **Quarterly**
+   - Review all migration docs for outdated content
+   - Consolidate overlapping guides
+   - Update links and references
+
+3. **Before Major Releases**
+   - Plan migration guide structure
+   - Identify potential overlaps
+   - Create clear documentation hierarchy
+
+### Content Updates
+
+1. **When Adding Breaking Changes**
+   - Add brief summary to CHANGELOG
+   - Create or update migration guide
+   - Link from CHANGELOG to migration guide
+
+2. **When Adding New Features**
+   - Add feature announcement to CHANGELOG
+   - Add usage examples to migration guide (if migration needed)
+   - Link from CHANGELOG if detailed guide exists
+
+3. **When Fixing Bugs**
+   - Add fix to CHANGELOG
+   - Add troubleshooting to migration guide (if relevant)
+   - Link if detailed troubleshooting needed
+
+## Examples
+
+### ✅ Good CHANGELOG Entry
+
+```markdown
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+- **BREAKING**: Database schema changes (table naming standardization)
+
+### Migration Notes
+
+**⚠️ CRITICAL**: This version includes major breaking changes.
+
+- **React 19 Upgrade**: See [React 19 Migration Guide](./docs/migration/V0.6.0_REACT_19_MIGRATION.md)
+- **Complete Migration**: See [v0.5.190 → v0.6.1 Migration Guide](./docs/migration/V0.5.190_TO_V0.6.1_MIGRATION.md)
+```
+
+### ❌ Bad CHANGELOG Entry
+
+```markdown
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+
+### Migration Steps
+
+**Step 1: Update Dependencies**
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+npm install -D @types/react@^19.2.7 @types/react-dom@^19.2.3
+```
+
+**Step 2: Update Vite Configuration**
+
+```typescript
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+})
+```
+
+[... many more steps ...]
+```
+
+### ✅ Good Migration Guide Entry
+
+```markdown
+# React 19 Migration Guide
+
+## Step 1: Update Dependencies
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+npm install -D @types/react@^19.2.7 @types/react-dom@^19.2.3
+npm install -D @vitejs/plugin-react@^5.1.2
+npm install -D babel-plugin-react-compiler@latest
+```
+
+## Step 2: Update Vite Configuration
+
+[... detailed instructions ...]
+
+## Troubleshooting
+
+### Issue: TypeScript errors with child.props
+
+[... detailed troubleshooting ...]
+```
+
+### ❌ Bad Migration Guide Entry
+
+```markdown
+# React 19 Migration Guide
+
+React 19 has been released! This is a major upgrade that includes...
+
+[... marketing content, no actionable steps ...]
+```
+
+## Summary
+
+- **CHANGELOG.md**: Announce, summarize, link
+- **Migration Docs**: Instruct, demonstrate, troubleshoot
+- **No Duplication**: Each piece of information lives in one place
+- **Clear Links**: Easy navigation between related content
+- **Regular Review**: Keep structure clean and maintainable
+

package/docs/migration/MIGRATION_GUIDE.md

@@ -160,31 +160,9 @@ This breaking change was made for security reasons:
 - Provides consistent user experience across all apps
 - Improves overall security posture
 
-### v2.0.0 - Service Architecture Changes
+### Service Architecture
 
-**Status**: ⚠️ **BREAKING CHANGE**  
-**Date**: December 2024  
-**Impact**: Medium - Affects apps using service architecture
-
-#### What Changed
-
-The library now uses a service-based architecture with pure TypeScript service classes and React integration through providers and hooks.
-
-#### Key Changes
-
-- ✅ **New Service Layer**: Pure TypeScript classes for business logic
-- ✅ **Provider Layer**: React context integration for services
-- ✅ **Hook Layer**: Reactive hooks for component integration
-- ✅ **Backward Compatible**: `UnifiedAuthProvider` maintained for compatibility
-
-#### Migration
-
-The service architecture is now the default. Existing code continues to work without changes:
-
-```tsx
-// Works out of the box - uses service architecture internally
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-```
+**Note**: Service architecture documentation is available in [Architecture Documentation](../architecture/services.md). The service-based architecture is backward compatible - existing code using `UnifiedAuthProvider` continues to work without changes as it uses the service architecture internally.
 
 ## Version-Specific Migrations