diff --git a/public/images/architecture-diagram.png b/public/images/architecture-diagram.png index 06f0994d..ce62aaa4 100644 Binary files a/public/images/architecture-diagram.png and b/public/images/architecture-diagram.png differ diff --git a/public/js/docs-app.js b/public/js/docs-app.js index 3081ba29..04f4c757 100644 --- a/public/js/docs-app.js +++ b/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': { - label: 'šŸ“˜ Getting Started', + 'introduction': { + label: 'šŸ“˜ Introduction', icon: 'šŸ“˜', - categories: ['conceptual', 'reference'], // Matches document.category field - slugs: ['architectural-overview', 'core-concepts', 'implementation-guide'], + description: 'Start here - core concepts for all audiences', order: 1, color: 'blue', bgColor: 'bg-blue-50', @@ -21,11 +20,10 @@ const CATEGORIES = { textColor: 'text-blue-700', collapsed: false }, - 'framework-details': { - label: 'šŸ“— Framework Details', - icon: 'šŸ“—', - categories: ['conceptual', 'practical'], - slugs: ['core-values', 'case-studies', 'business-case'], + 'implementation': { + label: 'āš™ļø Implementation', + icon: 'āš™ļø', + description: 'Practical guides for developers and implementers', order: 2, color: 'green', bgColor: 'bg-green-50', @@ -33,17 +31,38 @@ const CATEGORIES = { textColor: 'text-green-700', collapsed: false }, - 'reference': { - label: 'šŸ“• Reference', - icon: 'šŸ“•', - categories: ['reference'], - slugs: ['glossary'], + 'case-studies': { + label: 'šŸ“Š Case Studies', + icon: 'šŸ“Š', + description: 'Real-world examples and failure analysis', 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) { - return 'getting-started'; - } else if (order >= 4 && order <= 6) { - return 'framework-details'; - } else if (order >= 7 && order <= 8) { - return 'reference'; + // Introduction: 1-5 (beginner level, all audiences) + if (order >= 1 && order <= 5) { + return 'introduction'; } - // Fallback to getting-started for uncategorized - return 'getting-started'; + // Implementation: 10-19 (practical/technical for implementers) + 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) - const gettingStartedDocs = grouped['getting-started'] || []; - if (gettingStartedDocs.length > 0) { - // Load the architectural overview (order: 1) if available - const archOverview = gettingStartedDocs.find(d => d.order === 1); - if (archOverview) { - loadDocument(archOverview.slug); + // Auto-load first document in "Introduction" category (order: 1) + const introductionDocs = grouped['introduction'] || []; + if (introductionDocs.length > 0) { + // Load the first document (order: 1) if available + const firstDoc = introductionDocs.find(d => d.order === 1); + if (firstDoc) { + 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); diff --git a/scripts/reorganize-docs-sidebar.js b/scripts/reorganize-docs-sidebar.js new file mode 100755 index 00000000..636e5c73 --- /dev/null +++ b/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);