@kolkrabbi/kol-workshop 0.5.1 → 0.11.0

package/src/engine/index.js

@@ -2,7 +2,7 @@
  * The pure docs engine — zero dependencies, no React, no Vite.
  * Everything here is a plain function over strings/data.
  */
-export { parseDocsMarkdown, extractHashtags } from './parse-markdown.js'
+export { parseDocsMarkdown, extractHashtags, processInlineMarkdown } from './parse-markdown.js'
 export { parseFrontmatter } from './frontmatter.js'
 export { buildInventory, buildInventoryCounts } from './build-inventory.js'
 export { matchSearchItems } from './search.js'
@@ -15,6 +15,7 @@ export {
   subsectionPrefixes,
   categoryLabels,
   cleanTitle,
+  fileLabel,
   getTagColor,
   groupDocsByMajor,
 } from './doc-helpers.js'

package/src/engine/parse-markdown.js

@@ -21,7 +21,11 @@ export const extractHashtags = (content) => {
  * Supports: bold, italic, inline code, links, images, color swatches, hashtags.
  * Returns a token array; the render layer turns tokens into elements.
  */
-const processInlineMarkdown = (text) => {
+/* EXPORTED 2026-08-01. The props table needs the token producer so its cells
+ * can render `backticked` code as a chip instead of printing the backticks.
+ * It was module-private, which is why the table had no way to do it and the
+ * gap read as "the table is bad" rather than "the parser was unreachable". */
+export const processInlineMarkdown = (text) => {
   if (!text) return []
 
   const tokens = []

package/src/shell/RailRow.jsx

@@ -0,0 +1,85 @@
+import { NavLink } from 'react-router-dom'
+
+/**
+ * RailRow — THE L3 rail row. The ladder's bottom rung, owned like the other two.
+ *
+ * WHY IT EXISTS (user ruling 2026-08-01). `.shell-nav-item` was a shared class
+ * name and nothing more: every call site hand-wrote its own utility stack
+ * around it, so ONE row idiom shipped as NINE different strings across five
+ * files —
+ *
+ *   left tree      `shell-nav-item kol-mono-14 ${active ? … }`
+ *   toc rows       `shell-nav-item block kol-mono-14 text-body transition-colors
+ *                   focus-visible:ring-focus hover:text-emphasis`
+ *   related rows   the same minus the focus ring
+ *   quick actions  `shell-nav-item flex items-center gap-2 …`
+ *
+ * — and their containers disagreed too (`space-y-0` against `space-y-4` for the
+ * same list). R1/R2 lock the TYPE class; nothing locked the stack. That is the
+ * eyebrow-box failure exactly, one rung further down, which is why the rails
+ * kept drifting after RailSection fixed L1 and L2.
+ *
+ * The look now lives in `.shell-nav-item` (layout, colour, hover, focus,
+ * active); this component owns the markup. `validate:rails` R4 fails a
+ * hand-written `shell-nav-item` anywhere but here.
+ *
+ * ACTIVE IS BOTH RAILS' (user ruling 2026-08-01). The left tree highlighted the
+ * current page and the right rail highlighted nothing — same rung, one state.
+ * `NavLink` drives it for routes; `active` drives it for hash links and
+ * buttons, which react-router cannot resolve.
+ *
+ * @param {string}   [to]       route → NavLink, active resolved by the router
+ * @param {string}   [href]     plain anchor (hash links: on-this-page)
+ * @param {Function} [onClick]  no `to`/`href` → a <button>
+ * @param {boolean}  [active]   forced active state (hash links, buttons)
+ * @param {node}     [icon]     leading glyph
+ * @param {node}     [trailing] pushed right — a count, a doc number
+ * @param {boolean}  [sub]      nested depth (h3 under h2)
+ */
+export default function RailRow({
+  to,
+  href,
+  onClick,
+  active = false,
+  icon,
+  trailing,
+  sub = false,
+  onNavigate,
+  children,
+  className = '',
+}) {
+  /* ONE string. It is assembled here and nowhere else — that is the entire
+   * point of the component. `kol-mono-14` is the rail's row ramp (R1). */
+  const cls = (isActive) =>
+    ['shell-nav-item', 'kol-mono-14', sub ? 'shell-nav-item-sub' : '', isActive ? 'is-active' : '', className]
+      .filter(Boolean)
+      .join(' ')
+
+  const inner = (
+    <>
+      {icon}
+      <span className="truncate">{children}</span>
+      {trailing != null && <span className="shell-nav-item-trailing kol-mono-14">{trailing}</span>}
+    </>
+  )
+
+  if (to) {
+    return (
+      <NavLink to={to} end className={({ isActive }) => cls(isActive || active)} onClick={onNavigate}>
+        {inner}
+      </NavLink>
+    )
+  }
+  if (href) {
+    return (
+      <a href={href} className={cls(active)} onClick={onNavigate}>
+        {inner}
+      </a>
+    )
+  }
+  return (
+    <button type="button" className={cls(active)} onClick={onClick}>
+      {inner}
+    </button>
+  )
+}

package/src/shell/RailSection.jsx

@@ -0,0 +1,178 @@
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+
+/**
+ * RailSection — THE rail ladder. One component owns every rail header, at
+ * every rung, in both rails.
+ *
+ * WHY IT EXISTS (user ruling 2026-08-01). The rails already had a class per
+ * rung — `.shell-sidebar-toggle` (L1), `.shell-nav-group-header` (L2),
+ * `.shell-nav-item` (L3) — and drifted anyway, because a class is vocabulary
+ * and not grammar. Nothing declared the three a LADDER, and every affordance
+ * that hangs off a rung (the count, the collapse, the chevron) was hand-typed
+ * at each call site. So the right rail put its count on L1 and the left rail
+ * put its count on L2, and the user had to catch it in a screenshot.
+ *
+ * L3 is the proof of the fix: it is the only rung a component already owned
+ * (`DocsToc`), and it is the only rung that never drifted.
+ *
+ * THE LADDER
+ *
+ *   L1  section  `.shell-sidebar-toggle` + kol-doc-eyebrow    quiet, no chevron
+ *   L2  group    `.shell-nav-group-header` + kol-mono-14      louder, chevron
+ *   L3  row      `.shell-nav-item` + kol-mono-14              leaf, DocsToc/links
+ *
+ * THE RULES THIS COMPONENT ENFORCES BY CONSTRUCTION
+ *
+ *   - A rung's class is chosen here, never at the call site. Same rung in
+ *     either rail is literally the same string.
+ *   - The COUNT is placed by the rung, not by the caller. You cannot put it in
+ *     the wrong place because you never write the span.
+ *   - No chevron at L1 (user ruling 2026-08-01) — the section still collapses
+ *     and expands on click, the glyph is simply not drawn. L2 keeps its
+ *     chevron: it is the rung where a caret means "there is a subtree here".
+ *   - The box (padding + margin) belongs to the rung class alone. Nothing here
+ *     sets y-spacing inline; see the eyebrow-box law in kol-components-workshop.css.
+ *
+ * `pnpm validate:rails` R4 asserts that rail headers come from here.
+ *
+ * @param {1|2}      level        which rung. L3 rows are links, not sections.
+ * @param {string}   label        header text, rendered verbatim (casing is authored)
+ * @param {number}   [count]      leaf rows this section contains — L1 counts the
+ *                                whole subtree, L2 counts its own children
+ * @param {string}   [to]         make the LABEL a link; the rest of the row still toggles
+ * @param {boolean}  [collapsible=true]  false → a static header, no toggle, no aria
+ * @param {boolean}  [collapsed]  controlled state; omit for uncontrolled
+ * @param {Function} [onToggle]   required when `collapsed` is passed
+ * @param {boolean}  [defaultCollapsed=false]  uncontrolled initial state
+ * @param {Function} [onNavigate] click hook on the label link (close a drawer, etc.)
+ * @param {Icon}     [icon]       the chevron renderer, injected — the shell package
+ *                                must not reach into kol-component from here
+ */
+export default function RailSection({
+  level = 1,
+  label,
+  count,
+  to,
+  collapsible = true,
+  collapsed,
+  onToggle,
+  defaultCollapsed = false,
+  onNavigate,
+  icon: IconComponent,
+  children,
+}) {
+  const [internal, setInternal] = useState(defaultCollapsed)
+  const isControlled = collapsed !== undefined
+  const isCollapsed = isControlled ? collapsed : internal
+  const toggle = isControlled ? onToggle : () => setInternal((c) => !c)
+
+  /* The rung decides the class. This is the single line that used to live at
+   * four call sites in two rails, spelled differently at each. */
+  const headerClass = level === 1
+    ? 'shell-sidebar-toggle kol-doc-eyebrow'
+    : 'shell-nav-group-header kol-mono-14 text-body'
+
+  /* A static header is not a button and must not claim to be one. It still
+   * wears the same box — `.shell-sidebar-label` shares L1's rule. */
+  const staticClass = level === 1
+    ? 'shell-sidebar-label kol-doc-eyebrow'
+    : 'shell-nav-group-header kol-mono-14 text-body'
+
+  /* L2 only. At L1 the caret is not drawn (user ruling) — the row is still the
+   * toggle, so the affordance exists, it just isn't a glyph. */
+  const chevron = level === 2 && collapsible && IconComponent ? (
+    <IconComponent
+      name="chevron-right"
+      size={12}
+      className={`transition-transform ${isCollapsed ? '' : 'rotate-90'}`}
+    />
+  ) : null
+
+  /* THE COUNT IS AN L2 AFFORDANCE (user ruling 2026-08-01): "dont list counter
+   * next to eyebrow category, just inside". A category eyebrow names a body of
+   * material; the tally belongs to the groups inside it, not to the label over
+   * them. So L1 drops a `count` on the floor rather than rendering it — the
+   * rung refuses it, so no call site can put one back. */
+  const countNode = level === 2 && count !== undefined && count !== null
+    ? <span className="kol-mono-14 text-subtle">({count})</span>
+    : null
+
+  const labelNode = to ? (
+    /* The label navigates; the rest of the row toggles. stopPropagation keeps
+     * one click from doing both. */
+    <Link
+      to={to}
+      className={level === 1 ? 'kol-doc-eyebrow' : undefined}
+      onClick={(e) => {
+        e.stopPropagation()
+        if (isCollapsed && toggle) toggle()
+        if (onNavigate) onNavigate(e)
+      }}
+    >
+      {label}
+    </Link>
+  ) : (
+    <span>{label}</span>
+  )
+
+  const inner = (
+    <>
+      <span className="flex items-center gap-2">
+        {chevron}
+        {/* L2 rows without a caret keep the caret's width as space, so an
+          * expandable row and a childless one share a left edge. */}
+        {level === 2 && !chevron && <span aria-hidden="true" style={{ width: 12 }} />}
+        {labelNode}
+      </span>
+      {countNode}
+    </>
+  )
+
+  if (!collapsible) {
+    /* A rung with nothing to expand is not a section — it is a row that goes
+     * somewhere. It used to render as a header anyway: a chevron rotating over
+     * an empty body that never navigated, so "Icons" and "Components" did
+     * nothing when clicked. With `to` the WHOLE row is the link (the label
+     * alone would leave the rest of the row dead), and `inner` keeps the caret
+     * column as space so it shares a left edge with its expandable siblings. */
+    if (to) {
+      return (
+        <Link to={to} className={staticClass} onClick={onNavigate}>
+          <span className="flex items-center gap-2">
+            {level === 2 && <span aria-hidden="true" style={{ width: 12 }} />}
+            {label}
+          </span>
+          {countNode}
+        </Link>
+      )
+    }
+    return (
+      <div>
+        <div className={staticClass}>{inner}</div>
+        {children}
+      </div>
+    )
+  }
+
+  /* A div with role=button, not a <button>, because the label may be a Link —
+   * an anchor inside a button is invalid markup. The keyboard handler restores
+   * what the removed chevron button used to provide. */
+  return (
+    <div>
+      <div
+        className={headerClass}
+        role="button"
+        tabIndex={0}
+        aria-expanded={!isCollapsed}
+        onClick={toggle}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); if (toggle) toggle() }
+        }}
+      >
+        {inner}
+      </div>
+      {!isCollapsed && children}
+    </div>
+  )
+}

package/src/shell/ShellLayout.jsx

@@ -1,9 +1,11 @@
 import { createContext, useState, useEffect, Suspense } from 'react'
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
-import { ShellHeader } from '@kolkrabbi/kol-framework'
+import { ShellHeader, HEADER_ICON } from '@kolkrabbi/kol-framework'
 import ShellSidebar from './ShellSidebar.jsx'
 import { Button, ShellDrawer, ShellSearchOverlay, Tooltip } from '@kolkrabbi/kol-component'
 import { matchSearchItems } from '../engine/search.js'
+import { useTagMode } from '../tags/TagModeContext.jsx'
+import TagModeOverlay from '../tags/TagModeOverlay.jsx'
 import { Asset } from '@kolkrabbi/kol-brand/svg'
 
 // Pages can register right-rail TOC content via this context.
@@ -37,9 +39,33 @@ const MainColumn = ({ children, fullHeight }) => (
     className={`w-full min-w-0 h-full min-h-0 ${fullHeight ? 'overflow-hidden flex flex-col' : 'overflow-y-auto overscroll-none'}`}
     style={fullHeight ? undefined : { scrollbarGutter: 'stable' }}
   >
+    {/* THE cap lives HERE (2026-07-31), on the CONTENT — not on the grid that
+      * holds the rails. The theme's law is written about a page ("content
+      * LEFT-ANCHORED inside"), and the rails are chrome, not page. Capping the
+      * grid centred all three columns and pulled both rails inward off the
+      * viewport edge; the rails now sit flush at the chrome inset and only the
+      * main column carries a cap.
+      *
+      * It caps at CANVAS, not shell (user ruling 2026-07-31). Shell is the
+      * frame token and the middle grid track can never reach it — after both
+      * rails, gutters and inset there is ~1516 of room at a 2200 window — so a
+      * shell cap here was real code that could never fire, and every page just
+      * inherited whatever the window gave it. Canvas is the rung that binds.
+      * One decision, made once: 14 pages needed no per-page cap.
+      * `fullHeight` stays uncapped on purpose — it IS the fill-the-viewport
+      * escape hatch (iframe embeds).
+      *
+      * LEFT-ANCHORED, not centred (user ruling 2026-08-01). The capped div
+      * below carried `mx-auto`, which centres the column inside the main
+      * track — so above the canvas width the content drifted away from the
+      * rail it is supposed to line up with. The one-frame law has said
+      * "content LEFT-ANCHORED inside" since 2026-07-28 (kol-theme.css content
+      * block; docs/documentation/01-foundations/05-layout-systems.md): the
+      * FRAME centres in the viewport, the CONTENT does not centre in the
+      * frame. `validate:width` W4 asserts it now. */}
     {fullHeight
       ? children
-      : <div className="pt-6 md:pt-6 lg:pt-8 pb-16">{children}</div>
+      : <div className="w-full max-w-[var(--kol-content-canvas)] pt-6 md:pt-6 lg:pt-8 pb-16">{children}</div>
     }
   </main>
 )
@@ -52,7 +78,13 @@ const MainColumn = ({ children, fullHeight }) => (
  * decision and must not be stated twice differently. */
 const TocColumn = ({ children }) => (
   <aside aria-label="Table of contents" className="shell-sidebar-sticky hidden xl:block shrink-0 h-full min-h-0 overflow-y-auto overflow-x-hidden overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
-    {children}
+    {/* The WIDTH IS THE GRID TRACK now (--kol-shell-toc-w, see gridCols), not
+      * an inner wrapper. It used to be `w-56 empty:hidden` here precisely so a
+      * rail whose content rendered null would measure zero and let the main
+      * column reclaim the space — REVERSED by user ruling 2026-08-01: an empty
+      * rail still holds its column, because a rail that disappears re-flows
+      * main and the same page ends up at two different widths. */}
+    <div className="w-full">{children}</div>
   </aside>
 )
 
@@ -60,21 +92,51 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const [isNavDrawerOpen, setIsNavDrawerOpen] = useState(false)
   const [navCollapsed, setNavCollapsed] = useState(false)
   const [tocCollapsed, setTocCollapsed] = useState(false)
-  const [isSearchOpen, setIsSearchOpen] = useState(false)
-  const [searchQuery, setSearchQuery] = useState('')
+  /* ONE QUERY (user ruling 2026-08-01). The palette's text used to live here
+   * while tags lived in TagModeContext — two states, and therefore two
+   * surfaces. Both facets are the context's now. The local pair survives ONLY
+   * for a consumer mounting the shell without a TagModeProvider, where the
+   * context is the inert fallback and every keystroke would no-op. */
+  const tagMode = useTagMode()
+  const [localOpen, setLocalOpen] = useState(false)
+  const [localQuery, setLocalQuery] = useState('')
+
+  const isSearchOpen = tagMode.isProvided ? tagMode.isOpen : localOpen
+  const searchQuery = tagMode.isProvided ? tagMode.text : localQuery
+  const setSearchQuery = tagMode.isProvided ? tagMode.setText : setLocalQuery
+  const setIsSearchOpen = tagMode.isProvided
+    ? (v) => (v ? tagMode.openTagMode() : tagMode.closeTagMode())
+    : setLocalOpen
   const [tocContent, setTocContent] = useState(null)
   const [isFullHeight, setIsFullHeight] = useState(false)
+  const [isShortcutsOpen, setIsShortcutsOpen] = useState(false)
   const location = useLocation()
   const navigate = useNavigate()
 
+  /* THE shortcut map. One list, rendered by the `?` overlay AND bound by the
+   * handler below — a shortcut that isn't in this array doesn't exist, so the
+   * help sheet can never drift from the bindings. Before this there was no
+   * help UI at all: ⌘K was an unlabelled icon button and Alt+B was a duplicate
+   * nobody had written down anywhere. */
+  const SHORTCUTS = [
+    { keys: ['⌘', 'K'], label: 'Search everything', match: (e) => (e.metaKey || e.ctrlKey) && e.key === 'k' },
+    { keys: ['?'], label: 'This list', match: (e) => e.key === '?' },
+    { keys: ['Esc'], label: 'Close what is open', match: () => false, note: 'handled per surface' },
+  ]
+
   useEffect(() => {
     const handleKeyDown = (e) => {
+      /* never steal a key from a field the user is typing in */
+      const t = e.target
+      if (t?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t?.tagName ?? '')) return
       if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
         e.preventDefault()
         setIsSearchOpen(true)
-      } else if ((e.altKey) && e.key === 'b') {
+      } else if (e.key === '?') {
         e.preventDefault()
-        setIsSearchOpen(true)
+        setIsShortcutsOpen((v) => !v)
+      } else if (e.key === 'Escape') {
+        setIsShortcutsOpen(false)
       }
     }
     window.addEventListener('keydown', handleKeyDown)
@@ -82,26 +144,38 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   }, [])
 
   const effectiveTocContent = tocContent ?? defaultTocContent
-  /* KNOWN, deliberately not fixed here: an element is always truthy, so
-   * `<AutoToc/>` reserves a rail even on pages where it renders null. The
-   * obvious fix — measure the mounted column — deadlocks: once the column
-   * unmounts the probe is gone and can never report content again. The real
-   * fix is a consumer-side signal (a render-prop returning null, or an
-   * explicit `hasToc` prop), which is an API change. Filed, not improvised.
-   * The bug this caused — a half-height main column at 1024–1279px — was the
-   * `lg` vs `xl` mismatch on TocColumn above, and that IS fixed. */
+  /* THE RAIL HOLDS ITS COLUMN, EMPTY OR NOT (user ruling 2026-08-01).
+   *
+   * This used to hunt for a way to tell whether the rail had real content, so
+   * an empty one could collapse and hand its space back to main. That whole
+   * question is now moot — and it was the wrong question. A rail that vanishes
+   * on content-less routes means / renders at one main width and /foundations
+   * at another: the layout becomes a property of the page's content instead of
+   * the shell. The user caught it on the home page, where the TOC has no
+   * headings to show.
+   *
+   * So the track is RESERVED whenever the viewport is wide enough and the user
+   * has not collapsed it by hand. `hasToc` survives for ONE job — whether the
+   * header offers a toggle at all — because a control that collapses an
+   * already-empty rail is noise. Collapsing is still a user action, and a user
+   * action is allowed to change the layout; content appearing is not. */
   const hasToc = Boolean(effectiveTocContent)
   const showNav = !navCollapsed
-  const showToc = hasToc && !tocCollapsed
+  const showToc = !tocCollapsed
 
   const layoutType = showNav && showToc ? 'nav-toc' : showNav ? 'nav' : showToc ? 'toc' : 'none'
 
+  /* A FIXED track (--kol-shell-toc-w), not `auto`. `auto` sized the column to
+   * its content, which is exactly what let an empty rail measure zero. Both
+   * rail widths are tokens: the left is --kol-sidenav-w (the one number every
+   * grid track that lines up with it already reads), the right is
+   * --kol-shell-toc-w. */
   const gridCols = showNav
     ? showToc
-      ? 'lg:grid-cols-[256px_minmax(0,1fr)] xl:grid-cols-[256px_minmax(0,1fr)_224px]'
-      : 'lg:grid-cols-[256px_minmax(0,1fr)]'
+      ? 'lg:grid-cols-[var(--kol-sidenav-w)_minmax(0,1fr)] xl:grid-cols-[var(--kol-sidenav-w)_minmax(0,1fr)_var(--kol-shell-toc-w)]'
+      : 'lg:grid-cols-[var(--kol-sidenav-w)_minmax(0,1fr)]'
     : showToc
-      ? 'xl:grid-cols-[minmax(0,1fr)_224px]'
+      ? 'xl:grid-cols-[minmax(0,1fr)_var(--kol-shell-toc-w)]'
       : ''
 
   // Adapt the old flat `routes` + callbacks to the DS ShellHeader API
@@ -148,7 +222,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
     <>
       {actions}
       <Tooltip label="Search">
-        <Button variant="ghost" quiet iconOnly="search" iconSize={18} onClick={() => setIsSearchOpen(true)} aria-label="Search" />
+        <Button variant="ghost" quiet iconOnly="search" iconSize={HEADER_ICON} onClick={() => setIsSearchOpen(true)} aria-label="Search" />
       </Tooltip>
     </>
   )
@@ -162,6 +236,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
     group: item.sectionLabel ?? item.group,
     hint: item.matchedHeading ?? item.matchedKeyword ?? item.hint,
     href: item.href,
+    /* `action` must survive this reshape. It didn't: the map rebuilt every row
+     * as a fixed five-field object, so a consumer's action closure was dropped
+     * between the engine and onSelect and the row silently did nothing. The
+     * engine spreads `...item` and the overlay passes rows through untouched —
+     * this projection was the only lossy step in the chain. */
+    action: item.action,
   }))
 
   return (
@@ -203,10 +283,19 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
               * Tailwind's 16/20/24 steps instead of the ramp's 20/32/48 — so
               * every consumer page inherited the raw viewport (measured 2152px
               * of frame at a 2200px window against an 1800px law). Every
-              * page-level width fix is downstream of this line. */}
+              * page-level width fix is downstream of this line.
+              *
+              * CORRECTED 2026-07-31: that fix capped THIS element, which holds
+              * all three columns — so the whole chrome centred and both rails
+              * were dragged inward off the viewport edge. The chrome frame
+              * takes the full available width and the rails justify to it; the
+              * cap moved one level down onto MainColumn's content, which is
+              * what the theme's law is written about. Same disease as
+              * --kol-container-max stopping at 1600 under an 1800 law: one
+              * element, two answers. */}
             <div
-              className="mx-auto h-full w-full max-w-[var(--kol-content-shell)]"
-              style={{ paddingInline: 'var(--kol-pad-section-x)' }}
+              className="h-full w-full"
+              style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}
             >
               {/* gap lives in .shell-content-grid (theme) — a gap-8 utility here
                 * outranks the layered theme rule at every width and killed the
@@ -227,6 +316,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
                     </div>
                   </MainColumn>
 
+                  {/* Mounted on showToc alone — NOT on whether there is content
+                    * to put in it. An empty TocColumn is the point: it holds
+                    * the grid's third track so main keeps one width across
+                    * every route (user ruling 2026-08-01). */}
                   {showToc && (
                     <TocColumn>
                       {effectiveTocContent}
@@ -258,13 +351,76 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             query={searchQuery}
             onQueryChange={setSearchQuery}
             results={searchResults}
+            /* THE EXPANDED BODY (user ruling 2026-08-01). The tag browser is
+             * not a sibling overlay — it is this palette's second state. Enter
+             * commits the query and swaps the result rows for the full body;
+             * committed tags ride along as chips on the same query. */
+            expanded={tagMode.isProvided && tagMode.expanded}
+            onExpand={() => tagMode.setExpanded?.(true)}
+            chips={tagMode.isProvided ? tagMode.activeTags : []}
+            onRemoveChip={tagMode.removeTag}
+            placeholder="Search…"
             onSelect={(item) => {
+              /* `action` before `href`: not every hit is a destination. A tag
+               * row FILTERS the same query and the palette STAYS OPEN — closing
+               * it was the behaviour that forced tags into a second overlay.
+               * Only a destination dismisses. */
+              if (typeof item?.action === 'function') {
+                item.action()
+                setSearchQuery('')
+                return
+              }
               setIsSearchOpen(false)
               setSearchQuery('')
               if (item?.href) navigate(item.href)
             }}
-            placeholder="Search…"
-          />
+          >
+            {tagMode.isProvided && tagMode.expanded ? <TagModeOverlay /> : null}
+          </ShellSearchOverlay>
+
+          {/* The `?` sheet. Rendered FROM the SHORTCUTS array above, so the help
+            * and the bindings are one source — a shortcut can't be documented
+            * and unbound, or bound and undocumented, which is how Alt+B lived
+            * for months. */}
+          {isShortcutsOpen && (
+            <div
+              className="fixed inset-0 z-50 flex items-center justify-center bg-fg-48"
+              onClick={() => setIsShortcutsOpen(false)}
+              role="presentation"
+            >
+              <div
+                className="kol-doc-figure w-[min(28rem,90vw)] bg-surface-primary"
+                onClick={(e) => e.stopPropagation()}
+                role="dialog"
+                aria-modal="true"
+                aria-label="Keyboard shortcuts"
+              >
+                <div
+                  className="flex items-center justify-between border-b px-4 py-3"
+                  style={{ borderBottomColor: 'var(--kol-oq-08)' }}
+                >
+                  <span className="kol-doc-eyebrow text-meta">Keyboard shortcuts</span>
+                  <Button variant="outline" quiet size="sm" iconOnly="x"
+                    aria-label="Close" onClick={() => setIsShortcutsOpen(false)} />
+                </div>
+                <ul className="flex flex-col px-4 py-3">
+                  {SHORTCUTS.map((s) => (
+                    <li key={s.label} className="flex items-center justify-between gap-6 py-1.5">
+                      <span className="kol-mono-14 text-body">
+                        {s.label}
+                        {s.note && <span className="kol-helper-12 text-subtle"> · {s.note}</span>}
+                      </span>
+                      <span className="flex items-center gap-1">
+                        {s.keys.map((k) => (
+                          <kbd key={k} className="kol-helper-12 rounded-[var(--kol-radius-sm)] bg-fg-08 px-1.5 py-0.5 text-emphasis">{k}</kbd>
+                        ))}
+                      </span>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            </div>
+          )}
         </div>
         </ShellTocCollapsedContext.Provider>
       </ShellFullHeightContext.Provider>