@kolkrabbi/kol-workshop 0.5.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.5.1",
+  "version": "0.11.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-framework": "0.9.1",
-    "@kolkrabbi/kol-theme": "0.13.3",
-    "@kolkrabbi/kol-component": "0.14.3"
+    "@kolkrabbi/kol-theme": "0.18.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/compositions/WorkshopDefaultSidebar.jsx

@@ -1,5 +1,6 @@
 import { useLocation, Link } from 'react-router-dom'
 import { Icon } from '@kolkrabbi/kol-component'
+import { RailRow } from '../shell'
 
 /**
  * WorkshopDefaultSidebar — EXAMPLE composition. The contextual right rail:
@@ -28,17 +29,9 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
       {siblings.length > 1 && (
         <div>
           <div className="shell-sidebar-label kol-doc-eyebrow">{parentRoute.label}</div>
-          <nav className="space-y-0">
+          <nav className="shell-nav-items">
             {siblings.map(child => (
-              <Link
-                key={child.id}
-                to={`${basePath}/${child.path}`}
-                className={`shell-nav-item block kol-mono-14 ${
-                  location.pathname === `${basePath}/${child.path}` ? 'text-emphasis' : 'text-body'
-                }`}
-              >
-                {child.label}
-              </Link>
+              <RailRow key={child.id} to={`${basePath}/${child.path}`}>{child.label}</RailRow>
             ))}
           </nav>
         </div>
@@ -49,16 +42,10 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
           <div className="shell-sidebar-label kol-doc-eyebrow">Repository</div>
           <div>
             {links.live && (
-              <a href={links.live} target="_blank" rel="noopener noreferrer" className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
-                <Icon name="external-link" size={14} />
-                Live site
-              </a>
+              <RailRow href={links.live} icon={<Icon name="external-link" size={14} />}>Live site</RailRow>
             )}
             {links.repo && (
-              <a href={links.repo} target="_blank" rel="noopener noreferrer" className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
-                <Icon name="external-link" size={14} />
-                GitHub
-              </a>
+              <RailRow href={links.repo} icon={<Icon name="external-link" size={14} />}>GitHub</RailRow>
             )}
           </div>
         </div>
@@ -67,19 +54,8 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
       <div>
         <div className="shell-sidebar-label kol-doc-eyebrow">Quick actions</div>
         <div>
-          <Link to={basePath} className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
-            <Icon name="layout" size={14} />
-            Workshop home
-          </Link>
-          <button
-            type="button"
-            className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis"
-            onClick={() => navigator.clipboard.writeText(window.location.pathname)}
-            title="Copy page path to clipboard"
-          >
-            <Icon name="copy" size={14} />
-            Copy path
-          </button>
+          <RailRow to={basePath} icon={<Icon name="layout" size={14} />}>Workshop home</RailRow>
+          <RailRow onClick={() => navigator.clipboard.writeText(window.location.pathname)} icon={<Icon name="copy" size={14} />}>Copy path</RailRow>
         </div>
       </div>
     </div>

package/src/compositions/WorkshopSidebar.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import { Link, useLocation } from 'react-router-dom'
-import { ShellSidebar } from '../shell'
-import { Icon, Tooltip } from '@kolkrabbi/kol-component'
+import { ShellSidebar, RailSection, RailRow } from '../shell'
+import { Icon } from '@kolkrabbi/kol-component'
 import {
   extractDocNumber,
   cleanTitle,
@@ -61,76 +61,51 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
 
   return (
     <div className="space-y-4">
-      {/* kol-helper-10 types the wrapper box itself (was an untyped 16px box) */}
-      <div className="shell-sidebar-toggle shell-sidebar-label kol-doc-eyebrow" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
-        <Link to={docHref()} className="shell-sidebar-label kol-doc-eyebrow" onClick={(e) => {
-          if (collapsed && onToggle) onToggle()
-          if (onNavigate) onNavigate(e)
-        }}>
-          Documentation
-        </Link>
-        <Tooltip label={collapsed ? 'Expand Documentation' : 'Collapse Documentation'}>
-          <button
-            type="button"
-            onClick={onToggle}
-            aria-label={collapsed ? 'Expand Documentation' : 'Collapse Documentation'}
-            aria-expanded={!collapsed}
-            className="flex items-center justify-center"
-            style={{ height: '16.5px', marginBottom: '8px' }}
-          >
-            <Icon
-              name="chevron-down"
-              size={10}
-              className={`stroke-[2.5] transition-transform ${collapsed ? '' : 'rotate-180'}`}
-            />
-          </button>
-        </Tooltip>
-      </div>
-
-      {!collapsed && <div className="space-y-4">
+      {/* 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). */}
+      <RailSection
+        level={1}
+        label="Documentation"
+        to={docHref()}
+        collapsed={collapsed}
+        onToggle={onToggle}
+        onNavigate={onNavigate}
+      >
+        <div className="space-y-4">
         {Object.entries(groupedDocs)
           .sort(([a], [b]) => a.localeCompare(b))
           .map(([major, docs]) => {
             const isCollapsed = collapsedGroups[major]
             return (
               <div key={major} className="shell-nav-group">
-                <button
-                  type="button"
-                  className="shell-nav-group-header w-full text-left kol-mono-14 text-body"
-                  onClick={() => toggleGroup(major)}
+                <RailSection
+                  level={2}
+                  label={categoryLabels[major] || 'Other'}
+                  count={docs.length}
+                  collapsed={!!isCollapsed}
+                  onToggle={() => toggleGroup(major)}
+                  icon={Icon}
                 >
-                  <span className="flex items-center gap-2">
-                    <Icon
-                      name="chevron-right"
-                      size={12}
-                      className={`h-3 w-3 transition-transform ${isCollapsed ? '' : 'rotate-90'}`}
-                    />
-                    {categoryLabels[major] || 'Other'}
-                  </span>
-                  <span className="kol-mono-14 text-subtle">({docs.length})</span>
-                </button>
-                {!isCollapsed && (
                   <div className="shell-nav-items">
-                    {docs.map((d) => {
-                      const isActive = d.id === activeDocId
-                      return (
-                        <Link
-                          key={d.id}
-                          to={docHref(d.id)}
-                          className={`shell-nav-item shell-nav-item-doc kol-mono-14 ${isActive ? 'text-emphasis' : 'text-body'}`}
-                          onClick={onNavigate}
-                        >
-                          <span className="shell-nav-item-title">{cleanTitle(d.title, d.id)}</span>
-                          <span className="shell-nav-item-id kol-mono-14 text-subtle">{extractDocNumber(d.id)}</span>
-                        </Link>
-                      )
-                    })}
+                    {docs.map((d) => (
+                      <RailRow
+                        key={d.id}
+                        to={docHref(d.id)}
+                        active={d.id === activeDocId}
+                        trailing={extractDocNumber(d.id)}
+                        onNavigate={onNavigate}
+                      >
+                        {cleanTitle(d.title, d.id)}
+                      </RailRow>
+                    ))}
                   </div>
-                )}
+                </RailSection>
               </div>
             )
           })}
-      </div>}
+        </div>
+      </RailSection>
     </div>
   )
 }

package/src/docs/DocKit.jsx

@@ -11,6 +11,8 @@
  */
 
 import { Table } from '@kolkrabbi/kol-component'
+import { renderInlineTokens } from './render-tokens.jsx'
+import { processInlineMarkdown } from '../engine/parse-markdown.js'
 
 export function DocHeader({ eyebrow, title, lede, children }) {
   return (
@@ -38,11 +40,26 @@ export function DocSection({ id, title, lede, children }) {
  * classes through Table's per-column seams, doc chrome via the .kol-doc-table
  * class on Table's wrapper (the descendant rules out-specify Table's cell
  * defaults). Renders UNFRAMED (flush minimal — user ruling: no border). */
+/* CELLS PARSE INLINE MARKDOWN (user ruling 2026-08-01). `type` and `desc`
+ * carry backticked code — "`primary` is the grey fill" — and the cells printed
+ * the string raw, so every prop description showed its own backticks instead of
+ * a code chip. The vault's markdown got this right the whole time because it
+ * runs through `renderInlineTokens`; the props table simply never called it.
+ * `Table` has supported `column.render` all along (Table.jsx:35). Nothing new
+ * was written for this — two existing pieces that had never been introduced. */
+const inline = (v, key) =>
+  typeof v === 'string' && v
+    ? renderInlineTokens(processInlineMarkdown(v), key)
+    : v ?? '—'
+
 const PROPS_COLUMNS = [
-  { accessor: 'prop', header: 'Prop', className: 'kol-doc-table-value text-emphasis' },
-  { accessor: 'type', header: 'Type', className: 'kol-doc-table-value kol-doc-table-value--wrap text-meta' },
-  { accessor: 'def', header: 'Default', className: 'kol-doc-table-value text-meta' },
-  { accessor: 'desc', header: 'Description' },
+  { accessor: 'prop', header: 'Prop', sortable: true, className: 'kol-doc-table-value text-emphasis' },
+  /* type + default are TOKENS, so they wear the token chip (user ruling
+   * 2026-08-01) — .kol-table-token, the same chip the tables already use.
+   * They rendered as bare text while every neighbouring surface chipped them. */
+  { accessor: 'type', header: 'Type', className: 'kol-doc-table-value kol-doc-table-value--wrap text-meta', render: (r) => (r.type ? <code className="kol-table-token">{r.type}</code> : '—') },
+  { accessor: 'def', header: 'Default', className: 'kol-doc-table-value text-meta', render: (r) => (r.def ? <code className="kol-table-token">{r.def}</code> : '—') },
+  { accessor: 'desc', header: 'Description', render: (r) => inline(r.desc, `${r.prop}-desc`) },
 ]
 
 export function DocTable({ rows }) {

package/src/docs/DocsFrontmatter.jsx

@@ -1,24 +1,80 @@
 import { Icon, Tag } from '@kolkrabbi/kol-component'
-import { getTagColor } from '../engine'
 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. */
 const FIELD_ICONS = {
   file: 'file',
-  title: null,
-  type: 'folder',
+  title: 'type',
+  type: 'library',
   status: 'check',
-  updated: null,
-  created: null,
-  verified: null,
-  description: null,
-  audience: null,
-  aliases: null,
+  updated: 'refresh',
+  created: 'plus',
+  verified: 'shield-check',
+  description: 'message',
+  audience: 'user',
+  aliases: 'repeat',
+  sources: 'code',
+  superseded_by: 'arrow-right',
+  drift: 'alert-triangle',
   version: 'hash-01',
+  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. */
+  id: 'hash-01',
+  reuses: 'repeat',
+  slug: 'external-link',
+  /* provenance — folded in from the retired MetaRows panel 2026-08-01 */
+  source: 'code',
+  imported_from: 'arrow-right',
+  type_styles: 'type',
+  classes: 'library',
+  tokens: 'hash-01',
+  composes: 'component-01',
+  in_sets: 'grid',
+  used_in: 'layers',
   /* legacy dialect (workshop-sample docs) — kept so those still render */
-  date: null,
+  date: 'journal',
   category: 'folder',
-  tags: null,
-  modified: null,
+  modified: 'edit',
+}
+
+/* AUTHORED labels, not the raw key (user ruling 2026-08-01). The row printed
+ * `{key}` straight from the frontmatter, so the column read lowercase and
+ * snake_cased. KOL forbids `text-transform` on a component — casing is a
+ * content decision — so the strings are written here in the case they render.
+ * A key with no entry falls back to its own name rather than vanishing. */
+const FIELD_LABELS = {
+  file: 'File',
+  title: 'Title',
+  type: 'Type',
+  status: 'Status',
+  updated: 'Updated',
+  created: 'Created',
+  verified: 'Verified',
+  description: 'Description',
+  audience: 'Audience',
+  aliases: 'Aliases',
+  sources: 'Sources',
+  superseded_by: 'Superseded by',
+  drift: 'Drift',
+  version: 'Version',
+  tags: 'Tags',
+  source: 'Source',
+  imported_from: 'Imported from',
+  type_styles: 'Type styles',
+  classes: 'Classes',
+  tokens: 'Tokens',
+  composes: 'Composes',
+  in_sets: 'In sets',
+  used_in: 'Used in',
+  date: 'Date',
+  category: 'Category',
+  modified: 'Modified',
 }
 
 /* Reading ORDER, not an allowlist. The kol-docs contract first
@@ -37,7 +93,7 @@ const FIELD_ICONS = {
  * so printing the raw wikilinks here would be the same thing twice. */
 const FIELD_ORDER = [
   'title', 'type', 'status', 'updated', 'tags',
-  'description', 'aliases',
+  'description', 'aliases', 'sources',
   'created', 'verified', 'audience', 'superseded_by', 'drift',
   'category', 'date', 'modified', 'version',
 ]
@@ -85,19 +141,28 @@ 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} />}
-              {key}
+              {FIELD_LABELS[key] ?? key}
             </span>
             <span className="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
+                 * the one concept rendered as a solid pill here and as plain
+                 * coloured text six inches to the right.
+                 *
+                 * NO `color` (user ruling 2026-08-01): passing one swaps the
+                 * base class from `tag-control` to `tag tag--{color}`, and
+                 * only `tag-control` has a `:hover` rule — so a coloured Tag
+                 * silently loses its interaction state. Right component first;
+                 * colour is its own decision, later.
+                 * `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}
-                      size="sm"
-                      color={getTagColor(tag)}
-                      onClick={() => openTagMode(tag)}
-                    >
-                      {tag}
+                    <Tag key={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. */}
+                      <TagPath tag={tag} />
                     </Tag>
                   ))}
                 </span>

package/src/docs/DocumentationReader.jsx

@@ -1,9 +1,9 @@
 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 } from '../shell'
+import { ShellTocContext, RailSection, RailRow } from '../shell'
 import { useTagMode } from '../tags'
-import { parseDocsMarkdown, isIndexFile, getTagColor } from '../engine'
+import { parseDocsMarkdown, isIndexFile } from '../engine'
 import DocsHeader from './DocsHeader.jsx'
 import DocsArticle from './DocsArticle.jsx'
 import DocsFrontmatter from './DocsFrontmatter.jsx'
@@ -16,35 +16,28 @@ import { renderInlineTokens } from './render-tokens.jsx'
  * two rails are one system and a reader shouldn't have to learn each side
  * separately.
  *
- * These were bare text. They collapsed on click with no chevron, no count and
- * no hover, so the only way to discover they were interactive was to click
- * something that looked inert and watch the panel vanish. An affordance that
- * only announces itself after you've used it isn't one.
+ * 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 }) => {
-  const isOpen = !collapsedSections[sectionKey]
-  return (
-    <div>
-      <button
-        type="button"
-        className="shell-nav-group-header w-full text-left shell-sidebar-label kol-doc-eyebrow"
-        onClick={() => toggleSection(sectionKey)}
-        aria-expanded={isOpen}
-      >
-        <span className="flex items-center gap-2">
-          <Icon
-            name="chevron-right"
-            size={12}
-            className={`transition-transform ${isOpen ? 'rotate-90' : ''}`}
-          />
-          {label}
-        </span>
-        {count > 0 && <span className="kol-mono-14 text-subtle">({count})</span>}
-      </button>
-      {isOpen && children}
-    </div>
-  )
-}
+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 }) => {
   const navigate = useNavigate()
@@ -53,15 +46,21 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
   const toggleSection = (key) => setCollapsedSections(prev => ({ ...prev, [key]: !prev[key] }))
 
   return (
-    <div className="space-y-6">
+    /* 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="On this page"
+        label="Contents"
         count={toc?.length}
         collapsedSections={collapsedSections}
         toggleSection={toggleSection}
       >
-        <DocsToc toc={toc} />
+        <DocsToc toc={toc} root="#main" />
       </SidebarSection>
 
       {related.length > 0 && (
@@ -75,9 +74,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
           {/* ONE rail voice (user law): rows = the shell-nav-item idiom. */}
           <nav className="flex flex-col">
             {related.map((r) => (
-              <Link key={r.id} to={r.href} className="shell-nav-item block kol-mono-14 text-body transition-colors hover:text-emphasis">
-                {r.label}
-              </Link>
+              <RailRow key={r.id} to={r.href}>{r.label}</RailRow>
             ))}
           </nav>
         </SidebarSection>
@@ -94,49 +91,38 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
           * so this rail carried three different row idioms — under the
           * "ONE rail voice" comment above. */}
         <div>
-          <button
-            type="button"
-            className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis"
-            onClick={() => navigate(-1)}
-          >
-            <Icon name="arrow-left" size={14} />
-            Back
-          </button>
-          <Link to={docsIndexHref} className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
-            <Icon name="book-open" size={14} />
-            All documentation
-          </Link>
-          <Link to={componentsHref} className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
-            <Icon name="grid" size={14} />
-            View components
-          </Link>
-          <button
-            type="button"
-            className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis"
-            onClick={() => navigator.clipboard.writeText(docFilePath(docId))}
-            title="Copy file path to clipboard"
-          >
-            <Icon name="copy" size={14} />
-            Copy path
-          </button>
+          <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>
 
-      {allTags.length > 0 && (
-        <SidebarSection
-          sectionKey="tags"
-          count={allTags?.length}
-          label="Tags"
-          collapsedSections={collapsedSections}
-          toggleSection={toggleSection}
-        >
-          <div className="flex flex-col gap-1.5 items-start min-w-0 w-full">
+      {/* 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}
-                variant="naked"
-                size="lg"
-                color={getTagColor(tag)}
                 onClick={() => openTagMode(tag)}
                 className="max-w-full overflow-hidden text-ellipsis"
               >
@@ -144,9 +130,10 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
               </Tag>
             ))}
           </div>
-        </SidebarSection>
-      )}
-    </div>
+        )}
+      </SidebarSection>
+      </div>
+    </RailSection>
   )
 }
 
@@ -406,9 +393,11 @@ const DocumentationReader = ({
 
   if (!doc) {
     return (
-      /* framed to a 1400px tier that was removed from the scale at theme
-       * 0.11.22 and left behind here — a width nothing else still uses */
-      <div className="mx-auto max-w-[var(--kol-content-panel)] py-16">
+      /* framed to a tier that was removed from the scale at theme 0.11.22 and
+       * left behind here — a width nothing else still uses; now on the panel
+       * token. Left-anchored, not centred (2026-08-01): the frame centres in
+       * the viewport, the content does not centre in the frame. */
+      <div className="max-w-[var(--kol-content-panel)] py-16">
         <DocsHeader title="Document Not Found" subtitle={`Could not find document: ${docId}`} />
         <p className="kol-mono-12 mt-6">
           <Link to={docsIndex} className="text-accent-primary">

package/src/engine/doc-helpers.js

@@ -9,6 +9,28 @@
 export const capitalise = (value) =>
   value ? value.charAt(0).toUpperCase() + value.slice(1) : value
 
+/**
+ * fileLabel — a rail row's name, taken from the FILENAME (user ruling
+ * 2026-08-01).
+ *
+ * The tree used to label rows from the doc's H1, so `01-tokens.md` (opening
+ * `# Foundations — the token system`) rendered as "Foundations" — a row whose
+ * name appears nowhere in the folder, and two files whose H1s both began
+ * "Foundations" collapsed into two identical rows. A tree that mirrors a
+ * folder has to read the folder: what Finder shows is what the sidebar shows.
+ *
+ *   01-tokens.md             → Tokens
+ *   04-layout-breakpoints.md → Layout breakpoints
+ *
+ * Titles still drive SEARCH and the page header; this is the tree label only.
+ */
+export const fileLabel = (file = '') => {
+  const base = file.split('/').pop()?.replace(/\.md$/i, '') ?? ''
+  const named = base.replace(/^\d+(\.\d+)*[-.]?\s*/, '')
+  if (!named) return capitalise(base)
+  return capitalise(named.replace(/[-_]+/g, ' ').trim())
+}
+
 // Index.md files (e.g. "00-metadata-index", "foundry-index") have no version dots
 export const isIndexFile = (id) => id.endsWith('-index') && !id.includes('.')
 
@@ -60,6 +82,15 @@ export const cleanTitle = (title, id) => {
 
   let cleaned = title.replace(/^\d+\.\d+\.\d+\s*/, '')
   cleaned = cleaned.replace(/^[A-Za-z\s]+:\s*/, '')
+  /* SUBTITLE OFF (user ruling 2026-08-01): "dont Foundtation - the token
+   * system, just 'foundation'". A doc's `title` is written for the document —
+   * "Type classes — the two families and when to use which" — and a rail row
+   * is not the place to read a sentence: three of eight rows wrapped to two
+   * and three lines. Everything from the em/en dash on is the subtitle, so the
+   * row keeps the name and drops the explanation. The DOC's own title is
+   * untouched; this is the rail's label only.
+   * Spaced dash only — an unspaced one is a compound word, not a separator. */
+  cleaned = cleaned.replace(/\s+[—–]\s+.*$/, '')
   cleaned = cleaned.trim() || title
 
   const versionMatch = id.match(/^(\d+\.\d+)\.(\d+)/)