diff --git a/docs-site/.vitepress/config.ts b/docs-site/.vitepress/config.ts
index 63d35bd7..8187ea8a 100644
--- a/docs-site/.vitepress/config.ts
+++ b/docs-site/.vitepress/config.ts
@@ -146,6 +146,16 @@ export default withMermaid({
   mermaid: {
     // theme intentionally unset — vitepress-plugin-mermaid auto-switches
     // between 'default' (light) and 'dark' based on VitePress appearance
+    themeVariables: {
+      // keep in sync with the font-size override in custom.css so mermaid's
+      // node-size measurements match the rendered text and labels don't clip
+      fontSize: '15px',
+    },
+    flowchart: {
+      htmlLabels: true,
+      useMaxWidth: true,
+      padding: 12,
+    },
   },
   mermaidPlugin: {
     class: 'mermaid-diagram',
diff --git a/docs-site/.vitepress/theme/custom.css b/docs-site/.vitepress/theme/custom.css
index 9df91170..f0b4acbd 100644
--- a/docs-site/.vitepress/theme/custom.css
+++ b/docs-site/.vitepress/theme/custom.css
@@ -97,6 +97,19 @@
   font-size: 15px !important;
 }
 
+/* mermaid renders label text through a markdown parser that wraps lines in
+   <p> elements. The browser's default <p> margin inflates the rendered
+   label height beyond the foreignObject size mermaid measured, so the last
+   line gets clipped below the node rect. Zero the margin so rendered and
+   measured heights match. */
+.mermaid-diagram svg .nodeLabel p,
+.mermaid-diagram svg .edgeLabel p,
+.mermaid-diagram svg .cluster-label p,
+.mermaid-diagram svg .label p {
+  margin: 0 !important;
+  line-height: 1.5 !important;
+}
+
 /* dark mode: force readable label colors — mermaid's dark theme
    sometimes leaves inherited fills that blend into the background */
 .dark .mermaid-diagram svg .nodeLabel,
diff --git a/docs-site/index.md b/docs-site/index.md
index ce685e44..6e13dad9 100644
--- a/docs-site/index.md
+++ b/docs-site/index.md
@@ -43,7 +43,9 @@ features:
 ---
 
 <div class="fork-banner">
-<strong>Looking for <code>vercel/pkg</code>?</strong> This is <a href="https://github.com/yao-pkg/pkg"><code>yao-pkg/pkg</code></a> — the actively maintained fork. The original <code>vercel/pkg</code> is archived. <code>@yao-pkg/pkg</code> is a drop-in replacement — rename the dep and keep shipping. See the [migration guide](/guide/migration).
+
+**Looking for `vercel/pkg`?** This is [`yao-pkg/pkg`](https://github.com/yao-pkg/pkg) — the actively maintained fork. The original `vercel/pkg` is archived. `@yao-pkg/pkg` is a drop-in replacement — rename the dep and keep shipping. See the [migration guide](/guide/migration).
+
 </div>
 
 <div class="landing-badges">