docs(site): clearer left-nav hierarchy + clickable header title

Style section headers (Get started, Governance, …) as bold uppercase
labels distinct from page links, highlight the active page, and make the
"AgentFlow4J" header title navigate home like the logo. Also gate the
social-cards plugin behind SOCIAL_CARDS so the site builds locally
without Cairo.

Author: agentflow4j

docs/javascripts/header-home-link.js

@@ -0,0 +1,15 @@
+/* Make the header site title ("AgentFlow4J") clickable → home,
+   mirroring the logo's per-page relative href. */
+document.addEventListener("DOMContentLoaded", function () {
+  var title = document.querySelector(".md-header__title");
+  var logo = document.querySelector(".md-header__button.md-logo");
+  if (!title || !logo) return;
+
+  title.style.cursor = "pointer";
+  title.addEventListener("click", function (e) {
+    // leave genuinely interactive children (search, buttons) alone
+    if (e.target.closest("a, button, input, label, .md-search")) return;
+    var href = logo.getAttribute("href");
+    if (href) window.location.href = href;
+  });
+});

docs/stylesheets/extra.css

@@ -0,0 +1,31 @@
+/* ---------------------------------------------------------------------------
+   Left navigation — clear visual hierarchy between section headers and pages.
+
+   Section labels (Get started, Governance, …) are <label> elements rendered by
+   `navigation.sections`; page links are <a> elements. Styling each by element
+   type avoids any specificity conflict.
+   --------------------------------------------------------------------------- */
+
+/* Section headers: bold, uppercase, slightly LARGER than page links */
+.md-nav--primary .md-nav__item--section > label.md-nav__link,
+.md-nav--primary .md-nav__item--section > span.md-nav__link {
+  font-size: 0.8rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--md-default-fg-color);
+  margin-top: 1.1rem;
+  margin-bottom: 0.2rem;
+  cursor: default;
+}
+
+/* Page links: normal weight + case, slightly smaller than Material default */
+.md-nav--primary a.md-nav__link {
+  font-size: 0.76rem;
+}
+
+/* Active page link: accent colour + medium weight = clear "you are here" */
+.md-nav--primary a.md-nav__link--active {
+  font-weight: 600;
+  color: var(--md-primary-fg-color);
+}

mkdocs.yml

@@ -9,6 +9,12 @@ edit_uri: edit/main/docs/
 
 docs_dir: docs
 
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/header-home-link.js
+
 theme:
   name: material
   language: en
@@ -92,6 +98,7 @@ nav:
 plugins:
   - search
   - social:
+      enabled: !ENV [SOCIAL_CARDS, true]   # set SOCIAL_CARDS=false for local preview without Cairo
       cards: true
       cards_layout_options:
         background_color: "#0f172a"  # slate-900