From 34366b9d11cd28a0df696a66318315caaf0f11ba Mon Sep 17 00:00:00 2001
From: SIN-Agent <agent@opensin.ai>
Date: Tue, 21 Apr 2026 07:15:56 +0200
Subject: [PATCH 1/3] docs: refresh homepage hero copy

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 docs/index.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index ed999a81e2..7ac5d107e9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,8 +2,8 @@
 layout: home
 hero:
   name: "OpenSIN-AI"
-  text: "Dokumentation"
-  tagline: "Learn how to use the OpenSIN ecosystem, control your fleet, and build sovereign agents without guesswork."
+  text: "Sovereign Documentation"
+  tagline: "Learn how to operate the OpenSIN ecosystem, steer your fleet, and ship sovereign agents with a sharper control-plane view."
   image:
     src: /logo.png
     alt: OpenSIN Logo
@@ -18,17 +18,17 @@ features:
   - icon:
       src: /icons/docs.svg
     title: Autonomous Fleet
-    details: "Orchestrate a team of specialized agents that work 24/7 without human intervention."
+    details: "Operate specialized agents with a docs surface that keeps the critical paths obvious and the next step close at hand."
     link: /guide/fleet-orchestration
   - icon:
       src: /icons/a2a.svg
     title: A2A Protocol
-    details: "Zero-bottleneck communication. Agents talk to agents directly via the Neural-Bus."
+    details: "Move from isolated prompts to direct agent-to-agent execution with the Neural-Bus as the system contract."
     link: /guide/a2a-protocol
   - icon:
       src: /icons/registry.svg
     title: Stealth Automation
-    details: "Human-like browsing and action execution. Undetectable. Unstoppable."
+    details: "Run browser and system automation with a premium, legible surface that makes high-trust operations easier to scan."
     link: /guide/stealth-automation
 ---
 

From 311c41a102065b5ccddd79bf3cc82e979baed5e2 Mon Sep 17 00:00:00 2001
From: SIN-Agent <agent@opensin.ai>
Date: Tue, 21 Apr 2026 07:16:06 +0200
Subject: [PATCH 2/3] style: polish homepage theme surface contract

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 .../theme/components/HomeChoosePath.vue       | 166 ++++++++--
 .../theme/components/HomeRelatedTopics.vue    | 115 ++++---
 docs/.vitepress/theme/custom.css              | 297 ++++++++++++++++--
 docs/.vitepress/theme/index.ts                |   6 +
 4 files changed, 486 insertions(+), 98 deletions(-)

diff --git a/docs/.vitepress/theme/components/HomeChoosePath.vue b/docs/.vitepress/theme/components/HomeChoosePath.vue
index 66b07716a8..f88e21ebf0 100644
--- a/docs/.vitepress/theme/components/HomeChoosePath.vue
+++ b/docs/.vitepress/theme/components/HomeChoosePath.vue
@@ -1,42 +1,152 @@
 <template>
   <section class="home-choose-path">
+    <div class="home-choose-path__eyebrow">Start with the right entry point</div>
     <h2 class="home-choose-path__title">Choose Your Path</h2>
+    <p class="home-choose-path__lede">
+      The homepage contract protects exactly two cards here: one for operators and one for builders.
+    </p>
+
     <div class="home-choose-path__grid">
-      <a href="/guide/getting-started" class="home-choose-path__card is-highlight">
-        <div class="home-choose-path__heading">User Documentation <span class="home-choose-path__arrow">→</span></div>
-        <div class="home-choose-path__description">How to use OpenSIN, manage your fleet, and leverage autonomous intelligence.</div>
-      </a>
-      <a href="/sdk/overview" class="home-choose-path__card">
-        <div class="home-choose-path__heading">Developer Documentation <span class="home-choose-path__arrow">→</span></div>
-        <div class="home-choose-path__description">Build plugins, create A2A agents, and integrate with the Neural-Bus.</div>
+      <a
+        v-for="card in cards"
+        :key="card.title"
+        :href="card.href"
+        class="home-choose-path__card"
+        :class="{ 'is-highlight': card.highlight }"
+      >
+        <div class="home-choose-path__label">{{ card.label }}</div>
+        <div class="home-choose-path__heading">
+          {{ card.title }}
+          <span class="home-choose-path__arrow">→</span>
+        </div>
+        <div class="home-choose-path__description">{{ card.description }}</div>
       </a>
     </div>
   </section>
 </template>
 
+<script setup lang="ts">
+/**
+ * Homepage contract note:
+ * - Keep this array at exactly 2 entries unless issue #141 is formally replaced.
+ * - Styling intentionally consumes the shared homepage tokens from custom.css so
+ *   hero/features/path/topic cards feel like one surface system across themes.
+ */
+const cards = [
+  {
+    title: 'User Documentation',
+    description: 'Learn the operator path, daily workflows, and the shortest route to a productive OpenSIN fleet.',
+    href: '/guide/getting-started',
+    label: 'Operate',
+    highlight: true,
+  },
+  {
+    title: 'Developer Documentation',
+    description: 'Build plugins, compose A2A agents, and ship integrations without leaving the existing docs contract.',
+    href: '/sdk/overview',
+    label: 'Build',
+    highlight: false,
+  },
+]
+</script>
+
 <style scoped>
-.home-choose-path { margin-top: 2.75rem; }
-.home-choose-path__title { margin: 0 0 1rem; font-size: 1.6rem; font-weight: 700; letter-spacing: -0.03em; }
-.home-choose-path__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1rem; }
+.home-choose-path {
+  margin-top: 3.5rem;
+}
+
+.home-choose-path__eyebrow {
+  margin-bottom: 0.7rem;
+  color: var(--opensin-home-accent-text);
+  font-size: 0.8rem;
+  font-weight: 700;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.home-choose-path__title {
+  margin: 0;
+  font-size: clamp(1.75rem, 2.8vw, 2.2rem);
+  font-weight: 800;
+  letter-spacing: -0.04em;
+}
+
+.home-choose-path__lede {
+  max-width: 42rem;
+  margin: 0.85rem 0 1.5rem;
+  color: var(--vp-c-text-2);
+  font-size: 1rem;
+  line-height: 1.65;
+}
+
+.home-choose-path__grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 1rem;
+}
+
 .home-choose-path__card {
   display: block;
-  padding: 1.25rem 1.25rem;
-  border-radius: 14px;
-  border: 1px solid rgba(255,255,255,0.08);
-  background: #141414;
+  padding: 1.3rem 1.3rem 1.4rem;
+  border-radius: 20px;
+  border: 1px solid var(--opensin-home-card-border);
+  background: var(--opensin-home-card-bg);
+  box-shadow: var(--opensin-home-card-shadow);
   text-decoration: none;
-  transition: border-color .2s ease, transform .2s ease, box-shadow .2s ease;
-}
-.home-choose-path__card:hover { transform: translateY(-2px); border-color: rgba(0,204,136,.45); box-shadow: 0 12px 28px rgba(0,0,0,.22); }
-.home-choose-path__heading { color:#f5f5f5; font-size:1.05rem; font-weight:700; margin-bottom:.35rem; }
-.home-choose-path__description { color:#8e8ea0; font-size:.95rem; line-height:1.45; }
-.home-choose-path__card.is-highlight { border-color: rgba(0,204,136,.5); }
-.home-choose-path__card.is-highlight .home-choose-path__heading { color:#00cc88; }
-.home-choose-path__arrow { margin-left:.35rem; }
-:global(html:not(.dark)) .home-choose-path__card { background:#ffffff; border-color:rgba(0,0,0,.08); box-shadow:0 10px 24px rgba(15,23,42,.05); }
-:global(html:not(.dark)) .home-choose-path__heading { color:#0f172a; }
-:global(html:not(.dark)) .home-choose-path__description { color:#475569; }
-:global(html:not(.dark)) .home-choose-path__card.is-highlight { border-color: rgba(0,128,96,.3); background: linear-gradient(180deg,#ffffff 0%,#f5fbf8 100%); }
-:global(html:not(.dark)) .home-choose-path__card.is-highlight .home-choose-path__heading { color:#008060; }
-@media (max-width: 720px) { .home-choose-path__grid { grid-template-columns: 1fr; } }
+  transition: transform 0.22s ease, border-color 0.22s ease, box-shadow 0.22s ease, background 0.22s ease;
+}
+
+.home-choose-path__card:hover {
+  transform: translateY(-3px);
+  border-color: var(--opensin-home-card-border-strong);
+  box-shadow: var(--opensin-home-card-shadow-hover);
+}
+
+.home-choose-path__card.is-highlight {
+  background: var(--opensin-home-card-bg-highlight);
+}
+
+.home-choose-path__label {
+  display: inline-flex;
+  align-items: center;
+  min-height: 1.7rem;
+  margin-bottom: 0.95rem;
+  padding: 0.2rem 0.65rem;
+  border-radius: 999px;
+  background: var(--opensin-home-pill-bg);
+  color: var(--opensin-home-accent-text);
+  font-size: 0.77rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.home-choose-path__heading {
+  color: var(--vp-c-text-1);
+  font-size: 1.16rem;
+  font-weight: 750;
+  line-height: 1.3;
+}
+
+.home-choose-path__description {
+  margin-top: 0.55rem;
+  color: var(--vp-c-text-2);
+  font-size: 0.98rem;
+  line-height: 1.6;
+}
+
+.home-choose-path__arrow {
+  margin-left: 0.4rem;
+  color: var(--opensin-home-accent-text);
+}
+
+@media (max-width: 720px) {
+  .home-choose-path {
+    margin-top: 3rem;
+  }
+
+  .home-choose-path__grid {
+    grid-template-columns: 1fr;
+  }
+}
 </style>
diff --git a/docs/.vitepress/theme/components/HomeRelatedTopics.vue b/docs/.vitepress/theme/components/HomeRelatedTopics.vue
index 22e80f4294..8250621cf4 100644
--- a/docs/.vitepress/theme/components/HomeRelatedTopics.vue
+++ b/docs/.vitepress/theme/components/HomeRelatedTopics.vue
@@ -1,8 +1,14 @@
 <template>
   <section class="home-related-topics">
+    <div class="home-related-topics__eyebrow">Cross-surface navigation</div>
     <h2 class="home-related-topics__title">Related topics</h2>
+    <p class="home-related-topics__lede">
+      Keep the ecosystem scan-friendly without changing the protected four-card section shape.
+    </p>
+
     <div class="home-related-topics__grid">
       <a v-for="card in cards" :key="card.title" :href="card.href" class="home-related-topics__card">
+        <div class="home-related-topics__label">{{ card.label }}</div>
         <div class="home-related-topics__heading">
           {{ card.title }}
         </div>
@@ -15,44 +21,65 @@
 <script setup lang="ts">
 /**
  * Homepage related-topics grid.
- * DO NOT replace with inline HTML in index.md again.
- * This component exists so the homepage can keep the premium surface-card look
- * without polluting markdown content with raw layout markup.
+ * - Keep this array at exactly 4 items while issue #141 is the active contract.
+ * - This component exists so the homepage keeps a polished surface-card system
+ *   without pushing raw layout HTML into docs/index.md.
  */
 const cards = [
   {
     title: 'OpenSIN Marketing',
-    description: 'Brand, discovery and product storytelling',
+    description: 'Brand, discovery, and the public-facing narrative around the ecosystem.',
     href: 'https://opensin.ai',
+    label: 'Surface',
   },
   {
     title: 'OpenSIN Marketplace',
-    description: 'Plans, bundles and premium access',
+    description: 'Plans, bundles, and commercial packaging for premium access.',
     href: 'https://my.opensin.ai',
+    label: 'Commerce',
   },
   {
     title: 'OpenSIN Dashboard',
-    description: 'Authenticated fleet control and chat',
+    description: 'Authenticated fleet control, chat, and the active operator workspace.',
     href: 'https://chat.opensin.ai',
+    label: 'Control',
   },
   {
     title: 'Domain Registry',
-    description: 'Verified public, gated and internal surfaces',
+    description: 'Verified public, gated, and internal surfaces kept in one canonical map.',
     href: '/governance/domain-registry',
+    label: 'Governance',
   },
 ]
 </script>
 
 <style scoped>
 .home-related-topics {
-  margin-top: 3rem;
+  margin-top: 3.25rem;
 }
 
-.home-related-topics__title {
-  margin: 0 0 1rem;
-  font-size: 1.6rem;
+.home-related-topics__eyebrow {
+  margin-bottom: 0.7rem;
+  color: var(--opensin-home-accent-text);
+  font-size: 0.8rem;
   font-weight: 700;
-  letter-spacing: -0.03em;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.home-related-topics__title {
+  margin: 0;
+  font-size: clamp(1.75rem, 2.8vw, 2.2rem);
+  font-weight: 800;
+  letter-spacing: -0.04em;
+}
+
+.home-related-topics__lede {
+  max-width: 42rem;
+  margin: 0.85rem 0 1.5rem;
+  color: var(--vp-c-text-2);
+  font-size: 1rem;
+  line-height: 1.65;
 }
 
 .home-related-topics__grid {
@@ -63,51 +90,47 @@ const cards = [
 
 .home-related-topics__card {
   display: block;
-  padding: 1.15rem 1.2rem;
-  border-radius: 14px;
-  border: 1px solid rgba(255, 255, 255, 0.08);
-  background: #141414;
+  padding: 1.2rem 1.2rem 1.3rem;
+  border-radius: 20px;
+  border: 1px solid var(--opensin-home-card-border);
+  background: var(--opensin-home-card-bg);
+  box-shadow: var(--opensin-home-card-shadow);
   text-decoration: none;
-  transition: border-color 0.2s ease, transform 0.2s ease, box-shadow 0.2s ease;
+  transition: transform 0.22s ease, border-color 0.22s ease, box-shadow 0.22s ease;
 }
 
 .home-related-topics__card:hover {
-  transform: translateY(-2px);
-  border-color: rgba(0, 204, 136, 0.45);
-  box-shadow: 0 12px 28px rgba(0, 0, 0, 0.22);
+  transform: translateY(-3px);
+  border-color: var(--opensin-home-card-border-strong);
+  box-shadow: var(--opensin-home-card-shadow-hover);
 }
 
-.home-related-topics__heading {
-  color: #f5f5f5;
-  font-size: 1.05rem;
+.home-related-topics__label {
+  display: inline-flex;
+  align-items: center;
+  min-height: 1.65rem;
+  margin-bottom: 0.9rem;
+  padding: 0.18rem 0.62rem;
+  border-radius: 999px;
+  background: var(--opensin-home-pill-bg);
+  color: var(--opensin-home-accent-text);
+  font-size: 0.76rem;
   font-weight: 700;
-  margin-bottom: 0.3rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
 }
 
-.home-related-topics__description {
-  color: #8e8ea0;
-  font-size: 0.95rem;
-  line-height: 1.45;
-}
-
-:global(html:not(.dark)) .home-related-topics__card {
-  background: #ffffff;
-  border-color: rgba(0, 0, 0, 0.08);
-  box-shadow: 0 10px 24px rgba(15, 23, 42, 0.05);
-}
-
-:global(html:not(.dark)) .home-related-topics__heading {
-  color: #0f172a;
-}
-
-:global(html:not(.dark)) .home-related-topics__description {
-  color: #475569;
+.home-related-topics__heading {
+  color: var(--vp-c-text-1);
+  font-size: 1.08rem;
+  font-weight: 750;
+  margin-bottom: 0.35rem;
 }
 
-@media (max-width: 960px) {
-  .home-related-topics__grid {
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-  }
+.home-related-topics__description {
+  color: var(--vp-c-text-2);
+  font-size: 0.97rem;
+  line-height: 1.58;
 }
 
 @media (max-width: 640px) {
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 7f9db40d9b..74a3795b6f 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -19,7 +19,7 @@
   --vp-c-text-2: #444444;
   --vp-c-divider: rgba(0, 0, 0, 0.1);
   --vp-code-bg: #f8f8f8;
-  
+
   /* [BUTTONS LIGHT] */
   --vp-button-brand-bg: #00cc88;
   --vp-button-brand-border: #00cc88;
@@ -27,6 +27,18 @@
   --vp-button-alt-bg: #f6f6f7;
   --vp-button-alt-border: #dcdde1;
   --vp-button-alt-text: #0a0a0a;
+
+  /* [HOMEPAGE SURFACE TOKENS] */
+  --opensin-home-accent-text: #008060;
+  --opensin-home-hero-glow: radial-gradient(circle at top, rgba(0, 204, 136, 0.16), transparent 58%);
+  --opensin-home-panel-bg: linear-gradient(180deg, rgba(255, 255, 255, 0.96), rgba(245, 251, 248, 0.92));
+  --opensin-home-card-bg: linear-gradient(180deg, rgba(255, 255, 255, 0.98), rgba(248, 250, 252, 0.98));
+  --opensin-home-card-bg-highlight: linear-gradient(180deg, rgba(255, 255, 255, 1), rgba(240, 250, 245, 1));
+  --opensin-home-card-border: rgba(15, 23, 42, 0.08);
+  --opensin-home-card-border-strong: rgba(0, 128, 96, 0.28);
+  --opensin-home-card-shadow: 0 16px 40px rgba(15, 23, 42, 0.06);
+  --opensin-home-card-shadow-hover: 0 20px 48px rgba(15, 23, 42, 0.1);
+  --opensin-home-pill-bg: rgba(0, 128, 96, 0.08);
 }
 
 .dark {
@@ -39,17 +51,30 @@
   --vp-c-text-2: #c5c5d2;
   --vp-c-divider: rgba(255, 255, 255, 0.1);
   --vp-code-bg: #0f1115;
-  
+
   /* [BUTTONS DARK] */
   --vp-button-brand-text: #0a0a0a;
   --vp-button-alt-bg: #1a1a1a;
   --vp-button-alt-border: #2a2a2a;
   --vp-button-alt-text: #ececf1;
+
+  /* [HOMEPAGE SURFACE TOKENS] */
+  --opensin-home-accent-text: #5ff0bc;
+  --opensin-home-hero-glow: radial-gradient(circle at top, rgba(0, 204, 136, 0.22), transparent 58%);
+  --opensin-home-panel-bg: linear-gradient(180deg, rgba(20, 20, 20, 0.92), rgba(10, 10, 10, 0.9));
+  --opensin-home-card-bg: linear-gradient(180deg, rgba(20, 20, 20, 0.95), rgba(12, 12, 12, 0.95));
+  --opensin-home-card-bg-highlight: linear-gradient(180deg, rgba(20, 28, 24, 0.96), rgba(10, 10, 10, 0.96));
+  --opensin-home-card-border: rgba(255, 255, 255, 0.08);
+  --opensin-home-card-border-strong: rgba(0, 204, 136, 0.34);
+  --opensin-home-card-shadow: 0 16px 40px rgba(0, 0, 0, 0.28);
+  --opensin-home-card-shadow-hover: 0 24px 52px rgba(0, 0, 0, 0.34);
+  --opensin-home-pill-bg: rgba(0, 204, 136, 0.12);
 }
 
 /* 🚨 MANDATORY BUTTON SHAPE 🚨 */
-.VPButton, .VPButton:hover {
-  border-radius: 8px !important; 
+.VPButton,
+.VPButton:hover {
+  border-radius: 8px !important;
   font-weight: 600 !important;
 }
 
@@ -88,25 +113,185 @@
   transform: translateY(-1px);
 }
 
+/**
+ * HOMEPAGE CONTRACT LAYER
+ * - Preserve VitePress home layout and the verified 3/2/4 information shape.
+ * - Theme tokens live here so hero, features, and custom sections stay visually
+ *   aligned without forcing inline styles or markdown HTML layout hacks.
+ */
+.VPHome {
+  position: relative;
+}
+
+.VPHome::before {
+  content: '';
+  position: absolute;
+  inset: 0 0 auto;
+  height: 34rem;
+  background: var(--opensin-home-hero-glow);
+  pointer-events: none;
+  z-index: 0;
+}
+
+.VPHome .VPHero,
+.VPHome .VPHomeFeatures,
+.VPHome .vp-doc > div,
+.VPHome .vp-doc > h2 {
+  position: relative;
+  z-index: 1;
+}
+
+.VPHome .VPHero {
+  padding-top: 56px;
+  padding-bottom: 22px;
+}
+
+.VPHome .VPHero .container {
+  max-width: 1240px;
+}
+
+.VPHome .VPHero .main {
+  max-width: 640px;
+}
+
+.VPHome .VPHero .name,
+.VPHome .VPHero .text {
+  letter-spacing: -0.05em;
+}
+
+.VPHome .VPHero .name {
+  background: linear-gradient(90deg, var(--vp-c-text-1), var(--opensin-home-accent-text));
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+}
+
+.VPHome .VPHero .text {
+  max-width: 10ch;
+  font-size: clamp(2.8rem, 6vw, 4.8rem);
+  line-height: 0.98;
+}
+
+.VPHome .VPHero .tagline {
+  max-width: 38rem;
+  font-size: 1.1rem;
+  line-height: 1.7;
+  color: var(--vp-c-text-2);
+}
+
+.VPHome .VPHero .actions {
+  gap: 0.85rem;
+  margin-top: 28px;
+}
+
+/**
+ * The hero image stays inside the default VitePress slot to avoid rewriting the
+ * homepage contract, but the panel treatment makes the protected baseline feel
+ * premium without touching navigation, sidebar, toggle, or social links.
+ */
+.VPHome .VPHero .image {
+  flex: 0 1 420px;
+}
+
+.VPHome .VPHero .image-container {
+  position: relative;
+  min-height: 320px;
+  border-radius: 28px;
+  border: 1px solid var(--opensin-home-card-border);
+  background: var(--opensin-home-panel-bg);
+  box-shadow: var(--opensin-home-card-shadow);
+  overflow: hidden;
+}
+
+.VPHome .VPHero .image-container::before {
+  content: '';
+  position: absolute;
+  inset: 10% 12%;
+  border-radius: 999px;
+  background: radial-gradient(circle, rgba(0, 204, 136, 0.22), transparent 62%);
+  filter: blur(18px);
+}
+
+.VPHome .VPHero .image-bg,
+.VPHome .VPHero .image-src {
+  position: relative;
+  z-index: 1;
+}
+
+.VPHome .VPHero .image-src {
+  max-width: 280px !important;
+  height: auto !important;
+  filter: drop-shadow(0 18px 36px rgba(0, 0, 0, 0.16));
+}
+
+.VPHome .VPHomeFeatures {
+  padding-top: 18px;
+  padding-bottom: 10px;
+}
+
+.VPHome .VPHomeFeatures .container {
+  max-width: 1240px;
+}
+
+.VPHome .VPHomeFeatures .items {
+  gap: 18px;
+}
+
+.VPHome .VPFeature {
+  border: 1px solid var(--opensin-home-card-border);
+  border-radius: 24px;
+  background: var(--opensin-home-card-bg);
+  box-shadow: var(--opensin-home-card-shadow);
+  transition: transform 0.22s ease, border-color 0.22s ease, box-shadow 0.22s ease;
+}
+
+.VPHome .VPFeature:hover {
+  transform: translateY(-3px);
+  border-color: var(--opensin-home-card-border-strong);
+  box-shadow: var(--opensin-home-card-shadow-hover);
+}
+
 /* Homepage feature icons: premium green cards, not plain raw images. */
-.VPFeature .icon {
-  width: 52px;
-  height: 52px;
+.VPHome .VPFeature .icon {
+  width: 56px;
+  height: 56px;
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  padding: 10px;
-  border-radius: 12px;
+  padding: 11px;
+  border-radius: 16px;
   background: rgba(0, 204, 136, 0.08);
   border: 1px solid rgba(0, 204, 136, 0.18);
   box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.02);
 }
 
-html:not(.dark) .VPFeature .icon {
+html:not(.dark) .VPHome .VPFeature .icon {
   background: rgba(0, 204, 136, 0.07);
   border-color: rgba(0, 128, 96, 0.16);
 }
 
+.VPHome .VPFeature .title {
+  font-size: 1.16rem;
+  font-weight: 750;
+  letter-spacing: -0.02em;
+}
+
+.VPHome .VPFeature .details {
+  line-height: 1.65;
+}
+
+.VPHome .vp-doc {
+  margin: 0 auto 80px;
+  max-width: 1240px;
+}
+
+.VPHome .vp-doc > h2 {
+  margin: 4rem 0 0;
+  font-size: clamp(1.8rem, 3vw, 2.3rem);
+  font-weight: 800;
+  letter-spacing: -0.04em;
+}
+
 /* 🚨 TABLE ENHANCEMENTS 🚨 */
 .vp-doc table {
   width: 100%;
@@ -160,7 +345,7 @@ html:not(.dark) .VPFeature .icon {
 .vp-doc div[class*='language-'] > button.copy {
   position: absolute;
   top: 8px;
-  right: 48px; /* Neben das Label schieben */
+  right: 48px; /* Keep clear of the floating language label. */
   z-index: 3;
 }
 
@@ -192,30 +377,44 @@ html:not(.dark) .VPFeature .icon {
   background-color: rgba(0, 204, 136, 0.05) !important;
   border-color: #00cc88 !important;
 }
-.vp-doc .custom-block.tip .custom-block-title { color: #00ffaa; }
+
+.vp-doc .custom-block.tip .custom-block-title {
+  color: #00ffaa;
+}
 
 /* [WARNING] - Solar Yellow */
 .vp-doc .custom-block.warning {
   background-color: rgba(255, 191, 0, 0.05) !important;
   border-color: #ffbf00 !important;
 }
-.vp-doc .custom-block.warning .custom-block-title { color: #ffdb70; }
+
+.vp-doc .custom-block.warning .custom-block-title {
+  color: #ffdb70;
+}
 
 /* [DANGER / CAUTION] - Crimson Red */
-.vp-doc .custom-block.danger, .vp-doc .custom-block.caution {
+.vp-doc .custom-block.danger,
+.vp-doc .custom-block.caution {
   background-color: rgba(255, 95, 86, 0.05) !important;
   border-color: #ff5f56 !important;
 }
-.vp-doc .custom-block.danger .custom-block-title, 
-.vp-doc .custom-block.caution .custom-block-title { color: #ff918a; }
+
+.vp-doc .custom-block.danger .custom-block-title,
+.vp-doc .custom-block.caution .custom-block-title {
+  color: #ff918a;
+}
 
 /* [IMPORTANT / INFO] - Deep Sky */
-.vp-doc .custom-block.important, .vp-doc .custom-block.info {
+.vp-doc .custom-block.important,
+.vp-doc .custom-block.info {
   background-color: rgba(0, 153, 255, 0.05) !important;
   border-color: #0099ff !important;
 }
+
 .vp-doc .custom-block.important .custom-block-title,
-.vp-doc .custom-block.info .custom-block-title { color: #70c5ff; }
+.vp-doc .custom-block.info .custom-block-title {
+  color: #70c5ff;
+}
 
 /* Ensure text inside alerts is readable in both modes */
 .vp-doc .custom-block p {
@@ -223,10 +422,60 @@ html:not(.dark) .VPFeature .icon {
   margin: 0 !important;
 }
 
-/* 🚨 LOGO PROTECTION 🚨 */
-.VPNavBarTitle .logo { height: 32px !important; width: auto !important; margin-right: 12px !important; }
-.VPHero .image-container .image-src { max-width: 280px !important; height: auto !important; }
+/* 🚨 LOGO / NAV PROTECTION 🚨 */
+.VPNavBarTitle .logo {
+  height: 32px !important;
+  width: auto !important;
+  margin-right: 12px !important;
+}
+
+body {
+  font-family: 'Inter', sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+.VPNav {
+  backdrop-filter: blur(10px);
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.VPSwitchAppearance {
+  display: flex !important;
+}
+
+@media (max-width: 960px) {
+  .VPHome .VPHero {
+    padding-top: 44px;
+  }
+
+  .VPHome .VPHero .text {
+    max-width: 12ch;
+  }
+
+  .VPHome .VPHero .image {
+    flex-basis: 100%;
+  }
+
+  .VPHome .VPHero .image-container {
+    min-height: 260px;
+  }
+}
+
+@media (max-width: 640px) {
+  .VPHome::before {
+    height: 28rem;
+  }
+
+  .VPHome .VPHero .actions {
+    gap: 0.7rem;
+  }
+
+  .VPHome .VPHomeFeatures .items {
+    gap: 14px;
+  }
+
+  .VPHome .vp-doc {
+    margin-bottom: 64px;
+  }
+}
 
-body { font-family: "Inter", sans-serif; -webkit-font-smoothing: antialiased; }
-.VPNav { backdrop-filter: blur(10px); border-bottom: 1px solid var(--vp-c-divider); }
-.VPSwitchAppearance { display: flex !important; }
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 08dd36afb1..9875f502a5 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -6,6 +6,12 @@ import './custom.css'
 export default {
   ...DefaultTheme,
   enhanceApp({ app }) {
+    /**
+     * Keep homepage layout primitives registered at the theme layer.
+     * The homepage contract intentionally stays VitePress-native: markdown owns
+     * the structure, while Vue components provide the protected 2-card and
+     * 4-card sections without falling back to raw HTML blobs in docs/index.md.
+     */
     app.component('HomeChoosePath', HomeChoosePath)
     app.component('HomeRelatedTopics', HomeRelatedTopics)
   },

From 8008126c6324541762faa3bef91ec90d8d14261f Mon Sep 17 00:00:00 2001
From: SIN-Agent <agent@opensin.ai>
Date: Tue, 21 Apr 2026 07:16:13 +0200
Subject: [PATCH 3/3] docs: record homepage polish safeguards

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 docs/guide/changelog.md | 9 +++++++++
 docs/repair-docs.md     | 9 +++++++++
 2 files changed, 18 insertions(+)

diff --git a/docs/guide/changelog.md b/docs/guide/changelog.md
index 062a33bfb6..8e5843ba23 100644
--- a/docs/guide/changelog.md
+++ b/docs/guide/changelog.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## v1.1.0 (2026-04-21)
+
+### Changed
+- Polished the docs homepage inside the existing VitePress `layout: home` contract instead of rebuilding it.
+- Unified hero, feature, and custom homepage card styling behind shared surface tokens so the premium treatment is consistent across light and dark mode.
+- Added in-code comments around the protected 3/2/4 homepage structure and homepage-only theme logic to reduce accidental regressions.
+
+---
+
 ## v0.1.0 (2026-04-04)
 
 ### Added
diff --git a/docs/repair-docs.md b/docs/repair-docs.md
index 08d551821f..915adab6a5 100644
--- a/docs/repair-docs.md
+++ b/docs/repair-docs.md
@@ -1,5 +1,13 @@
 # OpenSIN Documentation Repair Log
 
+## 🎨 BUG-003: Homepage premium polish drift (FIXED 2026-04-21)
+
+**Symptom:** The homepage respected the protected 3/2/4 structure, but the hero and card system still felt visually flatter than the approved premium surface direction.
+**Root Cause:** Core VitePress home primitives and the custom homepage sections were styled independently, so spacing, card depth, and typography were not sharing one tokenized surface system.
+**Fix:** Introduced shared homepage surface tokens in `docs/.vitepress/theme/custom.css`, refined the hero/feature cadence, and rewired the two custom homepage sections to consume the same token system without changing the locked VitePress contract.
+**Contract check:** Homepage remains `layout: home`, preserves 3 feature cards, 2 `Choose Your Path` cards, 4 `Related topics` cards, dynamic sidebar behavior, visible toggle, visible Discord icon, and the protected button hover contract.
+**Tracking issue:** [#142](https://github.com/OpenSIN-AI/OpenSIN-documentation/issues/142)
+
 ## 🐛 BUG-001: Button Hover Shape Loss (FIXED 2026-04-16)
 
 **Symptom:** Buttons lose their 8px border-radius upon mouseover/hover, reverting to default pill or sharp shapes.
@@ -36,3 +44,4 @@ specific structural change.
 1. **DO NOT** remove the 8px border-radius from buttons.
 2. **ALWAYS** test hover states before deploying.
 3. **DOCUMENT** every visual fix in this file.
+4. **COMMENT** any non-obvious homepage theme logic in code near the affected selectors/components.