@kolkrabbi/kol-workshop 0.35.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "private": false,
   "description": "Docs viewer, shell and tag system",
   "license": "MIT",
@@ -13,14 +13,14 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "@kolkrabbi/kol-brand": "^0.1.3",
     "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-search": "^0.2.0"
+    "@kolkrabbi/kol-brand": "^0.1.3",
+    "@kolkrabbi/kol-search": "^0.3.0"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.234.0",
+    "@kolkrabbi/kol-component": ">=0.237.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
-    "@kolkrabbi/kol-theme": ">=0.161.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.234.0",
-    "@kolkrabbi/kol-icons": "^0.32.0",
     "@kolkrabbi/kol-framework": "^0.48.0",
-    "@kolkrabbi/kol-theme": "^0.161.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/docs/DocumentationReader.jsx

@@ -331,7 +331,9 @@ const DocumentationReader = ({
     setTocContent(
       <DocReaderSidebar
         key={docId}
-        toc={toc}
+        /* THE TITLE LEADS THE OUTLINE (2026-10-01 — user: "something is always on this page"): a
+         * chapter index with no h2 used to hand the rail an empty list */
+        toc={docTitle ? [{ id: 'page-top', label: docTitle }, ...toc] : toc}
         allTags={allTags}
         topTags={topTags}
         related={related}
@@ -342,7 +344,7 @@ const DocumentationReader = ({
       />
     )
     return () => setTocContent(null)
-  }, [rail, setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
+  }, [rail, setTocContent, docId, docTitle, toc, allTags, topTags, related, docsIndex, components, docFilePath])
 
   if (!doc) {
     return (
@@ -365,7 +367,7 @@ const DocumentationReader = ({
     <DocsArticle>
         {showFrontmatter && <DocsFrontmatter metadata={doc.metadata} docId={docId} />}
         {docTitle && (
-          <h1 className="kol-doc-heading">{docTitle}</h1>
+          <h1 id="page-top" className="kol-doc-heading scroll-mt-20">{docTitle}</h1>
         )}
         {/* Render intro blocks (excluding H1 which is docTitle) */}
         {introBlocks.filter(b => b.type !== 'heading1').map((block, index) =>

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

@@ -1,27 +1,29 @@
-import { Fragment, useMemo, useState } from 'react'
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react'
 import { getTagColor } from '@kolkrabbi/kol-markdown'
-import { useSearchParams } from 'react-router-dom'
-import { EmptyState, Input, TabsRow, Tag } from '@kolkrabbi/kol-component'
+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'
-import { DocHeader, DocSection } from '../docs/DocKit.jsx'
 
 /**
- * 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.
  *
  * @param {Array}  items   kol-search items: { id, title, href, kind?, space?, category?, tags?, headings?, keywords?, description?, date? }
  * @param {Array}  [spaces] the scope row, `[{ value, label }]` in header order — `value` is an item's `space`
- * @param {Array}  [facets] `[[field, label]]` shown as filter rows (default kind · category · tags)
+ * @param {Array}  [facets] `[[field, label]]` — the FIRST is the visible filter row, the rest fold behind `+`
+ *                          with the scope and the read-as line (default kind · category · tags)
  * @param {number} [limit=60]
+ * @param {string} [resultsPath] the route that shows results, when this box can also sit on another page
  */
 const DEFAULT_FACETS = [['kind', 'Kind'], ['category', 'Category'], ['tags', 'Tags']]
 const PREFIX = { space: 'in', kind: 'kind', category: 'cat', tags: 'tag' }
@@ -46,13 +48,18 @@ 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' }) {
+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') ?? ''
   const index = useMemo(() => createIndex(items), [items])
   const out = useMemo(() => search(index, q, { limit }), [index, q, limit])
 
-  const setQ = (next) => setParams(next.trim() ? { q: next } : {}, { replace: true })
+  /* `resultsPath`: the query is written to THAT route — a box on a search home sends its first
+   * keystroke straight to the results page instead of filtering in place */
+  const setQ = (next) => (resultsPath
+    ? navigate(next.trim() ? `${resultsPath}?q=${encodeURIComponent(next)}` : resultsPath, { replace: true })
+    : setParams(next.trim() ? { q: next } : {}, { replace: true }))
   /* a pick adds its token; picking it again takes the token back out */
   const toggleToken = (field, value) => {
     const tok = token(field, value)
@@ -61,29 +68,48 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
     setQ((has ? parts.filter((p) => p !== tok) : [...parts, tok]).join(' '))
   }
   const removeToken = (raw) => setQ(q.split(/\s+/).filter((p) => p && p !== raw).join(' '))
+  /* THE BOX OWNS ITS TEXT (2026-10-01). The URL is still the state, but a navigation lands a beat
+   * after the keystroke, and an input controlled by the URL alone dropped the letter typed in
+   * between ("tag" arrived as "tg"). The box shows what was typed; the URL follows; a query that
+   * changes from OUTSIDE (a chip, Back, a link) is read back into the box. */
+  const [text, setText] = useState(q)
+  const pushed = useRef(q)
+  useEffect(() => {
+    if (q !== pushed.current) { pushed.current = q; setText(q) }
+  }, [q])
+  const type = (next) => { pushed.current = next.trim() ? next : ''; setText(next); setQ(next) }
   const inSpace = parseQuery(q).filters.space ?? []
 
-  /* THE FACETS ARE TABS (the showcase review W11, 2026-09-30 — user: "could kind category and tags be
-   * folded into tabs? … if you are searching something and press enter, why do you need to scroll
-   * million kilometers down to get to the actual link"). Three facet sections sat between the box and
-   * the results; now one tab strip picks which facet's chips show, and the results follow it. */
-  const shown = facets.filter(([field]) => (out.facets[field] ?? []).length)
-  const [facetTab, setFacetTab] = useState(facets[0]?.[0])
-  const activeFacet = shown.find(([f]) => f === facetTab) ?? shown[0]
+  /* ONE FILTER ROW (2026-10-01 — user: "why are there so many categories and options, is it relevant
+   * to the results we are seeking as a 'searcher'"; ruled: kind stays, the rest folds behind a `+`).
+   * The page was a scope row, a "read as" row, a tab strip and its chips before the first result.
+   * Now: the box, one row of kind chips, the results. Scope · read-as · category · tags are the
+   * same controls, behind the `+` — and open by themselves while one of them is narrowing the list,
+   * so an active filter is never hidden. Reverses W11's tab strip (2026-09-30). */
+  const [first, ...rest] = facets.filter(([field]) => (out.facets[field] ?? []).length)
+  const tokens = out.query.tokens
+  const narrowed = inSpace.length > 0 || tokens.some((t) => t.kind !== 'term' && t.field !== first?.[0])
+  const [more, setMore] = useState(false)
+  const open = more || narrowed
+  const chips = ([field]) => (out.facets[field] ?? []).slice(0, 24).map((f) => (
+    <Tag key={f.value} hash={field === 'tags'} color={field === 'tags' ? getTagColor(f.value) : undefined} active={f.selected} onClick={() => toggleToken(field, f.value)}>
+      {f.value}<span className="ml-1.5 text-subtle">{f.count}</span>
+    </Tag>
+  ))
 
   return (
-    <div className="flex flex-col gap-10">
-      <DocHeader
-        eyebrow="Search"
-        title="Search"
-        lede={q ? `${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.` : 'Every page on the site.'}
-      />
+    <div className="flex flex-col gap-6">
+      {/* ONE LINE, AND ONLY ONCE THERE IS A QUERY (2026-10-01 — user: "section is search and the title
+        * is search, seems like redundant noise"): the eyebrow, the title and the count were three
+        * lines, and the count was printed again on the results heading. Without a query the page is
+        * its home's (the consumer renders it above) and this is just the box. */}
+      {q && <h1 className="kol-doc-section-title">{`${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.`}</h1>}
 
-      <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-3">
         {/* md, the ladder's default — lg towered over the page (W11) */}
         <Input
-          value={q}
-          onChange={(e) => setQ(e.target.value)}
+          value={text}
+          onChange={(e) => type(e.target.value)}
           placeholder="Search — try atom, tag:pattern/input, in:docs, -legacy"
           iconLeft="search"
           size="md"
@@ -91,57 +117,65 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
           autoFocus
         />
         {/* every chip on the page is THE Tag, one size (W11 — they were ghost Buttons and md Pills) */}
-        {spaces.length > 0 && (
-          <div className="flex flex-wrap items-center gap-2" role="group" aria-label="Scope">
-            <Tag hash={false} active={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Tag>
-            {spaces.map((sp) => (
-              <Tag key={sp.value} hash={false} active={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>{sp.label}</Tag>
-            ))}
+        {q && (first || spaces.length > 0) && (
+          <div className="flex flex-wrap items-center gap-2" role="group" aria-label={first?.[1] ?? 'Filters'}>
+            {first && chips(first)}
+            <Tag hash={false} variant="secondary" active={open} onClick={() => setMore((m) => !m)} aria-expanded={open} aria-label="More filters">{open ? '−' : '+'}</Tag>
           </div>
         )}
-        {out.query.tokens.length > 0 && (
-          <div className="flex flex-wrap items-center gap-2">
-            <span className="kol-doc-eyebrow">Read as</span>
-            {out.query.tokens.map((t, i) => (
-              <Tag key={`${t.raw}-${i}`} hash={false} variant="secondary" onRemove={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`}>{readToken(t)}</Tag>
+        {q && open && (
+          <div className="flex flex-col gap-3">
+            {spaces.length > 0 && (
+              <div className="flex flex-wrap items-center gap-2" role="group" aria-label="Scope">
+                <span className="kol-doc-eyebrow">Scope</span>
+                <Tag hash={false} active={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Tag>
+                {spaces.map((sp) => (
+                  <Tag key={sp.value} hash={false} active={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>{sp.label}</Tag>
+                ))}
+              </div>
+            )}
+            {rest.map((facet) => (
+              <div key={facet[0]} className="flex flex-wrap items-center gap-2" role="group" aria-label={facet[1]}>
+                <span className="kol-doc-eyebrow">{facet[1]}</span>
+                {chips(facet)}
+              </div>
             ))}
+            {tokens.length > 0 && (
+              <div className="flex flex-wrap items-center gap-2">
+                <span className="kol-doc-eyebrow">Read as</span>
+                {tokens.map((t, i) => (
+                  <Tag key={`${t.raw}-${i}`} hash={false} variant="secondary" onRemove={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`}>{readToken(t)}</Tag>
+                ))}
+              </div>
+            )}
           </div>
         )}
       </div>
 
-      {activeFacet && (
-        <div className="flex flex-col gap-4">
-          <TabsRow tabs={shown.map(([field, label]) => ({ id: field, label }))} value={activeFacet[0]} onChange={setFacetTab} />
-          <div className="flex flex-wrap gap-2">
-            {(out.facets[activeFacet[0]] ?? []).slice(0, 24).map((f) => (
-              <Tag key={f.value} hash={activeFacet[0] === 'tags'} color={activeFacet[0] === 'tags' ? getTagColor(f.value) : undefined} active={f.selected} onClick={() => toggleToken(activeFacet[0], f.value)}>
-                {f.value}<span className="ml-1.5 text-subtle">{f.count}</span>
-              </Tag>
-            ))}
-          </div>
-        </div>
+      {q && (
+        <section id="results" className="flex flex-col gap-4 scroll-mt-20">
+          {out.results.length === 0 ? (
+            <EmptyState eyebrow="No results" title="Nothing matches." body="Remove a token above, or try fewer words." />
+          ) : (
+            <ol className="flex flex-col border-t border-fg-08">
+              {out.results.map((r) => (
+                <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
+                  <ResultRow
+                    to={r.item.href}
+                    variant={rowVariant}
+                    title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
+                    /* 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>
+              ))}
+            </ol>
+          )}
+          {out.total > out.results.length && <p className="kol-helper-12 text-meta">{out.total - out.results.length} more — narrow the query.</p>}
+        </section>
       )}
-
-      <DocSection id="results" title={`Results (${out.total})`}>
-        {out.results.length === 0 ? (
-          <EmptyState eyebrow={q ? 'No results' : 'Search'} title={q ? 'Nothing matches.' : 'Type to search.'} body={q ? 'Remove a token above, or try fewer words.' : undefined} />
-        ) : (
-          <ol className="flex flex-col">
-            {out.results.map((r) => (
-              <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
-                <ResultRow
-                  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(' · ')}
-                  description={r.item.description}
-                />
-              </li>
-            ))}
-          </ol>
-        )}
-        {out.total > out.results.length && <p className="kol-helper-12 text-meta">{out.total - out.results.length} more — narrow the query.</p>}
-      </DocSection>
     </div>
   )
 }

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 } from 'react-router-dom'
+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-8">
-    {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
@@ -139,7 +169,7 @@ const MainColumn = ({ children, fullHeight, width = 'canvas', padStart, padEnd }
  * below). The breakpoint here and the one in gridCols are one decision and
  * must not be stated twice differently. */
 const TocColumn = ({ children, grip, railRef }) => (
-  <aside ref={railRef} aria-label="Table of contents" className="shell-rail shell-rail--toc shell-sidebar-sticky hidden xl:block pt-6 md:pt-6 lg:pt-8 pb-8">
+  <aside ref={railRef} aria-label="Table of contents" className="shell-rail shell-rail--toc shell-sidebar-sticky hidden xl:block pt-6 md:pt-6 lg:pt-8 pb-14">
     {grip}
     {/* The width is the grid track (--kol-shell-toc-w). An empty rail still
       * holds its column (user ruling 2026-08-01): a rail that disappears
@@ -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
@@ -231,10 +267,37 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
 
   /* a new page starts at the top of the one scroll region; a hash is the
    * browser's to resolve */
+  /* BACK RETURNS TO WHERE YOU WERE (2026-10-01 — user: "'back' loses the place vertically in the
+   * scroll … now I have to scroll and find my place"). Each history entry remembers its own
+   * scroll offset; Back/Forward (POP) restores it, a fresh navigation still starts at the top.
+   * The page may still be laying out when the entry returns (lazy walls, async demos), so the
+   * restore is retried for a moment until the region is tall enough to reach the offset. */
+  const navigationType = useNavigationType()
+  const scrollMemory = useRef(new Map())
+  useEffect(() => {
+    const el = document.getElementById('shell-scroll')
+    if (!el) return undefined
+    const key = location.key
+    const save = () => scrollMemory.current.set(key, el.scrollTop)
+    el.addEventListener('scroll', save, { passive: true })
+    return () => el.removeEventListener('scroll', save)
+  }, [location.key])
   useEffect(() => {
-    if (location.hash) return
-    document.getElementById('shell-scroll')?.scrollTo(0, 0)
-  }, [location.pathname, location.hash])
+    if (location.hash) return undefined
+    const el = document.getElementById('shell-scroll')
+    if (!el) return undefined
+    const saved = navigationType === 'POP' ? scrollMemory.current.get(location.key) : 0
+    if (!saved) { el.scrollTo(0, 0); return undefined }
+    let frame
+    let tries = 60
+    const restore = () => {
+      el.scrollTo(0, saved)
+      if (Math.abs(el.scrollTop - saved) > 1 && tries-- > 0) frame = requestAnimationFrame(restore)
+    }
+    restore()
+    return () => cancelAnimationFrame(frame)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location.pathname, location.hash, location.key])
 
   /* THE shortcut map. One list, rendered by the `S` sheet AND bound by the
    * handler below — a shortcut that isn't in this array doesn't exist, so the
@@ -254,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 })) }] : []),
@@ -347,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)]'
@@ -413,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
@@ -445,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: [
@@ -499,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}>
@@ -546,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}
@@ -560,12 +629,16 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
              * it. Without a `searchPath` Enter keeps the older in-place browser. */
             onExpand={searchPath ? openResultsPage : () => tagMode.setExpanded?.(true)}
             enterLabel={searchPath ? `All results for “${searchQuery.trim()}”` : undefined}
+            /* ⌘ENTER AND THE FOOTER LINK open the results page (2026-10-01); plain Enter opens
+             * the highlighted row and only falls through to the page when nothing matched. */
+            onOpenResults={searchPath ? openResultsPage : undefined}
+            resultsLabel={`All results for “${searchQuery.trim()}”`}
             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
+               * 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
@@ -39,7 +48,8 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
 
   /* THE RAIL FOLLOWS YOU — INTO A CHILD ONLY (2026-09-30, reversing the 2026-09-28 "open the
    * group you are in" on its landing page too). Landing on a page INSIDE a chapter opens that
-   * chapter and folds the rest; a chapter's own home opens nothing. Every other chapter starts
+   * chapter and folds the rest; a chapter's own home keeps that chapter open (2026-10-01, see
+   * `chainTo`). Every other chapter starts
    * folded — including ones this rail has never seen (a Group-by switch hands it new ids, and an
    * unknown id used to read as open, so every chapter sprang open).
    *
@@ -63,6 +73,11 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
       const deeper = chainTo(r.children, [...trail, r])
       if (deeper) return deeper
       if (r.children.some(isHere)) return [...trail, r]
+      /* A GROUP'S OWN HOME KEEPS IT OPEN (user 2026-10-01: *"I dont want to collapse the list
+       * like that when I just want to go to atoms home and still see the atoms list"* — reverses
+       * the 2026-09-30 "a chapter's own home opens nothing"). The label is a link; only the
+       * chevron folds. */
+      if (r.path && getChildPath(r, basePath).replace(/\/$/, '') === normalizedPath) return [...trail, r]
     }
     return null
   }
@@ -94,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}
@@ -112,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. */}