@bluefly/openstandardagents 0.2.4 → 0.2.5-RC

package/website/app/schema/page.tsx

@@ -1,18 +1,58 @@
 import Link from 'next/link';
 import { SchemaExplorer } from '@/components/schema/SchemaExplorer';
-import { OSSA_VERSION } from '@/lib/version';
-
-// Import schema directly - this is bundled at build time
-const schemaJson = require('../../public/schemas/ossa-0.2.3.schema.json');
+import { SchemaComponentsAccordion } from '@/components/schema/SchemaComponentsAccordion';
+import { STABLE_VERSION, STABLE_VERSION_TAG, getSchemaPath } from '@/lib/version';
+import { Logo } from '@/components/Logo';
+import fs from 'fs';
+import path from 'path';
+
+// Get actual stable version from versions.json (not website package.json)
+function getStableVersion(): string {
+  try {
+    const versionsPath = path.join(process.cwd(), 'lib', 'versions.json');
+    if (fs.existsSync(versionsPath)) {
+      const versions = JSON.parse(fs.readFileSync(versionsPath, 'utf8'));
+      return versions.stable || '0.2.4';
+    }
+  } catch (error) {
+    console.error('Error reading versions.json:', error);
+  }
+  // Fallback to 0.2.4 if versions.json not available
+  return '0.2.4';
+}
 
-function loadSchema(): any {
-  // Return the imported schema directly
-  // This works in both development and production
-  return schemaJson;
+// Try to load schema dynamically - fallback to stable version
+function loadSchema(version?: string): any {
+  const stableVersion = version || getStableVersion();
+  try {
+    // Try to load from public/schemas first
+    const publicSchemaPath = path.join(process.cwd(), 'public', 'schemas', `ossa-${stableVersion}.schema.json`);
+    if (fs.existsSync(publicSchemaPath)) {
+      return JSON.parse(fs.readFileSync(publicSchemaPath, 'utf8'));
+    }
+    
+    // Fallback to spec directory
+    const specSchemaPath = path.join(process.cwd(), '..', 'spec', `v${stableVersion}`, `ossa-${stableVersion}.schema.json`);
+    if (fs.existsSync(specSchemaPath)) {
+      return JSON.parse(fs.readFileSync(specSchemaPath, 'utf8'));
+    }
+    
+    // Final fallback - try to require (for build time)
+    try {
+      return require(`../../public/schemas/ossa-${stableVersion}.schema.json`);
+    } catch {
+      // If all else fails, return null
+      return null;
+    }
+  } catch (error) {
+    console.error('Error loading schema:', error);
+    return null;
+  }
 }
 
 export default function SchemaPage() {
-  const schema = loadSchema();
+  const stableVersion = getStableVersion();
+  const schema = loadSchema(stableVersion);
 
   if (!schema) {
     return (
@@ -28,7 +68,7 @@ export default function SchemaPage() {
   return (
     <>
       {/* Hero Section */}
-      <div className="bg-gradient-to-br from-primary via-accent to-secondary text-white py-16 px-4">
+      <div className="bg-gradient-to-br from-secondary via-primary to-accent text-white py-16 px-4">
         <div className="container mx-auto max-w-6xl text-center">
           <div className="inline-flex items-center justify-center w-20 h-20 bg-white/20 backdrop-blur-sm rounded-full mb-6">
             <svg className="w-10 h-10" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -40,7 +80,7 @@ export default function SchemaPage() {
             Complete JSON Schema for defining portable, framework-agnostic AI agents
           </p>
           <p className="text-lg text-white/80">
-            Version v0.2.x • The OpenAPI for AI Agents
+            Version v{stableVersion} • The OpenAPI for AI Agents
           </p>
         </div>
       </div>
@@ -50,7 +90,7 @@ export default function SchemaPage() {
         <section className="mb-16">
           <div className="bg-gradient-to-br from-amber-50 via-orange-50 to-yellow-50 rounded-2xl p-8 mb-8">
             <div className="flex items-start mb-6">
-              <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4 flex-shrink-0">
+              <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4 flex-shrink-0">
                 <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                   <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8.228 9c.549-1.165 2.03-2 3.772-2 2.21 0 4 1.343 4 3 0 1.4-1.278 2.575-3.006 2.907-.542.104-.994.54-.994 1.093m0 3h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
                 </svg>
@@ -80,7 +120,7 @@ export default function SchemaPage() {
         {/* Schema Architecture Diagram */}
         <section className="mb-16">
           <div className="flex items-center mb-8">
-            <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
               </svg>
@@ -97,29 +137,42 @@ export default function SchemaPage() {
 
             <div className="space-y-6">
               {/* Root */}
-              <div className="bg-gradient-to-r from-primary to-secondary text-white rounded-xl p-6 text-center shadow-md">
+              <div className="bg-gradient-to-r from-secondary via-primary to-accent text-white rounded-xl p-6 text-center shadow-md">
                 <div className="font-bold text-2xl mb-2">OSSA Agent Manifest</div>
                 <div className="text-base opacity-90">agent.yaml / agent.json</div>
               </div>
 
               {/* Top Level Fields */}
               <div className="grid md:grid-cols-3 gap-6">
-                <div className="bg-blue-50 border-3 border-blue-400 rounded-xl p-6 shadow-sm hover:shadow-md transition-shadow">
-                  <div className="font-bold text-blue-900 mb-3 text-xl">apiVersion</div>
-                  <div className="text-base text-gray-700 font-mono">ossa/v0.2.3</div>
-                </div>
-                <div className="bg-green-50 border-3 border-green-400 rounded-xl p-6 shadow-sm hover:shadow-md transition-shadow">
-                  <div className="font-bold text-green-900 mb-3 text-xl">kind</div>
-                  <div className="text-base text-gray-700 font-mono">Agent</div>
+                <div className="bg-blue-50/50 border-2 border-blue-200 rounded-xl p-6 shadow-sm hover:shadow-md transition-shadow">
+                  <div className="font-bold text-gray-900 mb-2 text-xl">apiVersion</div>
+                  <div className="text-base text-gray-600 mb-3">Specifies the OSSA specification version</div>
+                  <div className="text-lg text-gray-800 font-mono">ossa/v{stableVersion}</div>
+                </div>
+                <div className="bg-green-50/50 border-2 border-green-200 rounded-xl p-6 shadow-sm hover:shadow-md transition-shadow">
+                  <div className="font-bold text-gray-900 mb-2 text-xl">kind</div>
+                  <div className="text-base text-gray-600 mb-3">Resource type identifier that specifies what type of OSSA resource this manifest defines.</div>
+                  <div className="text-lg text-gray-800 font-mono mb-3">Agent</div>
+                  <div className="text-sm text-gray-700 space-y-2 pt-3 border-t border-green-200">
+                    <p><strong className="text-gray-900">Agent</strong> is the primary resource type in OSSA. An Agent represents an autonomous AI system that can:</p>
+                    <ul className="list-disc list-inside space-y-1 text-gray-600 ml-2">
+                      <li>Process natural language instructions</li>
+                      <li>Make decisions and take actions</li>
+                      <li>Use tools and interact with external systems</li>
+                      <li>Maintain context and state across interactions</li>
+                    </ul>
+                    <p className="text-gray-600">Think of an Agent as a reusable, portable definition of an AI assistant that can be deployed to any framework.</p>
+                  </div>
                 </div>
-                <div className="bg-purple-50 border-3 border-purple-400 rounded-xl p-6 shadow-sm hover:shadow-md transition-shadow">
-                  <div className="font-bold text-purple-900 mb-3 text-xl">metadata</div>
-                  <div className="text-sm text-gray-700 space-y-2">
-                    <div>• name</div>
-                    <div>• version</div>
-                    <div>• description</div>
-                    <div>• labels</div>
-                    <div>• annotations</div>
+                <div className="bg-purple-50/50 border-2 border-purple-200 rounded-xl p-6 shadow-sm hover:shadow-md transition-shadow">
+                  <div className="font-bold text-gray-900 mb-2 text-xl">metadata</div>
+                  <div className="text-base text-gray-600 mb-3">Agent identification and labeling</div>
+                  <div className="text-base text-gray-700 space-y-1.5 mt-3">
+                    <div>• name - Unique agent identifier</div>
+                    <div>• version - Agent version number</div>
+                    <div>• description - Human-readable description</div>
+                    <div>• labels - Key-value metadata tags</div>
+                    <div>• annotations - Additional metadata</div>
                   </div>
                 </div>
               </div>
@@ -127,143 +180,158 @@ export default function SchemaPage() {
               {/* Main Content: spec and extensions - STACKED */}
               <div className="space-y-6">
                 {/* spec */}
-                <div className="bg-gradient-to-br from-primary/5 to-primary/10 border-3 border-primary rounded-xl p-6 shadow-md">
-                  <div className="font-bold text-primary text-2xl mb-5">spec</div>
+                <div className="bg-gradient-to-br from-blue-50/30 to-indigo-50/30 border-2 border-blue-200 rounded-xl p-6 shadow-md">
+                  <div className="font-bold text-primary text-2xl mb-3">spec</div>
+                  <div className="text-base text-gray-700 mb-6">Core agent configuration including behavior, capabilities, and operational settings.</div>
                   <div className="space-y-3">
                     {/* role */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-2 flex items-center">
-                        <span className="mr-2">🎭</span> role
-                      </div>
-                      <div className="text-sm text-gray-700 mb-2">System prompt / identity</div>
-                      <div className="text-xs text-gray-600 bg-gray-50 rounded p-2 font-mono">
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2">role</div>
+                      <div className="text-base text-gray-700 mb-3">Defines the agent's system prompt and identity. This is the core instruction that tells the agent who it is and how it should behave.</div>
+                      <div className="text-sm text-gray-600 bg-gray-50 rounded p-3 font-mono border border-gray-200">
                         type: string (multi-line)
                       </div>
                     </div>
 
                     {/* llm */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-3 flex items-center">
-                        <span className="mr-2">🧠</span> llm
-                      </div>
-                      <div className="grid grid-cols-2 gap-2 text-sm text-gray-700">
-                        <div className="bg-blue-50 rounded p-2">
-                          <strong>provider</strong>: openai | anthropic | azure
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2">llm</div>
+                      <div className="text-base text-gray-700 mb-4">Configuration for the Large Language Model that powers the agent's reasoning and responses.</div>
+                      <div className="grid grid-cols-2 gap-3 text-base text-gray-700">
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">provider</strong>
+                          <div className="text-sm text-gray-600 mt-1">openai | anthropic | azure</div>
                         </div>
-                        <div className="bg-blue-50 rounded p-2">
-                          <strong>model</strong>: gpt-4, claude-3, etc.
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">model</strong>
+                          <div className="text-sm text-gray-600 mt-1">gpt-4, claude-3, etc.</div>
                         </div>
-                        <div className="bg-blue-50 rounded p-2">
-                          <strong>temperature</strong>: 0.0 - 2.0
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">temperature</strong>
+                          <div className="text-sm text-gray-600 mt-1">0.0 - 2.0 (creativity level)</div>
                         </div>
-                        <div className="bg-blue-50 rounded p-2">
-                          <strong>max_tokens</strong>: integer
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">max_tokens</strong>
+                          <div className="text-sm text-gray-600 mt-1">Maximum response length</div>
                         </div>
                       </div>
                     </div>
 
                     {/* tools */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-3 flex items-center">
-                        <span className="mr-2">🔧</span> tools
-                      </div>
-                      <div className="text-sm text-gray-700 space-y-2">
-                        <div className="bg-purple-50 border border-purple-200 rounded p-2">
-                          <strong>http</strong>: REST API calls
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2">tools</div>
+                      <div className="text-base text-gray-700 mb-4">Capabilities the agent can use to interact with external systems and perform actions.</div>
+                      <div className="text-base text-gray-700 space-y-2.5">
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">http</strong>
+                          <div className="text-sm text-gray-600 mt-1">Make REST API calls to external services</div>
                         </div>
-                        <div className="bg-green-50 border border-green-200 rounded p-2">
-                          <strong>code</strong>: Execute Python/JS/Shell
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">code</strong>
+                          <div className="text-sm text-gray-600 mt-1">Execute Python, JavaScript, or Shell scripts</div>
                         </div>
-                        <div className="bg-yellow-50 border border-yellow-200 rounded p-2">
-                          <strong>database</strong>: SQL queries
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">database</strong>
+                          <div className="text-sm text-gray-600 mt-1">Run SQL queries against databases</div>
                         </div>
-                        <div className="bg-pink-50 border border-pink-200 rounded p-2">
-                          <strong>file</strong>: Read/write operations
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">file</strong>
+                          <div className="text-sm text-gray-600 mt-1">Read and write file system operations</div>
                         </div>
-                        <div className="bg-cyan-50 border border-cyan-200 rounded p-2">
-                          <strong>search</strong>: Web/vector search
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">search</strong>
+                          <div className="text-sm text-gray-600 mt-1">Web search and vector similarity search</div>
                         </div>
                       </div>
                     </div>
 
                     {/* taxonomy */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-3 flex items-center">
-                        <span className="mr-2">🏷️</span> taxonomy
-                      </div>
-                      <div className="grid grid-cols-2 gap-2 text-xs">
-                        <div className="bg-orange-50 rounded p-2">
-                          <strong>domain</strong>: customer_service, engineering, etc.
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2">taxonomy</div>
+                      <div className="text-base text-gray-700 mb-4">Categorization metadata for organizing and discovering agents across domains and use cases.</div>
+                      <div className="grid grid-cols-2 gap-3 text-base">
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">domain</strong>
+                          <div className="text-sm text-gray-600 mt-1">customer_service, engineering, etc.</div>
                         </div>
-                        <div className="bg-orange-50 rounded p-2">
-                          <strong>subdomain</strong>: technical_support, devops, etc.
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">subdomain</strong>
+                          <div className="text-sm text-gray-600 mt-1">technical_support, devops, etc.</div>
                         </div>
-                        <div className="bg-orange-50 rounded p-2">
-                          <strong>use_case</strong>: troubleshooting, automation
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">use_case</strong>
+                          <div className="text-sm text-gray-600 mt-1">troubleshooting, automation</div>
                         </div>
-                        <div className="bg-orange-50 rounded p-2">
-                          <strong>industry</strong>: saas, healthcare, finance
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">industry</strong>
+                          <div className="text-sm text-gray-600 mt-1">saas, healthcare, finance</div>
                         </div>
                       </div>
                     </div>
 
                     {/* autonomy */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-3 flex items-center">
-                        <span className="mr-2">🎯</span> autonomy
-                      </div>
-                      <div className="space-y-2 text-sm">
-                        <div className="bg-red-50 border border-red-200 rounded p-2">
-                          <strong>level</strong>: L0 (no autonomy) → L5 (full autonomy)
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2">autonomy</div>
+                      <div className="text-base text-gray-700 mb-4">Controls how independently the agent can operate, from fully manual (L0) to fully autonomous (L5).</div>
+                      <div className="space-y-2.5 text-base">
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">level</strong>
+                          <div className="text-sm text-gray-600 mt-1">L0 (no autonomy) → L5 (full autonomy)</div>
                         </div>
-                        <div className="bg-yellow-50 border border-yellow-200 rounded p-2">
-                          <strong>approval_required</strong>: Actions needing approval
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">approval_required</strong>
+                          <div className="text-sm text-gray-600 mt-1">List of actions that require human approval before execution</div>
                         </div>
-                        <div className="bg-green-50 border border-green-200 rounded p-2">
-                          <strong>human_in_loop</strong>: Notification settings
+                        <div className="bg-gray-50 border border-gray-200 rounded-lg p-3">
+                          <strong className="text-gray-900">human_in_loop</strong>
+                          <div className="text-sm text-gray-600 mt-1">Notification and escalation settings for human oversight</div>
                         </div>
                       </div>
                     </div>
 
                     {/* observability */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-3 flex items-center">
-                        <span className="mr-2">📊</span> observability
-                      </div>
-                      <div className="grid grid-cols-3 gap-2 text-xs">
-                        <div className="bg-indigo-50 rounded p-2 text-center">
-                          <div className="font-bold">logging</div>
-                          <div className="text-gray-600">Logs & audit</div>
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2">observability</div>
+                      <div className="text-base text-gray-700 mb-4">Monitoring and debugging capabilities for tracking agent behavior and performance.</div>
+                      <div className="grid grid-cols-3 gap-3 text-base">
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200 text-center">
+                          <div className="font-bold text-gray-900">logging</div>
+                          <div className="text-sm text-gray-600 mt-1">Logs & audit trails</div>
                         </div>
-                        <div className="bg-purple-50 rounded p-2 text-center">
-                          <div className="font-bold">metrics</div>
-                          <div className="text-gray-600">Performance</div>
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200 text-center">
+                          <div className="font-bold text-gray-900">metrics</div>
+                          <div className="text-sm text-gray-600 mt-1">Performance data</div>
                         </div>
-                        <div className="bg-pink-50 rounded p-2 text-center">
-                          <div className="font-bold">tracing</div>
-                          <div className="text-gray-600">Execution paths</div>
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200 text-center">
+                          <div className="font-bold text-gray-900">tracing</div>
+                          <div className="text-sm text-gray-600 mt-1">Execution paths</div>
                         </div>
                       </div>
                     </div>
 
                     {/* constraints (additional) */}
-                    <div className="bg-white rounded-lg p-4 border-2 border-primary/30 shadow-sm hover:shadow-md transition-all hover:border-primary/50">
-                      <div className="font-semibold text-primary text-base mb-3 flex items-center">
-                        <span className="mr-2">⚠️</span> constraints
-                        <span className="ml-2 text-xs bg-gray-200 text-gray-700 px-2 py-0.5 rounded">Optional</span>
+                    <div className="bg-white rounded-lg p-5 border-2 border-gray-200 shadow-sm hover:shadow-md transition-all">
+                      <div className="font-bold text-gray-900 text-lg mb-2 flex items-center gap-2">
+                        constraints
+                        <span className="text-sm bg-gray-200 text-gray-700 px-2 py-1 rounded font-normal">Optional</span>
                       </div>
-                      <div className="grid grid-cols-2 gap-2 text-xs">
-                        <div className="bg-red-50 rounded p-2">
-                          <strong>cost</strong>: Budget limits
+                      <div className="text-base text-gray-700 mb-4">Resource limits and operational boundaries to ensure safe and controlled agent execution.</div>
+                      <div className="grid grid-cols-2 gap-3 text-base">
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">cost</strong>
+                          <div className="text-sm text-gray-600 mt-1">Budget and spending limits</div>
                         </div>
-                        <div className="bg-yellow-50 rounded p-2">
-                          <strong>performance</strong>: Timeout, rate limits
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">performance</strong>
+                          <div className="text-sm text-gray-600 mt-1">Timeout and rate limiting</div>
                         </div>
-                        <div className="bg-blue-50 rounded p-2">
-                          <strong>resources</strong>: Memory, CPU caps
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">resources</strong>
+                          <div className="text-sm text-gray-600 mt-1">Memory and CPU constraints</div>
                         </div>
-                        <div className="bg-green-50 rounded p-2">
-                          <strong>security</strong>: Access controls
+                        <div className="bg-gray-50 rounded-lg p-3 border border-gray-200">
+                          <strong className="text-gray-900">security</strong>
+                          <div className="text-sm text-gray-600 mt-1">Access control and permissions</div>
                         </div>
                       </div>
                     </div>
@@ -271,26 +339,32 @@ export default function SchemaPage() {
                 </div>
 
                 {/* extensions */}
-                <div className="bg-gradient-to-br from-secondary/5 to-secondary/10 border-3 border-secondary rounded-xl p-6 shadow-md">
-                  <div className="font-bold text-secondary text-2xl mb-4">extensions</div>
-                  <div className="text-base text-gray-800 mb-4 font-semibold">Framework-specific configs:</div>
-                  <div className="grid grid-cols-2 gap-3 text-sm">
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• kAgent</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• BuildKit</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• LangChain</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• CrewAI</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• OpenAI</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• Anthropic</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• Cursor</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• Langflow</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• AutoGen</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• Vercel AI</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• LlamaIndex</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• LangGraph</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• Drupal</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• LibreChat</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow">• MCP</div>
-                    <div className="bg-white rounded-lg px-3 py-2.5 border-2 border-secondary/30 shadow-sm hover:shadow-md transition-shadow text-center col-span-2 font-semibold">+ 10 more frameworks</div>
+                <div className="bg-gradient-to-br from-purple-50/30 to-pink-50/30 border-2 border-purple-200 rounded-xl p-6 shadow-md">
+                  <div className="font-bold text-secondary text-2xl mb-3">extensions</div>
+                  <div className="text-base text-gray-700 mb-6">Optional framework-specific configurations that extend the core OSSA specification for platform-specific features.</div>
+                  <div className="text-base text-gray-800 mb-6 font-semibold">Supported frameworks:</div>
+                  <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 xl:grid-cols-6 gap-4">
+                    <Logo domain="kagent.dev" name="kAgent" />
+                    <Logo domain="langchain.com" name="LangChain" />
+                    <Logo domain="crewai.com" name="CrewAI" />
+                    <Logo domain="openai.com" name="OpenAI" />
+                    <Logo domain="anthropic.com" name="Anthropic" />
+                    <Logo domain="cursor.sh" name="Cursor" />
+                    <Logo domain="langflow.com" name="Langflow" />
+                    <Logo domain="microsoft.com" name="AutoGen" />
+                    <Logo domain="vercel.com" name="Vercel AI" />
+                    <Logo domain="llamaindex.ai" name="LlamaIndex" />
+                    <Logo domain="langchain.com" name="LangGraph" />
+                    <Logo domain="drupal.org" name="Drupal" />
+                    <Logo domain="librechat.com" name="LibreChat" />
+                    <Logo domain="modelcontextprotocol.io" name="MCP" />
+                    <Logo domain="huggingface.co" name="Hugging Face" />
+                    <Logo domain="google.com" name="Google" />
+                    <Logo domain="aws.amazon.com" name="AWS" />
+                    <Logo domain="azure.com" name="Azure" />
+                    <Logo domain="github.com" name="GitHub" />
+                    <Logo domain="docker.com" name="Docker" />
+                    <Logo domain="kubernetes.io" name="Kubernetes" />
                   </div>
                 </div>
               </div>
@@ -301,7 +375,7 @@ export default function SchemaPage() {
         {/* Data Flow Diagram */}
         <section className="mb-16">
           <div className="flex items-center mb-8">
-            <div className="w-12 h-12 bg-gradient-to-br from-secondary to-primary rounded-lg flex items-center justify-center mr-4">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
               </svg>
@@ -381,124 +455,137 @@ export default function SchemaPage() {
           </div>
 
           {/* Visual Data Flow Diagram - Clean HTML/CSS Version */}
-          <div className="bg-gradient-to-br from-blue-50 to-cyan-50 rounded-2xl p-8 border-2 border-blue-300">
-            <h3 className="text-2xl font-bold mb-8 text-center text-gray-900">Complete Agent Lifecycle</h3>
+          <div className="bg-gradient-to-br from-gray-50 to-gray-100 rounded-2xl p-8 border-2 border-gray-300">
+            <h3 className="text-2xl font-bold mb-4 text-center text-gray-900">Complete Agent Lifecycle</h3>
+            <p className="text-center text-gray-600 mb-8 text-base">From development to deployment across any framework</p>
 
             <div className="space-y-6">
               {/* Step 1: Developer */}
               <div className="flex flex-col items-center">
-                <div className="bg-gradient-to-r from-purple-500 to-purple-600 text-white rounded-xl p-6 shadow-lg w-full max-w-md text-center">
-                  <div className="text-lg font-bold mb-2">👨‍💻 Developer</div>
-                  <div className="text-base">Writes OSSA Manifest</div>
-                  <div className="text-sm mt-2 opacity-90">agent.yaml</div>
+                <div className="bg-white border-2 border-gray-300 rounded-xl p-6 shadow-md w-full max-w-md text-center">
+                  <div className="text-lg font-bold mb-2 text-gray-900">Developer</div>
+                  <div className="text-base text-gray-700">Writes OSSA Manifest</div>
+                  <div className="text-sm mt-2 text-gray-600 font-mono">agent.yaml</div>
                 </div>
-                <div className="w-1 h-12 bg-gradient-to-b from-purple-500 to-blue-500"></div>
+                <div className="w-0.5 h-12 bg-gray-300"></div>
               </div>
 
               {/* Step 2: Validation */}
               <div className="flex flex-col items-center">
                 <div className="grid md:grid-cols-2 gap-4 w-full max-w-4xl">
-                  <div className="bg-gradient-to-r from-blue-500 to-blue-600 text-white rounded-xl p-6 shadow-lg">
-                    <div className="text-lg font-bold mb-2">🔍 OSSA Schema Validator</div>
+                  <div className="bg-gray-800 text-white rounded-xl p-6 shadow-lg">
+                    <div className="text-lg font-bold mb-2">OSSA Schema Validator</div>
                     <div className="text-sm opacity-90">JSON Schema validation engine</div>
                   </div>
-                  <div className="bg-white border-2 border-blue-400 rounded-xl p-6 shadow-md">
-                    <div className="text-base font-bold text-blue-900 mb-3">Validation Checks:</div>
-                    <div className="space-y-1 text-sm text-gray-700">
-                      <div>✓ Required fields present</div>
-                      <div>✓ Correct types</div>
-                      <div>✓ Value constraints</div>
-                      <div>✓ Schema compliance</div>
+                  <div className="bg-white border-2 border-gray-300 rounded-xl p-6 shadow-md">
+                    <div className="text-base font-bold text-gray-900 mb-3">Validation Checks:</div>
+                    <div className="space-y-2 text-sm text-gray-700">
+                      <div className="flex items-center">
+                        <span className="text-green-600 mr-2">✓</span>
+                        <span>Required fields present</span>
+                      </div>
+                      <div className="flex items-center">
+                        <span className="text-green-600 mr-2">✓</span>
+                        <span>Correct types</span>
+                      </div>
+                      <div className="flex items-center">
+                        <span className="text-green-600 mr-2">✓</span>
+                        <span>Value constraints</span>
+                      </div>
+                      <div className="flex items-center">
+                        <span className="text-green-600 mr-2">✓</span>
+                        <span>Schema compliance</span>
+                      </div>
                     </div>
                   </div>
                 </div>
-                <div className="w-1 h-12 bg-gradient-to-b from-blue-500 to-green-500"></div>
-                <div className="bg-green-500 text-white px-6 py-2 rounded-full font-bold shadow-md">
-                  ✓ Valid Manifest
+                <div className="w-0.5 h-12 bg-gray-300"></div>
+                <div className="bg-gray-800 text-white px-6 py-2 rounded-full font-bold shadow-md">
+                  Valid Manifest
                 </div>
-                <div className="w-1 h-12 bg-gradient-to-b from-green-500 to-orange-500"></div>
+                <div className="w-0.5 h-12 bg-gray-300"></div>
               </div>
 
               {/* Step 3: Framework Adapter Layer */}
               <div className="flex flex-col items-center">
-                <div className="bg-gradient-to-r from-orange-500 to-orange-600 text-white rounded-xl p-6 shadow-lg w-full max-w-3xl text-center">
-                  <div className="text-xl font-bold mb-2">⚙️ Framework Adapter Layer</div>
+                <div className="bg-gray-800 text-white rounded-xl p-6 shadow-lg w-full max-w-3xl text-center">
+                  <div className="text-xl font-bold mb-2">Framework Adapter Layer</div>
                   <div className="text-base opacity-90">Converts OSSA → Framework-Specific Config</div>
                 </div>
                 <div className="flex space-x-2 mt-4">
-                  <div className="w-1 h-12 bg-gradient-to-b from-orange-500 to-indigo-500"></div>
-                  <div className="w-1 h-12 bg-gradient-to-b from-orange-500 to-purple-500"></div>
-                  <div className="w-1 h-12 bg-gradient-to-b from-orange-500 to-pink-500"></div>
-                  <div className="w-1 h-12 bg-gradient-to-b from-orange-500 to-cyan-500"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
                 </div>
               </div>
 
               {/* Step 4: Runtimes */}
               <div className="flex flex-col items-center">
                 <div className="grid md:grid-cols-4 gap-4 w-full max-w-5xl">
-                  <div className="bg-gradient-to-br from-indigo-500 to-indigo-600 text-white rounded-xl p-5 shadow-lg text-center">
-                    <div className="text-base font-bold mb-2">🚀 kAgent</div>
-                    <div className="text-xs opacity-90">Runtime</div>
+                  <div className="bg-white border-2 border-gray-300 rounded-xl p-5 shadow-md text-center">
+                    <div className="text-base font-bold mb-2 text-gray-900">kAgent</div>
+                    <div className="text-xs text-gray-600">Runtime</div>
                   </div>
-                  <div className="bg-gradient-to-br from-purple-500 to-purple-600 text-white rounded-xl p-5 shadow-lg text-center">
-                    <div className="text-base font-bold mb-2">🔗 LangChain</div>
-                    <div className="text-xs opacity-90">Runtime</div>
+                  <div className="bg-white border-2 border-gray-300 rounded-xl p-5 shadow-md text-center">
+                    <div className="text-base font-bold mb-2 text-gray-900">LangChain</div>
+                    <div className="text-xs text-gray-600">Runtime</div>
                   </div>
-                  <div className="bg-gradient-to-br from-pink-500 to-pink-600 text-white rounded-xl p-5 shadow-lg text-center">
-                    <div className="text-base font-bold mb-2">👥 CrewAI</div>
-                    <div className="text-xs opacity-90">Runtime</div>
+                  <div className="bg-white border-2 border-gray-300 rounded-xl p-5 shadow-md text-center">
+                    <div className="text-base font-bold mb-2 text-gray-900">CrewAI</div>
+                    <div className="text-xs text-gray-600">Runtime</div>
                   </div>
-                  <div className="bg-gradient-to-br from-cyan-500 to-cyan-600 text-white rounded-xl p-5 shadow-lg text-center">
-                    <div className="text-base font-bold mb-2">🤖 OpenAI</div>
-                    <div className="text-xs opacity-90">Runtime</div>
+                  <div className="bg-white border-2 border-gray-300 rounded-xl p-5 shadow-md text-center">
+                    <div className="text-base font-bold mb-2 text-gray-900">OpenAI</div>
+                    <div className="text-xs text-gray-600">Runtime</div>
                   </div>
                 </div>
                 <div className="flex justify-center mt-4 space-x-2">
-                  <div className="w-1 h-12 bg-gradient-to-b from-indigo-500 to-teal-500"></div>
-                  <div className="w-1 h-12 bg-gradient-to-b from-purple-500 to-teal-500"></div>
-                  <div className="w-1 h-12 bg-gradient-to-b from-pink-500 to-teal-500"></div>
-                  <div className="w-1 h-12 bg-gradient-to-b from-cyan-500 to-teal-500"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
+                  <div className="w-0.5 h-12 bg-gray-300"></div>
                 </div>
               </div>
 
               {/* Step 5: Agent Execution */}
               <div className="flex flex-col items-center">
-                <div className="bg-gradient-to-r from-teal-500 to-teal-600 text-white rounded-xl p-6 shadow-lg w-full max-w-2xl">
-                  <div className="text-xl font-bold mb-4 text-center">⚡ Agent Execution</div>
-                  <div className="grid grid-cols-3 gap-3 text-sm">
-                    <div className="bg-white/20 backdrop-blur-sm rounded-lg p-3 text-center">
-                      <div className="font-bold mb-1">🧠 LLM Calls</div>
-                      <div className="text-xs opacity-90">GPT-4, Claude, etc.</div>
+                <div className="bg-white border-2 border-gray-300 rounded-xl p-6 shadow-md w-full max-w-2xl">
+                  <div className="text-xl font-bold mb-4 text-center text-gray-900">Agent Execution</div>
+                  <div className="grid grid-cols-3 gap-3 text-base">
+                    <div className="bg-gray-50 border border-gray-200 rounded-lg p-3 text-center">
+                      <div className="font-bold mb-1 text-gray-900">LLM Calls</div>
+                      <div className="text-sm text-gray-600">GPT-4, Claude, etc.</div>
                     </div>
-                    <div className="bg-white/20 backdrop-blur-sm rounded-lg p-3 text-center">
-                      <div className="font-bold mb-1">🔧 Tool Usage</div>
-                      <div className="text-xs opacity-90">APIs, Code, DB</div>
+                    <div className="bg-gray-50 border border-gray-200 rounded-lg p-3 text-center">
+                      <div className="font-bold mb-1 text-gray-900">Tool Usage</div>
+                      <div className="text-sm text-gray-600">APIs, Code, DB</div>
                     </div>
-                    <div className="bg-white/20 backdrop-blur-sm rounded-lg p-3 text-center">
-                      <div className="font-bold mb-1">📋 Task Processing</div>
-                      <div className="text-xs opacity-90">Execute workflows</div>
+                    <div className="bg-gray-50 border border-gray-200 rounded-lg p-3 text-center">
+                      <div className="font-bold mb-1 text-gray-900">Task Processing</div>
+                      <div className="text-sm text-gray-600">Execute workflows</div>
                     </div>
                   </div>
                 </div>
-                <div className="w-1 h-12 bg-gradient-to-b from-teal-500 to-amber-500"></div>
+                <div className="w-0.5 h-12 bg-gray-300"></div>
               </div>
 
               {/* Step 6: Observability */}
               <div className="flex flex-col items-center">
-                <div className="bg-gradient-to-r from-amber-500 to-amber-600 text-white rounded-xl p-6 shadow-lg w-full max-w-2xl">
-                  <div className="text-xl font-bold mb-4 text-center">📊 Observability</div>
-                  <div className="grid grid-cols-3 gap-3 text-sm">
-                    <div className="bg-white/20 backdrop-blur-sm rounded-lg p-3 text-center">
-                      <div className="font-bold mb-1">📝 Logs</div>
-                      <div className="text-xs opacity-90">Debug & audit</div>
+                <div className="bg-white border-2 border-gray-300 rounded-xl p-6 shadow-md w-full max-w-2xl">
+                  <div className="text-xl font-bold mb-4 text-center text-gray-900">Observability</div>
+                  <div className="grid grid-cols-3 gap-3 text-base">
+                    <div className="bg-gray-50 border border-gray-200 rounded-lg p-3 text-center">
+                      <div className="font-bold mb-1 text-gray-900">Logs</div>
+                      <div className="text-sm text-gray-600">Debug & audit</div>
                     </div>
-                    <div className="bg-white/20 backdrop-blur-sm rounded-lg p-3 text-center">
-                      <div className="font-bold mb-1">📈 Metrics</div>
-                      <div className="text-xs opacity-90">Performance data</div>
+                    <div className="bg-gray-50 border border-gray-200 rounded-lg p-3 text-center">
+                      <div className="font-bold mb-1 text-gray-900">Metrics</div>
+                      <div className="text-sm text-gray-600">Performance data</div>
                     </div>
-                    <div className="bg-white/20 backdrop-blur-sm rounded-lg p-3 text-center">
-                      <div className="font-bold mb-1">🔍 Traces</div>
-                      <div className="text-xs opacity-90">Execution paths</div>
+                    <div className="bg-gray-50 border border-gray-200 rounded-lg p-3 text-center">
+                      <div className="font-bold mb-1 text-gray-900">Traces</div>
+                      <div className="text-sm text-gray-600">Execution paths</div>
                     </div>
                   </div>
                 </div>
@@ -509,8 +596,8 @@ export default function SchemaPage() {
 
         {/* Core Components Breakdown */}
         <section className="mb-16">
-          <div className="flex items-center mb-8">
-            <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4">
+          <div className="flex items-center mb-6">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2V6zM14 6a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V6zM4 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2H6a2 2 0 01-2-2v-2zM14 16a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z" />
               </svg>
@@ -518,51 +605,50 @@ export default function SchemaPage() {
             <h2 className="text-3xl font-bold text-primary">Schema Components</h2>
           </div>
 
-          <div className="grid gap-6">
-            {/* apiVersion & kind */}
-            <div className="card p-6 border-l-4 border-primary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-primary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🔖</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-primary mb-3">apiVersion & kind</h3>
-                  <div className="space-y-3">
+          <p className="text-lg text-gray-700 mb-8 max-w-4xl">
+            The OSSA schema is organized into core components that define every aspect of an AI agent.
+            Each component serves a specific purpose in creating portable, framework-agnostic agent definitions.
+            Click on any component below to learn more about its structure, purpose, and usage.
+          </p>
+
+          <SchemaComponentsAccordion
+            items={[
+              {
+                id: 'apiversion-kind',
+                title: 'apiVersion & kind',
+                borderColor: 'border-primary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Version identifier and resource type for the manifest.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">Enables schema evolution while maintaining backward compatibility. Like Kubernetes resources or OpenAPI specs, agents can evolve without breaking existing definitions.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`apiVersion: ossa/v0.2.3
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`apiVersion: ossa/v${stableVersion}
 kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* metadata */}
-            <div className="card p-6 border-l-4 border-secondary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-secondary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">📋</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-secondary mb-3">metadata</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'metadata',
+                title: 'metadata',
+                borderColor: 'border-secondary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Identification and classification information: name, version, description, labels, annotations.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         <strong>Discovery:</strong> Find agents by name/labels in catalogs.<br/>
                         <strong>Versioning:</strong> Track changes over time.<br/>
@@ -571,9 +657,9 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`metadata:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`metadata:
   name: customer-support-agent
   version: 2.1.0
   description: Handles tier-1 support tickets with sentiment analysis
@@ -586,34 +672,29 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* spec.role */}
-            <div className="card p-6 border-l-4 border-primary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-primary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🎭</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-primary mb-3">spec.role</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'spec-role',
+                title: 'spec.role',
+                borderColor: 'border-primary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">The system prompt / role definition that guides the agent's behavior and personality.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         Defines <strong>who</strong> the agent is, <strong>what</strong> it can do, and <strong>how</strong> it should behave.
                         This is the agent's identity and primary instruction set that shapes all interactions.
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`spec:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`spec:
   role: |
     You are a senior software architect specializing in distributed systems.
     Your role is to review code for scalability, security, and best practices.
@@ -622,25 +703,20 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* spec.llm */}
-            <div className="card p-6 border-l-4 border-secondary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-secondary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🧠</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-secondary mb-3">spec.llm</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'spec-llm',
+                title: 'spec.llm',
+                borderColor: 'border-secondary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">LLM provider configuration: model, temperature, max_tokens, top_p, and other parameters.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         <strong>Portability:</strong> Switch from OpenAI to Anthropic without changing agent logic.<br/>
                         <strong>Optimization:</strong> Tune temperature for creativity vs consistency.<br/>
@@ -649,9 +725,9 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`spec:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`spec:
   llm:
     provider: openai
     model: gpt-4-turbo
@@ -663,25 +739,20 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* spec.tools */}
-            <div className="card p-6 border-l-4 border-primary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-primary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🔧</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-primary mb-3">spec.tools</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'spec-tools',
+                title: 'spec.tools',
+                borderColor: 'border-primary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Array of tools/functions the agent can call: HTTP APIs, code execution, database queries, file operations, etc.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         Agents need to <strong>take action</strong>, not just respond with text. Tools enable agents to:
                         interact with APIs, query databases, run code, search the web, manipulate files, and integrate with external systems.
@@ -689,7 +760,7 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">TYPES:</p>
+                      <p className="font-semibold text-gray-900 mb-2">TYPES:</p>
                       <ul className="list-disc list-inside text-gray-700 space-y-1 ml-4">
                         <li><strong>http:</strong> REST API calls</li>
                         <li><strong>code:</strong> Execute Python/JS/etc</li>
@@ -700,9 +771,9 @@ kind: Agent`}</code></pre>
                       </ul>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`spec:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`spec:
   tools:
     - type: http
       name: search_issues
@@ -719,25 +790,20 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* spec.taxonomy */}
-            <div className="card p-6 border-l-4 border-secondary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-secondary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🏷️</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-secondary mb-3">spec.taxonomy</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'spec-taxonomy',
+                title: 'spec.taxonomy',
+                borderColor: 'border-secondary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Classification of agent purpose: domain, subdomain, use_case, and industry.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         <strong>Discoverability:</strong> Find agents for specific use cases in catalogs.<br/>
                         <strong>Organization:</strong> Group similar agents together.<br/>
@@ -746,9 +812,9 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`spec:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`spec:
   taxonomy:
     domain: customer_service
     subdomain: technical_support
@@ -758,25 +824,20 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* spec.autonomy */}
-            <div className="card p-6 border-l-4 border-primary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-primary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🎯</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-primary mb-3">spec.autonomy</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'spec-autonomy',
+                title: 'spec.autonomy',
+                borderColor: 'border-primary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Defines how much independence the agent has: level (L0-L5), approval_required, human_in_loop settings.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         <strong>Safety:</strong> Prevent agents from taking destructive actions without oversight.<br/>
                         <strong>Compliance:</strong> Require approvals for regulated operations.<br/>
@@ -785,7 +846,7 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">LEVELS:</p>
+                      <p className="font-semibold text-gray-900 mb-2">LEVELS:</p>
                       <ul className="list-disc list-inside text-gray-700 space-y-1 ml-4">
                         <li><strong>L0:</strong> No autonomy (human controls everything)</li>
                         <li><strong>L1:</strong> Suggestions only (human approves all actions)</li>
@@ -796,9 +857,9 @@ kind: Agent`}</code></pre>
                       </ul>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`spec:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`spec:
   autonomy:
     level: L2
     approval_required:
@@ -811,25 +872,20 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* spec.observability */}
-            <div className="card p-6 border-l-4 border-secondary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-secondary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">📊</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-secondary mb-3">spec.observability</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'spec-observability',
+                title: 'spec.observability',
+                borderColor: 'border-secondary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Logging, metrics, and tracing configuration for monitoring agent behavior.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         <strong>Debugging:</strong> Understand what went wrong when agents fail.<br/>
                         <strong>Performance:</strong> Track response times, token usage, costs.<br/>
@@ -838,9 +894,9 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`spec:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`spec:
   observability:
     logging:
       level: info
@@ -856,25 +912,20 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-
-            {/* extensions */}
-            <div className="card p-6 border-l-4 border-primary hover:shadow-xl transition-shadow">
-              <div className="flex items-start">
-                <div className="w-10 h-10 bg-primary/10 rounded-lg flex items-center justify-center mr-4 flex-shrink-0 mt-1">
-                  <span className="text-2xl">🔌</span>
-                </div>
-                <div className="flex-1">
-                  <h3 className="text-2xl font-bold text-primary mb-3">extensions</h3>
-                  <div className="space-y-3">
+                ),
+              },
+              {
+                id: 'extensions',
+                title: 'extensions',
+                borderColor: 'border-primary',
+                content: (
+                  <div className="space-y-4">
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHAT:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHAT:</p>
                       <p className="text-gray-700">Framework-specific configuration blocks: kagent, buildkit, langchain, crewai, openai, anthropic, cursor, langflow, autogen, etc.</p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">WHY:</p>
+                      <p className="font-semibold text-gray-900 mb-2">WHY:</p>
                       <p className="text-gray-700">
                         While OSSA provides a <strong>common core</strong>, each framework has unique features. Extensions allow you to:
                         leverage framework-specific capabilities, maintain compatibility with existing code, and gradually migrate from proprietary formats.
@@ -882,29 +933,9 @@ kind: Agent`}</code></pre>
                       </p>
                     </div>
                     <div>
-                      <p className="font-semibold text-gray-900 mb-1">SUPPORTED FRAMEWORKS (15+):</p>
-                      <div className="grid grid-cols-2 gap-2 mt-2">
-                        <div className="bg-blue-50 p-2 rounded text-sm">• kAgent</div>
-                        <div className="bg-purple-50 p-2 rounded text-sm">• LangChain</div>
-                        <div className="bg-green-50 p-2 rounded text-sm">• CrewAI</div>
-                        <div className="bg-orange-50 p-2 rounded text-sm">• OpenAI Agents</div>
-                        <div className="bg-pink-50 p-2 rounded text-sm">• Anthropic Claude</div>
-                        <div className="bg-yellow-50 p-2 rounded text-sm">• Cursor</div>
-                        <div className="bg-red-50 p-2 rounded text-sm">• Langflow</div>
-                        <div className="bg-indigo-50 p-2 rounded text-sm">• AutoGen</div>
-                        <div className="bg-teal-50 p-2 rounded text-sm">• Vercel AI</div>
-                        <div className="bg-cyan-50 p-2 rounded text-sm">• LlamaIndex</div>
-                        <div className="bg-lime-50 p-2 rounded text-sm">• LangGraph</div>
-                        <div className="bg-amber-50 p-2 rounded text-sm">• BuildKit</div>
-                        <div className="bg-blue-100 p-2 rounded text-sm">• Drupal</div>
-                        <div className="bg-purple-100 p-2 rounded text-sm">• LibreChat</div>
-                        <div className="bg-green-100 p-2 rounded text-sm">• MCP</div>
-                      </div>
-                    </div>
-                    <div>
-                      <p className="font-semibold text-gray-900 mb-1">EXAMPLE:</p>
-                      <div className="bg-code-bg rounded-lg p-3 mt-2">
-                        <pre className="text-code-text text-sm"><code>{`extensions:
+                      <p className="font-semibold text-gray-900 mb-2">EXAMPLE:</p>
+                      <div className="bg-gray-900 rounded-lg p-4 mt-2">
+                        <pre className="text-green-400 text-sm font-mono"><code>{`extensions:
   kagent:
     mesh_discovery: true
     routing_strategy: round_robin
@@ -919,16 +950,16 @@ kind: Agent`}</code></pre>
                       </div>
                     </div>
                   </div>
-                </div>
-              </div>
-            </div>
-          </div>
+                ),
+              },
+            ]}
+          />
         </section>
 
         {/* Interactive Schema Explorer */}
         <section className="mb-16">
           <div className="flex items-center mb-8">
-            <div className="w-12 h-12 bg-gradient-to-br from-primary to-secondary rounded-lg flex items-center justify-center mr-4">
+            <div className="w-12 h-12 bg-gradient-to-br from-secondary via-primary to-accent rounded-lg flex items-center justify-center mr-4">
               <svg className="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                 <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
               </svg>