@kolkrabbi/kol-workshop 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "private": false,
   "description": "Docs viewer, shell and tag system",
   "license": "MIT",
@@ -14,13 +14,13 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-search": "^0.2.0",
-    "@kolkrabbi/kol-brand": "^0.1.3"
+    "@kolkrabbi/kol-brand": "^0.1.3",
+    "@kolkrabbi/kol-search": "^0.3.0"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.235.0",
+    "@kolkrabbi/kol-component": ">=0.237.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
-    "@kolkrabbi/kol-theme": ">=0.162.0",
+    "@kolkrabbi/kol-theme": ">=0.163.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
     "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
@@ -28,10 +28,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.235.0",
-    "@kolkrabbi/kol-theme": "^0.162.0",
     "@kolkrabbi/kol-framework": "^0.48.0",
-    "@kolkrabbi/kol-icons": "^0.32.0"
+    "@kolkrabbi/kol-theme": "^0.163.0",
+    "@kolkrabbi/kol-component": "^0.237.0",
+    "@kolkrabbi/kol-icons": "^0.33.0"
   },
   "files": [
     "src",

package/src/docs/DocKit.jsx

@@ -27,7 +27,11 @@ export function DocHeader({ eyebrow, title, lede, children }) {
 
 export function DocSection({ id, title, lede, children }) {
   return (
-    <section id={id} className="flex flex-col gap-4 border-t border-fg-08 pt-8 scroll-mt-20">
+    /* THE SECTION KEEPS ITS OWN DISTANCE (2026-10-01 — user, on the tokens page: the rule sat flush
+     * under the last swatch's caption). It drew a rule with nothing above it and left the gap to the
+     * page; ten pages stack sections in a fragment and supplied none. A page that already spaces its
+     * children with a flex gap keeps that gap — the margin only lands where the parent is not one. */
+    <section id={id} className="flex flex-col gap-4 border-t border-fg-08 pt-8 scroll-mt-20 [:not(.flex)>*+&]:mt-10">
       {title && <h2 className="kol-doc-section-title">{title}</h2>}
       {lede && <p className="kol-doc-body max-w-[var(--kol-content-measure)]">{lede}</p>}
       {children}

package/src/exhibit/ExhibitOverview.jsx

@@ -16,7 +16,7 @@ import useExhibitToc from './useExhibitToc.js'
  *   label="Scope: Dashboard — Overview"
  *   title="Dashboard"
  *   body="Modular dashboards, charts and KPI components…"
- *   action={<Button variant="primary" href="https://kolkrabbi.io/metrics">Open metrics</Button>}
+ *   action={<Button tone="primary" href="https://kolkrabbi.io/metrics">Open metrics</Button>}
  *   cards={[{ id: 'setup', label: 'Setup', subtitle: '…', icon: 'book-open', href: '/workshop/dashboard/setup' }]}
  * />
  * ```

package/src/search/ResultRow.jsx

@@ -13,6 +13,7 @@ import { Link } from 'react-router-dom'
  * @param {string}    to           the route the row opens
  * @param {ReactNode} title        the result's name (a highlighted node is fine)
  * @param {string}    [meta]       kind · category · space · date
+ * @param {ReactNode} [icon]       a glyph for the kind, before the title (Round 6, 2026-10-01)
  * @param {ReactNode} [description]
  * @param {'underline'|'wash'} [variant='underline']
  */
@@ -23,11 +24,11 @@ const VARIANTS = {
   wash: { row: 'flex flex-col gap-1 px-3 py-3 hover:bg-fg-04', title: '' },
 }
 
-export default function ResultRow({ to, title, meta, description, variant = 'underline' }) {
+export default function ResultRow({ to, title, meta, description, icon, variant = 'underline' }) {
   const v = VARIANTS[variant] ?? VARIANTS.underline
   return (
     <Link to={to} className={v.row}>
-      <span className={`kol-doc-body text-emphasis ${v.title}`.trim()}>{title}</span>
+      <span className={`kol-doc-body text-emphasis ${icon ? 'inline-flex items-center gap-2' : ''} ${v.title}`.replace(/\s+/g, ' ').trim()}>{icon}{title}</span>
       {meta && <span className="kol-helper-12 text-meta">{meta}</span>}
       {description && <span className="kol-doc-body text-body">{description}</span>}
     </Link>

package/src/search/SearchPage.jsx

@@ -3,17 +3,18 @@ import { getTagColor } from '@kolkrabbi/kol-markdown'
 import { useNavigate, useSearchParams } from 'react-router-dom'
 import { EmptyState, Input, Tag } from '@kolkrabbi/kol-component'
 import ResultRow from './ResultRow.jsx'
+import { Icon } from '@kolkrabbi/kol-icons'
 import { createIndex, search, parseQuery } from '@kolkrabbi/kol-search'
 
 /**
- * SearchPage — The search results page. THE results page (2026-09-28). Enter in the shell's palette
+ * SearchPage — The search results page. THE results page (2026-09-28). Enter in the shell's search modal
  * lands here with `?q=`; so does a tag clicked anywhere (`#tag`). The WHOLE
  * state is the query string in the URL — scope and facet picks are written back
  * into it as `in:` · `kind:` · `cat:` · `tag:` tokens — so Back returns to the
  * same results, a result link is an ordinary navigation, and a search can be
  * shared as a link.
  *
- * It replaced two surfaces that each did half the job: the palette's in-place
+ * It replaced two surfaces that each did half the job: the search modal's in-place
  * tag browser and a page whose groups were whatever `sectionLabel` each
  * source happened to emit.
  *
@@ -47,7 +48,7 @@ const readToken = (t) => (t.kind === 'term'
     ? `${t.field} ${t.value}`
     : `${t.negate ? 'not ' : ''}${t.field === 'tags' ? 'tag' : t.field}: ${t.value}${t.via === 'smart' ? ' (from the word)' : ''}`)
 
-export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60, rowVariant = 'underline', resultsPath }) {
+export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60, rowVariant = 'underline', rowMeta = 'facts', kindIcons, resultsPath }) {
   const [params, setParams] = useSearchParams()
   const navigate = useNavigate()
   const q = params.get('q') ?? ''
@@ -163,7 +164,9 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
                     to={r.item.href}
                     variant={rowVariant}
                     title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
-                    meta={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
+                    /* Round 6 (2026-10-01): `kindIcons` puts a glyph for the kind on the row, `rowMeta="path"` prints the route as the second line */
+                    icon={kindIcons?.[r.item.kind] && <Icon name={kindIcons[r.item.kind]} size={14} />}
+                    meta={rowMeta === 'path' ? r.item.href : [r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
                     description={r.item.description}
                   />
                 </li>

package/src/shell/RailRow.jsx

@@ -1,4 +1,4 @@
-import { NavLink } from 'react-router-dom'
+import { Link, NavLink } from 'react-router-dom'
 
 /**
  * RailRow — THE L3 rail row. The ladder's bottom rung, owned like the other two.
@@ -28,7 +28,9 @@ import { NavLink } from 'react-router-dom'
  * `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}   [to]       route → NavLink, active resolved by the router. A `to` carrying a `#` is a
+ *                              SECTION of a page (2026-10-01): the router would light every section of
+ *                              the open page at once, so it is a plain Link and `active` decides
  * @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)
@@ -63,6 +65,13 @@ export default function RailRow({
     </>
   )
 
+  if (to && to.includes('#')) {
+    return (
+      <Link to={to} className={cls(active)} onClick={onNavigate}>
+        {inner}
+      </Link>
+    )
+  }
   if (to) {
     return (
       <NavLink to={to} end className={({ isActive }) => cls(isActive || active)} onClick={onNavigate}>

package/src/shell/RailSection.jsx

@@ -72,6 +72,8 @@ export default function RailSection({
   defaultCollapsed = false,
   onNavigate,
   icon: IconComponent = Icon,
+  /* a leading glyph for the group, between the caret and the label (rail icons, 2026-10-01) */
+  glyph,
   children,
 }) {
   const [internal, setInternal] = useState(defaultCollapsed)
@@ -149,6 +151,7 @@ export default function RailSection({
         {/* 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 }} />}
+        {glyph}
         {labelNode}
       </span>
       <span className="flex items-center gap-2 shrink-0">

package/src/shell/ShellLayout.jsx

@@ -1,7 +1,7 @@
 import { createContext, useContext, useMemo, useRef, useState, useEffect, Suspense } from 'react'
 import { Outlet, Link, useLocation, useNavigate, useNavigationType } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
-import ShellSidebar, { RAIL_FOLD_EVENT } from './ShellSidebar.jsx'
+import ShellSidebar, { RAIL_FOLD_EVENT, ShellRailModeContext } from './ShellSidebar.jsx'
 import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
 import { createIndex, search } from '@kolkrabbi/kol-search'
 import { useTagMode } from '../tags/TagModeContext.jsx'
@@ -98,12 +98,42 @@ const useRailGrab = (token, side, hide) => {
   return { ref, grab: <div {...grabProps} className={`kol-rail-grab kol-rail-grab--${side} hidden lg:block`} /> }
 }
 
-const NavColumn = ({ children, grip, railRef }) => (
-  <aside ref={railRef} aria-label="Navigation" className="shell-rail shell-rail--nav shell-sidebar-sticky hidden lg:block pt-6 md:pt-6 lg:pt-8 pb-14">
-    {children}
-    {grip}
-  </aside>
-)
+/**
+ * ShellNavColumn — The left rail's column. the frame the shell's left rail sits in: sticky, one
+ * scroll region tall, a seam toward the page. It owns the rail's THREE STATES (user ruling
+ * 2026-10-02) — `open`, `icons` and hidden, which is simply not mounting it.
+ *
+ * In `icons` the column is a narrow strip (the track is the framework's collapsed-rail width,
+ * `--kol-sidenav-w-collapsed`) and every `ShellSidebar` inside draws one glyph per group. Hover
+ * opens the whole rail OVER the page at its full width — the track does not move, so the page
+ * never reflows — and leaving folds it back. A touch has no hover: there the glyphs are the nav.
+ *
+ * @param {'open'|'icons'} mode
+ * @param {ReactNode|Function} children  the rail; a function gets the state it is drawn in
+ *                                       (`open` while an icon rail is hovered), so a consumer can
+ *                                       drop what does not fit a strip
+ * @param {ReactNode} grip     the resize handle — not drawn on an icon rail
+ * @param {Object}    railRef
+ */
+export function ShellNavColumn({ mode = 'open', children, grip, railRef }) {
+  const [peek, setPeek] = useState(false)
+  const icons = mode === 'icons'
+  const shown = icons && !peek ? 'icons' : 'open'
+  return (
+    <aside
+      ref={railRef}
+      aria-label="Navigation"
+      className={`shell-rail shell-rail--nav shell-sidebar-sticky hidden lg:block pt-6 md:pt-6 lg:pt-8 pb-14 ${icons ? `shell-rail--icons ${peek ? 'is-peek' : ''}` : ''}`.trim()}
+      onMouseEnter={icons ? () => setPeek(true) : undefined}
+      onMouseLeave={icons ? () => setPeek(false) : undefined}
+    >
+      <ShellRailModeContext.Provider value={shown}>
+        {typeof children === 'function' ? children(shown) : children}
+      </ShellRailModeContext.Provider>
+      {!icons && grip}
+    </aside>
+  )
+}
 
 const MainColumn = ({ children, fullHeight, width = 'canvas', padStart, padEnd }) => {
   /* the map lives INSIDE MainColumn on purpose — validate:width W1 reads the
@@ -159,7 +189,7 @@ const writeSettings = (next) => {
 }
 
 /* A search item in either shape — the kol-search item (`title · kind · space ·
- * category · tags · headings · keywords · description · href`) or the palette's
+ * category · tags · headings · keywords · description · href`) or the search modal's
  * older row (`label · sectionLabel · …`). Both keep working. */
 const toSearchItem = (item, i) => ({
   ...item,
@@ -179,18 +209,24 @@ const toSearchItem = (item, i) => ({
  *                               so it names the space you are in
  * @param {Array}  [shortcuts]   the consumer's own keys, `{ id, label, combo, key, run }` — listed
  *                               in the `S` sheet and bound by the same handler (2026-09-30)
+ * @param {Function} [renderSidebar]  `({ activeRoute, onNavigate, mode }) => node` — the space's
+ *                               rail. `mode` is `open` or `icons` (the left rail's third state,
+ *                               2026-10-02): every `ShellSidebar` reads it by itself, so `mode`
+ *                               is only for what else the consumer puts in the rail
  */
 const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoSrc, brandLogoAlt = '', renderSidebar, searchItems, searchPath, settings = [], brandLabel, defaultTocContent, isActive: isActiveProp, actions, shortcuts = [] }) => {
   const [isNavDrawerOpen, setIsNavDrawerOpen] = useState(false)
   const [prefs, setPrefs] = useState(readSettings)
   const setPref = (key, value) => setPrefs((p) => { const next = { ...p, [key]: value }; writeSettings(next); return next })
   const [navCollapsed, setNavCollapsed] = useState(() => readSettings().navHidden === true)
+  /* the left rail's third state — a strip of icons that opens on hover (see ShellNavColumn) */
+  const navIcons = prefs.navIcons === true
 
   const [tocCollapsed, setTocCollapsed] = useState(() => readSettings().tocHidden === true)
   const navGrab = useRailGrab('kol-shell-nav', 'left', () => { setNavCollapsed(true); writeSettings({ ...readSettings(), navHidden: true }) })
   const tocGrab = useRailGrab('kol-shell-toc', 'right', () => { setTocCollapsed(true); writeSettings({ ...readSettings(), tocHidden: true }) })
   const [isSettingsOpen, setIsSettingsOpen] = useState(false)
-  /* ONE QUERY (user ruling 2026-08-01). The palette's text used to live here
+  /* ONE QUERY (user ruling 2026-08-01). The search modal'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
@@ -281,7 +317,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       { id: 'nav', label: 'Left rail', combo: '[' },
       { id: 'toc', label: 'Right rail', combo: ']' },
       { id: 'rails', label: 'Both rails', combo: '\\' },
-      { id: 'fold', label: 'Fold all', combo: 'C' },
+      { id: 'fold', label: 'Fold / expand all', combo: 'C' },
       { id: 'esc', label: 'Close', combo: 'Esc' },
     ] },
     ...(shortcuts.length ? [{ section: 'Page', items: shortcuts.map(({ id, label, combo }) => ({ id, label, combo })) }] : []),
@@ -374,7 +410,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
    * rails are the workshop shell's own pair (--kol-shell-nav-w ·
    * --kol-shell-toc-w, 256px each since 2026-09-28): the left used to read
    * --kol-sidenav-w, the draggable app sidenav's 264/320 ladder. */
-  const gridCols = showNav
+  /* an icon rail's track is the framework's collapsed-rail width — the same strip, one token */
+  const gridCols = showNav && navIcons
+    ? showToc
+      ? 'lg:grid-cols-[var(--kol-sidenav-w-collapsed)_minmax(0,1fr)] xl:grid-cols-[var(--kol-sidenav-w-collapsed)_minmax(0,1fr)_var(--kol-shell-toc-w)]'
+      : 'lg:grid-cols-[var(--kol-sidenav-w-collapsed)_minmax(0,1fr)]'
+    : showNav
     ? showToc
       ? 'lg:grid-cols-[var(--kol-shell-nav-w)_minmax(0,1fr)] xl:grid-cols-[var(--kol-shell-nav-w)_minmax(0,1fr)_var(--kol-shell-toc-w)]'
       : 'lg:grid-cols-[var(--kol-shell-nav-w)_minmax(0,1fr)]'
@@ -440,7 +481,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
     </>
   )
 
-  /* THE ENGINE IS kol-search (2026-09-28) — the palette ran a first-substring
+  /* THE ENGINE IS kol-search (2026-09-28) — the search modal ran a first-substring
    * match, so `atom` ranked AppHub first on a word in its description and only
    * one row lit its match. Ranked now, every hit highlighted, and a word that
    * names a category (`atom`) filters by it. `limitToSpace` (settings) scopes
@@ -472,6 +513,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const settingsSections = [
     { label: 'Layout', rows: [
       { id: 'nav', label: 'Left rail', render: () => <SettingsSwitch on={!navCollapsed} onChange={(on) => { setNavCollapsed(!on); setPref('navHidden', !on) }} /> },
+      { id: 'nav-icons', label: 'Icons only', render: () => <SettingsSwitch on={navIcons} onChange={(on) => setPref('navIcons', on)} /> },
       { id: 'toc', label: 'Right rail', render: () => <SettingsSwitch on={!tocCollapsed} onChange={(on) => { setTocCollapsed(!on); setPref('tocHidden', !on) }} /> },
     ] },
     { label: 'Search', rows: [
@@ -526,9 +568,9 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
           >
               <div className={`shell-content-grid grid ${gridCols}`} data-layout={layoutType} style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}>
                   {showNav && (
-                    <NavColumn railRef={navGrab.ref} grip={navGrab.grab}>
-                      {renderSidebar ? renderSidebar({ activeRoute }) : <ShellSidebar routes={routes} basePath={basePath} />}
-                    </NavColumn>
+                    <ShellNavColumn mode={navIcons ? 'icons' : 'open'} railRef={navGrab.ref} grip={navGrab.grab}>
+                      {(mode) => (renderSidebar ? renderSidebar({ activeRoute, mode }) : <ShellSidebar routes={routes} basePath={basePath} />)}
+                    </ShellNavColumn>
                   )}
 
                   <MainColumn fullHeight={isFullHeight} width={contentWidth} padStart={showNav} padEnd={showToc}>
@@ -573,10 +615,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             query={searchQuery}
             onQueryChange={setSearchQuery}
             results={searchResults}
-            /* an empty palette opens on the space table, not a blank box */
+            /* an empty search modal opens on the space table, not a blank box */
             suggestions={navItems.map((n) => ({ id: `space:${n.href}`, label: n.label, href: n.href, icon: 'arrow-right', group: 'Spaces' }))}
             /* THE EXPANDED BODY (user ruling 2026-08-01). The tag browser is
-             * not a sibling overlay — it is this palette's second state. Enter
+             * not a sibling overlay — it is this search modal'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}
@@ -596,7 +638,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             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
+               * row FILTERS the same query and the search modal STAYS OPEN — closing
                * it was the behaviour that forced tags into a second overlay.
                * Only a destination dismisses. */
               if (typeof item?.action === 'function') {

package/src/shell/ShellSidebar.jsx

@@ -1,6 +1,6 @@
-import { useState, useEffect } from 'react'
-import { useLocation } from 'react-router-dom'
-import { Icon } from '@kolkrabbi/kol-component'
+import { createContext, useContext, useState, useEffect } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { Button, Icon, Tooltip } from '@kolkrabbi/kol-component'
 import RailSection from './RailSection.jsx'
 import RailRow from './RailRow.jsx'
 
@@ -26,8 +26,17 @@ const getChildPath = (child, basePath) => {
 
 export const RAIL_FOLD_EVENT = 'kol-rail-fold'
 
+/* THE RAIL'S THIRD STATE (user ruling 2026-10-02: *"I wanted that icon state on the rails. even if
+ * we dont use it, I want to see it"*). Beside visible and hidden: `icons` — the rail is a narrow
+ * strip, one glyph per group, and opens on hover. The column that holds the rail (`ShellNavColumn`)
+ * provides the state; every ShellSidebar inside it reads it, so a consumer's rail takes the state
+ * without passing a prop. Outside a provider a rail is `open`, as it always was. */
+export const ShellRailModeContext = createContext('open')
+
 const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Navigation', labelTo, collapsed, onToggle, defaultCollapsed = false }) => {
   const location = useLocation()
+  const navigate = useNavigate()
+  const mode = useContext(ShellRailModeContext)
   const normalizedPath = location.pathname.replace(/\/$/, '')
 
   // Controlled mode: collapsed + onToggle from parent
@@ -100,12 +109,18 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
 
   /* The L1 count is every leaf row under it — RailSection shows it only while
    * the section is folded (2026-09-28). At any depth: leaves, not groups. */
-  const leavesOf = (list) => list.reduce((n, r) => n + (r.children?.length ? leavesOf(r.children) : 1), 0)
+  /* A PAGE THAT LISTS ITS SECTIONS IS STILL ONE PAGE (2026-10-01): `section: true` children are
+   * `#` anchors on their parent's page, not leaves of the tree. */
+  const isPage = (r) => !r.children?.length || r.children.every((c) => c.section)
+  const leavesOf = (list) => list.reduce((n, r) => n + (isPage(r) ? 1 : leavesOf(r.children)), 0)
   const leafCount = leavesOf(routes)
 
   /* ONE GROUP, AT ANY DEPTH. A chapter's child with children of its own is a chapter again — the
    * same RailSection rung, the same count and chevron, stepped in one row-indent by `.shell-nav-nest`
    * so its caret sits on its siblings' text edge. A leaf is a RailRow wherever it lands. */
+  /* A ROUTE MAY CARRY A GLYPH (rail icons, open-questions Round 6, ruled 2026-10-01): `icon` is an
+   * icon name, drawn on the row or beside the group's label. The consumer decides which routes. */
+  const glyphOf = (route) => (route.icon ? <Icon name={route.icon} size={14} className="shrink-0" /> : undefined)
   const renderGroup = (route) => (
     <RailSection
       level={2}
@@ -118,61 +133,91 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
       onToggle={() => handleSectionClick(route)}
       onNavigate={onNavigate}
       icon={Icon}
+      glyph={glyphOf(route)}
     >
-      <nav className="shell-nav-items">
+      {/* a group that wears a glyph steps its children in by the glyph (14 + the 8 gap), so they
+        * still hang under its LABEL — without it they sat left of the word they belong to */}
+      <nav className={`shell-nav-items ${route.icon ? 'pl-[22px]' : ''}`.trim()}>
         {route.children.map((child) => (child.children?.length ? (
           <div key={child.id} className="shell-nav-nest">{renderGroup(child)}</div>
         ) : (
-          <RailRow key={child.id} to={getChildPath(child, basePath)} onNavigate={onNavigate}>
+          <RailRow key={child.id} to={getChildPath(child, basePath)} onNavigate={onNavigate}
+            icon={glyphOf(child)}
+            active={child.section ? `${location.pathname}${location.hash}` === child.path : undefined}>
             {child.label}
           </RailRow>
         )))}
       </nav>
     </RailSection>
   )
+  /* ICONS ONLY — one glyph per group (a group's own, else the folder; a page's, else the file), no
+   * eyebrow, no rows. The DS nav button on the control ladder's `md` rung, the same rung the header
+   * glyphs stand on; the group you are in holds the rail's active wash (`.shell-rail-icons`). */
+  if (mode === 'icons') {
+    const holds = (r) => isHere(r) || (r.children ?? []).some(holds)
+    return (
+      <nav className="shell-rail-icons" aria-label={label ?? undefined}>
+        {routes.map((route) => (
+          <Tooltip key={route.id} label={route.label} placement="right">
+            <Button variant="nav" size="md" iconOnly={route.icon ?? (route.children?.length ? 'folder' : 'file')}
+              aria-label={route.label} aria-current={holds(route) ? 'page' : undefined}
+              onClick={(e) => { navigate(getSectionRootPath(route, basePath)); onNavigate?.(e) }} />
+          </Tooltip>
+        ))}
+      </nav>
+    )
+  }
+
+  /* `label={null}` draws the tree with no L1 section over it (2026-10-01) — a space whose rail is
+   * its pages, not a category of them (Search: user ruling, the space does not list itself). */
+  const body = (
+    <div className="shell-rail-stack-inner">
+      {/* LOOSE ROWS SHARE ONE LIST (the showcase review W12, 2026-09-30 — user: "the spaces are
+        * incorrect in the left sidebar"). Each childless entry rendered its own <nav>, and the
+        * stack's 16px gap landed between every pair, so a rail of four rows (Search) read 46px
+        * apart instead of a list's 26. Consecutive rows are one run now; a chapter breaks it. */}
+      {routes.reduce((runs, route) => {
+        const last = runs[runs.length - 1]
+        if (!route.children?.length && last && !last.group) last.rows.push(route)
+        else runs.push(route.children?.length ? { group: route } : { rows: [route] })
+        return runs
+      }, []).map((run) => (run.group ? (
+        <div key={run.group.id} className="shell-nav-group">
+          {renderGroup(run.group)}
+        </div>
+      ) : (
+        /* A CHILDLESS ENTRY IS A ROW, not a chapter (2026-09-30): drawn at L2 it read as an
+         * empty category with a blank caret slot. */
+        <nav key={run.rows[0].id} className="shell-nav-items">
+          {run.rows.map((route) => (
+            <RailRow key={route.id} to={route.path ?? getSectionRootPath(route, basePath)} onNavigate={onNavigate} icon={glyphOf(route)}>
+              {route.label}
+            </RailRow>
+          ))}
+        </nav>
+      )))}
+    </div>
+  )
   return (
     /* One rail layout, one class (2026-08-01). This was `space-y-4` against the
      * right rail's `space-y-6` against the outer `flex flex-col gap-6` — three
      * spellings of the same stack, and `space-y` fights any child that owns a
      * margin, which the eyebrow box does. */
     <div className="shell-rail-stack-inner">
-      <RailSection
-        level={1}
-        label={label}
-        to={labelTo}
-        count={leafCount}
-        collapsed={navCollapsed}
-        onToggle={handleToggle}
-        onNavigate={onNavigate}
-        icon={Icon}
-      >
-        <div className="shell-rail-stack-inner">
-          {/* LOOSE ROWS SHARE ONE LIST (the showcase review W12, 2026-09-30 — user: "the spaces are
-            * incorrect in the left sidebar"). Each childless entry rendered its own <nav>, and the
-            * stack's 16px gap landed between every pair, so a rail of four rows (Search) read 46px
-            * apart instead of a list's 26. Consecutive rows are one run now; a chapter breaks it. */}
-          {routes.reduce((runs, route) => {
-            const last = runs[runs.length - 1]
-            if (!route.children?.length && last && !last.group) last.rows.push(route)
-            else runs.push(route.children?.length ? { group: route } : { rows: [route] })
-            return runs
-          }, []).map((run) => (run.group ? (
-            <div key={run.group.id} className="shell-nav-group">
-              {renderGroup(run.group)}
-            </div>
-          ) : (
-            /* A CHILDLESS ENTRY IS A ROW, not a chapter (2026-09-30): drawn at L2 it read as an
-             * empty category with a blank caret slot. */
-            <nav key={run.rows[0].id} className="shell-nav-items">
-              {run.rows.map((route) => (
-                <RailRow key={route.id} to={route.path ?? getSectionRootPath(route, basePath)} onNavigate={onNavigate}>
-                  {route.label}
-                </RailRow>
-              ))}
-            </nav>
-          )))}
-        </div>
-      </RailSection>
+      {label === null ? body : (
+        <RailSection
+          level={1}
+          label={label}
+          to={labelTo}
+          count={leafCount}
+          collapsed={navCollapsed}
+          onToggle={handleToggle}
+          onNavigate={onNavigate}
+          icon={Icon}
+        >
+          {body}
+        </RailSection>
+      )}
     </div>
   )
 }

package/src/shell/index.js

@@ -9,6 +9,9 @@
 export { default as ShellLayout } from './ShellLayout.jsx'
 export { ShellTocContext, ShellFullHeightContext, ShellTocCollapsedContext, ShellNavCollapsedContext, ShellContentWidthContext, SHELL_SCROLL_ROOT, usePageMeta, usePageMetaValue } from './ShellLayout.jsx'
 export { default as ShellSidebar } from './ShellSidebar.jsx'
+/* the left rail's column and its three states — open · icons · hidden (2026-10-02) */
+export { ShellNavColumn } from './ShellLayout.jsx'
+export { ShellRailModeContext } from './ShellSidebar.jsx'
 /* RailSection — THE rail ladder. Every rail header at every rung comes from
  * here, in both rails; see the file header for why a class alone was not
  * enough. `pnpm validate:rails` R4 asserts it. */

package/src/tags/TagGraph.jsx

@@ -3,7 +3,7 @@ import * as d3 from 'd3'
 import { gsap } from 'gsap'
 import { useNavigate } from 'react-router-dom'
 import { getTagColor } from '@kolkrabbi/kol-markdown'
-import { tagGraph } from '@kolkrabbi/kol-search'
+import { indexGraph } from '@kolkrabbi/kol-search'
 import { EASE, DURATION, s } from '@kolkrabbi/kol-component/utilities/motion'
 
 /**
@@ -30,11 +30,25 @@ import { EASE, DURATION, s } from '@kolkrabbi/kol-component/utilities/motion'
  *     curves are kol-component's motion constants; reduced motion skips the tweens.
  *   - LABELS WHERE THEY HELP. Every node printed its name; now the larger tags carry a label at rest
  *     and the rest show theirs when focused.
+ *
+ * FILES, ORPHANS AND SETTINGS (2026-10-01 — user ruling: files and orphans beside tags, with filter
+ * and display settings; no force controls). The data is kol-search's `indexGraph`:
+ *
+ *   `files`      a node per tagged doc, joined to its tags (the tags then join through their docs)
+ *   `orphans`    a node per doc with no tags
+ *   `filter`     text — keeps the nodes it matches
+ *   `labels`     'auto' (the eight biggest tags, the rest on focus) · 'all' · 'none'
+ *   `nodeScale` · `linkScale`   multipliers on the drawn radius and the edge width (default 1)
+ *
+ * A doc node is a small neutral dot, named by its title; clicking one calls `onFileClick(node)`,
+ * else opens its `href`.
  */
 const defaultTagHref = (tag) => `/workshop/design-system/documentation?tag=${encodeURIComponent(tag)}`
 
 const radiusOf = (d) => Math.max(5, Math.min(14, 4 + Math.sqrt(d.count) * 2.2))
 const fillOf = (d) => {
+  /* a doc is not a tag: one neutral ink, an orphan fainter still */
+  if (d.type === 'file') return d.orphan ? 'var(--kol-oq-24)' : 'var(--kol-oq-48)'
   /* palette tokens, not copies; `dark` is a surface role with no palette entry */
   const key = getTagColor(d.id)
   return key === 'dark' ? 'var(--kol-surface-on-primary)' : `var(--kol-palette-${key}, var(--kol-palette-teal))`
@@ -42,7 +56,7 @@ const fillOf = (d) => {
 const EDGE = 'color-mix(in srgb, var(--kol-surface-on-primary) 24%, transparent)'
 const ACCENT = 'var(--kol-accent-primary)'
 
-const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHref }) => {
+const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHref, files = false, orphans = false, filter = '', labels = 'auto', nodeScale = 1, linkScale = 1, onFileClick }) => {
   const svgRef = useRef(null)
   const containerRef = useRef(null)
   const sceneRef = useRef(null)
@@ -54,7 +68,10 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
 
   const sourceDocs = allDocs || docs
   /* the engine's graph (kol-search `tagGraph`, 2026-09-29) over the docs' tags */
-  const graphData = useMemo(() => tagGraph(sourceDocs.map((d) => ({ id: d.id, tags: d.metadata?.tags ?? [] }))), [sourceDocs])
+  const graphData = useMemo(() => indexGraph(
+    sourceDocs.map((d) => ({ id: d.id, tags: d.metadata?.tags ?? [], title: d.metadata?.title ?? d.title, href: d.href })),
+    { files, orphans, filter },
+  ), [sourceDocs, files, orphans, filter])
 
   useEffect(() => {
     const update = () => {
@@ -82,10 +99,12 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
     const zoom = d3.zoom().scaleExtent([0.3, 4]).on('zoom', (e) => g.attr('transform', e.transform))
     svg.call(zoom).on('dblclick.zoom', null)
 
+    /* the drawn radius: a tag by its count, a doc small and fixed, both by the display scale */
+    const R = (d) => (d.type === 'file' ? 4 : radiusOf(d)) * nodeScale
     const nodes = graphData.nodes.map((d) => ({ ...d }))
     const links = graphData.edges.map((d) => ({ ...d }))
     const maxW = d3.max(links, (l) => l.weight) || 1
-    const counts = nodes.map((d) => d.count).sort((a, b) => b - a)
+    const counts = nodes.filter((d) => d.type !== 'file').map((d) => d.count).sort((a, b) => b - a)
     /* the eight biggest tags keep their label at rest; the rest show on focus */
     const labelFloor = counts[Math.min(7, counts.length - 1)] ?? 0
 
@@ -108,10 +127,10 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
       .force('link', d3.forceLink(links).id((d) => d.id)
         .distance((l) => 45 + 95 * (1 - l.weight / maxW))
         .strength((l) => 0.08 + 0.4 * (l.weight / maxW)))
-      .force('charge', d3.forceManyBody().strength((d) => -70 - radiusOf(d) * 16).distanceMax(span * 0.8))
+      .force('charge', d3.forceManyBody().strength((d) => -70 - R(d) * 16).distanceMax(span * 0.8))
       .force('x', d3.forceX(cx).strength(0.07))
       .force('y', d3.forceY(cy).strength(0.07))
-      .force('collide', d3.forceCollide((d) => radiusOf(d) + 9).iterations(2))
+      .force('collide', d3.forceCollide((d) => R(d) + 9).iterations(2))
       .velocityDecay(0.38)
       .alphaDecay(0.035)
       .stop()
@@ -120,7 +139,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
 
     const link = g.append('g').attr('class', 'links').selectAll('line').data(links).enter().append('line')
       .attr('stroke', EDGE)
-      .attr('stroke-width', (l) => 0.6 + 1.6 * (l.weight / maxW))
+      .attr('stroke-width', (l) => (0.6 + 1.6 * (l.weight / maxW)) * linkScale)
       .attr('stroke-linecap', 'round')
       .attr('opacity', 0)
 
@@ -135,8 +154,8 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
       .attr('stroke-width', 1.5)
 
     const label = node.append('text')
-      .text((d) => `#${d.id}`)
-      .attr('dy', (d) => radiusOf(d) + 12)
+      .text((d) => (d.type === 'file' ? d.label : `#${d.id}`))
+      .attr('dy', (d) => R(d) + 12)
       .attr('text-anchor', 'middle')
       .attr('fill', 'var(--kol-fg-72)')
       .attr('font-family', 'var(--kol-font-family-mono)')
@@ -152,7 +171,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
     sim.on('tick', place)
 
     /* ── the resting look, and a focus — both tweened ── */
-    const restLabel = (d) => (d.count >= labelFloor ? 1 : 0)
+    const restLabel = (d) => (labels === 'all' ? 1 : labels === 'none' ? 0 : d.type !== 'file' && d.count >= labelFloor ? 1 : 0)
     const paint = (focusId) => {
       const lit = focusId ? near.get(focusId) : null
       const act = activeRef.current
@@ -160,7 +179,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
         duration: t(DURATION.slow),
         ease: EASE.houseGsap,
         opacity: (i) => (lit ? (lit.has(nodes[i].id) ? 1 : 0.15) : act && nodes[i].id !== act ? 0.45 : 0.95),
-        attr: { r: (i) => radiusOf(nodes[i]) * (nodes[i].id === focusId ? 1.3 : 1) },
+        attr: { r: (i) => R(nodes[i]) * (nodes[i].id === focusId ? 1.3 : 1) },
         overwrite: 'auto',
       })
       gsap.to(label.nodes(), {
@@ -196,7 +215,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
     gsap.to(circle.nodes(), {
       duration: t(DURATION.spring),
       ease: 'back.out(1.6)',
-      attr: { r: (i) => radiusOf(nodes[i]) },
+      attr: { r: (i) => R(nodes[i]) },
       opacity: 0.95,
       delay: (i) => (reduced ? 0 : (dist(nodes[i]) / maxDist) * 0.35),
       onComplete: () => paint(null),
@@ -214,7 +233,8 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
     node
       .on('click', (event, d) => {
         event.stopPropagation()
-        if (onTagClick) onTagClick(d.id)
+        if (d.type === 'file') { if (onFileClick) onFileClick(d); else if (d.href) navigate(d.href) }
+        else if (onTagClick) onTagClick(d.id)
         else navigate(tagHref(d.id))
       })
       .on('mouseenter', (event, d) => { setHoveredNode(d); paint(d.id) })
@@ -231,7 +251,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
       svg.interrupt()
       sceneRef.current = null
     }
-  }, [graphData, dimensions, navigate, onTagClick, tagHref])
+  }, [graphData, dimensions, navigate, onTagClick, onFileClick, tagHref, labels, nodeScale, linkScale])
 
   /* ── an active-tag change re-paints; it never rebuilds the layout ── */
   useEffect(() => { sceneRef.current?.paint(null) }, [activeTag])
@@ -239,7 +259,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
   if (graphData.nodes.length === 0) {
     return (
       <div className="text-fg-48 kol-mono-12 py-4 px-2">
-        No tags found.
+        Nothing to draw.
       </div>
     )
   }
@@ -249,7 +269,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
       <svg ref={svgRef} width={dimensions.width} height={dimensions.height} className="tag-graph-svg" />
       {hoveredNode && (
         <div className="tag-graph-tooltip kol-helper-10 text-emphasis">
-          #{hoveredNode.id} ({hoveredNode.count} {hoveredNode.count === 1 ? 'doc' : 'docs'})
+          {hoveredNode.type === 'file' ? hoveredNode.label : `#${hoveredNode.id} (${hoveredNode.count} ${hoveredNode.count === 1 ? 'doc' : 'docs'})`}
         </div>
       )}
     </div>

package/src/tags/TagModeContext.jsx

@@ -33,7 +33,7 @@ export const TagModeProvider = ({
    * keywords"). `text` + `activeTags` are two facets of the SAME query, not
    * two searches — ShellLayout used to hold `searchQuery` in its own local
    * state while tags lived here, which is the whole reason the app had two
-   * surfaces. `expanded` is the palette's second state: Enter commits the
+   * surfaces. `expanded` is the search modal's second state: Enter commits the
    * query and opens the results body, Escape collapses it. */
   const openTagMode = useCallback((tag = null, { view = 'list', expanded = false } = {}) => {
     setState((prev) => ({
@@ -109,7 +109,7 @@ export const TagModeProvider = ({
 
   const value = useMemo(() => ({
     /* Lets a consumer tell a real provider from the inert fallback, so
-     * ShellLayout can own its own palette state when mounted without one
+     * ShellLayout can own its own search modal state when mounted without one
      * instead of silently no-op'ing every keystroke. */
     isProvided: true,
     isOpen: state.isOpen,

package/src/tags/TagModeOverlay.jsx

@@ -105,10 +105,10 @@ const TagModeOverlay = () => {
                 <div className="flex items-center justify-between pl-5 min-[1600px]:pl-6">
                   {/* PRIMARY (user 2026-08-01). `outline quiet` is the
                     * recessive rung — this is the one action in the body. */}
-                  <Button variant="primary" size="sm" onClick={clearTags}>
+                  <Button tone="primary" size="sm" onClick={clearTags}>
                     Clear filters
                   </Button>
-                  {/* NO CHIPS HERE (2026-08-01). The palette renders the
+                  {/* NO CHIPS HERE (2026-08-01). The search modal renders the
                     * active tags in its input row — this block repeated them
                     * inside the body, so one filter showed as two chips. The
                     * query's facets belong to the query's input. */}