@kolkrabbi/kol-workshop 0.34.0 → 0.36.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.34.0",
+  "version": "0.36.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",
@@ -18,19 +18,20 @@
     "@kolkrabbi/kol-brand": "^0.1.3"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.231.0",
+    "@kolkrabbi/kol-component": ">=0.235.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
-    "@kolkrabbi/kol-theme": ">=0.155.0",
+    "@kolkrabbi/kol-theme": ">=0.162.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.31.0",
-    "@kolkrabbi/kol-component": "^0.231.0",
-    "@kolkrabbi/kol-theme": "^0.159.0",
-    "@kolkrabbi/kol-framework": "^0.48.0"
+    "@kolkrabbi/kol-component": "^0.235.0",
+    "@kolkrabbi/kol-theme": "^0.162.0",
+    "@kolkrabbi/kol-framework": "^0.48.0",
+    "@kolkrabbi/kol-icons": "^0.32.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

@@ -197,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) => [
@@ -316,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}
@@ -327,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 (
@@ -350,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/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/search/ResultRow.jsx

@@ -1,7 +1,7 @@
 import { Link } from 'react-router-dom'
 
 /**
- * ResultRow — one search result: a title, a meta line, an optional description, the whole row a
+ * 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"*).
  *
@@ -17,7 +17,9 @@ import { Link } from 'react-router-dom'
  * @param {'underline'|'wash'} [variant='underline']
  */
 const VARIANTS = {
-  underline: { row: 'group flex flex-col gap-1 py-3 opacity-80 hover:opacity-100 focus-visible:opacity-100', title: 'group-hover:underline underline-offset-4' },
+  /* 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: '' },
 }
 
@@ -26,8 +28,8 @@ export default function ResultRow({ to, title, meta, description, variant = 'und
   return (
     <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-subtle">{meta}</span>}
-      {description && <span className="kol-doc-body">{description}</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,12 +1,12 @@
-import { Fragment, useMemo } from 'react'
-import { useSearchParams } from 'react-router-dom'
-import { Button, EmptyState, Input, Pill } from '@kolkrabbi/kol-component'
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react'
+import { getTagColor } from '@kolkrabbi/kol-markdown'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import { EmptyState, Input, Tag } from '@kolkrabbi/kol-component'
 import ResultRow from './ResultRow.jsx'
 import { 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
@@ -19,8 +19,10 @@ import { DocHeader, DocSection } from '../docs/DocKit.jsx'
  *
  * @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' }
@@ -45,13 +47,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', 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)
@@ -60,84 +67,112 @@ 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 ?? []
 
+  /* 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}”.` : 'Everything in the site — components, docs, blocks, sets.'}
-      />
+    <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="lg"
+          size="md"
           aria-label="Search query"
           autoFocus
         />
-        {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>
-            {spaces.map((sp) => (
-              <Button key={sp.value} variant="ghost" size="sm" pressed={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>
-                {sp.label}
-              </Button>
-            ))}
+        {/* every chip on the page is THE Tag, one size (W11 — they were ghost Buttons and md Pills) */}
+        {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) => (
-              <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>
+        {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>
 
-      {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>
+      {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} />}
+                    meta={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
+                    description={r.item.description}
+                  />
+                </li>
               ))}
-            </div>
-          </DocSection>
-        )
-      })}
-
-      <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-subtle">{out.total - out.results.length} more — narrow the query.</p>}
-      </DocSection>
+            </ol>
+          )}
+          {out.total > out.results.length && <p className="kol-helper-12 text-meta">{out.total - out.results.length} more — narrow the query.</p>}
+        </section>
+      )}
     </div>
   )
 }

package/src/shell/RailSection.jsx

@@ -128,6 +128,7 @@ export default function RailSection({
      * one click from doing both. */
     <Link
       to={to}
+      className="truncate"
       onClick={(e) => {
         /* the label opens the page, the chevron folds (audit § Homes) */
         e.stopPropagation()
@@ -137,19 +138,20 @@ export default function RailSection({
       {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>
   )
 }