feat: redesign docs sidebar with audience-based categories + fix PNG background

## Architecture Diagram PNG Fix
- Regenerated PNG with solid white background (no transparency)
- Removed alpha channel (RGBA → RGB)
- Increased resolution to 2400x2000 for true high-res quality
- Fixed poor UX with checkered/transparent background on implementer.html

## Documentation Sidebar Redesign
Reorganized from flat "getting started" list to 5 hierarchical categories
based on user journey and expertise level:

### New Category Structure:
- 📘 Introduction (1-5): Beginner level, all audiences
- ⚙️ Implementation (10-19): Practical/technical for implementers
- 📊 Case Studies (20-29): Real-world examples
- 💼 Business Strategy (30-35): For leaders/decision makers
- 🔬 Advanced Topics (40-49): Deep technical (collapsed by default)

### Benefits:
- Clear progression: beginner → intermediate → advanced
- Audience-specific paths (researcher, implementer, leader)
- Reduced cognitive load (5 categories vs 15+ flat items)
- Easy to find relevant content by expertise level

### Technical Implementation:
- Updated docs-app.js CATEGORIES object with new structure
- Updated categorizeDocument() to use order ranges (1-5, 10-19, 20-29, 30-35, 40-49)
- Created scripts/reorganize-docs-sidebar.js for automated metadata updates
- Reorganized 15 documents in MongoDB with new order/category/audience

### Production Deployment:
- ✅ Deployed architecture-diagram.png (887KB, RGB, 2400x2000)
- ✅ Deployed updated docs-app.js
- ✅ Ran reorganization script on tractatus_prod database
- ✅ Verified via API: correct categories and ordering

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

public/js/docs-app.js

@@ -7,13 +7,12 @@ if (typeof DocumentCards !== 'undefined') {
   documentCards = new DocumentCards('document-content');
 }
 
-// Document categorization
+// Document categorization - Organized by audience and expertise level
 const CATEGORIES = {
-  'getting-started': {
+  'introduction': {
-    label: '📘 Getting Started',
+    label: '📘 Introduction',
     icon: '📘',
-    categories: ['conceptual', 'reference'], // Matches document.category field
+    description: 'Start here - core concepts for all audiences',
-    slugs: ['architectural-overview', 'core-concepts', 'implementation-guide'],
     order: 1,
     color: 'blue',
     bgColor: 'bg-blue-50',
@@ -21,11 +20,10 @@ const CATEGORIES = {
     textColor: 'text-blue-700',
     collapsed: false
   },
-  'framework-details': {
+  'implementation': {
-    label: '📗 Framework Details',
+    label: '⚙️ Implementation',
-    icon: '📗',
+    icon: '⚙️',
-    categories: ['conceptual', 'practical'],
+    description: 'Practical guides for developers and implementers',
-    slugs: ['core-values', 'case-studies', 'business-case'],
     order: 2,
     color: 'green',
     bgColor: 'bg-green-50',
@@ -33,17 +31,38 @@ const CATEGORIES = {
     textColor: 'text-green-700',
     collapsed: false
   },
-  'reference': {
+  'case-studies': {
-    label: '📕 Reference',
+    label: '📊 Case Studies',
-    icon: '📕',
+    icon: '📊',
-    categories: ['reference'],
+    description: 'Real-world examples and failure analysis',
-    slugs: ['glossary'],
     order: 3,
     color: 'purple',
     bgColor: 'bg-purple-50',
     borderColor: 'border-l-4 border-purple-500',
     textColor: 'text-purple-700',
     collapsed: false
+  },
+  'business': {
+    label: '💼 Business Strategy',
+    icon: '💼',
+    description: 'ROI, business case, and strategic planning',
+    order: 4,
+    color: 'indigo',
+    bgColor: 'bg-indigo-50',
+    borderColor: 'border-l-4 border-indigo-500',
+    textColor: 'text-indigo-700',
+    collapsed: false
+  },
+  'advanced': {
+    label: '🔬 Advanced Topics',
+    icon: '🔬',
+    description: 'Deep technical details and research',
+    order: 5,
+    color: 'red',
+    bgColor: 'bg-red-50',
+    borderColor: 'border-l-4 border-red-500',
+    textColor: 'text-red-700',
+    collapsed: true  // Collapsed by default
   }
 };
 
@@ -56,7 +75,8 @@ const HIDDEN_DOCS = [
   'cover-letter'
 ];
 
-// Categorize a document based on order and category field
+// Categorize a document based on order field
+// Order ranges map to categories for audience/expertise-based organization
 function categorizeDocument(doc) {
   const slug = doc.slug.toLowerCase();
 
@@ -65,20 +85,35 @@ function categorizeDocument(doc) {
     return null;
   }
 
-  // Documents are pre-ordered by 'order' field (1-7 for public docs)
-  // Group by logical UI sections based on order
   const order = doc.order || 999;
 
-  if (order >= 1 && order <= 3) {
+  // Introduction: 1-5 (beginner level, all audiences)
-    return 'getting-started';
+  if (order >= 1 && order <= 5) {
-  } else if (order >= 4 && order <= 6) {
+    return 'introduction';
-    return 'framework-details';
-  } else if (order >= 7 && order <= 8) {
-    return 'reference';
   }
 
-  // Fallback to getting-started for uncategorized
+  // Implementation: 10-19 (practical/technical for implementers)
-  return 'getting-started';
+  if (order >= 10 && order <= 19) {
+    return 'implementation';
+  }
+
+  // Case Studies: 20-29 (real-world examples)
+  if (order >= 20 && order <= 29) {
+    return 'case-studies';
+  }
+
+  // Business Strategy: 30-35 (for leaders/decision makers)
+  if (order >= 30 && order <= 35) {
+    return 'business';
+  }
+
+  // Advanced Topics: 40-49 (deep technical/research)
+  if (order >= 40 && order <= 49) {
+    return 'advanced';
+  }
+
+  // Fallback to introduction for uncategorized (order 999)
+  return 'introduction';
 }
 
 // Group documents by category
@@ -176,7 +211,8 @@ async function loadDocuments() {
 
       // Render documents in category
       docs.forEach(doc => {
-        const isHighlighted = categoryId === 'getting-started' && doc.order === 1;
+        // Highlight the first document in Introduction category
+        const isHighlighted = categoryId === 'introduction' && doc.order === 1;
         html += renderDocLink(doc, isHighlighted);
       });
 
@@ -254,18 +290,18 @@ async function loadDocuments() {
       }
     });
 
-    // Auto-load first document in "Getting Started" category (order: 1)
+    // Auto-load first document in "Introduction" category (order: 1)
-    const gettingStartedDocs = grouped['getting-started'] || [];
+    const introductionDocs = grouped['introduction'] || [];
-    if (gettingStartedDocs.length > 0) {
+    if (introductionDocs.length > 0) {
-      // Load the architectural overview (order: 1) if available
+      // Load the first document (order: 1) if available
-      const archOverview = gettingStartedDocs.find(d => d.order === 1);
+      const firstDoc = introductionDocs.find(d => d.order === 1);
-      if (archOverview) {
+      if (firstDoc) {
-        loadDocument(archOverview.slug);
+        loadDocument(firstDoc.slug);
       } else {
-        loadDocument(gettingStartedDocs[0].slug);
+        loadDocument(introductionDocs[0].slug);
       }
     } else if (documents.length > 0) {
-      // Fallback to first available document
+      // Fallback to first available document in any category
       const firstCategory = sortedCategories.find(([catId]) => grouped[catId] && grouped[catId].length > 0);
       if (firstCategory) {
         loadDocument(grouped[firstCategory[0]][0].slug);

scripts/reorganize-docs-sidebar.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Reorganize docs.html sidebar - Update document metadata for better UX
+ *
+ * New structure based on audience and expertise level:
+ * - Introduction (1-5): Absolute beginners, all audiences
+ * - Implementation (10-19): Practical/technical for implementers
+ * - Case Studies (20-29): Real-world examples, all audiences
+ * - Business Strategy (30-35): Leaders/decision makers
+ * - Advanced Topics (40-49): Deep technical for experts
+ */
+
+const { MongoClient } = require('mongodb');
+require('dotenv').config();
+
+const MONGODB_URI = process.env.MONGODB_URI || 'mongodb://localhost:27017/tractatus_dev';
+
+// Document reorganization mapping
+// Format: { slug: { order, category, audience, description } }
+const DOCUMENT_MAPPING = {
+  // INTRODUCTION (1-5) - Absolute beginners, all audiences
+  'architectural-overview-and-research-status': {
+    order: 1,
+    category: 'introduction',
+    audience: 'general',
+    description: 'Start here - overview of the Tractatus Framework'
+  },
+  'core-concepts-of-the-tractatus-framework': {
+    order: 2,
+    category: 'introduction',
+    audience: 'general',
+    description: 'Core concepts and principles'
+  },
+  'tractatus-ai-safety-framework-core-values-and-principles': {
+    order: 3,
+    category: 'introduction',
+    audience: 'general',
+    description: 'Values and principles'
+  },
+  'technical-architecture': {
+    order: 4,
+    category: 'introduction',
+    audience: 'technical',
+    description: 'System architecture overview'
+  },
+  'tractatus-agentic-governance-system-glossary-of-terms': {
+    order: 5,
+    category: 'introduction',
+    audience: 'general',
+    description: 'Glossary and terminology'
+  },
+
+  // IMPLEMENTATION (10-19) - Practical/technical for implementers
+  'implementation-guide': {
+    order: 10,
+    category: 'implementation',
+    audience: 'implementer',
+    description: 'Complete implementation guide'
+  },
+  'tractatus-framework-implementation-guide': {
+    order: 11,
+    category: 'implementation',
+    audience: 'implementer',
+    description: 'Implementation guide v1.1 (detailed)'
+  },
+  'comparison-matrix-claude-code-claudemd-and-tractatus-framework': {
+    order: 12,
+    category: 'implementation',
+    audience: 'implementer',
+    description: 'Comparing different governance approaches'
+  },
+
+  // CASE STUDIES (20-29) - Real-world examples, all audiences
+  'the-27027-incident-a-case-study-in-pattern-recognition-bias': {
+    order: 20,
+    category: 'case-studies',
+    audience: 'general',
+    description: 'The famous 27027 incident - pattern recognition bias'
+  },
+  'our-framework-in-action-detecting-and-correcting-ai-fabrications': {
+    order: 21,
+    category: 'case-studies',
+    audience: 'general',
+    description: 'How Tractatus catches AI fabrications'
+  },
+  'when-frameworks-fail-and-why-thats-ok': {
+    order: 22,
+    category: 'case-studies',
+    audience: 'general',
+    description: 'Learning from framework failures'
+  },
+  'real-world-ai-governance-a-case-study-in-framework-failure-and-recovery': {
+    order: 23,
+    category: 'case-studies',
+    audience: 'general',
+    description: 'Failure analysis and recovery process'
+  },
+  'framework-governance-in-action-pre-publication-security-audit': {
+    order: 24,
+    category: 'case-studies',
+    audience: 'technical',
+    description: 'Security audit before publication'
+  },
+  'case-studies-real-world-llm-failure-modes': {
+    order: 25,
+    category: 'case-studies',
+    audience: 'researcher',
+    description: 'Collection of real-world LLM failures'
+  },
+
+  // BUSINESS STRATEGY (30-35) - Leaders/decision makers
+  'ai-governance-business-case-template-tractatus-framework': {
+    order: 30,
+    category: 'business',
+    audience: 'leader',
+    description: 'Business case template for AI governance'
+  }
+};
+
+async function reorganizeDocuments() {
+  console.log('╔════════════════════════════════════════════════════════════╗');
+  console.log('║   Reorganizing Documentation Sidebar Structure            ║');
+  console.log('╚════════════════════════════════════════════════════════════╝\n');
+
+  const client = new MongoClient(MONGODB_URI);
+
+  try {
+    await client.connect();
+    console.log('✓ Connected to MongoDB\n');
+
+    const db = client.db();
+    const documentsCollection = db.collection('documents');
+
+    // Get all documents
+    const allDocs = await documentsCollection.find({}).toArray();
+    console.log(`Found ${allDocs.length} total documents\n`);
+
+    let updated = 0;
+    let skipped = 0;
+
+    // Update each mapped document
+    for (const [slug, metadata] of Object.entries(DOCUMENT_MAPPING)) {
+      const doc = allDocs.find(d => d.slug === slug);
+
+      if (!doc) {
+        console.log(`⚠  Document not found: ${slug}`);
+        skipped++;
+        continue;
+      }
+
+      const updateFields = {
+        order: metadata.order,
+        category: metadata.category,
+        audience: metadata.audience,
+        updatedAt: new Date()
+      };
+
+      await documentsCollection.updateOne(
+        { slug },
+        { $set: updateFields }
+      );
+
+      console.log(`✓ Updated: ${doc.title}`);
+      console.log(`  Order: ${metadata.order} | Category: ${metadata.category} | Audience: ${metadata.audience}\n`);
+      updated++;
+    }
+
+    console.log('\n═══════════════════════════════════════════════════════════\n');
+    console.log(`✓ Updated: ${updated} documents`);
+    console.log(`⊘ Skipped: ${skipped} documents`);
+    console.log(`\n═══════════════════════════════════════════════════════════\n`);
+
+    // Show new category distribution
+    console.log('New Category Distribution:\n');
+
+    const categories = {
+      introduction: { count: 0, orders: '1-5' },
+      implementation: { count: 0, orders: '10-19' },
+      'case-studies': { count: 0, orders: '20-29' },
+      business: { count: 0, orders: '30-35' },
+      advanced: { count: 0, orders: '40-49' }
+    };
+
+    Object.values(DOCUMENT_MAPPING).forEach(meta => {
+      if (categories[meta.category]) {
+        categories[meta.category].count++;
+      }
+    });
+
+    console.log(`  📘 Introduction (${categories.introduction.count} docs) - Orders ${categories.introduction.orders}`);
+    console.log(`  ⚙️  Implementation (${categories.implementation.count} docs) - Orders ${categories.implementation.orders}`);
+    console.log(`  📊 Case Studies (${categories['case-studies'].count} docs) - Orders ${categories['case-studies'].orders}`);
+    console.log(`  💼 Business Strategy (${categories.business.count} docs) - Orders ${categories.business.orders}`);
+    console.log(`  🔬 Advanced Topics (${categories.advanced.count} docs) - Orders ${categories.advanced.orders}`);
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+  } finally {
+    await client.close();
+    console.log('\n✓ Database connection closed');
+  }
+}
+
+// Run
+reorganizeDocuments().catch(console.error);