@kolkrabbi/kol-workshop 0.11.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.11.0",
+  "version": "0.19.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).",
   "license": "MIT",
@@ -14,10 +14,10 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-brand": "^0.1.2",
-    "@kolkrabbi/kol-component": "0.19.0",
-    "@kolkrabbi/kol-framework": "0.11.1",
-    "@kolkrabbi/kol-icons": "0.8.11",
-    "@kolkrabbi/kol-theme": "0.18.0"
+    "@kolkrabbi/kol-component": "0.26.1",
+    "@kolkrabbi/kol-icons": "0.10.0",
+    "@kolkrabbi/kol-framework": "0.14.0",
+    "@kolkrabbi/kol-theme": "0.31.2"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/compositions/WorkshopDefaultSidebar.jsx

@@ -25,7 +25,7 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
   const links = currentChild?.links
 
   return (
-    <div className="space-y-4">
+    <div className="shell-rail-stack-inner">
       {siblings.length > 1 && (
         <div>
           <div className="shell-sidebar-label kol-doc-eyebrow">{parentRoute.label}</div>

package/src/compositions/WorkshopSidebar.jsx

@@ -60,7 +60,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
   }
 
   return (
-    <div className="space-y-4">
+    <div className="shell-rail-stack-inner">
       {/* L1 from RailSection — the same rung and the same box as every other
         * rail header. No count: the eyebrow names the material, the groups
         * inside carry the tally (user ruling 2026-08-01). */}
@@ -72,7 +72,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
         onToggle={onToggle}
         onNavigate={onNavigate}
       >
-        <div className="space-y-4">
+        <div className="shell-rail-stack-inner">
         {Object.entries(groupedDocs)
           .sort(([a], [b]) => a.localeCompare(b))
           .map(([major, docs]) => {
@@ -87,7 +87,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
                   onToggle={() => toggleGroup(major)}
                   icon={Icon}
                 >
-                  <div className="shell-nav-items">
+                  <nav className="shell-nav-items">
                     {docs.map((d) => (
                       <RailRow
                         key={d.id}
@@ -99,7 +99,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
                         {cleanTitle(d.title, d.id)}
                       </RailRow>
                     ))}
-                  </div>
+                  </nav>
                 </RailSection>
               </div>
             )
@@ -134,7 +134,7 @@ const WorkshopSidebar = ({
   )
 
   return (
-    <div className="space-y-6">
+    <div className="shell-rail-stack">
       <ShellSidebar
         routes={workshopRoutes}
         basePath={basePath}

package/src/docs/DocsFrontmatter.jsx

@@ -1,3 +1,4 @@
+import { useLayoutEffect, useRef, useState } from 'react'
 import { Icon, Tag } from '@kolkrabbi/kol-component'
 import { useTagMode } from '../tags'
 import TagPath from '../tags/TagPath.jsx'
@@ -77,6 +78,19 @@ const FIELD_LABELS = {
   modified: 'Modified',
 }
 
+/* THE FALLBACK IS A LABEL TOO (user ruling 2026-08-01). `FIELD_LABELS[key] ??
+ * key` printed an unnamed key raw, so a doc carrying `imported_from` before it
+ * was listed rendered the row as `imported_from` — snake_case and lowercase, in
+ * a column where every neighbour is sentence case. *"its very amateur that you
+ * cant start a sentence or word with a Capital?"*
+ *
+ * Casing is authored at the data layer, never by CSS (the no-auto-text-transform
+ * law) — so the fallback authors it here, where the string is made. */
+const humanise = (key) => {
+  const words = String(key).replace(/[-_]+/g, ' ').trim()
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
 /* Reading ORDER, not an allowlist. The kol-docs contract first
  * (`.kol/docs-framework/01-conventions.md`: required title/type/status/updated/
  * tags, then recommended description/aliases, then optional), legacy
@@ -92,13 +106,33 @@ const FIELD_LABELS = {
  * `related` is the one deliberate omission — the rail renders it as live links,
  * so printing the raw wikilinks here would be the same thing twice. */
 const FIELD_ORDER = [
-  'title', 'type', 'status', 'updated', 'tags',
+  /* `created` sits ABOVE `updated` (user ruling 2026-08-01) — a document's age
+   * reads oldest-first, and `updated` on its own says nothing about how long
+   * the thing has existed. */
+  'title', 'type', 'status', 'created', 'updated', 'tags',
   'description', 'aliases', 'sources',
-  'created', 'verified', 'audience', 'superseded_by', 'drift',
+  'verified', 'audience', 'superseded_by', 'drift',
   'category', 'date', 'modified', 'version',
 ]
 
-const HIDDEN = new Set(['related'])
+/* `related` — the rail renders it as live links; printing the raw wikilinks
+ * here would be the same thing twice.
+ *
+ * `aliases` — user ruling 2026-08-01: *"why is this a category in frontmatter?
+ * what purpose … its just not relevant"*. It is an OBSIDIAN field, not a tag
+ * and not a document fact: `.kol/docs-framework/01-conventions.md:65` says it
+ * feeds the Quick Switcher and search autocomplete and explicitly does **not**
+ * affect wikilink resolution. Nothing in this app reads it. It stays in the
+ * file for Obsidian and stops taking a row in a panel that renders facts. */
+const HIDDEN = new Set(['related', 'aliases'])
+
+/* VALUES ARE SENTENCE CASE TOO (user ruling 2026-08-01). The labels were fixed
+ * and the values were not, so the panel read `Type  reference` / `Status
+ * active` — a capitalised label pointing at a lowercase word. These two fields
+ * carry closed enums from the kol-docs contract, so the case is authored here
+ * 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'])
 
 /** Contract order first, then anything else the doc carries, alphabetically. */
 const orderFields = (metadata) => {
@@ -124,15 +158,33 @@ const formatDate = (dateStr) => {
 
 const DocsFrontmatter = ({ metadata, docId }) => {
   const { openTagMode } = useTagMode()
-  if (!metadata || Object.keys(metadata).length === 0) return null
+  /* THE PANEL COLLAPSES, THE PAGE SCROLLS (user call 2026-08-09). A long
+   * frontmatter (Dropdown: classes + reuses + tokens) made the panel the
+   * page, and its per-field scrollboxes captured the wheel on the way down.
+   * The whole panel now caps behind a fade and expands in normal flow — the
+   * toggle renders only when the content actually overflows the cap. */
+  const bodyRef = useRef(null)
+  const [expanded, setExpanded] = useState(false)
+  const [overflowing, setOverflowing] = useState(false)
+
+  const fields = metadata ? orderFields(metadata) : []
 
-  const fields = orderFields(metadata)
+  useLayoutEffect(() => {
+    const el = bodyRef.current
+    if (el) setOverflowing(el.scrollHeight > el.clientHeight + 1)
+  }, [metadata, expanded])
 
   if (fields.length === 0) return null
 
+  const capped = !expanded
+
   return (
     <div className="docs-frontmatter">
       <p className="shell-sidebar-label kol-doc-eyebrow">Frontmatter</p>
+      <div
+        ref={bodyRef}
+        className={`docs-frontmatter-body${capped ? ' docs-frontmatter-body--capped' : ''}`}
+      >
       {fields.map((key) => {
         const value = metadata[key]
         const icon = FIELD_ICONS[key]
@@ -141,9 +193,9 @@ const DocsFrontmatter = ({ metadata, docId }) => {
           <div key={key} className="docs-frontmatter-row">
             <span className="docs-frontmatter-key kol-helper-12 text-meta">
               {icon && <Icon name={icon} size={14} />}
-              {FIELD_LABELS[key] ?? key}
+              {FIELD_LABELS[key] ?? humanise(key)}
             </span>
-            <span className="kol-mono-12 text-strong">
+            <span className="docs-frontmatter-value kol-mono-12 text-strong">
               {key === 'tags' && Array.isArray(value) ? (
                 /* `naked`, the SAME Tag rendering the rail's own tag list uses
                  * (DocReaderSidebar). This was the default filled variant, so
@@ -168,8 +220,31 @@ const DocsFrontmatter = ({ metadata, docId }) => {
                 </span>
               ) : DATE_FIELDS.has(key) ? (
                 formatDate(String(value))
+              ) : CASED_VALUE_FIELDS.has(key) ? (
+                humanise(String(value))
               ) : Array.isArray(value) ? (
-                value.join(' · ')
+                /* STACKED, ONE PER LINE (user ruling 2026-08-01). Arrays were
+                 * `value.join(' · ')` — a single run-on string, so `sources`
+                 * with three file paths ran straight off the right edge of the
+                 * panel and the reader could not tell where one path ended and
+                 * the next began. A list of paths IS a list; the dot-join was
+                 * printing it as a sentence.
+                 *
+                 * `break-all` because these are paths, not words: a wrapped
+                 * path must break at the character, never leave a gap and drop
+                 * the whole segment to the next line.
+                 *
+                 * THE LIST SCROLLS PAST ITS CAP (user question 2026-08-01:
+                 * "I just wonder what it will be when the sources are f.e. more
+                 * then 15?"). Unbounded, fifteen paths push the article fifteen
+                 * lines down and the metadata panel becomes the page. No
+                 * file-type icons — a path already ends in its own extension,
+                 * and a glyph restating it is decoration. */
+                <span className="docs-frontmatter-list">
+                  {value.map((item, i) => (
+                    <span key={i} className="break-all">{String(item)}</span>
+                  ))}
+                </span>
               ) : (
                 String(value)
               )}
@@ -177,6 +252,18 @@ const DocsFrontmatter = ({ metadata, docId }) => {
           </div>
         )
       })}
+        {capped && overflowing && <div className="docs-frontmatter-fade" aria-hidden="true" />}
+      </div>
+      {(overflowing || expanded) && (
+        <button
+          type="button"
+          className="docs-frontmatter-toggle kol-helper-12 text-meta"
+          onClick={() => setExpanded((v) => !v)}
+        >
+          <Icon name={expanded ? 'chevron-up' : 'chevron-down'} size={14} />
+          {expanded ? 'Collapse' : 'Expand'}
+        </button>
+      )}
     </div>
   )
 }

package/src/docs/DocumentationReader.jsx

@@ -1,139 +1,52 @@
 import { useContext, useEffect, useMemo, useState } from 'react'
 import { useParams, Link, useNavigate } from 'react-router-dom'
-import { CodeBlock, Divider, DocsToc, Icon, Table, Tag } from '@kolkrabbi/kol-component'
-import { ShellTocContext, RailSection, RailRow } from '../shell'
+import { CodeBlock, Divider, Icon, Table, useScrollSpy } from '@kolkrabbi/kol-component'
+import { ShellTocContext, RightRail } from '../shell'
 import { useTagMode } from '../tags'
+import TagPath from '../tags/TagPath.jsx'
 import { parseDocsMarkdown, isIndexFile } from '../engine'
+import { buildTagCounts } from '../engine/tags.js'
+import { fileLabel } from '../engine/doc-helpers.js'
 import DocsHeader from './DocsHeader.jsx'
 import DocsArticle from './DocsArticle.jsx'
 import DocsFrontmatter from './DocsFrontmatter.jsx'
 import { DocSection } from './DocKit.jsx'
 import { renderInlineTokens } from './render-tokens.jsx'
 
-/**
- * A rail section header. Same anatomy as the LEFT tree's group header — a
- * rotating chevron, the label, and the item count pushed right — because the
- * two rails are one system and a reader shouldn't have to learn each side
- * separately.
- *
- * These were bare text with no count and no hover. They carry both now, and
- * the whole row is the toggle — with no chevron drawn at L1 (user ruling
- * 2026-08-01): the section collapses and expands, the affordance just isn't an
- * icon.
- *
- * It is a thin wrapper over RailSection, which owns the rung: the class, the
- * box, and WHERE THE COUNT SITS. This header used to hand-write all three and
- * borrowed `.shell-nav-group-header` + `.shell-sidebar-label` to do it, which
- * is how the two rails ended up printing their counts on different rows.
- */
-const SidebarSection = ({ sectionKey, label, count, collapsedSections, toggleSection, children }) => (
-  <RailSection
-    level={2}
-    label={label}
-    count={count > 0 ? count : undefined}
-    collapsed={!!collapsedSections[sectionKey]}
-    onToggle={() => toggleSection(sectionKey)}
-    icon={Icon}
-  >
-    {children}
-  </RailSection>
-)
-
-const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, componentsHref, docFilePath }) => {
+/* THE RIGHT RAIL IS ONE COMPONENT (user ruling 2026-08-01). This file used to
+ * carry its own — `DocReaderSidebar`, with its own section set, its own collapse
+ * state and its own JSX — while the showcase's ShellChrome carried a second one.
+ * They disagreed about which sections exist, so sections appeared and vanished,
+ * and `SidebarSection` here was a third spelling of a rung `RailSection` already
+ * owned. All of it is `RightRail` now; this is an adapter that hands it data. */
+const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, componentsHref, docFilePath, topTags = [] }) => {
   const navigate = useNavigate()
   const { openTagMode } = useTagMode()
-  const [collapsedSections, setCollapsedSections] = useState({})
-  const toggleSection = (key) => setCollapsedSections(prev => ({ ...prev, [key]: !prev[key] }))
-
-  return (
-    /* THE SAME LADDER AS THE LEFT RAIL (user ruling 2026-08-01). One L1 eyebrow
-     * naming the body, then L2 groups that collapse and carry a chevron + a
-     * count. These four sections used to be four bare L1 eyebrows stacked with
-     * no parent and no chevron — the left rail's shape stated differently on
-     * the other side of the page. */
-    <RailSection level={1} label="This page">
-      <div className="space-y-6">
-      <SidebarSection
-        sectionKey="toc"
-        label="Contents"
-        count={toc?.length}
-        collapsedSections={collapsedSections}
-        toggleSection={toggleSection}
-      >
-        <DocsToc toc={toc} root="#main" />
-      </SidebarSection>
+  /* `#main` is the scroll container — the shell is `fixed inset-0` with its own
+   * scroll regions, so a viewport-rooted observer never fires. Same call the
+   * other rail makes; the rail is handed the answer, never a second observer. */
+  const activeId = useScrollSpy((toc ?? []).map((h) => h.id), { root: '#main' })
 
-      {related.length > 0 && (
-        <SidebarSection
-          sectionKey="related"
-          label="Related"
-          count={related.length}
-          collapsedSections={collapsedSections}
-          toggleSection={toggleSection}
-        >
-          {/* ONE rail voice (user law): rows = the shell-nav-item idiom. */}
-          <nav className="flex flex-col">
-            {related.map((r) => (
-              <RailRow key={r.id} to={r.href}>{r.label}</RailRow>
-            ))}
-          </nav>
-        </SidebarSection>
-      )}
+  const actions = [
+    { id: 'back', label: 'Back', icon: <Icon name="arrow-left" size={14} />, onClick: () => navigate(-1) },
+    { id: 'docs', label: 'All documentation', icon: <Icon name="book-open" size={14} />, to: docsIndexHref },
+    { id: 'components', label: 'View components', icon: <Icon name="grid" size={14} />, to: componentsHref },
+    { id: 'copy', label: 'Copy path', icon: <Icon name="copy" size={14} />, onClick: () => navigator.clipboard.writeText(docFilePath(docId)) },
+    { id: 'graph', label: 'Graph view', icon: <Icon name="polygon" size={14} />, onClick: () => openTagMode(null, { view: 'graph' }) },
+  ]
 
-      <SidebarSection
-        sectionKey="actions"
-        label="Quick actions"
-        collapsedSections={collapsedSections}
-        toggleSection={toggleSection}
-      >
-        {/* Quick actions wear the SAME row as On-this-page and Related. They
-          * were `.shell-sidebar-action`, a third geometry with no left indent,
-          * so this rail carried three different row idioms — under the
-          * "ONE rail voice" comment above. */}
-        <div>
-          <RailRow onClick={() => navigate(-1)} icon={<Icon name="arrow-left" size={14} />}>Back</RailRow>
-          <RailRow to={docsIndexHref} icon={<Icon name="book-open" size={14} />}>All documentation</RailRow>
-          <RailRow to={componentsHref} icon={<Icon name="grid" size={14} />}>View components</RailRow>
-          <RailRow onClick={() => navigator.clipboard.writeText(docFilePath(docId))} icon={<Icon name="copy" size={14} />}>Copy path</RailRow>
-          <RailRow onClick={() => openTagMode(null, { view: 'graph' })} icon={<Icon name="polygon" size={14} />}>Graph view</RailRow>
-        </div>
-      </SidebarSection>
-
-      {/* TAGS IS A CATEGORY (user ruling 2026-08-01) — not a bare tag dump.
-        * It holds the two ENTRY POINTS into the tag system plus this page's
-        * own tags. The graph view was reachable only through an unlabelled hex
-        * glyph floating at the corner of the overlay: a feature nobody could
-        * find unless they already knew it existed. Both entries are rail rows
-        * now, in the one row idiom. */}
-      <SidebarSection
-        sectionKey="tags"
-        count={allTags?.length}
-        label="Tags"
-        collapsedSections={collapsedSections}
-        toggleSection={toggleSection}
-      >
-        {/* NO Search row (user ruling 2026-08-01) — the nav search icon already
-          * opens the one modal, and a second door to it is the duplication we
-          * just spent an arc deleting. Graph view moved to Quick actions: it
-          * is an ACTION on the tag system, not one of this page's tags. */}
-        {allTags.length > 0 && (
-          /* No `color`, no `size` — see DocsFrontmatter. `sm` is the default
-           * and the only size; a colour would cost the hover state. */
-          <div className="flex flex-wrap gap-1.5 items-start min-w-0 w-full mt-2">
-            {allTags.map((tag) => (
-              <Tag
-                key={tag}
-                onClick={() => openTagMode(tag)}
-                className="max-w-full overflow-hidden text-ellipsis"
-              >
-                {tag}
-              </Tag>
-            ))}
-          </div>
-        )}
-      </SidebarSection>
-      </div>
-    </RailSection>
+  return (
+    <RightRail
+      toc={toc}
+      activeId={activeId}
+      related={related}
+      actions={actions}
+      topTags={topTags}
+      tags={allTags}
+      renderTag={(tag) => <TagPath tag={tag} />}
+      onTagClick={(tag) => openTagMode(tag)}
+      icon={Icon}
+    />
   )
 }
 
@@ -331,6 +244,11 @@ const DocumentationReader = ({
   }, [rawMarkdown])
 
   // Combine frontmatter tags with inline hashtags
+  /* THE SAME Top tags THE OTHER RAIL SHOWS (user ruling 2026-08-01). The rail
+   * is standardised, so this section cannot exist on one route and not another;
+   * the inventory is already a prop here, so there is nothing to fetch. */
+  const topTags = useMemo(() => buildTagCounts(inventory).slice(0, 12), [inventory])
+
   const allTags = useMemo(() => {
     const frontmatterTags = doc?.metadata?.tags || []
     return [...new Set([...frontmatterTags, ...inlineTags])]
@@ -366,7 +284,15 @@ const DocumentationReader = ({
           inventory.find((d) => d.file.replace(/\.md$/, '') === full) ??
           inventory.find((d) => d.file.replace(/\.md$/, '').toLowerCase() === `${full}/index`.toLowerCase()) ??
           inventory.find((d) => d.id === basename)
-        return hit ? { id: hit.id, href: docHref(hit.id), label: display } : null
+        /* `fileLabel`, THE rail-label rule — the same one the left tree uses
+         * (user rulings 2026-08-01). Three spellings have been tried on this
+         * row: the wikilink's display text (`[[02-color|color]]` → lowercase
+         * `color`), then the doc's frontmatter title (which carried a subtitle
+         * after an em dash, so the row read `Color — anchors and ramps` and
+         * truncated). A rail row is a NAME: one or two words, from the
+         * filename, identical to how the same doc appears in the left tree.
+         * The display text stays the fallback for an unresolvable target. */
+        return hit ? { id: hit.id, href: docHref(hit.id), label: fileLabel(hit.file) || display } : null
       })
       .filter(Boolean)
   }, [doc, inventory, docHref])
@@ -381,6 +307,7 @@ const DocumentationReader = ({
         key={docId}
         toc={toc}
         allTags={allTags}
+        topTags={topTags}
         related={related}
         docId={docId}
         docsIndexHref={docsIndex}
@@ -389,7 +316,7 @@ const DocumentationReader = ({
       />
     )
     return () => setTocContent(null)
-  }, [setTocContent, docId, toc, allTags, related, docsIndex, components, docFilePath])
+  }, [setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
 
   if (!doc) {
     return (

package/src/shell/RailSection.jsx

@@ -20,6 +20,11 @@ import { Link } from 'react-router-dom'
  *
  *   L1  section  `.shell-sidebar-toggle` + kol-doc-eyebrow    quiet, no chevron
  *   L2  group    `.shell-nav-group-header` + kol-mono-14      louder, chevron
+ *
+ * L2 carries NO colour class: `.shell-nav-group-header` owns weight 500 and
+ * `--kol-fg-shout` itself (user ruling 2026-08-01). It used to carry
+ * `text-body` — a utility that resolved to nothing at the time, and would now
+ * fight the rule for the same property. One owner.
  *   L3  row      `.shell-nav-item` + kol-mono-14              leaf, DocsToc/links
  *
  * THE RULES THIS COMPONENT ENFORCES BY CONSTRUCTION
@@ -71,13 +76,13 @@ export default function RailSection({
    * four call sites in two rails, spelled differently at each. */
   const headerClass = level === 1
     ? 'shell-sidebar-toggle kol-doc-eyebrow'
-    : 'shell-nav-group-header kol-mono-14 text-body'
+    : 'shell-nav-group-header kol-mono-14'
 
   /* A static header is not a button and must not claim to be one. It still
    * wears the same box — `.shell-sidebar-label` shares L1's rule. */
   const staticClass = level === 1
     ? 'shell-sidebar-label kol-doc-eyebrow'
-    : 'shell-nav-group-header kol-mono-14 text-body'
+    : 'shell-nav-group-header kol-mono-14'
 
   /* L2 only. At L1 the caret is not drawn (user ruling) — the row is still the
    * toggle, so the affordance exists, it just isn't a glyph. */

package/src/shell/RightRail.jsx

@@ -0,0 +1,168 @@
+import { useState } from 'react'
+import RailSection from './RailSection.jsx'
+import RailRow from './RailRow.jsx'
+
+/**
+ * RightRail — THE right rail. One component, every route.
+ *
+ * WHY IT EXISTS (user ruling 2026-08-01). The rail was TWO components:
+ * `AutoToc` in the showcase's ShellChrome served every non-vault page, and
+ * `DocReaderSidebar` in DocumentationReader overrode it through
+ * ShellTocContext on a vault route. They disagreed about which sections exist —
+ * one had Top tags and no Related, the other had Related and tag chips and no
+ * Top tags — so sections appeared and vanished as you moved, and an edit to one
+ * rail was invisible in the other. That is the same two-systems fault the rail
+ * LADDER (RailSection) and the rail ROW (RailRow) were each built to end, one
+ * level further out.
+ *
+ * THE SECTION SET IS FIXED — *"these are not conditional, they should be
+ * STANDARDISED"*. Every section renders on every route. A section with nothing
+ * in it renders with `(0)` and an empty body; it does not disappear, because a
+ * rail whose shape depends on its content teaches the reader nothing.
+ *
+ *   THIS PAGE  ── Contents        the headings of the open document
+ *   LINKS      ── Quick actions   what you can do from here
+ *              ── Tags            THIS page's tags first and brighter, then
+ *                                 the rest of the system underneath
+ *              ── Related         other documents this one names, and its
+ *                                 sources
+ *
+ * `LINKS`, after one turn as `TOOLS` (2026-08-01). The left rail already has a
+ * `TOOLS` category — the routes the app serves — so the same word sat on the
+ * same rung in both rails meaning two unrelated things. The right rail's is the
+ * one that moved: its contents ARE destinations plus the actions that reach
+ * them, and the left rail's TOOLS is a fixed route list that cannot be renamed
+ * without lying about what it holds.
+ *
+ * ONE Tags section, not two. `Tags` and `Top tags` were separate groups saying
+ * the same word twice; a reader had to learn which was which. They are one list
+ * now, ordered: this page's own tags at the top carrying `emphasis` ink, the
+ * system's most-used underneath at the resting stop. Order and ink carry the
+ * distinction the two headings used to.
+ *
+ * THE DIV RULE — *"sometimes you group things sometimes not, there is no rule
+ * in the madness"*. There is one now, and it is applied without exception:
+ *
+ *   1. An L1 category ALWAYS wraps its groups in `.shell-rail-stack-inner`.
+ *   2. An L2 group ALWAYS wraps its rows in `nav.shell-nav-items`.
+ *   3. Nothing else wraps anything. No bare children at a rung, no conditional
+ *      wrapper, no `<div>` added because one section happened to need spacing.
+ *
+ * Spacing therefore comes from exactly two classes, both theme-owned, and a
+ * section cannot acquire its own geometry by accident.
+ *
+ * @param {Array}    toc          [{ id, label, sub }] — headings of the open doc
+ * @param {string}   [activeId]   the heading currently in view (the caller owns
+ *                                the scroll spy; both rails must agree on it)
+ * @param {Array}    related      [{ id, href, label }] — label is the target's
+ *                                own SHORT title, never a wikilink display text
+ * @param {Array}    actions      [{ id, label, icon, to?, onClick? }]
+ * @param {Array}    topTags      [{ tag, count }] — the way in, not a dump
+ * @param {Array}    tags         [string] — this page's own tags
+ * @param {Function} renderTag    (tag) => node — the chip renderer, injected so
+ *                                this package does not reach into kol-component
+ * @param {Function} onTagClick   (tag) => void
+ */
+export default function RightRail({
+  toc = [],
+  activeId,
+  related = [],
+  actions = [],
+  topTags = [],
+  tags = [],
+  renderTag,
+  onTagClick,
+  icon: IconComponent,
+}) {
+  /* One collapse map, not a useState per section — a section added later must
+   * not need a new hook at the top of this function. */
+  const [collapsed, setCollapsed] = useState({})
+  const toggle = (key) => setCollapsed((c) => ({ ...c, [key]: !c[key] }))
+
+  /* A tag shown as "this page's" must not repeat below as "the system's". */
+  const own = new Set(tags)
+  const otherTags = topTags.filter(({ tag }) => !own.has(tag))
+
+  /* Every group is described here rather than spelled out in JSX below, so a
+   * section cannot be present in one branch and missing in another — the exact
+   * defect that split the two rails. */
+  const group = (key, label, count, children) => (
+    <RailSection
+      level={2}
+      label={label}
+      count={count}
+      collapsed={!!collapsed[key]}
+      onToggle={() => toggle(key)}
+      icon={IconComponent}
+    >
+      <nav className="shell-nav-items">{children}</nav>
+    </RailSection>
+  )
+
+  return (
+    <div className="shell-rail-stack">
+      <RailSection level={1} label="This page">
+        <div className="shell-rail-stack-inner">
+          {group('toc', 'Contents', toc.length,
+            toc.map((h) => (
+              <RailRow key={h.id} href={`#${h.id}`} active={h.id === activeId} sub={h.sub}>
+                {h.label}
+              </RailRow>
+            ))
+          )}
+        </div>
+      </RailSection>
+
+      <RailSection level={1} label="Links">
+        <div className="shell-rail-stack-inner">
+          {group('actions', 'Quick actions', actions.length,
+            actions.map((a) => (
+              <RailRow key={a.id} to={a.to} onClick={a.onClick} icon={a.icon}>
+                {a.label}
+              </RailRow>
+            ))
+          )}
+
+          {/* ONE list, two ranks. This page's tags lead and carry `emphasis`;
+            * the system's most-used follow at the resting stop with their
+            * count. `otherTags` filters out anything already shown above, so a
+            * tag cannot appear twice in one list. */}
+          {group('tags', 'Tags', tags.length + otherTags.length, (
+            <>
+              {tags.map((tag) => (
+                <RailRow
+                  key={`own-${tag}`}
+                  onClick={() => onTagClick?.(tag)}
+                  icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
+                  className="shell-nav-item--own"
+                >
+                  {renderTag ? renderTag(tag) : tag}
+                </RailRow>
+              ))}
+              {otherTags.map(({ tag, count }) => (
+                <RailRow
+                  key={`top-${tag}`}
+                  onClick={() => onTagClick?.(tag)}
+                  icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
+                  trailing={count}
+                  className="shell-nav-item--muted"
+                >
+                  {renderTag ? renderTag(tag) : tag}
+                </RailRow>
+              ))}
+            </>
+          ))}
+
+          {/* 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. */}
+          {group('related', 'Related', related.length,
+            related.map((r) => (
+              <RailRow key={r.id} to={r.href} href={r.url}>{r.label}</RailRow>
+            ))
+          )}
+        </div>
+      </RailSection>
+    </div>
+  )
+}

package/src/shell/ShellLayout.jsx

@@ -1,8 +1,8 @@
 import { createContext, useState, useEffect, Suspense } from 'react'
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
-import { ShellHeader, HEADER_ICON } from '@kolkrabbi/kol-framework'
+import { ShellHeader } from '@kolkrabbi/kol-framework'
 import ShellSidebar from './ShellSidebar.jsx'
-import { Button, ShellDrawer, ShellSearchOverlay, Tooltip } from '@kolkrabbi/kol-component'
+import { Button, IconFrame, ShellDrawer, ShellSearchOverlay, Tooltip } from '@kolkrabbi/kol-component'
 import { matchSearchItems } from '../engine/search.js'
 import { useTagMode } from '../tags/TagModeContext.jsx'
 import TagModeOverlay from '../tags/TagModeOverlay.jsx'
@@ -222,7 +222,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
     <>
       {actions}
       <Tooltip label="Search">
-        <Button variant="ghost" quiet iconOnly="search" iconSize={HEADER_ICON} onClick={() => setIsSearchOpen(true)} aria-label="Search" />
+        {/* IconFrame at the `lg` rung (user ruling 2026-08-01). Two faults in
+          * one call: it was a Button, and at the default `md` rung it drew the
+          * solo-lg glyph inside an `md` square while every neighbour sat on
+          * `lg`. `quiet` is gone too — on ghost it rested at oq-48 × 0.5, which
+          * made search the faintest thing in a row of oq-64 controls. */}
+        <IconFrame name="search" variant="nav" size="lg" onClick={() => setIsSearchOpen(true)} aria-label="Search" />
       </Tooltip>
     </>
   )

package/src/shell/ShellSidebar.jsx

@@ -69,7 +69,11 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
    * on the groups inside it (user ruling 2026-08-01). RailSection refuses one
    * at this rung, so there is nothing to compute here. */
   return (
-    <div className="space-y-4">
+    /* 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}
@@ -78,7 +82,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
         onToggle={handleToggle}
         onNavigate={onNavigate}
       >
-        <div className="space-y-4">
+        <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
@@ -93,14 +97,20 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
                   level={2}
                   label={route.label}
                   count={hasChildren ? route.children.length : undefined}
-                  to={hasChildren ? undefined : getSectionRootPath(route, basePath)}
+                  /* 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}
                 >
-                  <div className="shell-nav-items">
+                  <nav className="shell-nav-items">
                     {(route.children ?? []).map((child) => (
                       <RailRow
                         key={child.id}
@@ -110,7 +120,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
                         {child.label}
                       </RailRow>
                     ))}
-                  </div>
+                  </nav>
                 </RailSection>
               </div>
             )

package/src/shell/index.js

@@ -16,3 +16,7 @@ export { default as RailSection } from './RailSection.jsx'
 /* RailRow — THE L3 rail row. The look lives in `.shell-nav-item`; this owns the
  * markup so nine hand-written utility stacks cannot come back. R4 asserts it. */
 export { default as RailRow } from './RailRow.jsx'
+/* RightRail — THE right rail, one component for every route. It replaced two
+ * that disagreed about which sections exist, which is why sections used to
+ * appear and vanish. The section set is fixed and unconditional. */
+export { default as RightRail } from './RightRail.jsx'

package/src/tags/TagPath.jsx

@@ -17,7 +17,10 @@ export default function TagPath({ tag }) {
   if (!parts.length) return leaf
   return (
     <>
-      <span className="text-fg-32">{parts.join('/')}/</span>
+      {/* 64, not 32 (user ruling 2026-08-01). The namespace dims — it does not
+        * disappear. At 32 the prefix dropped so far under the leaf that a
+        * nested tag read as a one-word tag with dirt in front of it. */}
+      <span className="text-fg-64">{parts.join('/')}/</span>
       {leaf}
     </>
   )