fix: broken links, docs sidebar inconsistency, nav light-mode contrast

src/components/DocsSidebar.astro

@@ -0,0 +1,49 @@
+---
+export interface Props {
+  active: string;
+}
+const { active } = Astro.props;
+
+const sections = [
+  {
+    title: 'Getting Started',
+    links: [{ href: '/docs/quickstart.html', label: 'Quickstart' }],
+  },
+  {
+    title: 'Core Concepts',
+    links: [
+      { href: '/docs/concepts.html', label: 'Contracts' },
+      { href: '/docs/architecture.html', label: 'Architecture' },
+    ],
+  },
+  {
+    title: 'Guides',
+    links: [
+      { href: '/docs/guides.html', label: 'All Guides' },
+      { href: '/docs/guides/mcp-setup.html', label: 'MCP Setup' },
+      { href: '/docs/guides/react-integration.html', label: 'React Integration' },
+    ],
+  },
+  {
+    title: 'Reference',
+    links: [
+      { href: '/docs/cli-reference.html', label: 'CLI Reference' },
+      { href: '/docs/troubleshooting.html', label: 'Troubleshooting' },
+      { href: '/examples.html', label: 'Examples' },
+      { href: '/changelog.html', label: 'Changelog' },
+    ],
+  },
+];
+---
+<aside class="docs-sidebar">
+  {sections.map((section) => (
+    <div class="docs-sidebar-section">
+      <div class="docs-sidebar-title">{section.title}</div>
+      <div class="docs-sidebar-links">
+        {section.links.map((link) => (
+          <a href={link.href} class={link.href === active ? 'active' : undefined}>{link.label}</a>
+        ))}
+      </div>
+    </div>
+  ))}
+</aside>

src/components/Footer.astro

@@ -17,26 +17,26 @@
       <div>
         <div class="footer-col-title">Product</div>
         <ul class="footer-links">
-          <li><a href="/use-cases/">Use Cases</a></li>
-          <li><a href="/solutions/">Solutions</a></li>
+          <li><a href="/use-cases.html">Use Cases</a></li>
+          <li><a href="/solutions.html">Solutions</a></li>
           <li><a href="/changelog.html">Changelog</a></li>
           <li><a href="/roadmap.html">Roadmap</a></li>
         </ul>
       </div>
       <div>
         <div class="footer-col-title">Developers</div>
         <ul class="footer-links">
-          <li><a href="/docs/">Overview</a></li>
+          <li><a href="/docs.html">Overview</a></li>
           <li><a href="/docs/quickstart.html">Quickstart</a></li>
           <li><a href="/docs/cli-reference.html">CLI Reference</a></li>
-          <li><a href="/questions/">All Questions</a></li>
+          <li><a href="/questions.html">All Questions</a></li>
         </ul>
       </div>
       <div>
         <div class="footer-col-title">Company</div>
         <ul class="footer-links">
           <li><a href="/about.html">About</a></li>
-          <li><a href="/blog/">Blog</a></li>
+          <li><a href="/blog.html">Blog</a></li>
           <li><a href="https://github.com/traverse-framework/traverse" target="_blank" rel="noopener">GitHub</a></li>
         </ul>
       </div>

src/components/Nav.astro

@@ -144,14 +144,14 @@ const { currentPath = '' } = Astro.props;
           </div>
           <div class="dropdown-section">
             <div class="dropdown-label">Resources</div>
-            <a href="/questions/" class="dropdown-item" role="menuitem">
+            <a href="/questions.html" class="dropdown-item" role="menuitem">
               <span class="dropdown-icon">◎</span>
               <span>
                 <span class="dropdown-item-title">All Questions</span>
                 <span class="dropdown-item-desc">55 answered questions</span>
               </span>
             </a>
-            <a href="/examples/" class="dropdown-item" role="menuitem">
+            <a href="/examples.html" class="dropdown-item" role="menuitem">
               <span class="dropdown-icon">◷</span>
               <span>
                 <span class="dropdown-item-title">Examples</span>
@@ -162,7 +162,7 @@ const { currentPath = '' } = Astro.props;
         </div>
       </li>
 
-      <li class="nav-item"><a href="/blog/" class="nav-link">Blog</a></li>
+      <li class="nav-item"><a href="/blog.html" class="nav-link">Blog</a></li>
     </ul>
 
     <div class="nav-right">
@@ -184,9 +184,9 @@ const { currentPath = '' } = Astro.props;
 
 <div class="nav-mobile-menu" id="nav-mobile-menu">
   <a href="/questions/what-is-traverse.html">What is Traverse</a>
-  <a href="/solutions/">Solutions</a>
-  <a href="/docs/">Docs</a>
-  <a href="/blog/">Blog</a>
+  <a href="/solutions.html">Solutions</a>
+  <a href="/docs.html">Docs</a>
+  <a href="/blog.html">Blog</a>
   <a href="/changelog.html">Changelog</a>
   <a href="https://github.com/traverse-framework/traverse" target="_blank" rel="noopener">GitHub →</a>
   <a href="/docs/quickstart.html" class="btn btn-primary btn-sm" style="margin-top:0.5rem">Get started</a>
@@ -238,6 +238,24 @@ const { currentPath = '' } = Astro.props;
   .nav-logo img { width: 24px; height: 24px; object-fit: contain; }
   .nav-logo-dot { color: var(--accent); }
 
+  /* The homepage hero has a hardcoded-dark background regardless of theme
+     (brand art). While the nav is transparent and sitting on top of it,
+     force light text so light-mode's dark --fg doesn't vanish against it. */
+  :global(body.home) .nav:not(.scrolled) .nav-logo { color: #f0eeff; }
+  :global(body.home) .nav:not(.scrolled) .nav-link-btn,
+  :global(body.home) .nav:not(.scrolled) .nav-link { color: rgba(240,238,255,0.7); }
+  :global(body.home) .nav:not(.scrolled) .nav-theme-btn,
+  :global(body.home) .nav:not(.scrolled) .nav-mobile-btn { color: rgba(240,238,255,0.7); }
+  :global(body.home) .nav:not(.scrolled) .nav-right .btn-ghost {
+    color: rgba(240,238,255,0.7);
+    border-color: rgba(240,238,255,0.25);
+  }
+  :global(body.home) .nav:not(.scrolled) .nav-right .btn-ghost:hover {
+    color: #f0eeff;
+    border-color: rgba(240,238,255,0.4);
+    background: rgba(255,255,255,0.06);
+  }
+
   .nav-links {
     display: flex;
     align-items: center;

src/layouts/BaseLayout.astro

@@ -17,6 +17,7 @@ const {
   canonical = Astro.url.href,
   jsonLd,
   ogImage = '/assets/img/logo/traverse_icon_1024x1024.png',
+  class: bodyClass,
 } = Astro.props;
 
 const fullTitle = title.includes('Traverse') ? title : `${title} — Traverse Framework`;
@@ -103,7 +104,7 @@ const siteJsonLd = JSON.stringify({
     })();
   </script>
 </head>
-<body>
+<body class={bodyClass}>
   <Nav />
   <slot />
   <Footer />

src/layouts/QuestionLayout.astro

@@ -18,7 +18,7 @@ const {
   canonical,
   jsonLd,
   category,
-  crumbs = [{ label: 'Home', href: '/' }, { label: 'Questions', href: '/questions/' }],
+  crumbs = [{ label: 'Home', href: '/' }, { label: 'Questions', href: '/questions.html' }],
   relatedLinks = [],
 } = Astro.props;
 ---

src/pages/blog/index.astro

@@ -0,0 +1,42 @@
+---
+import SubpageLayout from '@layouts/SubpageLayout.astro';
+
+const posts = [
+  { href: '/blog/ai-agents-need-contracts.html', title: 'AI agents need contracts, not just function definitions', desc: 'Function calling tells an agent what a tool does. It says nothing about what has to be true before or after it runs.' },
+  { href: '/blog/logic-duplication.html', title: 'Why I stopped writing the same business logic four times', desc: 'The same pricing rule lived in the web app, the mobile app, the backend, and the AI pipeline. Each copy drifted.' },
+  { href: '/blog/runtime-assumptions.html', title: 'The hidden cost of runtime assumptions', desc: 'Most bugs in business logic are not logic bugs. They are assumptions about the environment that turned out to be false.' },
+  { href: '/blog/uma-explained.html', title: 'What Universal Microservices Architecture got right', desc: 'UMA argued for one deployable unit that runs anywhere. Traverse is one way to build that.' },
+  { href: '/blog/wasm-business-logic.html', title: 'What WASM actually gives you for business logic', desc: 'Portability and sandboxing, not performance, is the reason WASM matters for governed business logic.' },
+];
+---
+<SubpageLayout
+  title={"Blog — Traverse Framework"}
+  description={"Writing on contract-driven development, portable business logic, and the Traverse runtime."}
+  canonical={"https://traverse-framework.com/blog.html"}
+  crumbs={[{ label: "Home", href: "/" }]}
+>
+  <main>
+    <section class="page-hero">
+      <div class="container">
+        <div class="page-hero-inner">
+          <span class="section-label">Blog</span>
+          <h1 class="t-h1">Notes on contract-driven development.</h1>
+          <p class="page-hero-sub">Writing on portable business logic, contract governance, and why the same rule keeps getting rewritten four times.</p>
+        </div>
+      </div>
+    </section>
+    <section class="section">
+      <div class="container">
+        <div class="usecase-grid">
+          {posts.map((p) => (
+            <a href={p.href} class="usecase-card" style="text-decoration:none;display:block">
+              <h3>{p.title}</h3>
+              <p>{p.desc}</p>
+              <span style="color:var(--accent);font-size:0.82rem">Read more →</span>
+            </a>
+          ))}
+        </div>
+      </div>
+    </section>
+  </main>
+</SubpageLayout>