@kolkrabbi/kol-workshop 0.33.0 → 0.35.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "private": false,
-  "description": "KOL workshop/docs system — a handrolled markdown engine, search, tag system (incl. a d3 tag graph), docs viewer, and docs shell. Sits above @kolkrabbi/kol-{theme,icons,component,framework}; content is consumer-injected (the package never globs docs).",
+  "description": "Docs viewer, shell and tag system",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
@@ -13,24 +13,25 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "@kolkrabbi/kol-search": "^0.2.0",
+    "@kolkrabbi/kol-brand": "^0.1.3",
     "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-brand": "^0.1.3"
+    "@kolkrabbi/kol-search": "^0.2.0"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.228.0",
+    "@kolkrabbi/kol-component": ">=0.234.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
-    "@kolkrabbi/kol-theme": ">=0.155.0",
+    "@kolkrabbi/kol-theme": ">=0.161.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
+    "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.30.0",
+    "@kolkrabbi/kol-component": "^0.234.0",
+    "@kolkrabbi/kol-icons": "^0.32.0",
     "@kolkrabbi/kol-framework": "^0.48.0",
-    "@kolkrabbi/kol-theme": "^0.159.0",
-    "@kolkrabbi/kol-component": "^0.230.0"
+    "@kolkrabbi/kol-theme": "^0.161.0"
   },
   "files": [
     "src",

package/src/docs/DocsFrontmatter.jsx

@@ -1,12 +1,13 @@
 import { useLayoutEffect, useRef, useState } from 'react'
-import { Icon, Tag } from '@kolkrabbi/kol-component'
+import { Badge, Icon, Tag } from '@kolkrabbi/kol-component'
+import { getTagColor } from '@kolkrabbi/kol-markdown'
 import { useTagMode } from '../tags'
 import TagPath from '../tags/TagPath.jsx'
 
 /* EVERY field carries an icon (user ruling 2026-08-01). Ten of these were
  * hard-coded `null`, so two rows had a glyph and the rest sat at a ragged left
  * edge — a column that is sometimes iconned is worse than one that never is.
- * Every name below is verified present in kol-icon-set-v1. */
+ * Every name below is verified present in kol-icon-set-interface. */
 const FIELD_ICONS = {
   file: 'file',
   title: 'type',
@@ -25,7 +26,7 @@ const FIELD_ICONS = {
   tags: 'hash-02',
   /* 2026-08-01: these three rendered iconless while the rule above promised
    * every field carries one — the exact ragged edge that rule exists to stop.
-   * All verified present in kol-icon-set-v1. */
+   * All verified present in kol-icon-set-interface. */
   id: 'hash-01',
   reuses: 'repeat',
   slug: 'external-link',
@@ -133,6 +134,8 @@ const HIDDEN = new Set(['related', 'aliases'])
  * against the key, never with a text-transform. Every other value is content
  * and is printed exactly as written. */
 const CASED_VALUE_FIELDS = new Set(['type', 'status'])
+/* a doc's lifecycle on Badge's status tones (W17): live reads success, in progress warning, gone error */
+const STATUS_TONE = { active: 'success', canonical: 'info', draft: 'warning', archived: 'error', superseded: 'error', deprecated: 'error' }
 
 /** Contract order first, then anything else the doc carries, alphabetically. */
 const orderFields = (metadata) => {
@@ -210,7 +213,7 @@ const DocsFrontmatter = ({ metadata, docId }) => {
                  * `size` is omitted: `sm` is the default and the only size. */
                 <span className="flex flex-wrap gap-1.5">
                   {value.map((tag) => (
-                    <Tag key={tag} onClick={() => openTagMode(tag)}>
+                    <Tag key={tag} color={getTagColor(tag)} onClick={() => openTagMode(tag)}>
                       {/* the path renderer, not the raw string — namespace dims,
                         * leaf carries. Shared with the tag overlay so the two
                         * surfaces cannot spell a tag two ways. */}
@@ -220,6 +223,9 @@ const DocsFrontmatter = ({ metadata, docId }) => {
                 </span>
               ) : DATE_FIELDS.has(key) ? (
                 formatDate(String(value))
+              ) : key === 'status' && STATUS_TONE[String(value).toLowerCase()] ? (
+                /* STATUS WEARS ITS TONE (W17, 2026-09-30 — user: "no active error warning nothing") */
+                <Badge variant={STATUS_TONE[String(value).toLowerCase()]} size="sm">{humanise(String(value))}</Badge>
               ) : CASED_VALUE_FIELDS.has(key) ? (
                 humanise(String(value))
               ) : Array.isArray(value) ? (

package/src/docs/DocumentationReader.jsx

@@ -85,6 +85,9 @@ const DocumentationReader = ({
   routes = {},
   docId: docIdProp,
   showFrontmatter = true,
+  /* false → render the article only and leave the right rail to the page (a HOME sits on top of
+   * a page whose sections the rail must list — 2026-09-30, "This page (0)" on every home) */
+  rail = true,
 }) => {
   const {
     docsIndex = '/docs',
@@ -194,7 +197,22 @@ const DocumentationReader = ({
           <div key={blockKey} className="max-w-[var(--kol-content-panel)]">
             <Table
               variant="simple"
-              columns={block.headers.map((header, i) => ({ accessor: `c${i}`, header }))}
+              /* THE CELL ROLE PER COLUMN (the showcase review W8, 2026-09-30 — the Icons home's third
+               * column clipped). Every cell took Table's default `kol-table-cell-text`, which never
+               * wraps, inside a wrapper whose scrollbar is hidden: a wide markdown table lost its right
+               * edge silently on every doc. A column whose cells all fit in three words and 24 characters is a TOKEN
+               * column (single line); any longer cell makes it COPY, which wraps with real leading —
+               * the two roles kol-type-roles.css already defines for exactly this split. */
+              columns={block.headers.map((header, i) => ({
+                accessor: `c${i}`,
+                header,
+                className: block.rows.some((row) => {
+                  const text = String(row[i]?.content ?? '')
+                  return text.split(/\s+/).filter(Boolean).length > 3 || text.length > 24
+                })
+                  ? 'kol-doc-table-copy'
+                  : 'kol-doc-table-token',
+              }))}
               rows={block.rows.map((row, rowIndex) => ({
                 id: rowIndex,
                 ...Object.fromEntries(row.map((cell, cellIndex) => [
@@ -309,7 +327,7 @@ const DocumentationReader = ({
    * ShellTocContext then defaults to null, so calling it unguarded threw.
    * No shell → no right rail, and the reader just renders its article. */
   useEffect(() => {
-    if (!setTocContent) return undefined
+    if (!setTocContent || !rail) return undefined
     setTocContent(
       <DocReaderSidebar
         key={docId}
@@ -324,7 +342,7 @@ const DocumentationReader = ({
       />
     )
     return () => setTocContent(null)
-  }, [setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
+  }, [rail, setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
 
   if (!doc) {
     return (

package/src/exhibit/ExhibitCard.jsx

@@ -1,5 +1,5 @@
 /**
- * ExhibitCard — the specimen header inside an exhibit section: what this
+ * ExhibitCard — The header of an exhibit section. the specimen header inside an exhibit section: what this
  * variant is called, what it does, and (optionally) its technical line and its
  * prop signature. Recreated from kol-website's local `DesCard` (37L), which
  * every showcase page in that repo imported by relative path.

package/src/exhibit/ExhibitLinkCard.jsx

@@ -2,7 +2,7 @@ import { Link } from 'react-router-dom'
 import { Icon } from '@kolkrabbi/kol-component'
 
 /**
- * ExhibitLinkCard — the card an exhibit's landing page uses for each child
+ * ExhibitLinkCard — A card linking to an exhibit page. the card an exhibit's landing page uses for each child
  * page. Recreated from kol-website's `OverviewCard`, which carried a standing
  * note on itself: *"vendored verbatim from elder @kol/ui (no DS twin as of
  * kol-dashboards 0.2.0); lobby to the DS or fold into kol-dashboards if a

package/src/exhibit/ExhibitOverview.jsx

@@ -3,7 +3,7 @@ import ExhibitLinkCard from './ExhibitLinkCard.jsx'
 import useExhibitToc from './useExhibitToc.js'
 
 /**
- * ExhibitOverview — an exhibit's landing page: what this section is, then every
+ * ExhibitOverview — An exhibit's landing page. an exhibit's landing page: what this section is, then every
  * child page as a card.
  *
  * The overview contract kol-website's DashboardOverview implements by hand —

package/src/exhibit/ExhibitSidebar.jsx

@@ -4,7 +4,7 @@ import RailSection from '../shell/RailSection.jsx'
 import RailRow from '../shell/RailRow.jsx'
 
 /**
- * ExhibitSidebar — the rail block an exhibit page registers into the shell's
+ * ExhibitSidebar — An exhibit page's rail block. the rail block an exhibit page registers into the shell's
  * TOC slot: on-this-page, the section's documentation links, and quick actions.
  * Recreated from kol-website's local `WorkshopSidebarContent`.
  *

package/src/index.js

@@ -14,6 +14,4 @@ export * from './tags/index.js'
 export * from './exhibit/index.js'
 export * from './compositions/index.js'
 export * from './search/index.js'
-/* retiring — ContentRow replaces it (retirement ledger, 2026-09-30) */
-export { default as ResultRow } from './search/ResultRow.jsx'
 export * from './engine/index.js'

package/src/search/ResultRow.jsx

@@ -1,28 +1,35 @@
-/**
- * @deprecated — use kol-component's `ContentRow` (variant `article`, `media={false}`). ResultRow was
- * minted 2026-09-30 for the search page while the design system already shipped its row; it
- * forwards to ContentRow and drops at 30 days on the retirement ledger. `variant` is ignored.
- */
-
-import { useNavigate } from 'react-router-dom'
-import { ContentRow } from '@kolkrabbi/kol-component'
+import { Link } from 'react-router-dom'
 
 /**
- * @deprecated — use kol-component's `ContentRow` (variant `article`, `media={false}`). ResultRow was
- * minted 2026-09-30 for the search page while the design system already shipped its row; it
- * forwards to ContentRow and drops at 30 days on the retirement ledger. `variant` is ignored.
+ * ResultRow — One search result. one search result: a title, a meta line, an optional description, the whole row a
+ * link (2026-09-30, open questions Round 2 — the user: *"I like both, is this a component? if it
+ * is I would just have it available as variants … underline is more appealing currently"*).
+ *
+ * Two variants, each a complete pair — the wash needs its x padding, the underline must not have
+ * one (Round 1: x padding without a wash was drawn wrong):
+ *   `underline` (default) — no ground; the title underlines and the row inks up on hover
+ *   `wash`                — x padding and a ground wash on hover
+ *
+ * @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} [description]
+ * @param {'underline'|'wash'} [variant='underline']
  */
-export default function ResultRow({ to, title, meta, description }) {
-  const navigate = useNavigate()
+const VARIANTS = {
+  /* full ink at rest (W11, 2026-09-30 — user: "Results item is also so low opacity"); the ROLES carry
+   * the hierarchy — title emphasis, meta, body — not an opacity on the whole row */
+  underline: { row: 'group flex flex-col gap-1 py-3', title: 'group-hover:underline underline-offset-4' },
+  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' }) {
+  const v = VARIANTS[variant] ?? VARIANTS.underline
   return (
-    <ContentRow
-      variant="article"
-      media={false}
-      href={to}
-      onNavigate={(e) => { e.preventDefault(); navigate(to) }}
-      eyebrow={meta}
-      title={title}
-      body={description}
-    />
+    <Link to={to} className={v.row}>
+      <span className={`kol-doc-body text-emphasis ${v.title}`.trim()}>{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,11 +1,13 @@
-import { Fragment, useMemo } from 'react'
-import { useNavigate, useSearchParams } from 'react-router-dom'
-import { Button, ContentRow, EmptyState, Input, Pill } from '@kolkrabbi/kol-component'
+import { Fragment, useMemo, 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 ResultRow from './ResultRow.jsx'
 import { createIndex, search, parseQuery } from '@kolkrabbi/kol-search'
 import { DocHeader, DocSection } from '../docs/DocKit.jsx'
 
 /**
- * SearchPage — 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 palette
  * 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
@@ -44,8 +46,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 }) {
-  const navigate = useNavigate()
+export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60, rowVariant = 'underline' }) {
   const [params, setParams] = useSearchParams()
   const q = params.get('q') ?? ''
   const index = useMemo(() => createIndex(items), [items])
@@ -62,31 +63,39 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
   const removeToken = (raw) => setQ(q.split(/\s+/).filter((p) => p && p !== raw).join(' '))
   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]
+
   return (
     <div className="flex flex-col gap-10">
       <DocHeader
         eyebrow="Search"
         title="Search"
-        lede={q ? `${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.` : 'Everything in the site — components, docs, blocks, sets.'}
+        lede={q ? `${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.` : 'Every page on the site.'}
       />
 
       <div className="flex flex-col gap-4">
+        {/* md, the ladder's default — lg towered over the page (W11) */}
         <Input
           value={q}
           onChange={(e) => setQ(e.target.value)}
           placeholder="Search — try atom, tag:pattern/input, in:docs, -legacy"
           iconLeft="search"
-          size="lg"
+          size="md"
           aria-label="Search query"
           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">
-            <Button variant="ghost" size="sm" pressed={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Button>
+            <Tag hash={false} active={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Tag>
             {spaces.map((sp) => (
-              <Button key={sp.value} variant="ghost" size="sm" pressed={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>
-                {sp.label}
-              </Button>
+              <Tag key={sp.value} hash={false} active={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>{sp.label}</Tag>
             ))}
           </div>
         )}
@@ -94,29 +103,24 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
           <div className="flex flex-wrap items-center gap-2">
             <span className="kol-doc-eyebrow">Read as</span>
             {out.query.tokens.map((t, i) => (
-              <button key={`${t.raw}-${i}`} type="button" onClick={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`} className="cursor-pointer">
-                <Pill variant={t.kind === 'term' ? 'secondary' : 'primary'} size="md">{readToken(t)} ×</Pill>
-              </button>
+              <Tag key={`${t.raw}-${i}`} hash={false} variant="secondary" onRemove={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`}>{readToken(t)}</Tag>
             ))}
           </div>
         )}
       </div>
 
-      {facets.map(([field, label]) => {
-        const values = (out.facets[field] ?? []).slice(0, 16)
-        if (!values.length) return null
-        return (
-          <DocSection key={field} id={`facet-${field}`} title={label}>
-            <div className="flex flex-wrap gap-2">
-              {values.map((f) => (
-                <Button key={f.value} variant="ghost" size="sm" pressed={f.selected} onClick={() => toggleToken(field, f.value)}>
-                  {f.value}<span className="ml-1.5 opacity-60">{f.count}</span>
-                </Button>
-              ))}
-            </div>
-          </DocSection>
-        )
-      })}
+      {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>
+      )}
 
       <DocSection id="results" title={`Results (${out.total})`}>
         {out.results.length === 0 ? (
@@ -125,22 +129,18 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
           <ol className="flex flex-col">
             {out.results.map((r) => (
               <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
-                {/* THE SHIPPED ROW (2026-09-30): kol-component's ContentRow, the row form of the
-                  * content-card system — not a row minted here. Article form, no cover. */}
-                <ContentRow
-                  variant="article"
-                  media={false}
-                  href={r.item.href}
-                  onNavigate={(e) => { e.preventDefault(); navigate(r.item.href) }}
-                  eyebrow={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
+                <ResultRow
+                  to={r.item.href}
+                  variant={rowVariant}
                   title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
-                  body={r.item.description}
+                  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-subtle">{out.total - out.results.length} more — narrow the query.</p>}
+        {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/search/index.js

@@ -1 +1,2 @@
 export { default as SearchPage } from './SearchPage.jsx'
+export { default as ResultRow } from './ResultRow.jsx'

package/src/shell/RailSection.jsx

@@ -1,5 +1,6 @@
 import { useState } from 'react'
 import { Link } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
 
 /**
  * RailSection — THE rail ladder. One component owns every rail header, at
@@ -70,7 +71,7 @@ export default function RailSection({
   onToggle,
   defaultCollapsed = false,
   onNavigate,
-  icon: IconComponent,
+  icon: IconComponent = Icon,
   children,
 }) {
   const [internal, setInternal] = useState(defaultCollapsed)
@@ -120,33 +121,37 @@ export default function RailSection({
    * the eyebrow felt expand-only. A category's door lives in the header tabs.
    * L2 keeps the split (2026-08-02 ruling): its label is a chapter's only
    * door to the landing page, and the chevron marks the toggle. */
-  const labelNode = to && level === 2 ? (
+  /* L1 JOINS L2 (2026-09-30, user: every label opens its home — *"components from the top and
+   * components go to the same components home"*; reverses the 2026-08-09 pure-toggle eyebrow). */
+  const labelNode = to ? (
     /* The label navigates; the rest of the row toggles. stopPropagation keeps
      * one click from doing both. */
     <Link
       to={to}
+      className="truncate"
       onClick={(e) => {
+        /* the label opens the page, the chevron folds (audit § Homes) */
         e.stopPropagation()
-        if (isCollapsed && toggle) toggle()
         if (onNavigate) onNavigate(e)
       }}
     >
       {label}
     </Link>
   ) : (
-    <span>{label}</span>
+    <span className="truncate">{label}</span>
   )
 
   const inner = (
     <>
-      <span className="flex items-center gap-2">
+      {/* the label truncates like a row does (W4, 2026-09-30: long set names wrapped to two lines) */}
+      <span className="flex items-center gap-2 min-w-0">
         {chevron}
         {/* L2 rows without a caret keep the caret's width as space, so an
           * expandable row and a childless one share a left edge. */}
         {level === 2 && !chevron && <span aria-hidden="true" style={{ width: 12 }} />}
         {labelNode}
       </span>
-      <span className="flex items-center gap-2">
+      <span className="flex items-center gap-2 shrink-0">
         {countNode}
         {l1State}
       </span>

package/src/shell/RightRail.jsx

@@ -1,8 +1,11 @@
 import { useState } from 'react'
+import { getTagColor } from '@kolkrabbi/kol-markdown'
 import { useLocation } from 'react-router-dom'
 import RailSection from './RailSection.jsx'
 import RailRow from './RailRow.jsx'
 
+const hueOf = (tag) => { const c = getTagColor(tag); return c === 'dark' ? undefined : `var(--kol-palette-${c})` }
+
 /**
  * RightRail — THE right rail. One component, every route.
  *
@@ -81,6 +84,8 @@ export default function RightRail({
   tags = [],
   renderTag,
   onTagClick,
+  /* where every tag in use is listed (the showcase's /search/tags) — a row in the Tags section */
+  tagsHref,
   icon: IconComponent,
 }) {
   /* One collapse map, not a useState per section — a section added later must
@@ -100,10 +105,19 @@ export default function RightRail({
     setPins(next)
     writePins(next)
   }
+  /* TAGS ARE THEIR OWN SECTION (the showcase review W15, 2026-09-30 — user: "right sidebar has this
+   * page, links, and inside links is tags? feel like maybe tags is its own thing? with tag graph and
+   * all that"). The tag graph is a TAG view, so the caller's `graph` action moves out of Quick actions
+   * and leads the Tags section; every caller already passes it under that id. */
+  const graphAction = actions.find((a) => a.id === 'graph')
   const allActions = [
-    ...actions,
+    ...actions.filter((a) => a.id !== 'graph'),
     { id: 'pin', label: isPinned ? 'Unpin' : 'Pin', icon: IconComponent ? <IconComponent name="pushpin" size={14} /> : null, onClick: togglePin },
   ]
+  const tagViews = [
+    ...(graphAction ? [graphAction] : []),
+    ...(tagsHref ? [{ id: 'all-tags', label: 'All tags', to: tagsHref, icon: IconComponent ? <IconComponent name="hash-02" size={14} /> : null }] : []),
+  ]
   const toggle = (key) => setCollapsed((c) => ({ ...c, [key]: !c[key] }))
 
   /* OWN TAGS ONLY, GROUPED BY NAMESPACE (2026-09-30, the names audit — ruled on the
@@ -153,7 +167,7 @@ export default function RightRail({
         </div>
       </RailSection>
 
-      <RailSection level={1} label="Links" count={pins.length + allActions.length + tags.length + related.length}>
+      <RailSection level={1} label="Links" count={pins.length + allActions.length + related.length}>
         <div className="shell-rail-stack-inner">
           {group('pinned', 'Pinned', pins.length,
             pins.map((p) => (
@@ -171,26 +185,6 @@ export default function RightRail({
             ))
           )}
 
-          {group('tags', 'Tags', tags.length, (
-            <>
-              {Object.entries(byNamespace).map(([ns, list]) => (
-                <div key={`ns-${ns}`}>
-                  {ns && <RailRow className="shell-nav-item--muted">{ns.charAt(0).toUpperCase() + ns.slice(1)}</RailRow>}
-                  {list.map(({ tag, leaf }) => (
-                    <RailRow
-                      key={`own-${tag}`}
-                      sub={!!ns}
-                      onClick={() => onTagClick?.(tag)}
-                      icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
-                    >
-                      {leaf}
-                    </RailRow>
-                  ))}
-                </div>
-              ))}
-            </>
-          ))}
-
           {/* Related carries SOURCES too (user ruling 2026-08-01) — a repo URL
             * or an external reference is another document this one names, and
             * splitting them made two sections that answer the same question. */}
@@ -201,6 +195,33 @@ export default function RightRail({
           )}
         </div>
       </RailSection>
+
+      {/* TAGS — the views of the tag system, then this page's tags, a group per namespace */}
+      {(tagViews.length > 0 || tags.length > 0) && (
+        <RailSection level={1} label="Tags" count={tags.length}>
+          <div className="shell-rail-stack-inner">
+            {tagViews.length > 0 && (
+              <nav className="shell-nav-items">
+                {tagViews.map((a) => (
+                  <RailRow key={a.id} to={a.to} onClick={a.onClick} icon={a.icon}>{a.label}</RailRow>
+                ))}
+              </nav>
+            )}
+            {Object.entries(byNamespace).map(([ns, list]) => <div key={`tags-${ns || 'flat'}`}>{group(`tags-${ns || 'flat'}`, ns ? ns.charAt(0).toUpperCase() + ns.slice(1) : 'Tags', list.length,
+              list.map(({ tag, leaf }) => (
+                <RailRow
+                  key={`own-${tag}`}
+                  onClick={() => onTagClick?.(tag)}
+                  /* the hash wears the tag's namespace color (W17), the same hue its chip and graph node wear */
+                  icon={IconComponent ? <span className="inline-flex" style={{ color: hueOf(tag) }}><IconComponent name="hash-02" size={14} /></span> : null}
+                >
+                  {leaf}
+                </RailRow>
+              ))
+            )}</div>)}
+          </div>
+        </RailSection>
+      )}
     </div>
   )
 }

package/src/shell/ShellLayout.jsx

@@ -241,19 +241,21 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
    * sheet can never drift from the bindings. The sheet is kol-component's
    * ShortcutsOverlay (2026-09-28): the same sheet, on the same key, as every
    * app — it was a `?` sheet of its own here. `?` still opens it. */
+  /* FEWEST WORDS (the showcase review W16, 2026-09-30 — user: "shortcuts overlay, too wordy"):
+   * a label names the thing the key does, nothing more. `\\` hides or shows both rails at once. */
   const SHORTCUTS = [
     { section: 'Search', items: [
-      { id: 'k', label: 'Search everything', combo: '⌘ K' },
-      { id: 'slash', label: 'Search everything', combo: '/' },
-      { id: 'enter', label: 'All results, on the search page', combo: '↵' },
+      { id: 'k', label: 'Search', combo: '⌘ K , /' },
+      { id: 'enter', label: 'All results', combo: '↵' },
     ] },
     { section: 'Shell', items: [
-      { id: 'sheet', label: 'This sheet', combo: 'S' },
+      { id: 'sheet', label: 'Shortcuts', combo: 'S' },
       { id: 'settings', label: 'Settings', combo: ',' },
       { id: 'nav', label: 'Left rail', combo: '[' },
       { id: 'toc', label: 'Right rail', combo: ']' },
-      { id: 'fold', label: 'Fold or open every chapter', combo: 'C' },
-      { id: 'esc', label: 'Close what is open', combo: 'Esc' },
+      { id: 'rails', label: 'Both rails', combo: '\\' },
+      { id: 'fold', label: 'Fold all', combo: 'C' },
+      { id: 'esc', label: 'Close', combo: 'Esc' },
     ] },
     ...(shortcuts.length ? [{ section: 'Page', items: shortcuts.map(({ id, label, combo }) => ({ id, label, combo })) }] : []),
   ]
@@ -289,6 +291,14 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       } else if (e.key === ']') {
         e.preventDefault()
         setTocCollapsed((v) => { writeSettings({ ...readSettings(), tocHidden: !v }); return !v })
+      } else if (e.key === '\\') {
+        /* BOTH RAILS (W16): any rail showing → hide both; both hidden → show both */
+        e.preventDefault()
+        const s = readSettings()
+        const hide = !(s.navHidden && s.tocHidden)
+        setNavCollapsed(hide)
+        setTocCollapsed(hide)
+        writeSettings({ ...s, navHidden: hide, tocHidden: hide })
       } else if (e.key === 'c' || e.key === 'C') {
         e.preventDefault()
         foldedRef.current = !foldedRef.current
@@ -438,7 +448,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       { id: 'toc', label: 'Right rail', render: () => <SettingsSwitch on={!tocCollapsed} onChange={(on) => { setTocCollapsed(!on); setPref('tocHidden', !on) }} /> },
     ] },
     { label: 'Search', rows: [
-      { id: 'scope', label: 'Quick search in this space only', render: () => <SettingsSwitch on={!!prefs.limitToSpace} onChange={(on) => setPref('limitToSpace', on)} /> },
+      { id: 'scope', label: 'This space only', render: () => <SettingsSwitch on={!!prefs.limitToSpace} onChange={(on) => setPref('limitToSpace', on)} /> },
     ] },
     ...settings,
     { label: 'Keys', rowGap: 1, rows: SHORTCUTS.flatMap((sec) => sec.items).map((k) => ({
@@ -536,6 +546,8 @@ 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 */
+            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
              * commits the query and swaps the result rows for the full body;

package/src/shell/ShellSidebar.jsx

@@ -37,55 +37,93 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
   const navCollapsed = isControlled ? collapsed : internalCollapsed
   const handleToggle = isControlled ? onToggle : () => setInternalCollapsed(prev => !prev)
 
-  const [collapsedSections, setCollapsedSections] = useState(() => {
-    const initial = {}
-    routes.forEach((route) => {
-      const sectionPath = getSectionRootPath(route, basePath)
-      const isActive =
-        sectionPath === basePath
-          ? normalizedPath === basePath
-          : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
-      initial[route.id] = !isActive
-    })
-    return initial
-  })
-
-  /* THE RAIL FOLLOWS YOU (2026-09-28, user: "the sidebar doesnt highlight that
-   * part, which it probably should by closing/collapsing other categories").
-   * Arriving in a group opens it AND folds its siblings, so the open group is
-   * the one you are in. Opening another by hand still works until you move. */
-  const isRouteActive = (route) => {
-    const sectionPath = getSectionRootPath(route, basePath)
-    const own = sectionPath === basePath
-      ? normalizedPath === basePath
-      : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
-    return own || (route.children ?? []).some((c) => {
-      const cp = getChildPath(c, basePath).replace(/\/$/, '')
-      return normalizedPath === cp || normalizedPath.startsWith(cp + '/')
-    })
+  /* 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
+   * 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).
+   *
+   * ANY DEPTH (2026-09-30, the showcase review W1 — user: Library › Composition › Components ›
+   * Atoms › Button). A chapter may hold chapters; every group at every depth is a fold of its own,
+   * and the chain down to where you are opens and everything off it folds. */
+  const isHere = (route) => {
+    /* a pathless group is not a place — without this its basePath fallback matched every URL */
+    if (!route.path) return false
+    const cp = getChildPath(route, basePath).replace(/\/$/, '')
+    return normalizedPath === cp || normalizedPath.startsWith(cp + '/')
+  }
+  const groupsOf = (list) => list.flatMap((r) => (r.children?.length ? [r, ...groupsOf(r.children)] : []))
+  /* ONE PLACE YOU ARE (W4, 2026-09-30). A page can sit in more than one group — Button is an
+   * atom AND a member of every set that uses it — and opening every group that holds it would
+   * unfold half the rail. The first place in tree order wins: its chain opens, the rest fold. */
+  const chainTo = (list, trail = []) => {
+    for (const r of list) {
+      if (!r.children?.length) continue
+      /* deepest first: `/sets` holds `/sets/app-shell` by prefix, but the set's own row is the place */
+      const deeper = chainTo(r.children, [...trail, r])
+      if (deeper) return deeper
+      if (r.children.some(isHere)) return [...trail, r]
+    }
+    return null
+  }
+  const followed = () => {
+    const chain = chainTo(routes)
+    if (!chain) return null
+    const open = new Set(chain.map((g) => g.id))
+    return Object.fromEntries(groupsOf(routes).map((g) => [g.id, !open.has(g.id)]))
   }
+  const [collapsedSections, setCollapsedSections] = useState(() => followed() ?? {})
   useEffect(() => {
-    const active = routes.filter(isRouteActive)
-    if (!active.length) return
-    setCollapsedSections(Object.fromEntries(routes.map((r) => [r.id, !active.includes(r)])))
+    const next = followed()
+    if (next) setCollapsedSections(next)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [normalizedPath, routes, basePath])
+  const isFolded = (route) => collapsedSections[route.id] ?? true
 
   /* FOLD ALL (2026-09-30, the names audit: *"shortcut collapse/expand the categories"*). The
    * shell's `C` key broadcasts one target state; every rail's chapters take it. */
   useEffect(() => {
-    const onFold = (e) => setCollapsedSections(Object.fromEntries(routes.map((r) => [r.id, !!e.detail?.collapsed])))
+    const onFold = (e) => setCollapsedSections(Object.fromEntries(groupsOf(routes).map((r) => [r.id, !!e.detail?.collapsed])))
     window.addEventListener(RAIL_FOLD_EVENT, onFold)
     return () => window.removeEventListener(RAIL_FOLD_EVENT, onFold)
   }, [routes])
 
   const handleSectionClick = (route) => {
-    setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
+    setCollapsedSections((prev) => ({ ...prev, [route.id]: !(prev[route.id] ?? true) }))
   }
 
   /* The L1 count is every leaf row under it — RailSection shows it only while
-   * the section is folded (2026-09-28). */
-  const leafCount = routes.reduce((n, r) => n + (r.children?.length ? r.children.length : 1), 0)
+   * 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)
+  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. */
+  const renderGroup = (route) => (
+    <RailSection
+      level={2}
+      label={route.label}
+      count={route.children.length}
+      /* THE HEADER ALWAYS LINKS (2026-08-02): the label opens the chapter's home,
+       * the chevron folds. */
+      to={route.path ?? getSectionRootPath(route, basePath)}
+      collapsed={isFolded(route)}
+      onToggle={() => handleSectionClick(route)}
+      onNavigate={onNavigate}
+      icon={Icon}
+    >
+      <nav className="shell-nav-items">
+        {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}>
+            {child.label}
+          </RailRow>
+        )))}
+      </nav>
+    </RailSection>
+  )
   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
@@ -103,48 +141,30 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
         icon={Icon}
       >
         <div className="shell-rail-stack-inner">
-          {routes.map((route) => {
-            /* A group with no children is not a group — it is a link. It used
-             * to render as a header anyway: a chevron that rotated over an
-             * empty body, no count, and no navigation, so clicking "Icons" or
-             * "Components" in the tree did nothing at all while looking like
-             * it should. `collapsible` is what that distinction is now. */
-            const hasChildren = route.children?.length > 0
-
-            return (
-              <div key={route.id} className="shell-nav-group">
-                <RailSection
-                  level={2}
-                  label={route.label}
-                  count={hasChildren ? route.children.length : undefined}
-                  /* THE HEADER ALWAYS LINKS (2026-08-02). It used to link only
-                   * when the group had NO children, so a chapter with pages had
-                   * a dead header and its index had to ride as a row inside
-                   * itself. RailSection already separates the two gestures —
-                   * the label navigates, the rest of the row toggles — so a
-                   * group can open its landing page and still collapse. */
-                  to={route.path ?? getSectionRootPath(route, basePath)}
-                  collapsible={hasChildren}
-                  collapsed={!!collapsedSections[route.id]}
-                  onToggle={() => handleSectionClick(route)}
-                  onNavigate={onNavigate}
-                  icon={Icon}
-                >
-                  <nav className="shell-nav-items">
-                    {(route.children ?? []).map((child) => (
-                      <RailRow
-                        key={child.id}
-                        to={getChildPath(child, basePath)}
-                        onNavigate={onNavigate}
-                      >
-                        {child.label}
-                      </RailRow>
-                    ))}
-                  </nav>
-                </RailSection>
-              </div>
-            )
-          })}
+          {/* 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>
     </div>

package/src/tags/TagGraph.jsx

@@ -1,8 +1,10 @@
 import { useEffect, useRef, useMemo, useState } from 'react'
 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 { EASE, DURATION, s } from '@kolkrabbi/kol-component/utilities/motion'
 
 /**
  * TagGraph - Obsidian-style tag graph
@@ -12,209 +14,227 @@ import { tagGraph } from '@kolkrabbi/kol-search'
  *
  * `tagHref(tag)` builds the navigation target when no `onTagClick` is provided
  * (route-decoupled — no hardcoded workshop paths here).
+ *
+ * REBUILT (the showcase review W14, 2026-09-30 — user: *"the node graph is fucked, it needs better
+ * gsap and physics. asap."*). What was wrong, and what replaced it:
+ *
+ *   - ONE SIMULATION. Every hover and every active-tag change wiped the SVG and restarted the
+ *     simulation from random positions, so the graph re-exploded on each interaction. The layout now
+ *     builds once per data/size; highlight is a separate, tweened pass over the same elements.
+ *   - PHYSICS THAT SCALES. Fixed numbers (charge −150, link 60, collide 30) whatever the graph held.
+ *     Now: charge by node size and capped in range, link length and pull by how many pages two tags
+ *     share, a gentle gravity so the cluster stays centred, collision from the drawn radius. Seeded on
+ *     a phyllotaxis spiral and settled BEFORE the first frame, so it opens composed, not exploding.
+ *   - MOTION ON THE HOUSE CURVE. Nodes grow in from the centre outward, edges fade in, the view eases
+ *     to fit; hovering a tag brings it and its neighbours forward and dims the rest. Durations and
+ *     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.
  */
 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) => {
+  /* 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))`
+}
+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 svgRef = useRef(null)
   const containerRef = useRef(null)
+  const sceneRef = useRef(null)
   const navigate = useNavigate()
   const [dimensions, setDimensions] = useState({ width: 300, height: 300 })
   const [hoveredNode, setHoveredNode] = useState(null)
+  const activeRef = useRef(activeTag)
+  activeRef.current = activeTag
 
-  // Use allDocs if provided, otherwise fall back to docs
   const sourceDocs = allDocs || docs
-
-  // Compute graph data: ALL tags with connections (pure — see engine/tags.js)
   /* 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])
 
-  // Update dimensions on resize
   useEffect(() => {
-    const updateDimensions = () => {
-      if (containerRef.current) {
-        const { width } = containerRef.current.getBoundingClientRect()
-        const size = Math.max(250, width)
-        setDimensions({ width: size, height: size })
-      }
+    const update = () => {
+      if (!containerRef.current) return
+      const { width } = containerRef.current.getBoundingClientRect()
+      const size = Math.max(250, width)
+      setDimensions((d) => (d.width === size ? d : { width: size, height: size }))
     }
-    updateDimensions()
-    const resizeObserver = new ResizeObserver(updateDimensions)
-    if (containerRef.current) {
-      resizeObserver.observe(containerRef.current)
-    }
-    return () => resizeObserver.disconnect()
+    update()
+    const ro = new ResizeObserver(update)
+    if (containerRef.current) ro.observe(containerRef.current)
+    return () => ro.disconnect()
   }, [])
 
-  // Render the force-directed graph
+  /* ── THE LAYOUT — once per data and size ─────────────────────────────────── */
   useEffect(() => {
     if (!svgRef.current || graphData.nodes.length === 0) return
-
     const { width, height } = dimensions
+    const reduced = typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+    const t = (ms) => (reduced ? 0 : s(ms))
 
-    // Clear previous
     const svg = d3.select(svgRef.current)
     svg.selectAll('*').remove()
-
-    // Create container group
     const g = svg.append('g')
+    const zoom = d3.zoom().scaleExtent([0.3, 4]).on('zoom', (e) => g.attr('transform', e.transform))
+    svg.call(zoom).on('dblclick.zoom', null)
 
-    // Create zoom behavior
-    const zoom = d3.zoom()
-      .scaleExtent([0.3, 3])
-      .on('zoom', (event) => {
-        g.attr('transform', event.transform)
-      })
-    svg.call(zoom)
-
-    // Prepare data with D3-friendly structure
-    const nodes = graphData.nodes.map(d => ({ ...d }))
-    const links = graphData.edges.map(d => ({ ...d }))
-
-    // Create force simulation
-    const simulation = d3.forceSimulation(nodes)
-      .force('link', d3.forceLink(links).id(d => d.id).distance(60).strength(0.5))
-      .force('charge', d3.forceManyBody().strength(-150))
-      .force('center', d3.forceCenter(width / 2, height / 2))
-      .force('collision', d3.forceCollide().radius(30))
-
-    // Draw edges
-    const link = g.append('g')
-      .attr('class', 'links')
-      .selectAll('line')
-      .data(links)
-      .enter()
-      .append('line')
-      .attr('stroke', d => {
-        // Highlight edges connected to active tag
-        if (activeTag && (d.source.id === activeTag || d.target.id === activeTag)) {
-          return 'var(--kol-accent-primary)'
-        }
-        return 'color-mix(in srgb, var(--kol-surface-on-primary) 20%, transparent)'
-      })
-      .attr('stroke-width', d => {
-        if (activeTag && (d.source.id === activeTag || d.target.id === activeTag)) {
-          return 2
-        }
-        return Math.min(2, d.weight * 0.5)
-      })
-      .attr('opacity', d => {
-        if (!activeTag) return 0.6
-        return (d.source.id === activeTag || d.target.id === activeTag) ? 1 : 0.2
-      })
+    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)
+    /* the eight biggest tags keep their label at rest; the rest show on focus */
+    const labelFloor = counts[Math.min(7, counts.length - 1)] ?? 0
+
+    /* neighbours, for focus */
+    const near = new Map(nodes.map((d) => [d.id, new Set([d.id])]))
+    for (const l of graphData.edges) { near.get(l.source)?.add(l.target); near.get(l.target)?.add(l.source) }
+
+    /* seed on a phyllotaxis spiral, biggest first — deterministic, and already roughly in place */
+    const cx = width / 2
+    const cy = height / 2
+    ;[...nodes].sort((a, b) => b.count - a.count).forEach((d, i) => {
+      const r = 10 * Math.sqrt(i + 0.5)
+      const a = i * 2.39996
+      d.x = cx + r * Math.cos(a)
+      d.y = cy + r * Math.sin(a)
+    })
 
-    // Draw nodes
-    const node = g.append('g')
-      .attr('class', 'nodes')
-      .selectAll('g')
-      .data(nodes)
-      .enter()
-      .append('g')
+    const span = Math.min(width, height)
+    const sim = d3.forceSimulation(nodes)
+      .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('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))
+      .velocityDecay(0.38)
+      .alphaDecay(0.035)
+      .stop()
+    /* settle before the first frame — it opens composed, not exploding */
+    for (let i = 0; i < 260; i++) sim.tick()
+
+    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-linecap', 'round')
+      .attr('opacity', 0)
+
+    const node = g.append('g').attr('class', 'nodes').selectAll('g').data(nodes).enter().append('g')
       .attr('class', 'node')
       .style('cursor', 'pointer')
-      .call(d3.drag()
-        .on('start', dragstarted)
-        .on('drag', dragged)
-        .on('end', dragended))
-
-    // Node circles
-    node.append('circle')
-      .attr('r', d => Math.max(8, Math.min(16, 6 + d.count * 2)))
-      /* Palette tokens, not copies. This held eight hardcoded hexes that were
-       * transcriptions of --kol-palette-* (#3740D3 IS palette-blue) — correct
-       * the day they were typed and frozen ever since, so a retuned palette
-       * would move every chip and leave the graph behind. The chip rules in
-       * kol-components-molecules.css resolve the variables; the graph now
-       * reads the same ones. `dark` has no palette entry — it is a surface
-       * role — so it falls back rather than emitting an invalid var(). */
-      .attr('fill', d => {
-        const key = getTagColor(d.id)
-        return key === 'dark'
-          ? 'var(--kol-surface-on-primary)'
-          : `var(--kol-palette-${key}, var(--kol-palette-teal))`
-      })
-      .attr('opacity', d => activeTag && d.id !== activeTag ? 0.4 : 0.9)
-      .attr('stroke', d => d.id === activeTag ? 'var(--kol-accent-primary)' : 'none')
-      .attr('stroke-width', d => d.id === activeTag ? 2 : 0)
-
-    // Node labels
-    node.append('text')
-      .text(d => `#${d.id}`)
-      .attr('dy', d => Math.max(8, Math.min(16, 6 + d.count * 2)) + 12)
+
+    const circle = node.append('circle')
+      .attr('r', 0)
+      .attr('fill', fillOf)
+      .attr('stroke', 'var(--kol-surface-primary)')
+      .attr('stroke-width', 1.5)
+
+    const label = node.append('text')
+      .text((d) => `#${d.id}`)
+      .attr('dy', (d) => radiusOf(d) + 12)
       .attr('text-anchor', 'middle')
-      .attr('fill', 'color-mix(in srgb, var(--kol-surface-on-primary) 64%, transparent)')
+      .attr('fill', 'var(--kol-fg-72)')
       .attr('font-family', 'var(--kol-font-family-mono)')
       .attr('font-size', '9px')
       .attr('pointer-events', 'none')
+      .attr('opacity', 0)
 
-    // Node interactions
-    node
-      .on('click', (event, d) => {
-        event.stopPropagation()
-        if (onTagClick) {
-          onTagClick(d.id)
-        } else {
-          navigate(tagHref(d.id))
-        }
+    const place = () => {
+      link.attr('x1', (d) => d.source.x).attr('y1', (d) => d.source.y).attr('x2', (d) => d.target.x).attr('y2', (d) => d.target.y)
+      node.attr('transform', (d) => `translate(${d.x}, ${d.y})`)
+    }
+    place()
+    sim.on('tick', place)
+
+    /* ── the resting look, and a focus — both tweened ── */
+    const restLabel = (d) => (d.count >= labelFloor ? 1 : 0)
+    const paint = (focusId) => {
+      const lit = focusId ? near.get(focusId) : null
+      const act = activeRef.current
+      gsap.to(circle.nodes(), {
+        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) },
+        overwrite: 'auto',
       })
-      .on('mouseenter', (event, d) => {
-        setHoveredNode(d)
-        // Highlight connected edges
-        link
-          .attr('opacity', l => l.source.id === d.id || l.target.id === d.id ? 1 : 0.15)
-          .attr('stroke', l => l.source.id === d.id || l.target.id === d.id
-            ? 'var(--kol-accent-primary)'
-            : 'color-mix(in srgb, var(--kol-surface-on-primary) 20%, transparent)')
+      gsap.to(label.nodes(), {
+        duration: t(DURATION.slow),
+        ease: EASE.houseGsap,
+        opacity: (i) => (lit ? (lit.has(nodes[i].id) ? 1 : 0) : nodes[i].id === act ? 1 : restLabel(nodes[i])),
+        overwrite: 'auto',
       })
-      .on('mouseleave', () => {
-        setHoveredNode(null)
-        link
-          .attr('opacity', d => {
-            if (!activeTag) return 0.6
-            return (d.source.id === activeTag || d.target.id === activeTag) ? 1 : 0.2
-          })
-          .attr('stroke', d => {
-            if (activeTag && (d.source.id === activeTag || d.target.id === activeTag)) {
-              return 'var(--kol-accent-primary)'
-            }
-            return 'color-mix(in srgb, var(--kol-surface-on-primary) 20%, transparent)'
-          })
+      gsap.to(link.nodes(), {
+        duration: t(DURATION.slow),
+        ease: EASE.houseGsap,
+        opacity: (i) => {
+          const l = links[i]
+          const hit = (id) => l.source.id === id || l.target.id === id
+          if (focusId) return hit(focusId) ? 1 : 0.06
+          if (act) return hit(act) ? 1 : 0.15
+          return 0.35
+        },
+        overwrite: 'auto',
       })
+      /* the stroke is SET, not tweened — two color-mix()/var() strings do not interpolate */
+      link.attr('stroke', (l) => {
+        const id = focusId ?? act
+        return id && (l.source.id === id || l.target.id === id) ? ACCENT : EDGE
+      })
+      circle.attr('stroke', (d) => (d.id === act ? ACCENT : 'var(--kol-surface-primary)'))
+    }
 
-    // Simulation tick
-    simulation.on('tick', () => {
-      link
-        .attr('x1', d => d.source.x)
-        .attr('y1', d => d.source.y)
-        .attr('x2', d => d.target.x)
-        .attr('y2', d => d.target.y)
-
-      node.attr('transform', d => `translate(${d.x}, ${d.y})`)
+    /* ── the entrance: edges fade, nodes grow from the centre outward, the view eases to fit ── */
+    const dist = (d) => Math.hypot(d.x - cx, d.y - cy)
+    const maxDist = d3.max(nodes, dist) || 1
+    gsap.to(link.nodes(), { duration: t(DURATION.zoom), ease: EASE.houseGsap, opacity: 0.35 })
+    gsap.to(circle.nodes(), {
+      duration: t(DURATION.spring),
+      ease: 'back.out(1.6)',
+      attr: { r: (i) => radiusOf(nodes[i]) },
+      opacity: 0.95,
+      delay: (i) => (reduced ? 0 : (dist(nodes[i]) / maxDist) * 0.35),
+      onComplete: () => paint(null),
     })
+    gsap.to(label.nodes(), { duration: t(DURATION.zoom), delay: t(300), ease: EASE.houseGsap, opacity: (i) => restLabel(nodes[i]) })
 
-    // Drag functions
-    function dragstarted(event, d) {
-      if (!event.active) simulation.alphaTarget(0.3).restart()
-      d.fx = d.x
-      d.fy = d.y
-    }
+    const [x0, x1] = d3.extent(nodes, (d) => d.x)
+    const [y0, y1] = d3.extent(nodes, (d) => d.y)
+    const pad = 36
+    const k = Math.min(3, 0.95 * Math.min(width / (x1 - x0 + pad * 2 || 1), height / (y1 - y0 + pad * 2 || 1)))
+    const fit = d3.zoomIdentity.translate(width / 2, height / 2).scale(k).translate(-(x0 + x1) / 2, -(y0 + y1) / 2)
+    svg.transition().duration(reduced ? 0 : DURATION.zoom).ease(d3.easeCubicInOut).call(zoom.transform, fit)
 
-    function dragged(event, d) {
-      d.fx = event.x
-      d.fy = event.y
-    }
-
-    function dragended(event, d) {
-      if (!event.active) simulation.alphaTarget(0)
-      d.fx = null
-      d.fy = null
-    }
+    /* ── interaction ── */
+    node
+      .on('click', (event, d) => {
+        event.stopPropagation()
+        if (onTagClick) onTagClick(d.id)
+        else navigate(tagHref(d.id))
+      })
+      .on('mouseenter', (event, d) => { setHoveredNode(d); paint(d.id) })
+      .on('mouseleave', () => { setHoveredNode(null); paint(null) })
+      .call(d3.drag()
+        .on('start', (event, d) => { if (!event.active) sim.alphaTarget(0.2).restart(); d.fx = d.x; d.fy = d.y })
+        .on('drag', (event, d) => { d.fx = event.x; d.fy = event.y })
+        .on('end', (event, d) => { if (!event.active) sim.alphaTarget(0); d.fx = null; d.fy = null }))
 
-    // Cleanup
+    sceneRef.current = { paint }
     return () => {
-      simulation.stop()
+      sim.stop()
+      gsap.killTweensOf([...circle.nodes(), ...label.nodes(), ...link.nodes()])
+      svg.interrupt()
+      sceneRef.current = null
     }
-  }, [graphData, dimensions, activeTag, navigate, onTagClick, tagHref])
+  }, [graphData, dimensions, navigate, onTagClick, tagHref])
+
+  /* ── an active-tag change re-paints; it never rebuilds the layout ── */
+  useEffect(() => { sceneRef.current?.paint(null) }, [activeTag])
 
   if (graphData.nodes.length === 0) {
     return (
@@ -226,12 +246,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
 
   return (
     <div ref={containerRef} className="tag-graph-sidebar">
-      <svg
-        ref={svgRef}
-        width={dimensions.width}
-        height={dimensions.height}
-        className="tag-graph-svg"
-      />
+      <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'})