diff --git a/ARCHITECTURE-KNOWLEDGE-BASE.md b/ARCHITECTURE-KNOWLEDGE-BASE.md
new file mode 100644
index 00000000..01e73ec0
--- /dev/null
+++ b/ARCHITECTURE-KNOWLEDGE-BASE.md
@@ -0,0 +1,516 @@
+# Architecture Knowledge Base
+**Last Updated:** December 8, 2025  
+**Purpose:** Critical architectural patterns, common issues, and solutions reference
+
+---
+
+## Table of Contents
+1. [Authentication & Session Management](#authentication--session-management)
+2. [Site/Sector Architecture](#sitesector-architecture)
+3. [State Management & Race Conditions](#state-management--race-conditions)
+4. [Permission System](#permission-system)
+5. [Frontend Component Dependencies](#frontend-component-dependencies)
+6. [Common Pitfalls & Solutions](#common-pitfalls--solutions)
+
+---
+
+## Authentication & Session Management
+
+### Token Persistence Architecture
+
+**Problem Pattern:**
+- Zustand persist middleware writes to localStorage asynchronously
+- API calls can happen before tokens are persisted
+- Results in 403 "Authentication credentials were not provided" errors
+
+**Solution Implemented:**
+```typescript
+// In authStore.ts login/register functions
+// CRITICAL: Immediately persist tokens synchronously after setting state
+const authState = {
+  state: { user, token, refreshToken, isAuthenticated: true },
+  version: 0
+};
+localStorage.setItem('auth-storage', JSON.stringify(authState));
+```
+
+**Key Principle:** Always write tokens to localStorage synchronously in auth actions, don't rely solely on persist middleware.
+
+---
+
+### Logout & State Cleanup
+
+**WRONG APPROACH (causes race conditions):**
+```typescript
+logout: () => {
+  localStorage.clear(); // ❌ BREAKS EVERYTHING
+  set({ user: null, token: null });
+}
+```
+
+**CORRECT APPROACH:**
+```typescript
+logout: () => {
+  // ✅ Selective removal - only auth-related keys
+  const authKeys = ['auth-storage', 'site-storage', 'sector-storage', 'billing-storage'];
+  authKeys.forEach(key => localStorage.removeItem(key));
+  
+  // ✅ Reset dependent stores explicitly
+  useSiteStore.setState({ activeSite: null });
+  useSectorStore.setState({ activeSector: null, sectors: [] });
+  
+  set({ user: null, token: null, isAuthenticated: false });
+}
+```
+
+**Key Principle:** Never use `localStorage.clear()` - it breaks Zustand persist middleware initialization. Always selectively remove keys.
+
+---
+
+### 403 Error Handling
+
+**Problem Pattern:**
+- 403 errors thrown before checking if it's an auth error
+- Token validation code becomes unreachable
+- Invalid tokens persist in localStorage
+
+**WRONG ORDER:**
+```typescript
+// In api.ts
+if (response.status === 403) {
+  throw new Error(response.statusText); // ❌ Thrown immediately
+}
+
+// This code NEVER runs (unreachable):
+if (errorData?.detail?.includes('Authentication credentials')) {
+  logout(); // Never called!
+}
+```
+
+**CORRECT ORDER:**
+```typescript
+// Check for auth errors FIRST, then throw
+if (response.status === 403) {
+  const errorData = JSON.parse(text);
+  
+  // ✅ Check authentication BEFORE throwing
+  if (errorData?.detail?.includes('Authentication credentials')) {
+    const authState = useAuthStore.getState();
+    if (authState?.isAuthenticated) {
+      authState.logout();
+      window.location.href = '/signin';
+    }
+  }
+  
+  // Now throw the error
+  throw new Error(errorMessage);
+}
+```
+
+**Key Principle:** Handle authentication errors before throwing. Order matters in error handling logic.
+
+---
+
+## Site/Sector Architecture
+
+### Data Hierarchy
+```
+Account (Tenant)
+  └── Site (e.g., myblog.com)
+      └── Sector (e.g., Technology, Health)
+          └── Keywords
+              └── Clusters
+                  └── Ideas
+                      └── Content
+```
+
+### Where Sectors Are Used (Global Context)
+
+**USES SECTORS (requires site/sector selection):**
+- ✅ Planner Module (Keywords, Clusters, Ideas)
+- ✅ Writer Module (Tasks, Content, Drafts, Published)
+- ✅ Linker Module (Internal linking)
+- ✅ Optimizer Module (Content optimization)
+- ✅ Setup/Add Keywords page
+- ✅ Seed Keywords reference data
+
+**DOES NOT USE SECTORS (account-level only):**
+- ❌ Billing/Plans pages (`/account/*`)
+- ❌ Account Settings
+- ❌ Team Management
+- ❌ User Profile
+- ❌ Admin Dashboard
+- ❌ System Settings
+
+### Sector Loading Pattern
+
+**Architecture Decision:**
+- Sectors loaded by **PageHeader component** (not AppLayout)
+- Only loads when `hideSiteSector={false}` prop is set
+- Account/billing pages pass `hideSiteSector={true}` to skip loading
+
+**Implementation:**
+```typescript
+// PageHeader.tsx
+useEffect(() => {
+  if (hideSiteSector) return; // Skip for account pages
+  
+  const currentSiteId = activeSite?.id ?? null;
+  if (currentSiteId && activeSite?.is_active) {
+    loadSectorsForSite(currentSiteId);
+  }
+}, [activeSite?.id, hideSiteSector]);
+```
+
+**Key Principle:** Lazy-load sectors only when components need them. Don't load globally for all pages.
+
+---
+
+### Site/Sector Store Persistence
+
+**Storage Keys:**
+- `site-storage` - Active site selection
+- `sector-storage` - Active sector selection
+
+**Reset Pattern:**
+```typescript
+// When site changes, reset sector if it belongs to different site
+if (currentSector && currentSector.site_id !== newSiteId) {
+  set({ activeSector: null });
+  localStorage.setItem('sector-storage', JSON.stringify({
+    state: { activeSector: null },
+    version: 0
+  }));
+}
+```
+
+**Key Principle:** Sector selection is site-scoped. Always validate sector belongs to active site.
+
+---
+
+## State Management & Race Conditions
+
+### Common Race Condition Patterns
+
+#### 1. User Switching
+**Problem:** Rapid logout → login leaves stale state in stores
+
+**Solution:**
+```typescript
+logout: () => {
+  // Reset ALL dependent stores explicitly
+  import('./siteStore').then(({ useSiteStore }) => {
+    useSiteStore.setState({ activeSite: null, loading: false, error: null });
+  });
+  import('./sectorStore').then(({ useSectorStore }) => {
+    useSectorStore.setState({ activeSector: null, sectors: [], loading: false, error: null });
+  });
+}
+```
+
+#### 2. API Calls Before Token Persistence
+**Problem:** API calls happen before Zustand persist writes token
+
+**Solution:** Synchronous localStorage write immediately after state update (see Authentication section)
+
+#### 3. Module Loading Failures
+**Problem:** 404 errors during page navigation cause module loading to fail
+
+**Solution:** Ensure API endpoints exist before pages try to load them. Use conditional rendering based on route.
+
+---
+
+### Zustand Persist Middleware Gotchas
+
+**Issue 1: Version Mismatch**
+```typescript
+// Stored format
+{ state: { user, token }, version: 0 }
+
+// If version changes, persist middleware clears state
+```
+
+**Issue 2: Async Hydration**
+- State rehydration from localStorage is async
+- Can cause brief flash of "no user" state
+
+**Solution:** Use loading states or check both store AND localStorage:
+```typescript
+const getAuthToken = (): string | null => {
+  // Try Zustand store first
+  const authState = useAuthStore.getState();
+  if (authState?.token) return authState.token;
+  
+  // Fallback to localStorage
+  const stored = localStorage.getItem('auth-storage');
+  return JSON.parse(stored)?.state?.token || null;
+};
+```
+
+---
+
+## Permission System
+
+### Superuser/Developer Bypass Pattern
+
+**Critical Locations for Bypass:**
+1. Middleware - `auth/middleware.py`
+2. Permission Classes - `api/permissions.py`
+3. ViewSet Querysets - `api/base.py`
+4. Validation Functions - `auth/utils.py`
+
+**Standard Bypass Check:**
+```python
+def check_bypass(user):
+    return (
+        user.is_superuser or
+        user.role == 'developer' or
+        is_system_account_user(user)
+    )
+```
+
+**Apply at ALL levels:**
+- Middleware request validation
+- DRF permission `has_permission()`
+- ViewSet `get_queryset()` filtering
+- Custom validation functions
+
+**Key Principle:** Bypass checks must be consistent across all permission layers. Missing one layer breaks superuser access.
+
+---
+
+### System Account Pattern
+
+**Reserved Accounts:**
+- `aws-admin` - System automation account
+- `default-account` - Default tenant fallback
+
+**Check Function:**
+```python
+def is_system_account_user(user):
+    if not user or not user.account:
+        return False
+    return user.account.slug in ['aws-admin', 'default-account']
+```
+
+**Usage:** Always include in bypass checks alongside superuser/developer.
+
+---
+
+## Frontend Component Dependencies
+
+### PageHeader Component
+**Dependencies:**
+- `useSiteStore` - Active site
+- `useSectorStore` - Active sector
+- `SiteAndSectorSelector` - Dropdown component
+
+**Props:**
+- `hideSiteSector: boolean` - Skip site/sector display and loading
+- `title: string` - Page title
+- `navigation: ReactNode` - Optional module tabs
+
+**Used By:**
+- All Planner pages
+- All Writer pages
+- All Optimizer pages
+- Setup pages
+- Seed Keywords page
+
+**NOT Used By:**
+- Account/billing pages (use plain headers instead)
+
+---
+
+### Module Navigation Pattern
+
+**Component:** `ModuleNavigationTabs.tsx`
+
+**CRITICAL:** Must be wrapped in `<Router>` context
+- Uses `useLocation()` and `useNavigate()` hooks
+- Cannot be used outside `<Routes>` tree
+
+**Common Error:**
+```
+Error: useLocation() may be used only in the context of a <Router> component
+```
+
+**Cause:** Component rendered outside React Router context
+
+**Solution:** Ensure component is within `<Route>` element in App.tsx
+
+---
+
+## Common Pitfalls & Solutions
+
+### Pitfall 1: Frontend 403 Errors After User Switch
+
+**Symptoms:**
+- "Authentication credentials were not provided"
+- User appears logged in but API calls fail
+- Manually clearing cache fixes it
+
+**Root Cause:** Invalid tokens persisting in localStorage after logout
+
+**Solution:** 
+1. Check 403 handler runs BEFORE throwing error
+2. Ensure logout clears specific auth keys (not `localStorage.clear()`)
+3. Add immediate token persistence after login
+
+**Prevention:** See "Authentication & Session Management" section
+
+---
+
+### Pitfall 2: Sector 404 Errors on Billing Pages
+
+**Symptoms:**
+- `GET /v1/auth/sites/{id}/sectors/` returns 404
+- "Failed to fetch dynamically imported module" error
+- Billing pages don't load
+
+**Root Cause:** AppLayout loading sectors for ALL pages globally
+
+**Solution:** Move sector loading to PageHeader component (lazy loading)
+
+**Prevention:** Only load data when components that need it are mounted
+
+---
+
+### Pitfall 3: Module Loading Failures After Git Commits
+
+**Symptoms:**
+- React Router context errors
+- "useLocation() may be used only in context of <Router>" errors
+- Pages work after rebuild but fail after git push
+
+**Root Cause:** Docker build cache not invalidated properly
+
+**Solution:**
+```bash
+# Force clean rebuild
+docker compose -f docker-compose.app.yml down
+docker compose -f docker-compose.app.yml build --no-cache igny8_frontend
+docker compose -f docker-compose.app.yml up -d
+```
+
+**Prevention:** Use `--no-cache` flag when rebuilding after major changes
+
+---
+
+### Pitfall 4: Plan Selection Issues in Pricing Page
+
+**Symptoms:**
+- Monthly/Annual toggle missing
+- Pre-selected plan not highlighted
+- Discount calculation wrong
+
+**Root Cause:** 
+1. PricingTable component missing `showToggle` prop
+2. Backend missing `is_featured` and `annual_discount_percent` fields
+3. Frontend not calculating annual price from discount
+
+**Solution:**
+1. Add fields to Plan model with migration
+2. Pass `annualDiscountPercent` to PricingTable
+3. Calculate: `annualPrice = monthlyPrice * 12 * (1 - discount/100)`
+
+**Files Modified:**
+- `backend/igny8_core/auth/models.py`
+- `backend/igny8_core/auth/serializers.py`
+- `frontend/src/services/billing.api.ts`
+- `frontend/src/components/ui/pricing-table/PricingTable.tsx`
+
+---
+
+### Pitfall 5: Adjacent JSX Elements Error
+
+**Symptoms:**
+- "Adjacent JSX elements must be wrapped in an enclosing tag"
+- Build fails but line numbers don't help
+
+**Root Cause:** Mismatched opening/closing tags (usually missing `</div>`)
+
+**Debugging Strategy:**
+1. Use TypeScript compiler: `npx tsc --noEmit <file>`
+2. Count opening vs closing tags: `grep -c "<div" vs grep -c "</div>"`
+3. Check conditionals have matching closing parens/braces
+
+**Common Pattern:**
+```tsx
+{condition && (
+  <div>
+    {/* Content */}
+  </div>
+  {/* Missing closing parenthesis causes "adjacent elements" error */}
+}
+```
+
+**Solution:** Ensure every opening bracket has matching close bracket
+
+---
+
+## Best Practices Summary
+
+### State Management
+✅ **DO:** Immediately persist auth tokens synchronously  
+✅ **DO:** Selectively remove localStorage keys  
+✅ **DO:** Reset dependent stores on logout  
+❌ **DON'T:** Use `localStorage.clear()`  
+❌ **DON'T:** Rely solely on Zustand persist middleware timing
+
+### Error Handling
+✅ **DO:** Check authentication errors BEFORE throwing  
+✅ **DO:** Force logout on invalid tokens  
+✅ **DO:** Redirect to login after logout  
+❌ **DON'T:** Throw errors before checking auth status  
+❌ **DON'T:** Leave invalid tokens in storage
+
+### Component Architecture
+✅ **DO:** Lazy-load data at component level  
+✅ **DO:** Skip unnecessary data loading (hideSiteSector pattern)  
+✅ **DO:** Keep components in Router context  
+❌ **DON'T:** Load data globally in AppLayout  
+❌ **DON'T:** Use Router hooks outside Router context
+
+### Permission System
+✅ **DO:** Implement bypass at ALL permission layers  
+✅ **DO:** Include system accounts in bypass checks  
+✅ **DO:** Use consistent bypass logic everywhere  
+❌ **DON'T:** Forget middleware layer bypass  
+❌ **DON'T:** Mix permission approaches
+
+### Docker Builds
+✅ **DO:** Use `--no-cache` after major changes  
+✅ **DO:** Restart containers after rebuilds  
+✅ **DO:** Check logs for module loading errors  
+❌ **DON'T:** Trust build cache after git commits  
+❌ **DON'T:** Deploy without testing fresh build
+
+---
+
+## Quick Reference: File Locations
+
+### Authentication
+- Token handling: `frontend/src/services/api.ts`
+- Auth store: `frontend/src/store/authStore.ts`
+- Middleware: `backend/igny8_core/auth/middleware.py`
+
+### Permissions
+- Permission classes: `backend/igny8_core/api/permissions.py`
+- Base viewsets: `backend/igny8_core/api/base.py`
+- Validation utils: `backend/igny8_core/auth/utils.py`
+
+### Site/Sector
+- Site store: `frontend/src/store/siteStore.ts`
+- Sector store: `frontend/src/store/sectorStore.ts`
+- PageHeader: `frontend/src/components/common/PageHeader.tsx`
+
+### Billing
+- Billing API: `frontend/src/services/billing.api.ts`
+- Plans page: `frontend/src/pages/account/PlansAndBillingPage.tsx`
+- Plan model: `backend/igny8_core/auth/models.py`
+
+---
+
+**End of Knowledge Base**  
+*Update this document when architectural patterns change or new common issues are discovered.*
diff --git a/CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md b/CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md
deleted file mode 100644
index 5355074a..00000000
--- a/CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md
+++ /dev/null
@@ -1,333 +0,0 @@
-# CRITICAL ISSUE: Router Context Error After Git Commits
-
-**Date:** December 8, 2025  
-**Status:** 🔴 CRITICAL - Blocks deployment  
-**Priority:** P0 - Must fix before any git push to remote
-
----
-
-## Problem Summary
-
-After committing backend changes to git and syncing with remote, **frontend pages break** with React Router context errors. The system is currently working but **will break** when the 6 modified backend files are pushed to remote.
-
-### Affected Pages
-1. `/planner/keywords` - Planner Keywords page
-2. `/writer/tasks` - Writer Tasks page  
-3. `/sites` - Sites management page
-4. `/thinker/prompts` - Thinker Prompts page
-5. `/automation` - Automation page
-6. `/setup/add-keywords` - Add Keywords setup page
-
-### Error Pattern
-
-**Primary Error:**
-```
-Error: useLocation() may be used only in the context of a <Router> component.
-    at ModuleNavigationTabs (ModuleNavigationTabs.tsx:22:20)
-```
-
-**Secondary Error:**
-```
-Error: useNavigate() may be used only in the context of a <Router> component.
-```
-
-**Associated API Errors (related to permission fixes):**
-```
-403 Forbidden: /api/v1/auth/sites/5/sectors/
-403 Forbidden: /api/v1/auth/sites/
-404 Not Found: /api/v1/billing/transactions/balance/
-```
-
----
-
-## Root Cause Analysis
-
-### NOT a Code Issue
-The code works fine in development and after fresh rebuild. The Router errors are **NOT** caused by the backend permission fixes.
-
-### ACTUAL Cause: Docker Build Cache Invalidation Failure
-
-**The Problem Chain:**
-1. Backend code changes are committed to git
-2. Git push triggers remote sync
-3. Docker Compose sees changed files
-4. **Docker does NOT properly rebuild frontend container** (uses stale cache)
-5. Frontend serves old JavaScript bundles with mismatched module boundaries
-6. React Router hooks fail because component tree structure changed
-7. Pages crash with "useLocation/useNavigate not in Router context"
-
-**Why This Happens:**
-- Frontend `Dockerfile.dev` uses `npm install` (not `npm ci`)
-- `package.json` changes don't always trigger full rebuild
-- Docker layer caching is too aggressive
-- `node_modules` volume persists stale dependencies
-- Vite HMR works during dev, but production bundle gets out of sync
-
----
-
-## Current Workaround (Manual Fix)
-
-**When errors occur, run these steps:**
-
-```bash
-# 1. Remove ALL containers in Portainer (manual deletion via UI)
-
-# 2. Rebuild infrastructure containers
-cd /data/app
-docker compose -f docker-compose.yml -p igny8-infra up -d
-sleep 3
-
-# 3. Rebuild application containers  
-cd /data/app/igny8
-docker compose -f docker-compose.app.yml -p igny8-app up -d
-
-# 4. Clear user session
-# - Log out from app
-# - Clear all cookies
-# - Log back in
-```
-
-**Result:** All pages work again ✅
-
----
-
-## Files That Will Trigger This Issue
-
-**Currently modified (unstaged) backend files:**
-```
-backend/igny8_core/api/base.py          - Superuser bypass in ViewSets
-backend/igny8_core/api/permissions.py   - Bypass in permission classes  
-backend/igny8_core/api/throttles.py     - Bypass in rate throttling
-backend/igny8_core/auth/middleware.py   - Session validation bypass
-backend/igny8_core/auth/utils.py        - Account validation bypass
-backend/igny8_core/modules/billing/urls.py - Billing endpoint alias
-```
-
-**When these are pushed to remote → frontend breaks**
-
----
-
-## Permanent Fix Required
-
-### Solution A: Fix Docker Build Cache (RECOMMENDED)
-
-**1. Update `frontend/Dockerfile.dev`:**
-
-```dockerfile
-# Before:
-RUN npm install
-
-# After:
-COPY package.json package-lock.json ./
-RUN npm ci --prefer-offline --no-audit
-COPY . .
-```
-
-**Explanation:**
-- `npm ci` does clean install (deletes node_modules first)
-- Separate COPY layers ensure package.json changes invalidate cache
-- `--prefer-offline` speeds up rebuild with local cache
-
-**2. Update `docker-compose.app.yml` frontend service:**
-
-```yaml
-volumes:
-  - ./frontend:/app
-  - /app/node_modules  # ← ADD THIS LINE
-```
-
-**Explanation:**
-- Excludes `node_modules` from volume mount
-- Prevents host `node_modules` from overriding container's
-- Forces Docker to use freshly installed dependencies
-
-**3. Update deployment commands to use `--no-cache` flag:**
-
-```bash
-# Development rebuild (when issues occur)
-docker compose -f docker-compose.app.yml build --no-cache frontend
-docker compose -f docker-compose.app.yml up -d frontend
-
-# Production deployment (always use)
-docker compose -f docker-compose.app.yml build --no-cache
-docker compose -f docker-compose.app.yml up -d
-```
-
-### Solution B: Add Build Verification Step
-
-**Add to deployment script:**
-
-```bash
-#!/bin/bash
-# deploy_frontend.sh
-
-echo "Building frontend with cache busting..."
-docker compose -f docker-compose.app.yml build --no-cache frontend
-
-echo "Checking build artifacts..."
-docker run --rm igny8-app-frontend ls -la /app/dist/
-
-echo "Deploying frontend..."
-docker compose -f docker-compose.app.yml up -d frontend
-
-echo "Waiting for health check..."
-sleep 5
-curl -f https://app.igny8.com || echo "WARNING: Frontend not responding"
-```
-
----
-
-## Why Backend Changes Break Frontend
-
-**This seems counterintuitive but here's why:**
-
-1. **Backend changes get committed** → triggers rebuild process
-2. **docker-compose.app.yml rebuilds ALL services** (backend + frontend)
-3. **Backend rebuilds correctly** (Django reloads Python modules)
-4. **Frontend rebuild FAILS SILENTLY** (uses cached layers)
-5. **Old frontend bundle** tries to connect to **new backend API**
-6. **React component tree structure mismatch** → Router context errors
-
-**The Fix:**
-- Ensure frontend ALWAYS rebuilds when ANY file in docker-compose.app.yml changes
-- Use `--no-cache` on deployments
-- Add build hash verification
-
----
-
-## Testing Plan
-
-### Before Pushing to Remote
-
-**1. Test current system works:**
-```bash
-curl -I https://app.igny8.com/planner/keywords
-curl -I https://app.igny8.com/writer/tasks
-curl -I https://app.igny8.com/sites
-```
-
-**2. Apply Docker fixes:**
-- Update `frontend/Dockerfile.dev`
-- Update `docker-compose.app.yml`
-- Test rebuild with `--no-cache`
-
-**3. Verify pages load:**
-- Login as dev@igny8.com
-- Visit all 6 affected pages
-- Check browser console for errors
-
-**4. Commit and push:**
-```bash
-git add backend/
-git commit -m "Fix superuser/developer access bypass"
-git push origin main
-```
-
-**5. Monitor production:**
-- SSH to server
-- Watch docker logs: `docker logs -f igny8_frontend`
-- Check all 6 pages still work
-
-### If Errors Still Occur
-
-Run the manual workaround:
-1. Remove containers in Portainer
-2. Rebuild infra + app
-3. Clear cookies + re-login
-
----
-
-## Impact Assessment
-
-**Current Status:**
-- ✅ System working locally
-- ✅ All pages functional after rebuild
-- ⚠️ **6 backend files uncommitted** (permission fixes)
-- 🔴 **Cannot push to remote** (will break production)
-
-**Deployment Blocked Until:**
-- [ ] Docker build cache fix implemented
-- [ ] Frontend Dockerfile.dev updated
-- [ ] docker-compose.app.yml volume exclusion added
-- [ ] Deployment script uses --no-cache
-- [ ] Test push to staging branch first
-
-**Business Impact:**
-- Superuser/developer access fixes are ready but **cannot be deployed**
-- Production system stuck on old code
-- Manual rebuild required after every deployment
-- High risk of breaking production
-
----
-
-## Next Steps
-
-**Immediate (Before Any Git Push):**
-1. ⏸️ **DO NOT commit or push the 6 backend files yet**
-2. 🔧 Fix `frontend/Dockerfile.dev` first
-3. 🔧 Update `docker-compose.app.yml` volumes
-4. ✅ Test full rebuild with --no-cache
-5. ✅ Verify all 6 pages work
-6. 📝 Commit Docker fixes first
-7. 📝 Then commit backend permission fixes
-8. 🚀 Push to remote in correct order
-
-**After Router Fix:**
-1. User will test account/billing pages (user-level)
-2. Check for permission leakage in admin menu
-3. Verify superuser-only access works correctly
-4. Test user menu vs admin menu isolation
-
----
-
-## Related Issues
-
-**From Previous Documentation:**
-- Issue D: Docker Build Cache (FINAL-IMPLEMENTATION-REQUIREMENTS.md)
-- Session Contamination (CRITICAL-ISSUE-C.md)  
-- Subscription Creation Gap (Issue B)
-
-**New Findings:**
-- Router context errors are **symptom** of build cache issue
-- Backend commits trigger the problem (unexpected)
-- Frontend needs proper dependency invalidation
-- Cookie clearing required after rebuild (session state persists)
-
----
-
-## References
-
-**Files Modified (Current Session):**
-```
-✅ backend/igny8_core/auth/middleware.py - Added superuser bypass
-✅ backend/igny8_core/api/permissions.py - Added bypass to 4 classes
-✅ backend/igny8_core/api/base.py - Added bypass to ViewSet querysets
-✅ backend/igny8_core/auth/utils.py - Added bypass to validation
-✅ backend/igny8_core/modules/billing/urls.py - Added endpoint alias
-✅ backend/igny8_core/api/throttles.py - Added throttle bypass
-```
-
-**Database Changes (Current Session):**
-```
-✅ Deleted duplicate free-trial plan (ID: 7)
-✅ Renamed enterprise → internal (System/Superuser only)
-✅ 5 plans now active: free, starter, growth, scale, internal
-```
-
-**Documentation Created:**
-```
-- IMPLEMENTATION-COMPLETE-DEC-8-2025.md (comprehensive summary)
-- QUICK-FIX-IMPLEMENTATION-SUMMARY.md (initial fixes)
-- SYSTEM-AUDIT-REPORT-2025-12-08.md (audit results)
-- CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md (this document)
-```
-
----
-
-## Conclusion
-
-**The system is working perfectly right now**, but **will break when code is pushed to remote** due to Docker build cache issues. 
-
-**Priority:** Fix Docker caching BEFORE committing the 6 backend permission files.
-
-**DO NOT PUSH TO REMOTE until Docker fixes are tested and verified.**
diff --git a/IMPLEMENTATION-COMPLETE-DEC-8-2025.md b/IMPLEMENTATION-COMPLETE-DEC-8-2025.md
deleted file mode 100644
index cd2b7ddd..00000000
--- a/IMPLEMENTATION-COMPLETE-DEC-8-2025.md
+++ /dev/null
@@ -1,288 +0,0 @@
-# COMPLETE IMPLEMENTATION - Dec 8, 2025
-## All Issues Fixed - Comprehensive System Repair
-
----
-
-## ✅ COMPLETED FIXES
-
-### 1. Free-Trial Plan Created ✅
-**Command Run:**
-```bash
-docker exec igny8_backend python3 manage.py create_free_trial_plan
-```
-
-**Result:**
-- Plan ID: 7
-- Slug: `free-trial`
-- Credits: 2000
-- Max Sites: 1
-- Max Sectors: 3
-- Status: Active
-
-**Impact:** New users can now sign up and get 2000 credits automatically.
-
----
-
-### 2. Superuser/Developer Bypass Fixed ✅
-
-#### Files Modified:
-1. **`backend/igny8_core/auth/middleware.py`** - Session blocking removed, validation bypass added
-2. **`backend/igny8_core/api/permissions.py`** - All permission classes updated with bypass
-3. **`backend/igny8_core/api/base.py`** - AccountModelViewSet and SiteSectorModelViewSet bypass added
-4. **`backend/igny8_core/auth/utils.py`** - validate_account_and_plan() bypass added
-
-#### Changes Made:
-
-**Middleware (`auth/middleware.py`):**
-- ❌ **REMOVED:** Session auth blocking for superusers (lines 35-41)
-- ✅ **ADDED:** Bypass in `_validate_account_and_plan()` for:
-  - `is_superuser=True`
-  - `role='developer'`
-  - `is_system_account_user()=True`
-
-**Permissions (`api/permissions.py`):**
-- ✅ **HasTenantAccess:** Added superuser, developer, system account bypass
-- ✅ **IsViewerOrAbove:** Added superuser, developer bypass
-- ✅ **IsEditorOrAbove:** Added superuser, developer bypass  
-- ✅ **IsAdminOrOwner:** Added superuser, developer bypass
-
-**Base ViewSets (`api/base.py`):**
-- ✅ **AccountModelViewSet.get_queryset():** Returns all objects for superuser/developer
-- ✅ **SiteSectorModelViewSet.get_queryset():** Skips site filtering for superuser/developer
-
-**Validation (`auth/utils.py`):**
-- ✅ **validate_account_and_plan():** Early return (True, None, None) for superuser/developer/system accounts
-
-**Impact:** 
-- Superusers can now access ALL resources across ALL tenants
-- Developers have same privileges as superusers
-- System accounts (aws-admin, default-account) bypass validation
-- Regular users still properly isolated to their account
-
----
-
-### 3. Billing Endpoint Fixed ✅
-
-**File:** `backend/igny8_core/modules/billing/urls.py`
-
-**Added:**
-```python
-path('transactions/balance/', CreditBalanceViewSet.as_view({'get': 'list'}), name='transactions-balance'),
-```
-
-**Impact:** Frontend can now call `/v1/billing/transactions/balance/` without 404 error.
-
----
-
-### 4. Planner Keywords 403 Error Fixed ✅
-
-**Root Cause:** `SiteSectorModelViewSet` was filtering by accessible sites, blocking superusers.
-
-**Fix:** Added bypass logic in `SiteSectorModelViewSet.get_queryset()`:
-- Superusers/developers skip site filtering
-- Still apply site_id query param if provided
-- Regular users filtered by accessible sites
-
-**Impact:** Superusers can now access keywords/clusters/ideas across all sites.
-
----
-
-## 🔄 STILL NEEDS FIXING
-
-### 1. Throttling 429 Errors ⚠️
-**Problem:** Too many requests, throttle limits too strict for development
-
-**Temporary Solution:** Increase throttle limits in settings or disable for development
-
-**Proper Fix Needed:**
-```python
-# backend/igny8_core/api/throttles.py
-class DebugScopedRateThrottle(ScopedRateThrottle):
-    def allow_request(self, request, view):
-        # Bypass for superusers/developers
-        if request.user and request.user.is_authenticated:
-            if getattr(request.user, 'is_superuser', False):
-                return True
-            if hasattr(request.user, 'role') and request.user.role == 'developer':
-                return True
-        return super().allow_request(request, view)
-```
-
----
-
-### 2. Session Contamination (CRITICAL) 🔥
-**Problem:** Regular users might get superuser session if browsing from same browser
-
-**Status:** Partially fixed (middleware bypass added) but session auth still enabled
-
-**Complete Fix Needed:**
-1. **Remove `CSRFExemptSessionAuthentication` from API ViewSets**
-2. **Add middleware detection to logout superuser sessions on /api/\***
-3. **Frontend: Clear cookies before registration**
-
-**Files to Update:**
-- `backend/igny8_core/auth/middleware.py` - Add superuser session detection
-- `frontend/src/store/authStore.ts` - Clear sessions before register
-- All ViewSets - Remove CSRFExemptSessionAuthentication
-
----
-
-### 3. Subscription Creation on Signup ⚠️
-**Problem:** RegisterSerializer doesn't create Subscription record
-
-**Fix Needed:**
-```python
-# backend/igny8_core/auth/serializers.py - Line 365
-from datetime import timedelta
-from django.utils import timezone
-
-subscription = Subscription.objects.create(
-    account=account,
-    status='trialing',
-    payment_method='trial',
-    current_period_start=timezone.now(),
-    current_period_end=timezone.now() + timedelta(days=14),
-    cancel_at_period_end=False
-)
-```
-
----
-
-### 4. Docker Build Cache Issues 🐳
-**Problem:** Router errors appear after deployments due to stale node_modules
-
-**Fix:** Already documented in requirements, needs implementation:
-1. Update `frontend/Dockerfile.dev` - use `npm ci`
-2. Update `docker-compose.app.yml` - exclude node_modules volume
-3. Always use `--no-cache` for builds
-
----
-
-## 📋 VERIFICATION CHECKLIST
-
-### Test Superuser Access ✅
-```bash
-# 1. Login as dev@igny8.com
-# 2. Navigate to:
-- /dashboard ✅
-- /sites ✅  
-- /planner ✅
-- /billing ✅
-- /account/settings ✅
-
-# Expected: All pages load, no 403 errors
-```
-
-### Test Regular User Isolation ⏳
-```bash
-# 1. Login as regular user (owner role)
-# 2. Check they only see their account's data
-# 3. Ensure they cannot access other accounts
-
-# Expected: Proper tenant isolation
-```
-
-### Test Free Trial Signup ⏳
-```bash
-# 1. Visit /signup
-# 2. Fill form, submit
-# 3. Check account created with:
-#    - status='trial'
-#    - credits=2000
-#    - plan=free-trial
-
-# Expected: Successful signup with credits
-```
-
----
-
-## 🔧 COMMANDS TO RUN
-
-### Apply Remaining Fixes
-```bash
-# 1. Check current state
-docker exec igny8_backend python3 -c "
-import os, django
-os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'igny8_core.settings')
-django.setup()
-from igny8_core.auth.models import User, Plan, Subscription
-print('Plans:', Plan.objects.count())
-print('Users:', User.objects.count())  
-print('Subscriptions:', Subscription.objects.count())
-"
-
-# 2. Test superuser access
-curl -H "Cookie: sessionid=YOUR_SESSION" http://localhost:8011/api/v1/planner/keywords/?site_id=16
-
-# 3. Test billing endpoint
-curl -H "Cookie: sessionid=YOUR_SESSION" http://localhost:8011/api/v1/billing/transactions/balance/
-```
-
----
-
-## 📝 SUMMARY
-
-### What Works Now:
-✅ Free-trial plan exists (2000 credits)
-✅ Superuser can access all resources
-✅ Developer role has full access
-✅ System accounts bypass validation
-✅ Billing /transactions/balance/ endpoint exists
-✅ Planner keywords accessible to superuser
-✅ Regular users still isolated to their account
-
-### What Still Needs Work:
-⚠️ Throttling too strict (429 errors)
-🔥 Session contamination risk (needs JWT-only enforcement)
-⚠️ Subscription not created on signup
-⚠️ Docker build cache issues
-⚠️ Enterprise plan protection
-
-### Critical Next Steps:
-1. **Test everything thoroughly** - Login as superuser and regular user
-2. **Fix throttling** - Add bypass for superuser/developer
-3. **Implement session isolation** - Remove session auth from API
-4. **Add subscription creation** - Update RegisterSerializer
-5. **Document for team** - Update master-docs with changes
-
----
-
-## 🎯 SUCCESS CRITERIA
-
-- [x] Superuser can access dashboard
-- [x] Superuser can see all sites  
-- [x] Superuser can access planner/keywords
-- [x] Billing endpoints work
-- [ ] No 429 throttle errors for superuser
-- [ ] Regular users properly isolated
-- [ ] Signup creates subscription
-- [ ] No session contamination
-
-**Status:** 70% Complete - Core access restored, fine-tuning needed
-
----
-
-## 📞 FOR NEXT SESSION
-
-**Priority 1 (Critical):**
-1. Fix throttling bypass for superuser/developer
-2. Remove session auth from API routes
-3. Test signup flow end-to-end
-
-**Priority 2 (Important):**
-4. Add subscription creation on signup
-5. Fix Docker build process
-6. Update documentation
-
-**Priority 3 (Nice to have):**
-7. Comprehensive test suite
-8. Performance optimization
-9. Code cleanup
-
----
-
-**Implementation Date:** December 8, 2025  
-**Time Taken:** ~2 hours  
-**Files Modified:** 5  
-**Lines Changed:** ~150  
-**Status:** Partially Complete - Core functionality restored
diff --git a/QUICK-FIX-IMPLEMENTATION-SUMMARY.md b/QUICK-FIX-IMPLEMENTATION-SUMMARY.md
deleted file mode 100644
index a4dc399b..00000000
--- a/QUICK-FIX-IMPLEMENTATION-SUMMARY.md
+++ /dev/null
@@ -1,285 +0,0 @@
-# Quick Fix Implementation Summary
-**Date:** December 8, 2025  
-**Option:** Option 1 - Quick Fix (Restore Superuser Access)  
-**Status:** ✅ COMPLETED
-
----
-
-## Changes Implemented
-
-### 1. ✅ Middleware Bypass (CRITICAL FIX)
-**File:** `/backend/igny8_core/auth/middleware.py`
-
-**Changes:**
-- ❌ **REMOVED:** Session auth blocking for superusers (lines 35-41)
-- ✅ **ADDED:** Bypass for superusers in `_validate_account_and_plan()`
-- ✅ **ADDED:** Bypass for developers (role='developer')
-- ✅ **ADDED:** Bypass for system account users
-
-**Impact:** Superusers can now access the app via session auth (Django admin login)
-
----
-
-### 2. ✅ Permission Bypass
-**File:** `/backend/igny8_core/api/permissions.py`
-
-**Changes to `HasTenantAccess` class:**
-- ✅ **ADDED:** Superuser bypass (`is_superuser=True` → allow)
-- ✅ **ADDED:** Developer role bypass (`role='developer'` → allow)
-- ✅ **ADDED:** System account bypass (aws-admin, default-account → allow)
-
-**Impact:** Superusers and developers bypass tenant isolation checks
-
----
-
-### 3. ✅ Queryset Filtering Bypass
-**File:** `/backend/igny8_core/api/base.py`
-
-**Changes to `AccountModelViewSet.get_queryset()`:**
-- ✅ **ADDED:** Superuser sees ALL accounts (no filtering)
-- ✅ **ADDED:** Developer sees ALL accounts (no filtering)
-- ✅ **ADDED:** System account users see ALL accounts
-
-**Impact:** Superusers can access resources across all tenants
-
----
-
-### 4. ✅ Account Validation Bypass
-**File:** `/backend/igny8_core/auth/utils.py`
-
-**Changes to `validate_account_and_plan()` function:**
-- ✅ **ADDED:** Early return for superusers (skip validation)
-- ✅ **ADDED:** Early return for developers (skip validation)
-- ✅ **ADDED:** Early return for system account users (skip validation)
-- ✅ **ADDED:** Early return for system accounts (skip validation)
-
-**Impact:** Superusers don't need valid account/plan to access system
-
----
-
-## Bypass Hierarchy (Order of Checks)
-
-All critical components now check in this order:
-
-1. **Is Superuser?** → `is_superuser=True` → ✅ ALLOW (bypass everything)
-2. **Is Developer?** → `role='developer'` → ✅ ALLOW (bypass everything)
-3. **Is System Account User?** → `account.slug in ['aws-admin', 'default-account', 'default']` → ✅ ALLOW
-4. **Regular User** → Apply normal tenant isolation rules
-
----
-
-## Files Modified
-
-| File | Lines Changed | Purpose |
-|------|---------------|---------|
-| `backend/igny8_core/auth/middleware.py` | ~30 lines | Remove session blocking, add validation bypass |
-| `backend/igny8_core/api/permissions.py` | ~20 lines | Add bypass to HasTenantAccess |
-| `backend/igny8_core/api/base.py` | ~20 lines | Add bypass to queryset filtering |
-| `backend/igny8_core/auth/utils.py` | ~25 lines | Add bypass to account validation |
-
-**Total:** ~95 lines of code changes across 4 critical files
-
----
-
-## Testing Instructions
-
-### Step 1: Start the Application
-
-```bash
-cd /data/app/igny8
-docker compose up -d
-# OR
-docker-compose up -d
-```
-
-### Step 2: Test Superuser Login
-
-1. Go to admin panel: `http://localhost:8011/admin/` (or your backend URL)
-2. Login with superuser credentials (dev@igny8.com or your superuser account)
-3. Navigate to any API endpoint: `http://localhost:8011/api/v1/auth/users/`
-
-**Expected Result:** ✅ Superuser can access without errors
-
-### Step 3: Test App Access
-
-1. Open app: `http://localhost:3000/` (or your frontend URL)
-2. Login with superuser account
-3. Navigate to:
-   - Dashboard
-   - Sites page
-   - Planner page
-   - Billing page
-   - Account settings
-
-**Expected Result:** ✅ All pages load without permission errors
-
-### Step 4: Test Cross-Tenant Access
-
-As superuser:
-1. Go to Sites page
-2. Should see sites from ALL accounts (not just your account)
-3. Can access/edit any site
-
-**Expected Result:** ✅ Superuser can see and manage all tenant resources
-
-### Step 5: Test Regular User (Tenant Isolation)
-
-1. Logout superuser
-2. Login with regular user (e.g., owner/editor role)
-3. Navigate to Sites page
-
-**Expected Result:** ✅ Regular users only see their own account's sites
-
----
-
-## What's FIXED
-
-✅ **Superuser can access application**
-- Session auth works (no JWT required for now)
-- Django admin login → app access
-- All API endpoints accessible
-
-✅ **Developer role has full access**
-- Same privileges as superuser
-- Bypasses all tenant checks
-- Can debug across all accounts
-
-✅ **System accounts work**
-- aws-admin, default-account bypass checks
-- No plan validation required
-- Emergency access restored
-
-✅ **Tenant isolation maintained**
-- Regular users still isolated to their account
-- Plan limits still enforced for tenants
-- Security boundaries intact for non-privileged users
-
----
-
-## What's NOT Fixed (For Option 2 - Full Rebuild)
-
-⚠️ **Still needs work:**
-- Paid plan signup flow (no payment page yet)
-- JWT token generation (still using session auth)
-- Documentation consolidation
-- Permission module unification
-- Account.payment_method migration
-- Comprehensive test suite
-
-**These will be addressed in Option 2 (Proper Rebuild) if you choose to proceed.**
-
----
-
-## Rollback Plan (If Issues Occur)
-
-If the quick fix causes problems:
-
-```bash
-# 1. Restore from git (if you have version control)
-cd /data/app/igny8/backend
-git checkout backend/igny8_core/auth/middleware.py
-git checkout backend/igny8_core/api/permissions.py
-git checkout backend/igny8_core/api/base.py
-git checkout backend/igny8_core/auth/utils.py
-
-# 2. Restart containers
-cd /data/app/igny8
-docker compose restart backend
-
-# 3. Or restore from audit report reference
-# See SYSTEM-AUDIT-REPORT-2025-12-08.md for original code
-```
-
----
-
-## Next Steps
-
-### Immediate (Now)
-1. ✅ Start application containers
-2. ✅ Test superuser login and access
-3. ✅ Verify all pages load
-4. ✅ Confirm tenant isolation still works for regular users
-
-### Short-term (This Week)
-- Document which endpoints superuser accessed
-- Note any remaining permission errors
-- List features still not working
-
-### Medium-term (When Ready)
-**Option 2 - Proper Rebuild:**
-- Unified permission system
-- JWT authentication
-- Paid plan signup flow
-- Complete payment integration
-- Consolidated documentation
-- Comprehensive tests
-
----
-
-## Success Criteria
-
-### ✅ Must Pass
-- [x] Superuser can login
-- [x] Superuser can access dashboard
-- [x] Superuser can see all sites
-- [x] Superuser can access billing pages
-- [x] Regular users still isolated to their account
-- [x] No 403 errors for superuser
-- [x] No 401 errors for superuser
-
-### Verification Commands
-
-```bash
-# Check if backend is running
-curl http://localhost:8011/api/v1/auth/users/ -H "Cookie: sessionid=YOUR_SESSION_ID"
-
-# Check if middleware allows access (should return data, not 403)
-# After logging in as superuser in Django admin
-```
-
----
-
-## Support
-
-If you encounter issues:
-
-1. **Check logs:**
-   ```bash
-   docker compose logs backend -f
-   ```
-
-2. **Check middleware execution:**
-   - Look for "Session authentication not allowed" errors
-   - Should NOT appear after fix
-
-3. **Check permission errors:**
-   - Look for HasTenantAccess denials
-   - Should NOT appear for superusers after fix
-
-4. **Verify user attributes:**
-   ```python
-   # In Django shell
-   from igny8_core.auth.models import User
-   user = User.objects.get(email='dev@igny8.com')
-   print(f"Superuser: {user.is_superuser}")
-   print(f"Role: {user.role}")
-   print(f"Account: {user.account}")
-   ```
-
----
-
-## Conclusion
-
-**Quick Fix Status: ✅ COMPLETE**
-
-All 4 critical components now have proper bypass logic for:
-- Superusers (`is_superuser=True`)
-- Developers (`role='developer'`)
-- System accounts (`aws-admin`, `default-account`)
-
-**Estimated Time Taken:** ~1 hour  
-**Code Quality:** Good (targeted fixes, minimal changes)  
-**Stability:** High (only added bypass logic, didn't remove tenant isolation)  
-**Ready for Testing:** ✅ YES
-
-Start your application and test superuser access!
diff --git a/SYSTEM-AUDIT-REPORT-2025-12-08.md b/SYSTEM-AUDIT-REPORT-2025-12-08.md
deleted file mode 100644
index d63d04aa..00000000
--- a/SYSTEM-AUDIT-REPORT-2025-12-08.md
+++ /dev/null
@@ -1,453 +0,0 @@
-# Complete System Audit Report
-**Date:** December 8, 2025  
-**Scope:** Full stack audit - Backend models, permissions, middleware, frontend, documentation  
-**Status:** 🔴 CRITICAL ISSUES FOUND
-
----
-
-## Executive Summary
-
-### Overall System State: 🔴 BROKEN
-
-Your multi-tenancy system has **5 CRITICAL ISSUES** that are causing widespread failures:
-
-1. **Superuser Access Broken** - Session auth blocked on API, no bypass logic working
-2. **Permission System Contradictions** - Multiple conflicting permission classes
-3. **Missing Bypass Logic** - Superuser/developer checks removed from critical paths
-4. **Account Validation Too Strict** - Blocks all users including system accounts
-5. **Paid Plan Signup Missing** - No path for users to subscribe to paid plans
-
-**Impact:** Neither regular tenants NOR superusers can access the application.
-
----
-
-## Critical Issue #1: Superuser Access COMPLETELY BROKEN
-
-### Problem
-Superusers cannot access the application at all due to conflicting middleware logic.
-
-### Root Cause
-**File:** `backend/igny8_core/auth/middleware.py:35-41`
-
-```python
-# Block superuser access via session on non-admin routes (JWT required)
-auth_header = request.META.get('HTTP_AUTHORIZATION', '')
-if request.user.is_superuser and not auth_header.startswith('Bearer '):
-    logout(request)
-    return JsonResponse(
-        {'success': False, 'error': 'Session authentication not allowed for API. Use JWT.'},
-        status=status.HTTP_403_FORBIDDEN,
-    )
-```
-
-**This blocks ALL superuser access** because:
-- Superusers login via Django admin (session-based)
-- Session cookies are sent to API automatically
-- Middleware detects superuser + no JWT = LOGOUT + 403 error
-- Even WITH JWT, there's no bypass logic downstream
-
-### Evidence
-1. Middleware forces JWT-only for superusers
-2. No JWT generation on login (traditional Django session auth)
-3. Permission classes have `is_superuser` checks BUT middleware blocks before reaching them
-4. Admin panel uses session auth, but API rejects it
-
-### Impact
-- Superusers cannot access ANY page in the app
-- Developer account cannot debug issues
-- System administration impossible
-
----
-
-## Critical Issue #2: Permission System Has CONTRADICTIONS
-
-### Problem
-Three different permission modules with conflicting logic:
-
-#### Module A: `backend/igny8_core/auth/permissions.py`
-```python
-class IsOwnerOrAdmin(permissions.BasePermission):
-    def has_permission(self, request, view):
-        if getattr(user, "is_superuser", False):
-            return True  # ✅ Superuser allowed
-        return user.role in ['owner', 'admin', 'developer']
-```
-
-#### Module B: `backend/igny8_core/api/permissions.py`
-```python
-class HasTenantAccess(permissions.BasePermission):
-    def has_permission(self, request, view):
-        # NO superuser bypass ❌
-        # Regular users must have account access
-        if account:
-            return user_account == account
-        return False  # Denies superusers without account match
-```
-
-#### Module C: `backend/igny8_core/admin/base.py`
-```python
-class AccountAdminMixin:
-    def get_queryset(self, request):
-        if request.user.is_superuser or request.user.is_developer():
-            return qs  # ✅ Bypass for superuser/developer
-```
-
-### The Contradiction
-- **auth/permissions.py** - Allows superuser bypass
-- **api/permissions.py** - NO superuser bypass (strict tenant-only)
-- **admin/base.py** - Allows superuser/developer bypass
-- **ViewSets** - Use MIXED permission classes from different modules
-
-### Example of Broken ViewSet
-**File:** `backend/igny8_core/auth/views.py:144`
-
-```python
-class UsersViewSet(AccountModelViewSet):
-    permission_classes = [
-        IsAuthenticatedAndActive,  # From api/permissions - no bypass
-        HasTenantAccess,           # From api/permissions - no bypass
-        IsOwnerOrAdmin             # From auth/permissions - has bypass
-    ]
-```
-
-**Result:** Permission denied because `HasTenantAccess` (2nd check) fails before `IsOwnerOrAdmin` (3rd check) runs.
-
-### Impact
-- Inconsistent behavior across endpoints
-- Some endpoints work, some don't
-- Debugging is impossible - which permission is denying?
-
----
-
-## Critical Issue #3: Account Validation TOO STRICT
-
-### Problem
-Middleware validation blocks even system accounts and developers.
-
-**File:** `backend/igny8_core/auth/middleware.py:148-170` + `auth/utils.py:133-195`
-
-```python
-def _validate_account_and_plan(self, request, user):
-    from .utils import validate_account_and_plan
-    is_valid, error_message, http_status = validate_account_and_plan(user)
-    if not is_valid:
-        return self._deny_request(request, error_message, http_status)
-```
-
-```python
-def validate_account_and_plan(user_or_account):
-    account = getattr(user_or_account, 'account', None)
-    if not account:
-        return (False, 'Account not configured', 403)
-    
-    if account.status in ['suspended', 'cancelled']:
-        return (False, f'Account is {account.status}', 403)
-    
-    plan = getattr(account, 'plan', None)
-    if not plan:
-        return (False, 'No subscription plan', 402)
-    
-    if not plan.is_active:
-        return (False, 'Active subscription required', 402)
-    
-    return (True, None, None)
-```
-
-### The Problem
-**NO bypass for:**
-- Superusers (is_superuser=True)
-- Developer role (role='developer')
-- System accounts (aws-admin, default-account)
-
-Even the developer account (dev@igny8.com) gets blocked if:
-- Their account doesn't have a plan
-- Their plan is inactive
-- Their account status is suspended
-
-### Impact
-- Cannot fix issues even with superuser access
-- System accounts get blocked
-- No emergency access path
-
----
-
-## Critical Issue #4: Missing Bypass Logic in Core Components
-
-### AccountModelViewSet - NO Bypass
-**File:** `backend/igny8_core/api/base.py:17-42`
-
-```python
-def get_queryset(self):
-    queryset = super().get_queryset()
-    if hasattr(queryset.model, 'account'):
-        # Filter by account
-        if account:
-            queryset = queryset.filter(account=account)
-        else:
-            return queryset.none()  # ❌ Blocks everyone without account
-```
-
-**Missing:**
-- No check for `is_superuser`
-- No check for `role='developer'`
-- No check for system accounts
-
-### HasTenantAccess Permission - NO Bypass
-**File:** `backend/igny8_core/api/permissions.py:23-52`
-
-```python
-class HasTenantAccess(permissions.BasePermission):
-    def has_permission(self, request, view):
-        # NO superuser bypass
-        if account:
-            return user_account == account
-        return False  # ❌ Denies superusers
-```
-
-### Impact
-Every API endpoint using these base classes is broken for superusers.
-
----
-
-## Critical Issue #5: Paid Plan Signup Path MISSING
-
-### Problem
-Marketing page shows paid plans ($89, $139, $229) but all signup buttons go to free trial.
-
-**File:** `tenancy-accounts-payments-still-have issues/PRICING-TO-PAID-SIGNUP-GAP.md`
-
-### Gap Analysis
-- ✅ Free trial signup works
-- ❌ Paid plan signup does NOT exist
-- ❌ No payment page
-- ❌ No plan selection on signup
-- ❌ No payment method collection
-
-### Missing Components
-1. Payment page UI (frontend)
-2. Plan parameter routing (/signup?plan=starter)
-3. Payment method selection
-4. Pending payment account creation
-5. Bank transfer confirmation flow
-
----
-
-## Models & Database State
-
-### ✅ What's Working
-1. **Models are well-designed:**
-   - Account, User, Plan, Subscription, Site, Sector
-   - Credit system (CreditTransaction, CreditUsageLog)
-   - Payment/Invoice models exist
-   - Proper relationships (ForeignKey, OneToOne)
-
-2. **Database has data:**
-   - 5 plans (free, starter, growth, scale, enterprise)
-   - 8 accounts actively using system
-   - 280+ credit transactions
-   - Credit tracking working
-
-3. **Soft delete implemented:**
-   - SoftDeletableModel base class
-   - Retention policies
-   - Restore functionality
-
-### ❌ What's Broken
-1. **Missing field in Account model:**
-   - `payment_method` field defined in model but NOT in database (migration missing)
-
-2. **Subscription table empty:**
-   - No subscriptions exist despite Subscription model
-   - Users operating on credits without subscription tracking
-
-3. **Payment system incomplete:**
-   - Models exist but no data
-   - No payment gateway integration
-   - No invoice generation in use
-
----
-
-## Documentation Issues
-
-### Problem: Scattered & Contradictory
-
-**Three separate doc folders:**
-1. `master-docs/` - Structured, organized, but may be outdated
-2. `old-docs/` - Legacy docs, unclear what's still valid
-3. `tenancy-accounts-payments-still-have issues/` - Recent fixes, most accurate
-
-### Contradictions Found
-1. **Superuser bypass:** Docs say it exists, code shows it was removed
-2. **Payment methods:** Docs describe manual payment flow, but frontend doesn't implement it
-3. **Plan allocation:** Docs show complex fallback logic, implementation shows it was simplified
-4. **Session auth:** Docs don't mention JWT requirement for API
-
-### Missing from Docs
-1. Current state of superuser access (broken)
-2. Which permission module is canonical
-3. Middleware validation rules
-4. Account.payment_method migration status
-
----
-
-## Frontend Analysis
-
-### ✅ Frontend Code Quality: GOOD
-- Well-structured React/TypeScript
-- Proper state management (Zustand)
-- Error handling hooks exist
-- API service layer organized
-
-### ❌ Frontend Issues
-1. **No paid plan signup page** - Missing `/payment` route
-2. **No error display for permission denied** - Silent failures
-3. **No JWT token generation** - Still using session auth
-4. **No superuser indicator** - Users don't know why access is denied
-
----
-
-## ROOT CAUSE ANALYSIS
-
-### Timeline of What Happened
-
-1. **Initially:** Superuser had full bypass, everything worked
-2. **Tenancy work started:** Added strict tenant isolation
-3. **Security concern:** Removed some bypass logic to prevent session contamination
-4. **Over-correction:** Removed TOO MUCH bypass logic
-5. **Now:** Neither tenants nor superusers can access anything
-
-### The Core Problem
-
-**Attempted to fix security issue but broke fundamental access:**
-- Session contamination IS a real issue
-- JWT-only for API IS correct approach
-- BUT: Removed all bypass logic instead of fixing authentication method
-- AND: Middleware blocks before permission classes can allow bypass
-
----
-
-## RECOMMENDATIONS
-
-I have **TWO OPTIONS** for you:
-
-### Option 1: QUICK FIX (2-4 hours) ⚡
-**Restore superuser access immediately, patch critical flows**
-
-**Pros:**
-- Fastest path to working system
-- Superuser can access app today
-- Tenant system keeps working
-
-**Cons:**
-- Technical debt remains
-- Documentation still messy
-- Some inconsistencies persist
-
-**What gets fixed:**
-1. Add superuser bypass to middleware
-2. Add developer role bypass to HasTenantAccess
-3. Add system account bypass to AccountModelViewSet
-4. Generate JWT tokens on login
-5. Update frontend to use JWT
-
-**Estimated time:** 2-4 hours  
-**Effort:** LOW  
-**Risk:** LOW
-
----
-
-### Option 2: PROPER REBUILD (2-3 days) 🏗️
-**Redesign tenancy system with clean architecture**
-
-**Pros:**
-- Clean, maintainable code
-- Consistent permission logic
-- Proper documentation
-- All flows working correctly
-- Future-proof architecture
-
-**Cons:**
-- Takes 2-3 days
-- Requires careful testing
-- Must migrate existing data
-
-**What gets rebuilt:**
-1. **Unified permission system** - One module, clear hierarchy
-2. **Clean middleware** - Proper bypass logic for all roles
-3. **JWT authentication** - Token generation + refresh
-4. **Paid plan signup** - Complete payment flow
-5. **Consolidated docs** - Single source of truth
-6. **Account migration** - Add missing payment_method field
-7. **Subscription system** - Link accounts to subscriptions
-8. **Test suite** - Cover all permission scenarios
-
-**Estimated time:** 2-3 days  
-**Effort:** MEDIUM  
-**Risk:** MEDIUM (with proper testing)
-
----
-
-## MY RECOMMENDATION
-
-### Start with Option 1 (Quick Fix), then Option 2
-
-**Why:**
-1. You need access NOW - can't wait 3 days
-2. Quick fix restores functionality in hours
-3. Then properly rebuild when system is accessible
-4. Less risk - incremental improvement
-
-**Action Plan:**
-1. **NOW:** Quick fix (2-4 hours) - restore superuser access
-2. **Tomorrow:** Test all flows, document issues
-3. **Next 2-3 days:** Proper rebuild with clean architecture
-4. **End result:** Production-ready multi-tenancy system
-
----
-
-## Next Steps
-
-**Please confirm which option you want:**
-
-**Option A:** Quick fix now (I'll start immediately)  
-**Option B:** Full rebuild (2-3 days, but cleaner)  
-**Option C:** Quick fix now + full rebuild after (RECOMMENDED)
-
-Once you confirm, I'll begin implementation with detailed progress updates.
-
----
-
-## File Inventory (Issues Found)
-
-### Backend Files with Issues
-1. ✅ `/backend/igny8_core/auth/middleware.py` - Blocks superusers
-2. ✅ `/backend/igny8_core/auth/utils.py` - No bypass in validation
-3. ✅ `/backend/igny8_core/api/permissions.py` - No superuser bypass
-4. ✅ `/backend/igny8_core/api/base.py` - No bypass in queryset filter
-5. ⚠️ `/backend/igny8_core/auth/models.py` - Missing payment_method migration
-6. ✅ `/backend/igny8_core/auth/views.py` - Mixed permission classes
-
-### Frontend Files with Issues
-7. ⚠️ `/frontend/src/services/api.ts` - No JWT token handling
-8. ❌ `/frontend/src/pages/Payment.tsx` - MISSING (paid signup)
-9. ⚠️ `/frontend/src/components/auth/SignUpForm.tsx` - No plan parameter
-
-### Documentation Issues
-10. ⚠️ `master-docs/` - May be outdated
-11. ⚠️ `old-docs/` - Unclear what's valid
-12. ✅ `tenancy-accounts-payments-still-have issues/` - Most accurate
-
-**Legend:**
-- ✅ = Critical issue, must fix
-- ⚠️ = Important but not blocking
-- ❌ = Missing component
-
----
-
-## Conclusion
-
-Your system has **good architecture** but **broken implementation** due to over-correction during security fixes. The models are solid, the database is working, but the permission/access layer is preventing anyone (including you) from using the app.
-
-**The good news:** This is fixable in a few hours with targeted changes.
-
-**Waiting for your decision on which option to proceed with...**