jekyll-theme-zer0 1.28.0 → 1.30.0

data/_includes/navigation/nav-tree.html

@@ -1,4 +1,4 @@
-<!--
+{% comment %}
   ===================================================================
   NAV TREE - Flat YAML Navigation Renderer
   ===================================================================
@@ -28,7 +28,7 @@
   Usage:
   include navigation/nav-tree.html nav="docs"
   ===================================================================
--->
+{% endcomment %}
 
 {% assign navigation = site.data.navigation[include.nav] %}
 
@@ -42,7 +42,7 @@
     
     <li class="mb-1 nav-tree-item" data-depth="0">
       {% if has_children %}
-        <!-- Parent item with children - collapsible -->
+        {% comment %} Parent item with children - collapsible {% endcomment %}
         <div class="d-flex align-items-center">
           {% if item.url %}
             <a href="{{ item.url | relative_url }}" 
@@ -73,7 +73,7 @@
           {% endif %}
         </div>
         
-        <!-- Children container (Level 1) -->
+        {% comment %} Children container (Level 1) {% endcomment %}
         <div class="collapse{% if is_expanded %} show{% endif %}" id="{{ item_id }}">
           <ul class="list-unstyled fw-normal ps-3 nav-tree-children">
             {% for child in item.children %}
@@ -84,7 +84,7 @@
               
               <li class="mb-1 nav-tree-item" data-depth="1">
                 {% if child_has_children %}
-                  <!-- Level 1 parent with children -->
+                  {% comment %} Level 1 parent with children {% endcomment %}
                   <div class="d-flex align-items-center">
                     {% if child.url %}
                       <a href="{{ child.url | relative_url }}" 
@@ -114,7 +114,7 @@
                     {% endif %}
                   </div>
                   
-                  <!-- Children container (Level 2) -->
+                  {% comment %} Children container (Level 2) {% endcomment %}
                   <div class="collapse{% if child_expanded %} show{% endif %}" id="{{ child_id }}">
                     <ul class="list-unstyled fw-normal ps-3 nav-tree-children">
                       {% for grandchild in child.children %}
@@ -137,7 +137,7 @@
                     </ul>
                   </div>
                 {% else %}
-                  <!-- Level 1 leaf item -->
+                  {% comment %} Level 1 leaf item {% endcomment %}
                   {% if child.url %}
                     <a href="{{ child.url | relative_url }}" 
                        class="nav-tree-link d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none{% if child_active %} active{% endif %}">
@@ -156,7 +156,7 @@
           </ul>
         </div>
       {% else %}
-        <!-- Root level leaf item -->
+        {% comment %} Root level leaf item {% endcomment %}
         {% if item.url %}
           <a href="{{ item.url | relative_url }}" 
              class="nav-tree-link d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none{% if is_active %} active{% endif %}">

data/_includes/navigation/navbar.html

@@ -1,25 +1,25 @@
 {% comment %} Features: ZER0-049, ZER0-055 {% endcomment %}
-<!-- 
+{% comment %} 
     file: navbar.html
     path: /includes/navbar.html
     includes:
     purpose: Offcanvas main navigation following Bootstrap 5 best practices
              with hover-activated dropdowns for desktop and accessible interactions
- -->
+ {% endcomment %}
 
-<!-- Navigation Links - Responsive Offcanvas (inline at lg+, offcanvas below) -->
+{% comment %} Navigation Links - Responsive Offcanvas (inline at lg+, offcanvas below) {% endcomment %}
 {%- include core/i18n.html -%}
 <div class="offcanvas-lg offcanvas-end" tabindex="-1" id="bdNavbar" aria-labelledby="mainNavOffcanvasLabel">
 
-    <!-- Main Navigation Header - Offcanvas -->
+    {% comment %} Main Navigation Header - Offcanvas {% endcomment %}
     <div class="offcanvas-header border-bottom">
         <h2 class="offcanvas-title h5 mb-0" id="mainNavOffcanvasLabel">{{ ui.main_nav_label | default: "Main Navigation" }}</h2>
         <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close navigation menu" data-bs-target="#bdNavbar"></button>
     </div>
 
-    <!-- Main Navigation Body - Offcanvas -->
+    {% comment %} Main Navigation Body - Offcanvas {% endcomment %}
     <div class="offcanvas-body">
-        <!-- Desktop: width is the grid middle track; labels ellipsis or icon-only via container query -->
+        {% comment %} Desktop: width is the grid middle track; labels ellipsis or icon-only via container query {% endcomment %}
         <div class="bd-navbar-nav-viewport">
         <ul class="navbar-nav justify-content-lg-center text-start flex-grow-1">
             <li class="nav-item d-lg-none">
@@ -44,7 +44,7 @@
 
                 {%- if has_children -%}
                     <li class="nav-item dropdown d-flex align-items-center nav-hover-dropdown">
-                        <!-- Parent link navigates directly -->
+                        {% comment %} Parent link navigates directly {% endcomment %}
                         <a
                             class="nav-link"
                             href="{{ link.url | relative_url }}"
@@ -58,9 +58,9 @@
                             <span class="nav-link-text">{{ link.title }}</span>
                         </a>
 
-                        <!-- Split toggle opens the dropdown (click on mobile, hover on desktop) -->
-                        <!-- Note: No data-bs-toggle="dropdown" — custom JS handles all interactions
-                             to avoid Bootstrap's native handler conflicting with our toggle logic -->
+                        {% comment %} Split toggle opens the dropdown (click on mobile, hover on desktop) {% endcomment %}
+                        {% comment %} Note: No data-bs-toggle="dropdown" — custom JS handles all interactions
+                             to avoid Bootstrap's native handler conflicting with our toggle logic {% endcomment %}
                         <button
                             class="nav-link dropdown-toggle dropdown-toggle-split ms-1"
                             type="button"
@@ -165,8 +165,8 @@
     </div>
 </div>
 
-<!-- 
+{% comment %} 
   Navigation styles are now in _sass/core/_navbar.scss
   Navigation scripts are now in assets/js/navigation.js
   These are loaded automatically via the theme's asset pipeline
--->
+{% endcomment %}

data/_includes/navigation/section-sidebar.html

@@ -1,4 +1,4 @@
-<!--
+{% comment %}
   ===================================================================
   SECTION SIDEBAR - Fixed Topic Navigation
   ===================================================================
@@ -12,32 +12,72 @@
   - sub_categories: Array of unique tags/topics from section posts
   - page_title: Title of the current section
   - sidebar_id: Unique ID for the sidebar (default: "sectionSidebar")
-  
+  - section_style: The parent layout's display style, one of grid | list |
+    magazine (default: "grid"). Decides whether topics render as scroll
+    anchors or as filter buttons — see the Topic controls note below.
+
   Features:
   - Desktop: Fixed sticky sidebar on the left
   - Mobile: Offcanvas drawer
   - Topic navigation with article counts
   - Section statistics
-  - Smooth scroll to sections
+  - Smooth scroll to sections (magazine style, where scroll targets exist)
+  - Card filtering via [data-filter] (grid/list styles)
   
   Dependencies:
   - Bootstrap 5 offcanvas component
   - Bootstrap Icons
   ===================================================================
--->
+{% endcomment %}
 
 {% assign sidebar_id = include.sidebar_id | default: "sectionSidebar" %}
 {% assign section_posts = include.section_posts %}
 {% assign sub_categories = include.sub_categories %}
 {% assign page_title = include.page_title | default: page.title %}
+{% assign section_style = include.section_style | default: "grid" %}
+
+{% comment %}
+  Topic controls: link vs filter.
+
+  Only the `magazine` branch of _layouts/section.html emits per-subcategory
+  `<section id="{{ subcat | slugify }}">` scroll targets, and only for the first
+  5 sub-categories that still have a post once the featured hero is excluded.
+  The `grid` and `list` branches emit no sub-topic ids at all — they filter
+  `[data-tags]` cards through `[data-filter]` buttons instead.
 
-<!-- ================================ -->
-<!-- DESKTOP SIDEBAR (Fixed Sticky)   -->
-<!-- ================================ -->
+  So an <a href="#slug"> here is only ever valid under magazine, and only for
+  that exact set. Emitting one anywhere else produced guaranteed-dead anchors:
+  invalid markup, a dead click for keyboard/AT users, and a scrollspy that could
+  never activate. `_linkable_subcats` below reproduces the layout's set exactly;
+  every other style renders filter buttons, which the layout's existing
+  `[data-filter]` handler already wires up with no extra JS.
+{% endcomment %}
+{% assign _anchors_resolve = false %}
+{% if section_style == "magazine" %}{% assign _anchors_resolve = true %}{% endif %}
+
+{% assign _linkable_subcats = "" | split: "" %}
+{% if _anchors_resolve %}
+  {% assign _featured = section_posts | where: "featured", true | first %}
+  {% unless _featured %}{% assign _featured = section_posts | first %}{% endunless %}
+  {% for subcat in sub_categories limit: 5 %}
+    {% assign _subcat_posts = section_posts | where_exp: "post", "post.tags contains subcat" %}
+    {% assign _remaining = 0 %}
+    {% for p in _subcat_posts %}
+      {% unless p.url == _featured.url %}{% assign _remaining = _remaining | plus: 1 %}{% endunless %}
+    {% endfor %}
+    {% if _remaining > 0 %}
+      {% assign _linkable_subcats = _linkable_subcats | push: subcat %}
+    {% endif %}
+  {% endfor %}
+{% endif %}
+
+{% comment %} ================================ {% endcomment %}
+{% comment %} DESKTOP SIDEBAR (Fixed Sticky)   {% endcomment %}
+{% comment %} ================================ {% endcomment %}
 <aside class="section-sidebar-desktop d-none d-lg-block w-100">
   <div class="position-sticky" style="top: 80px;">
     
-    <!-- Topics Card -->
+    {% comment %} Topics Card {% endcomment %}
     <div class="card border-0 shadow-sm">
       <div class="card-header bg-primary text-white d-flex justify-content-between align-items-center">
         <h5 class="mb-0">
@@ -47,21 +87,37 @@
       </div>
       <div class="card-body p-0">
         <nav class="nav flex-column sidebar-nav">
+          {% if _anchors_resolve %}
           <a class="nav-link active" href="#all-posts" data-section="all-posts">
             <i class="bi bi-grid me-2"></i>
             <span class="nav-text">All Articles</span>
             <span class="badge bg-secondary ms-auto">{{ section_posts.size }}</span>
           </a>
-          {% for subcat in sub_categories limit: 15 %}
+          {% for subcat in _linkable_subcats %}
             {% assign subcat_posts = section_posts | where_exp: "post", "post.tags contains subcat" %}
-            {% if subcat_posts.size > 0 %}
             <a class="nav-link" href="#{{ subcat | slugify }}" data-section="{{ subcat | slugify }}">
               <i class="bi bi-tag me-2"></i>
               <span class="nav-text">{{ subcat | capitalize }}</span>
               <span class="badge bg-light text-dark ms-auto">{{ subcat_posts.size }}</span>
             </a>
+          {% endfor %}
+          {% else %}
+          <button type="button" class="nav-link text-start active" data-filter="all">
+            <i class="bi bi-grid me-2"></i>
+            <span class="nav-text">All Articles</span>
+            <span class="badge bg-secondary ms-auto">{{ section_posts.size }}</span>
+          </button>
+          {% for subcat in sub_categories limit: 15 %}
+            {% assign subcat_posts = section_posts | where_exp: "post", "post.tags contains subcat" %}
+            {% if subcat_posts.size > 0 %}
+            <button type="button" class="nav-link text-start" data-filter="{{ subcat | slugify }}">
+              <i class="bi bi-tag me-2"></i>
+              <span class="nav-text">{{ subcat | capitalize }}</span>
+              <span class="badge bg-light text-dark ms-auto">{{ subcat_posts.size }}</span>
+            </button>
             {% endif %}
           {% endfor %}
+          {% endif %}
         </nav>
       </div>
       {% comment %} Existence-gate the tags index: a remote-theme consumer without
@@ -78,7 +134,7 @@
       {% endif %}
     </div>
     
-    <!-- Section Stats -->
+    {% comment %} Section Stats {% endcomment %}
     <div class="card border-0 shadow-sm mt-3">
       <div class="card-body">
         <h6 class="text-muted mb-3">
@@ -102,31 +158,45 @@
   </div>
 </aside>
 
-<!-- ================================ -->
-<!-- MOBILE OFFCANVAS SIDEBAR         -->
-<!-- ================================ -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} MOBILE OFFCANVAS SIDEBAR         {% endcomment %}
+{% comment %} ================================ {% endcomment %}
 <div class="offcanvas offcanvas-start" tabindex="-1" id="{{ sidebar_id }}" aria-labelledby="{{ sidebar_id }}Label">
   <div class="offcanvas-header bg-primary text-white">
-    <h5 class="offcanvas-title" id="{{ sidebar_id }}Label">
+    <h2 class="offcanvas-title h5" id="{{ sidebar_id }}Label">
       <i class="bi bi-bookmark me-2"></i>{{ page_title }} Topics
-    </h5>
+    </h2>
     <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvas" aria-label="Close"></button>
   </div>
   <div class="offcanvas-body p-0">
     <nav class="nav flex-column">
+      {% if _anchors_resolve %}
       <a class="nav-link active bg-light py-3 border-bottom" href="#all-posts" data-bs-dismiss="offcanvas">
         <i class="bi bi-grid me-2"></i>All Articles
         <span class="badge bg-secondary float-end">{{ section_posts.size }}</span>
       </a>
-      {% for subcat in sub_categories %}
+      {% for subcat in _linkable_subcats %}
         {% assign subcat_posts = section_posts | where_exp: "post", "post.tags contains subcat" %}
-        {% if subcat_posts.size > 0 %}
         <a class="nav-link text-body-secondary py-3 border-bottom" href="#{{ subcat | slugify }}" data-bs-dismiss="offcanvas">
           <i class="bi bi-tag me-2"></i>{{ subcat | capitalize }}
           <span class="badge bg-light text-dark float-end">{{ subcat_posts.size }}</span>
         </a>
+      {% endfor %}
+      {% else %}
+      <button type="button" class="nav-link text-start active bg-light py-3 border-bottom w-100" data-filter="all" data-bs-dismiss="offcanvas">
+        <i class="bi bi-grid me-2"></i>All Articles
+        <span class="badge bg-secondary float-end">{{ section_posts.size }}</span>
+      </button>
+      {% for subcat in sub_categories %}
+        {% assign subcat_posts = section_posts | where_exp: "post", "post.tags contains subcat" %}
+        {% if subcat_posts.size > 0 %}
+        <button type="button" class="nav-link text-start text-body-secondary py-3 border-bottom w-100" data-filter="{{ subcat | slugify }}" data-bs-dismiss="offcanvas">
+          <i class="bi bi-tag me-2"></i>{{ subcat | capitalize }}
+          <span class="badge bg-light text-dark float-end">{{ subcat_posts.size }}</span>
+        </button>
         {% endif %}
       {% endfor %}
+      {% endif %}
     </nav>
     {% if _tags_page %}
     <div class="p-3">
@@ -138,9 +208,9 @@
   </div>
 </div>
 
-<!-- ================================ -->
-<!-- SIDEBAR STYLES                   -->
-<!-- ================================ -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} SIDEBAR STYLES                   {% endcomment %}
+{% comment %} ================================ {% endcomment %}
 <style>
   /* Sidebar Navigation */
   .sidebar-nav .nav-link {
@@ -169,6 +239,16 @@
     overflow: hidden;
     text-overflow: ellipsis;
   }
+
+  /* In grid/list styles the topic controls are <button data-filter> (there is
+     no per-topic scroll target to link to). Bootstrap's .nav-link already
+     clears button background/border; these are the two properties a <button>
+     still needs to render identically to the anchor form. */
+  .sidebar-nav button.nav-link,
+  .offcanvas button.nav-link {
+    width: 100%;
+    text-align: left;
+  }
   
   /* Offcanvas mobile styling */
   .offcanvas .nav-link {
@@ -178,9 +258,9 @@
   }
 </style>
 
-<!-- ================================ -->
-<!-- SIDEBAR JAVASCRIPT               -->
-<!-- ================================ -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} SIDEBAR JAVASCRIPT               {% endcomment %}
+{% comment %} ================================ {% endcomment %}
 <script>
 (function() {
   // Smooth scroll for sidebar links
@@ -194,8 +274,10 @@
           if (target) {
             target.scrollIntoView({ behavior: 'smooth' });
             
-            // Update active state in sidebar
-            document.querySelectorAll('.sidebar-nav .nav-link').forEach(link => {
+            // Update active state in sidebar. Scoped to anchors: in grid/list
+            // styles the topic controls are <button data-filter> elements whose
+            // active state belongs to the layout's filter handler, not here.
+            document.querySelectorAll('.sidebar-nav a.nav-link').forEach(link => {
               link.classList.remove('active');
             });
             
@@ -220,7 +302,7 @@
       entries.forEach(entry => {
         if (entry.isIntersecting) {
           const id = entry.target.getAttribute('id');
-          document.querySelectorAll('.sidebar-nav .nav-link').forEach(link => {
+          document.querySelectorAll('.sidebar-nav a.nav-link').forEach(link => {
             link.classList.remove('active');
             if (link.getAttribute('href') === `#${id}`) {
               link.classList.add('active');

data/_includes/navigation/sidebar-config.html

@@ -16,8 +16,13 @@
                                      "categories", "tags", or the name of a
                                      _data/navigation/*.yml file (nil = none)
                sidebar_has_content — true only when sidebar_nav will actually
-                                     render items (gates the left column and
-                                     the mobile toggle)
+                                     render items (gates the left column)
+               sidebar_offcanvas_rendered
+                                   — true only when the CURRENT LAYOUT emits
+                                     the #bdSidebar / #tocContents offcanvases
+                                     at all. sidebar_has_content is not enough
+                                     to gate a toggle: see the note at the
+                                     bottom of this file (issue #373).
                sidebar_title       — heading text for the sidebar panel
                sidebar_icon        — Bootstrap Icons class for the heading
   Config precedence (most specific wins):
@@ -134,3 +139,32 @@
 {%- if page.sidebar.icon -%}
   {%- assign sidebar_icon = page.sidebar.icon -%}
 {%- endif -%}
+
+{%- comment -%}
+  7. Does THIS LAYOUT actually render the offcanvas panels? (issue #373)
+
+  `sidebar_has_content` answers "is there nav content", which is what gates the
+  left column inside _layouts/default.html. It is NOT sufficient to gate the
+  TOGGLES, because core/header.html and core/footer-fabs.html are included from
+  _layouts/root.html — so they render on every layout, while `#bdSidebar`
+  (navigation/sidebar-left.html) and `#tocContents` (navigation/sidebar-right.html)
+  are emitted by _layouts/default.html alone.
+
+  The result was a dead control plus a dangling ARIA reference on every page
+  whose layout inherits `root` directly: measured at 37 pages of a 415-page
+  build, including all of `/about/**` (layout: admin) and 404/CHANGELOG.
+  Clicking did nothing, and assistive tech followed aria-controls to an element
+  that was not there.
+
+  There is no Liquid API for "resolve the layout inheritance chain", so the set
+  of layouts that reach default.html is listed here explicitly. It is pinned by
+  a test (test/test_core.sh :: test_sidebar_offcanvas_layout_gate) that reads
+  the front matter of every _layouts/*.html and fails if reality drifts from
+  this list — the same invariant pattern #425 used for the pixel-gate filter.
+  Add a layout here when, and only when, its `layout:` chain reaches default.
+{%- endcomment -%}
+{%- assign _sidebar_offcanvas_layouts = "default,article,author,authors,collection,cookbook,note,notebook,recipe,tag" | split: "," -%}
+{%- assign sidebar_offcanvas_rendered = false -%}
+{%- if _sidebar_offcanvas_layouts contains page.layout -%}
+  {%- assign sidebar_offcanvas_rendered = true -%}
+{%- endif -%}

data/_includes/navigation/sidebar-left.html

@@ -1,5 +1,5 @@
 {% comment %} Feature: ZER0-008 {% endcomment %}
-<!--
+{% comment %}
   ===================================================================
   SIDEBAR LEFT - Dynamic Navigation Sidebar
   ===================================================================
@@ -27,14 +27,14 @@
   - Heading text/icon: page.sidebar.title/icon → collection metadata →
     site.sidebar.title/icon → "Browse docs"
   ===================================================================
--->
+{% endcomment %}
 
 {% include navigation/sidebar-config.html %}
 
-<!-- ================================ -->
-<!-- SIDEBAR NAVIGATION CONTAINER   -->
-<!-- ================================ -->
-<!-- Responsive offcanvas sidebar - full-width on mobile, fixed on desktop -->
+{% comment %} ================================ {% endcomment %}
+{% comment %} SIDEBAR NAVIGATION CONTAINER   {% endcomment %}
+{% comment %} ================================ {% endcomment %}
+{% comment %} Responsive offcanvas sidebar - full-width on mobile, fixed on desktop {% endcomment %}
 <script>
   try {
     if (localStorage.getItem('zer0-nav-sidebar-visible') === 'false') {
@@ -44,10 +44,10 @@
 </script>
 <div class="offcanvas-lg offcanvas-start" tabindex="-1" id="bdSidebar" aria-labelledby="bdSidebarOffcanvasLabel">
 
-  <!-- ========================== -->
-  <!-- SIDEBAR HEADER            -->
-  <!-- ========================== -->
-  <!-- Mobile-only header with close button -->
+  {% comment %} ========================== {% endcomment %}
+  {% comment %} SIDEBAR HEADER            {% endcomment %}
+  {% comment %} ========================== {% endcomment %}
+  {% comment %} Mobile-only header with close button {% endcomment %}
   <div class="offcanvas-header">
     <h2 class="offcanvas-title h5 mb-0" id="bdSidebarOffcanvasLabel">{{ sidebar_title }}</h2>
     <div class="d-flex align-items-center gap-1">
@@ -63,10 +63,10 @@
     </div>
   </div>
 
-  <!-- ========================== -->
-  <!-- SIDEBAR CONTENT AREA      -->
-  <!-- ========================== -->
-  <!-- Scrollable content area with dynamic navigation options -->
+  {% comment %} ========================== {% endcomment %}
+  {% comment %} SIDEBAR CONTENT AREA      {% endcomment %}
+  {% comment %} ========================== {% endcomment %}
+  {% comment %} Scrollable content area with dynamic navigation options {% endcomment %}
   <div class="offcanvas-body overflow-auto">
 
     <div class="bd-sidebar-desktop-header mb-3 d-none d-lg-flex align-items-center justify-content-between gap-2 w-100">
@@ -79,13 +79,14 @@
               aria-controls="bdSidebar"
               aria-expanded="true"
               aria-label="Hide documentation sidebar"
-              title="Hide documentation sidebar">
+              aria-keyshortcuts="b"
+              title="Hide documentation sidebar (b)">
         <i class="bi bi-layout-sidebar-inset" aria-hidden="true"></i>
         <span class="visually-hidden">Hide documentation sidebar</span>
       </button>
     </div>
 
-    <!-- Resolved navigation content (see navigation/sidebar-nav.html) -->
+    {% comment %} Resolved navigation content (see navigation/sidebar-nav.html) {% endcomment %}
     {% include navigation/sidebar-nav.html id="sidebar-content" %}
 
   </div>

data/_includes/navigation/sidebar-right.html

@@ -1,12 +1,12 @@
 {% comment %} Features: ZER0-008, ZER0-010 {% endcomment %}
-<!-- 
+{% comment %} 
   file: sidebar-right.html 
   path: _includes/sidebar-right.html
   includes: nav_list.html, content/toc.html
--->
+{% endcomment %}
 
 {%- include core/i18n.html -%}
-<!-- FOUC guard: apply hidden TOC preference before paint -->
+{% comment %} FOUC guard: apply hidden TOC preference before paint {% endcomment %}
 <script>
   try {
     if (localStorage.getItem('zer0-nav-toc-visible') === 'false') {
@@ -15,7 +15,7 @@
   } catch (e) {}
 </script>
 
-<!-- Right sidebar container -->
+{% comment %} Right sidebar container {% endcomment %}
 <div class="offcanvas-lg offcanvas-end" tabindex="-1" id="tocContents" aria-labelledby="tocLabel">
   <div class="offcanvas-header">
     <h2 class="offcanvas-title h5 mb-0" id="tocLabel">{{ ui.toc_title | default: "Table of Contents" }}</h2>
@@ -32,9 +32,9 @@
     </div>
   </div>
   <div class="offcanvas-body">
-    <!-- Table of contents -->
+    {% comment %} Table of contents {% endcomment %}
     <nav id="TableOfContents" role="navigation" aria-label="Table of Contents">
-      <!-- TOC title -->
+      {% comment %} TOC title {% endcomment %}
       <div class="mb-3 d-flex align-items-center justify-content-between gap-2">
         <strong class="d-flex align-items-center mb-0">
           <i class="bi bi-file-text me-2" aria-hidden="true"></i>
@@ -45,7 +45,8 @@
                 aria-controls="tocContents"
                 aria-expanded="true"
                 aria-label="Hide table of contents"
-                title="Hide table of contents">
+                aria-keyshortcuts="t"
+                title="Hide table of contents (t)">
           <i class="bi bi-layout-sidebar-inset-reverse" aria-hidden="true"></i>
           <span class="visually-hidden">Hide table of contents</span>
         </button>

data/_includes/obsidian/full-graph.html

@@ -197,9 +197,9 @@ unresolved targets show up as dashed red nodes so you can find dangling
 links at a glance. The graph is regenerated every Jekyll build; nothing
 runs client-side except cytoscape's force layout.
 
-<!-- Cytoscape.js is vendored (no runtime CDN) and lazy-loaded by
+{% comment %} Cytoscape.js is vendored (no runtime CDN) and lazy-loaded by
      obsidian-graph.js from window.OBSIDIAN_CONFIG.cytoscapeUrl, only on this
-     page, with an in-page recovery message if the fetch fails. -->
+     page, with an in-page recovery message if the fetch fails. {% endcomment %}
 {% if site.obsidian.enabled != false %}
 <script src="{{ '/assets/js/obsidian-graph.js' | relative_url }}?v={{ site.time | date: '%s' }}" defer></script>
 {% endif %}

data/_includes/setup/claude-session.html

@@ -0,0 +1,72 @@
+{% comment %} Feature: ZER0-086, ZER0-087 {% endcomment %}
+{%- comment -%}
+  Component:   setup/claude-session
+  Path:        _includes/setup/claude-session.html
+  Purpose:     The embedded AI session that rides alongside every Site
+               Builder step: connection state, provider + mode badges,
+               transcript, suggested prompts, and the composer with a Stop
+               button for long tool runs. The assistant (Claude or Grok —
+               whichever the Connect step connected) sees the whole wizard
+               state on every turn and acts on it through tools (fill fields,
+               run checks, read theme source, write or modify the project,
+               generate images, run Docker).
+  Params:      none — configured by #siteBuilderConfig in setup/wizard.html
+  Depends on:  Bootstrap 5.3 + Icons, assets/js/site-builder.js,
+               _sass/components/_setup-wizard.scss
+  Notes:
+    - Proxy-only. Nothing renders a credential; the panel shows a connect
+      prompt until GET {endpoint}/status answers AND the chosen provider has
+      a key (data-ready="true"), then goes live.
+    - Rendering is escape-first (a limited Markdown subset); action cards are
+      built with createElement/textContent — see ai-chat.instructions.md.
+    - role="log" + aria-live so screen readers hear replies; Escape does not
+      close the panel (it is a page region, not a dialog).
+{%- endcomment -%}
+
+<section class="sb-panel card" id="siteBuilderPanel" aria-labelledby="sb-title" data-state="offline" data-ready="false" data-mode="guided">
+  <div class="card-header d-flex align-items-center justify-content-between gap-2 py-2">
+    <div class="d-flex align-items-center gap-2 min-w-0">
+      <i class="bi bi-stars" aria-hidden="true"></i>
+      <h2 class="h6 mb-0 text-truncate" id="sb-title">AI session</h2>
+      <span class="badge rounded-pill text-bg-light border sb-mode-badge" id="sb-mode-badge" hidden>guided</span>
+    </div>
+    <div class="d-flex align-items-center gap-2">
+      <span class="sb-status-badge badge rounded-pill text-bg-secondary" id="sb-status-badge" aria-live="polite">offline</span>
+      <button class="btn btn-sm btn-link text-body p-0" type="button" id="sb-clear" title="Clear the conversation" aria-label="Clear the conversation">
+        <i class="bi bi-eraser" aria-hidden="true"></i>
+      </button>
+      <button class="btn btn-sm btn-link text-body p-0" type="button" id="sb-collapse" aria-expanded="true" aria-controls="sb-body" title="Collapse">
+        <i class="bi bi-chevron-up" aria-hidden="true"></i>
+      </button>
+    </div>
+  </div>
+
+  <div class="sb-body" id="sb-body">
+    <div class="sb-messages p-3" id="sb-messages" role="log" aria-live="polite" aria-relevant="additions">
+      <div class="sb-offline text-body-secondary small" id="sb-offline">
+        <p class="mb-1"><strong>Not connected.</strong> Start the dev proxy and connect Claude or Grok on step 1. The assistant can then read your answers, fill in the forms, check your machine, read the theme's source, write or modify your project, generate images and run the build.</p>
+        <p class="mb-0">Everything else on this page works without it.</p>
+      </div>
+    </div>
+
+    <div class="sb-chips px-3 pb-2 d-flex gap-2 flex-wrap" id="sb-chips" aria-label="Suggested prompts"></div>
+
+    <form class="sb-composer p-3 pt-0" id="sb-form" autocomplete="off">
+      <label for="sb-input" class="visually-hidden">Message the assistant</label>
+      <div class="input-group">
+        <textarea class="form-control" id="sb-input" rows="1" maxlength="6000"
+                  placeholder="Connect a provider to start chatting" disabled></textarea>
+        <button class="btn btn-primary" type="submit" id="sb-send" aria-label="Send" disabled>
+          <i class="bi bi-send" aria-hidden="true"></i>
+        </button>
+        <button class="btn btn-outline-danger" type="button" id="sb-stop" aria-label="Stop the current run" hidden disabled>
+          <i class="bi bi-stop-fill" aria-hidden="true"></i> Stop
+        </button>
+      </div>
+      <div class="d-flex justify-content-between align-items-center mt-1">
+        <small class="text-body-secondary sb-disclaimer" id="sb-disclaimer">The assistant sees every answer on this page. Actions ask for confirmation first.</small>
+        <small class="text-body-secondary" id="sb-context-note"></small>
+      </div>
+    </form>
+  </div>
+</section>