From b15bf00783c24b00e9529f1158bcaf97056f1563 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= <carlosmflorencio@gmail.com>
Date: Sun, 23 Aug 2026 13:39:07 +0000
Subject: [PATCH] fix: shorten PR walkthrough links and align shell branding
 (#2954)

---
 .../skills/pr-walkthrough/references/build.py |  32 +++-
 .../pr-walkthrough/references/shell.html      | 161 +++++++++++++-----
 .../pr-walkthrough/references/test_build.py   |  90 +++++++++-
 .../pr-walkthrough-workflow-contract_test.py  |   7 +-
 .github/workflows/pr-walkthrough.yml          |   4 +-
 .../2026-08-22-pr-walkthrough-r2-hosting.md   |   6 +-
 .../2026-08-23-pr-walkthrough-short-urls.md   |  46 +++++
 docs/decisions/INDEX.md                       |   1 +
 .../plan.md                                   |   7 +-
 ...sk-04-public-url-and-shell-presentation.md |  43 +++++
 docs/plans/pr-walkthrough/plan.md             |   9 +-
 .../task-02-agent-rendering-contract.md       |   3 +-
 .../task-04-r2-html-publication.md            |   8 +-
 docs/specs/pr-walkthrough/spec.md             |  32 +++-
 scripts/pr-walkthrough-pr-body                |   6 +-
 scripts/pr-walkthrough-pr-body.test.py        |   5 +-
 16 files changed, 389 insertions(+), 71 deletions(-)
 create mode 100644 docs/decisions/2026-08-23-pr-walkthrough-short-urls.md
 create mode 100644 docs/plans/pr-walkthrough-portable-runner-fix/task-04-public-url-and-shell-presentation.md

diff --git a/.agents/skills/pr-walkthrough/references/build.py b/.agents/skills/pr-walkthrough/references/build.py
index 7c30680593..7509e47561 100644
--- a/.agents/skills/pr-walkthrough/references/build.py
+++ b/.agents/skills/pr-walkthrough/references/build.py
@@ -380,14 +380,44 @@ def render_groups(boxes):
     )
 
 
+def edge_lanes(edges):
+    """Assign stable slots for endpoints and repeated node pairs."""
+    outgoing, incoming, pairs = {}, {}, {}
+    for index, edge in enumerate(edges):
+        outgoing.setdefault(edge["from"], []).append(index)
+        incoming.setdefault(edge["to"], []).append(index)
+        pair = tuple(sorted((edge["from"], edge["to"])))
+        pairs.setdefault(pair, []).append(index)
+    lanes = []
+    for index, edge in enumerate(edges):
+        source_edges = outgoing[edge["from"]]
+        target_edges = incoming[edge["to"]]
+        pair_edges = pairs[tuple(sorted((edge["from"], edge["to"])))]
+        lanes.append({
+            "from_lane": source_edges.index(index),
+            "from_lanes": len(source_edges),
+            "to_lane": target_edges.index(index),
+            "to_lanes": len(target_edges),
+            "pair_lane": pair_edges.index(index),
+            "pair_lanes": len(pair_edges),
+        })
+    return lanes
+
+
 def render_edges(edges, ids):
     out = ""
     for e in edges:
         require(e.get("from") in ids, f'edge references unknown node "{e.get("from")}"')
         require(e.get("to") in ids, f'edge references unknown node "{e.get("to")}"')
+    for e, lane in zip(edges, edge_lanes(edges)):
+        lane_attrs = " ".join(
+            f'data-{name.replace("_", "-")}="{value}"'
+            for name, value in lane.items()
+        )
         out += (f'<div class="cedge" data-from="{esc_attr(e["from"])}" '
                 f'data-to="{esc_attr(e["to"])}" '
-                f'data-label="{esc_attr(e.get("label", ""))}"></div>')
+                f'data-label="{esc_attr(e.get("label", ""))}" '
+                f'{lane_attrs}></div>')
     return out
 
 
diff --git a/.agents/skills/pr-walkthrough/references/shell.html b/.agents/skills/pr-walkthrough/references/shell.html
index 2f6f41d03b..2e576cc0f7 100644
--- a/.agents/skills/pr-walkthrough/references/shell.html
+++ b/.agents/skills/pr-walkthrough/references/shell.html
@@ -11,14 +11,16 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <link rel="icon" href="https://kandev.ai/favicon.ico" sizes="32x32" />
+  <link rel="icon" href="https://kandev.ai/icon.svg" type="image/svg+xml" />
+  <link rel="apple-touch-icon" href="https://kandev.ai/apple-touch-icon.png" sizes="180x180" />
   <title>{{PR_TITLE}} - Walkthrough</title>
 
-  <!-- External resources (all pinned, loaded from CDN).
-       Tailwind loads here as a classic script. The four ESM libraries below
-       are declared in this import map so every external URL is visible at the
-       top. The module script near the end imports them by their bare name
-       (mermaid, marked, dompurify, shiki). To change a version, edit only the
-       URLs here. -->
+  <!-- External package resources use exact-version CDN URLs. Website brand
+       assets intentionally use live kandev.ai URLs so new pages match the
+       current site branding. Tailwind loads here as a classic script. The
+       four ESM libraries below are declared in this import map so every
+       package URL is visible at the top. -->
   <script src="https://cdn.tailwindcss.com/3.4.17"></script>
   <script type="importmap">
     {
@@ -35,15 +37,14 @@
     tailwind.config = {
       darkMode: 'class',
       theme: { extend: { maxWidth: { content: '72rem' }, colors: {
-        brand: { DEFAULT: '#4f46e5', soft: '#818cf8', deep: '#3730a3' },
+        brand: { DEFAULT: '#6366f1', soft: '#818cf8', deep: '#4f46e5' },
       } } },
     };
   </script>
   <style>
-    /* Visual language shared with kandev.ai landing: Figtree for UI copy,
-       Geist Mono for code, indigo actions, near-black product surfaces, and
-       compact shadcn-style radii. The font URLs are pinned to the landing
-       repository commit used for this design. */
+    /* Visual language shared with the documentation shell: Figtree for UI
+       copy, Geist Mono for code, indigo actions, dark-gray surfaces, and
+       compact shadcn-style radii. */
     @font-face {
       font-family: 'Figtree'; font-style: normal; font-weight: 300 900; font-display: swap;
       src: url('https://cdn.jsdelivr.net/gh/kdlbs/landing@71c3f609df07d6ff67fbe7c9213482d0c0c22c70/public/fonts/figtree/figtree-300-normal.woff2') format('woff2');
@@ -54,24 +55,25 @@
     }
     :root {
       color-scheme: light;
-      --wt-bg: #ffffff;
-      --wt-fg: #0d0d10;
-      --wt-muted: #71717a;
-      --wt-border: rgba(13, 13, 16, .12);
-      --wt-surface: #f7f7f8;
+      --wt-bg: #f5f5f5;
+      --wt-fg: #0a0a0a;
+      --wt-muted: #666666;
+      --wt-border: rgba(204, 204, 204, .5);
+      --wt-surface: #f1f1f1;
       --wt-primary: #4f46e5;
       --wt-primary-soft: #818cf8;
-      --wt-primary-deep: #3730a3;
-      --wt-dark-surface: #111114;
+      --wt-primary-deep: #4f46e5;
+      --wt-dark-surface: #1e1e1e;
       --wt-radius: .5rem;
     }
     html.dark {
       color-scheme: dark;
-      --wt-bg: #0d0d10;
-      --wt-fg: #fafafa;
-      --wt-muted: rgba(255, 255, 255, .58);
-      --wt-border: rgba(255, 255, 255, .10);
-      --wt-surface: #111114;
+      --wt-bg: #121212;
+      --wt-fg: #ebebeb;
+      --wt-muted: #b3b3b3;
+      --wt-border: rgba(102, 102, 102, .2);
+      --wt-surface: #191919;
+      --wt-primary: #6366f1;
     }
     html { scroll-behavior: smooth; }
     body {
@@ -80,11 +82,11 @@
       letter-spacing: -.01em;
     }
     .wt-topbar {
-      background: rgba(255, 255, 255, .88); border-color: var(--wt-border);
-      box-shadow: 0 1px 0 rgba(13, 13, 16, .02);
+      background: rgba(245, 245, 245, .95); border-color: var(--wt-border);
+      box-shadow: 0 1px 0 rgba(0, 0, 0, .02);
       backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px);
     }
-    html.dark .wt-topbar { background: rgba(13, 13, 16, .88); }
+    html.dark .wt-topbar { background: rgba(18, 18, 18, .95); }
     .wt-main { line-height: 1.7; }
     .wt-main h2, .wt-main h3 { letter-spacing: -.035em; }
     .wt-main h2 { font-weight: 650; }
@@ -98,10 +100,11 @@
     .wt-brand:hover { color: var(--wt-primary); }
     .wt-brand-mark {
       display: inline-flex; align-items: center; justify-content: center; width: 1.75rem; height: 1.75rem;
-      border-radius: .375rem; color: white; background: linear-gradient(135deg, #4f46e5, #818cf8);
-      box-shadow: 0 0 0 1px rgba(13, 13, 16, .08), 0 8px 18px rgba(79, 70, 229, .22);
-      font-size: .95rem; font-weight: 800; letter-spacing: -.08em;
+      overflow: hidden; border-radius: .375rem; background: var(--wt-surface);
+      box-shadow: 0 0 0 1px rgba(0, 0, 0, .08), 0 8px 18px rgba(99, 102, 241, .22);
     }
+    html.dark .wt-brand-mark { box-shadow: 0 0 0 1px rgba(255, 255, 255, .1), 0 8px 18px rgba(99, 102, 241, .22); }
+    .wt-brand-mark img { display: block; width: 100%; height: 100%; object-fit: cover; }
     .wt-brand-name { font-size: .875rem; font-weight: 650; }
     .wt-brand-divider { width: 1px; height: 1rem; background: var(--wt-border); }
     .wt-brand-pr { font-size: .8125rem; font-weight: 600; white-space: nowrap; }
@@ -118,6 +121,7 @@
       border: 1px solid var(--wt-border); border-radius: .5rem; background: var(--wt-bg);
       box-shadow: 0 12px 28px rgba(13, 13, 16, .14);
     }
+    html.dark .wt-mobile-menu { background: var(--wt-dark-surface); }
     .wt-mobile-menu a {
       display: block; min-height: 2.5rem; padding: .65rem .75rem; border-radius: .375rem; color: var(--wt-muted);
       font-size: .8125rem; font-weight: 550; text-decoration: none;
@@ -131,7 +135,14 @@
     /* Shiki dual-theme via defaultColor:false. Light by default, dark on html.dark. */
     .shiki, .shiki span { color: var(--shiki-light); background-color: var(--shiki-light-bg); }
     html.dark .shiki, html.dark .shiki span { color: var(--shiki-dark) !important; background-color: var(--shiki-dark-bg) !important; }
-    .shiki { padding: 14px 16px; border-radius: var(--wt-radius); overflow-x: auto; font-family: 'Geist Mono', ui-monospace, monospace; font-size: .82rem; line-height: 1.55; border: 1px solid var(--wt-border); }
+    .shiki { padding: 14px 16px; border-radius: var(--wt-radius); overflow-x: auto; font-family: 'Geist Mono', ui-monospace, monospace; font-size: .82rem; line-height: 1.55; border: 1px solid var(--wt-border); scrollbar-width: thin; scrollbar-color: transparent transparent; }
+    .shiki::-webkit-scrollbar { height: 6px; }
+    .shiki::-webkit-scrollbar-track { background: transparent; }
+    .shiki::-webkit-scrollbar-thumb { background: transparent; border-radius: 999px; }
+    .shiki:hover, .shiki:focus-within { scrollbar-color: rgba(100,116,139,.55) transparent; }
+    .shiki:hover::-webkit-scrollbar-thumb, .shiki:focus-within::-webkit-scrollbar-thumb { background: rgba(100,116,139,.55); }
+    html.dark .shiki:hover, html.dark .shiki:focus-within { scrollbar-color: rgba(148,163,184,.5) transparent; }
+    html.dark .shiki:hover::-webkit-scrollbar-thumb, html.dark .shiki:focus-within::-webkit-scrollbar-thumb { background: rgba(148,163,184,.5); }
     /* GitHub-style diff lines. applyLineDiff() tags changed lines with
        .diff.add / .diff.remove from the data-added / data-removed indices
        build.py emits. Each .line is a full-width block so the tint spans the
@@ -391,7 +402,9 @@
     <div class="mx-auto max-w-content px-4 sm:px-6 h-14 flex items-center justify-between gap-3">
       <a href="{{PR_URL}}" target="_blank" rel="noopener"
          class="wt-brand shrink-0" title="Open the pull request on GitHub">
-        <span class="wt-brand-mark" aria-hidden="true">k</span>
+        <span class="wt-brand-mark" aria-hidden="true">
+          <img src="https://kandev.ai/brand/kandev-github-org.png" alt="" />
+        </span>
         <span class="wt-brand-name hidden sm:inline">Kandev</span>
         <span class="wt-brand-divider hidden sm:inline" aria-hidden="true"></span>
         <span class="wt-brand-pr">PR #{{PR_NUMBER}}</span>
@@ -787,6 +800,25 @@
       const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
       const apply = () => { stage.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`; };
 
+      // Spread edges that share a node across that node's edge. The old
+      // midpoint route made every branch leave and enter at the same pixel,
+      // which stacked paths and labels on dense graphs.
+      function laneOffset(index, count, span, maxGap = 48) {
+        const total = Math.max(1, Number(count) || 1);
+        if (total === 1) return 0;
+        const slot = clamp(Number(index) || 0, 0, total - 1);
+        const gap = Math.min(maxGap, (span * .62) / (total - 1));
+        return (slot - (total - 1) / 2) * gap;
+      }
+
+      function cubicPoint(p0, p1, p2, p3, t) {
+        const u = 1 - t;
+        return {
+          x: u ** 3 * p0.x + 3 * u ** 2 * t * p1.x + 3 * u * t ** 2 * p2.x + t ** 3 * p3.x,
+          y: u ** 3 * p0.y + 3 * u ** 2 * t * p1.y + 3 * u * t ** 2 * p2.y + t ** 3 * p3.y,
+        };
+      }
+
       // Draw one arrow per .cedge, from the FROM node edge to the TO node edge.
       function drawEdges() {
         svg.innerHTML = '';
@@ -802,30 +834,69 @@
           const bcx = bx + bw / 2, bcy = by + bh / 2;
           // Anchor on the near vertical or horizontal edge of each node.
           const dx = bcx - acx, dy = bcy - acy;
+          const horizontal = Math.abs(dx) >= Math.abs(dy);
+          const fromLane = laneOffset(
+            e.dataset.fromLane, e.dataset.fromLanes, horizontal ? ah : aw,
+          );
+          const toLane = laneOffset(
+            e.dataset.toLane, e.dataset.toLanes, horizontal ? bh : bw,
+          );
+          // Reciprocal or parallel edges have the same endpoint geometry even
+          // when their source/target slots differ. Give the whole node pair a
+          // smaller parallel offset so those routes do not collapse into one.
+          const pairLane = laneOffset(
+            e.dataset.pairLane, e.dataset.pairLanes,
+            (horizontal ? Math.min(ah, bh) : Math.min(aw, bw)) * .6,
+          );
           let x1, y1, x2, y2;
-          if (Math.abs(dx) >= Math.abs(dy)) {
-            x1 = dx >= 0 ? ax + aw : ax; y1 = acy;
-            x2 = dx >= 0 ? bx : bx + bw; y2 = bcy;
+          if (horizontal) {
+            x1 = dx >= 0 ? ax + aw : ax; y1 = acy + fromLane + pairLane;
+            x2 = dx >= 0 ? bx : bx + bw; y2 = bcy + toLane + pairLane;
           } else {
-            x1 = acx; y1 = dy >= 0 ? ay + ah : ay;
-            x2 = bcx; y2 = dy >= 0 ? by : by + bh;
+            x1 = acx + fromLane + pairLane; y1 = dy >= 0 ? ay + ah : ay;
+            x2 = bcx + toLane + pairLane; y2 = dy >= 0 ? by : by + bh;
           }
-          const mx = (x1 + x2) / 2, my = (y1 + y2) / 2;
-          const c1x = Math.abs(dx) >= Math.abs(dy) ? mx : x1;
-          const c1y = Math.abs(dx) >= Math.abs(dy) ? y1 : my;
-          const c2x = Math.abs(dx) >= Math.abs(dy) ? mx : x2;
-          const c2y = Math.abs(dx) >= Math.abs(dy) ? y2 : my;
+          const direction = horizontal ? (dx >= 0 ? 1 : -1) : (dy >= 0 ? 1 : -1);
+          const curve = Math.max(52, (horizontal ? Math.abs(x2 - x1) : Math.abs(y2 - y1)) * .42);
+          const p0 = { x: x1, y: y1 };
+          const p1 = horizontal
+            ? { x: x1 + direction * curve, y: y1 }
+            : { x: x1, y: y1 + direction * curve };
+          const p2 = horizontal
+            ? { x: x2 - direction * curve, y: y2 }
+            : { x: x2, y: y2 - direction * curve };
+          const p3 = { x: x2, y: y2 };
           const path = document.createElementNS(SVGNS, 'path');
-          path.setAttribute('d', `M ${x1} ${y1} C ${c1x} ${c1y}, ${c2x} ${c2y}, ${x2} ${y2}`);
+          path.setAttribute('d', `M ${p0.x} ${p0.y} C ${p1.x} ${p1.y}, ${p2.x} ${p2.y}, ${p3.x} ${p3.y}`);
           path.setAttribute('class', 'cedge-path');
           path.setAttribute('marker-end', 'url(#arrow)');
           svg.appendChild(path);
           if (e.dataset.label) {
+            const labelPoint = cubicPoint(p0, p1, p2, p3, .5);
+            const labelSpan = horizontal ? Math.min(ah, bh) : Math.min(aw, bw);
+            const labelFromLane = laneOffset(
+              e.dataset.fromLane, e.dataset.fromLanes, labelSpan, 192,
+            );
+            const labelToLane = laneOffset(
+              e.dataset.toLane, e.dataset.toLanes, labelSpan, 192,
+            );
+            // Prefer the endpoint with the stronger fan-out. This keeps labels
+            // apart when two different routes happen to share a midpoint.
+            const endpointLabelLane = Math.abs(labelToLane) >= Math.abs(labelFromLane)
+              ? labelToLane : labelFromLane;
+            const pairLabelLane = laneOffset(
+              e.dataset.pairLane, e.dataset.pairLanes,
+              labelSpan * .6, 96,
+            );
+            const labelLane = Number(e.dataset.pairLanes) > 1
+              ? pairLabelLane : endpointLabelLane;
+            if (horizontal) labelPoint.y += labelLane;
+            else labelPoint.x += labelLane;
             const lab = document.createElement('div');
             lab.className = 'cedge-label';
             lab.textContent = e.dataset.label;
-            lab.style.left = mx + 'px';
-            lab.style.top = my + 'px';
+            lab.style.left = labelPoint.x + 'px';
+            lab.style.top = labelPoint.y + 'px';
             stage.appendChild(lab);
           }
         }
@@ -1027,7 +1098,7 @@
 
       // Lay out after Shiki settles node heights, then fit.
       shikiReady.finally(() => { requestAnimationFrame(() => { sizeGroups(); drawEdges(); fit(); }); });
-      window.addEventListener('resize', () => { sizeGroups(); drawEdges(); });
+      window.addEventListener('resize', () => { sizeGroups(); drawEdges(); fit(); });
     })();
   </script>
 </body>
diff --git a/.agents/skills/pr-walkthrough/references/test_build.py b/.agents/skills/pr-walkthrough/references/test_build.py
index f5eb77a67d..c341811072 100644
--- a/.agents/skills/pr-walkthrough/references/test_build.py
+++ b/.agents/skills/pr-walkthrough/references/test_build.py
@@ -333,6 +333,54 @@ class TestRenderEdges(unittest.TestCase):
         self.assertIn('data-from="n1"', html)
         self.assertIn('data-label="calls"', html)
 
+    def test_shared_endpoints_receive_distinct_route_lanes(self):
+        html = build.render_edges(
+            [
+                {"from": "n1", "to": "n2", "label": "first"},
+                {"from": "n1", "to": "n3", "label": "second"},
+                {"from": "n2", "to": "n4", "label": "third"},
+                {"from": "n3", "to": "n4", "label": "fourth"},
+            ],
+            {"n1", "n2", "n3", "n4"},
+        )
+        self.assertIn(
+            'data-from-lane="0" data-from-lanes="2" '
+            'data-to-lane="0" data-to-lanes="1"',
+            html,
+        )
+        self.assertIn(
+            'data-from-lane="1" data-from-lanes="2" '
+            'data-to-lane="0" data-to-lanes="1"',
+            html,
+        )
+        self.assertIn(
+            'data-from-lane="0" data-from-lanes="1" '
+            'data-to-lane="0" data-to-lanes="2"',
+            html,
+        )
+        self.assertIn(
+            'data-from-lane="0" data-from-lanes="1" '
+            'data-to-lane="1" data-to-lanes="2"',
+            html,
+        )
+
+    def test_reciprocal_edges_receive_distinct_pair_lanes(self):
+        html = build.render_edges(
+            [
+                {"from": "n1", "to": "n2", "label": "forward"},
+                {"from": "n2", "to": "n1", "label": "backward"},
+            ],
+            {"n1", "n2"},
+        )
+        self.assertIn(
+            'data-pair-lane="0" data-pair-lanes="2"',
+            html,
+        )
+        self.assertIn(
+            'data-pair-lane="1" data-pair-lanes="2"',
+            html,
+        )
+
     def test_unknown_from_node_fails(self):
         with self.assertRaises(build.BuildError):
             build.render_edges([{"from": "nX", "to": "n1"}], {"n1"})
@@ -417,14 +465,28 @@ class TestBuild(unittest.TestCase):
             '<h3 class="font-semibold text-brand-soft mb-1">'
             'UniqueChangeTitle</h3>', out)
 
-    def test_shell_matches_kandev_landing_visual_language(self):
+    def test_shell_matches_docs_brand_and_dark_visual_language(self):
         out = build.build(minimal_data())
-        self.assertIn("--wt-primary: #4f46e5", out)
-        self.assertIn("--wt-bg: #0d0d10", out)
+        self.assertIn("--wt-primary: #6366f1", out)
+        self.assertIn("--wt-bg: #121212", out)
+        self.assertIn("--wt-surface: #191919", out)
+        self.assertIn("--wt-dark-surface: #1e1e1e", out)
+        self.assertIn("--wt-fg: #ebebeb", out)
         self.assertIn("font-family: 'Figtree'", out)
         self.assertIn("font-family: 'Geist Mono'", out)
         self.assertIn('class="wt-topbar sticky', out)
         self.assertIn('class="wt-brand-mark"', out)
+        self.assertIn('href="https://kandev.ai/favicon.ico"', out)
+        self.assertIn('href="https://kandev.ai/icon.svg"', out)
+        self.assertIn(
+            'rel="apple-touch-icon" href="https://kandev.ai/apple-touch-icon.png"',
+            out,
+        )
+        self.assertIn('src="https://kandev.ai/brand/kandev-github-org.png"', out)
+        self.assertIn(
+            "brand: { DEFAULT: '#6366f1', soft: '#818cf8', deep: '#4f46e5' },",
+            out,
+        )
 
     def test_runtime_cdn_dependencies_use_exact_versions(self):
         out = build.build(minimal_data())
@@ -445,6 +507,28 @@ class TestBuild(unittest.TestCase):
         self.assertIn('id="mobile-nav-data"', out)
         self.assertIn("@media (max-width: 640px)", out)
 
+    def test_shell_makes_code_scrollbars_subtle_until_hover(self):
+        out = build.build(minimal_data())
+        self.assertIn("scrollbar-width: thin", out)
+        self.assertIn("scrollbar-color: transparent transparent", out)
+        self.assertIn(".shiki::-webkit-scrollbar-thumb", out)
+        self.assertIn(".shiki:hover::-webkit-scrollbar-thumb", out)
+        self.assertIn(".shiki:focus-within::-webkit-scrollbar-thumb", out)
+
+    def test_shell_uses_lanes_to_route_canvas_edges(self):
+        out = build.build(minimal_data())
+        self.assertIn("function laneOffset", out)
+        self.assertIn("e.dataset.fromLane", out)
+        self.assertIn("e.dataset.toLane", out)
+        self.assertIn("e.dataset.pairLane", out)
+        self.assertIn("const labelLane", out)
+        self.assertIn("const labelFromLane", out)
+        self.assertIn("const labelToLane", out)
+        self.assertIn("const endpointLabelLane", out)
+        self.assertIn("const pairLabelLane", out)
+        self.assertIn("labelPoint.x += labelLane", out)
+        self.assertIn("sizeGroups(); drawEdges(); fit();", out)
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/.github/scripts/pr-walkthrough-workflow-contract_test.py b/.github/scripts/pr-walkthrough-workflow-contract_test.py
index ec3602fa69..21e198af36 100644
--- a/.github/scripts/pr-walkthrough-workflow-contract_test.py
+++ b/.github/scripts/pr-walkthrough-workflow-contract_test.py
@@ -132,6 +132,10 @@ class PRWalkthroughWorkflowContractTest(unittest.TestCase):
         )
         self.assertIn("--agent github-pr-walkthrough", self.generation)
         self.assertIn("--file .pr-walkthrough/guidelines.md", self.generation)
+        self.assertIn(
+            "Never put shell template sentinels such as PR_TITLE or PR_URL in a code, patch, or rendered-Markdown block.",
+            self.generation,
+        )
         self.assertIn("--file .pr-walkthrough/walkthrough.patch", self.generation)
         self.assertIn(".pr-walkthrough/head-context/manifest.json", self.generation)
         self.assertNotIn("render_pr_walkthrough", self.generation)
@@ -233,7 +237,8 @@ class PRWalkthroughWorkflowContractTest(unittest.TestCase):
 
     def test_publication_uploads_only_html_with_expected_metadata(self) -> None:
         for value in (
-            'OBJECT_KEY="pr/${PR_NUMBER}/${HEAD_SHA}.html"',
+            'SHORT_HEAD_SHA="${HEAD_SHA:0:12}"',
+            'OBJECT_KEY="pr/${PR_NUMBER}/${SHORT_HEAD_SHA}.html"',
             "aws s3 cp",
             '--content-type "text/html; charset=utf-8"',
             '--cache-control "public, max-age=300"',
diff --git a/.github/workflows/pr-walkthrough.yml b/.github/workflows/pr-walkthrough.yml
index 5751abfb04..76490d2ed6 100644
--- a/.github/workflows/pr-walkthrough.yml
+++ b/.github/workflows/pr-walkthrough.yml
@@ -171,6 +171,7 @@ jobs:
           - Read the attached guidelines and walkthrough patch first.
           - The checked-out repository is the trusted base commit. Inspect it only when needed to understand callers and surrounding architecture.
           - Use real file paths and real code excerpts from the PR head or attached diff. Do not fabricate code.
+          - Never put shell template sentinels such as PR_TITLE or PR_URL in a code, patch, or rendered-Markdown block. If a source diff hunk contains a shell template sentinel, trim that hunk or use a shorter excerpt that omits the sentinel.
           - Follow the pr-walkthrough skill from the trusted repository checkout.
           - Write the complete JSON object to .pr-walkthrough/draft.json, then run the renderer.
           - If the renderer rejects the draft, correct that file and run the renderer again.
@@ -272,7 +273,8 @@ jobs:
 
           HTML_PATH=".r2-artifact/docs/pr-walkthrough/pr-${PR_NUMBER}.html"
           test -s "$HTML_PATH"
-          OBJECT_KEY="pr/${PR_NUMBER}/${HEAD_SHA}.html"
+          SHORT_HEAD_SHA="${HEAD_SHA:0:12}"
+          OBJECT_KEY="pr/${PR_NUMBER}/${SHORT_HEAD_SHA}.html"
 
           aws s3 cp "$HTML_PATH" "s3://${CLOUDFLARE_R2_BUCKET}/${OBJECT_KEY}" \
             --endpoint-url "$CLOUDFLARE_R2_ENDPOINT" \
diff --git a/docs/decisions/2026-08-22-pr-walkthrough-r2-hosting.md b/docs/decisions/2026-08-22-pr-walkthrough-r2-hosting.md
index abd60138ec..7ebc3619be 100644
--- a/docs/decisions/2026-08-22-pr-walkthrough-r2-hosting.md
+++ b/docs/decisions/2026-08-22-pr-walkthrough-r2-hosting.md
@@ -18,8 +18,10 @@ object on every push if the model cost is acceptable.
 Publish walkthrough HTML files to a dedicated Cloudflare R2 bucket named
 `kandev-pr-walkthroughs`, exposed through the custom domain
 `walkthrough.kandev.ai`. Store objects under
-`pr/<pull-request-number>/<head-sha>.html` and publish only the HTML, not the
-JSON generation artifact.
+`pr/<pull-request-number>/<short-head-sha>.html`, where `short-head-sha` is the
+first 12 lowercase hexadecimal characters of the exact head SHA. Publish only
+the HTML, not the JSON generation artifact. The URL naming rule is recorded in
+[ADR-2026-08-23-pr-walkthrough-short-urls](2026-08-23-pr-walkthrough-short-urls.md).
 
 The GitHub Actions publication job uses a bucket-scoped R2 S3-compatible
 Object Read & Write credential. The generation job receives no R2 credential;
diff --git a/docs/decisions/2026-08-23-pr-walkthrough-short-urls.md b/docs/decisions/2026-08-23-pr-walkthrough-short-urls.md
new file mode 100644
index 0000000000..25897dc74f
--- /dev/null
+++ b/docs/decisions/2026-08-23-pr-walkthrough-short-urls.md
@@ -0,0 +1,46 @@
+# ADR-2026-08-23-pr-walkthrough-short-urls: Use 12-character SHA prefixes for PR walkthrough URLs
+
+**Status:** accepted
+**Date:** 2026-08-23
+**Area:** infra, workflow
+
+## Context
+
+The public PR walkthrough URL currently includes the full 40-character commit
+SHA. The full value is useful for workflow identity, but it makes a reviewer
+link unnecessarily long. A shorter value must still identify a PR snapshot
+with a low practical collision risk.
+
+## Decision
+
+Keep the full lowercase commit SHA in workflow inputs and validation. Use its
+first 12 lowercase hexadecimal characters for the R2 object key, public URL,
+and PR-description callout. The workflow and the PR-body helper derive this
+prefix from the trusted 40-character event SHA.
+
+The fixed shell loads the current website logo and favicon from the website's
+stable public asset paths. This live branding is intentional. Package URLs in
+the shell remain pinned, but new pages follow the current website identity.
+
+## Consequences
+
+- Walkthrough links are 28 characters shorter while retaining a 48-bit prefix.
+- The public URL is stable for a given PR head and remains independent of the
+  generated HTML bytes.
+- Different commits with the same 12-character prefix can share an object
+  key. The prefix is long enough for the repository's active PR snapshots and
+  is safer than a conventional 7-character display prefix.
+- Existing full-SHA objects are not renamed. New generations use the short
+  path, and reruns update the PR callout to that path.
+- Existing pages can show a later website brand asset because the shell loads
+  that asset at page-load time.
+
+## Alternatives Considered
+
+- **Keep the full SHA:** It avoids prefix collisions, but produces unnecessarily
+  long public links.
+- **Use a 7-character prefix:** It is familiar in Git interfaces, but has a
+  smaller collision space for a public object namespace.
+- **Use a generated alias:** It can make links shorter, but it requires a
+  separate alias store and lifecycle rules that are not needed for a commit
+  snapshot.
diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md
index 640951f1fa..91336b3d62 100644
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -196,3 +196,4 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
 | 2026-08-22-agent-owned-pr-walkthrough-rendering | [Keep PR walkthrough rendering agent owned and provider neutral](2026-08-22-agent-owned-pr-walkthrough-rendering.md) | superseded by 2026-08-22-pr-walkthrough-filesystem-runner | workflow, infra, security | 2026-08-22 |
 | 2026-08-22-pr-walkthrough-filesystem-runner | [Use a Filesystem Contract for PR Walkthrough Runners](2026-08-22-pr-walkthrough-filesystem-runner.md) | accepted | workflow, infra, security | 2026-08-22 |
 | 2026-08-22-pr-walkthrough-description-link | [Own a top-level PR walkthrough callout](2026-08-22-pr-walkthrough-description-link.md) | accepted | workflow, infra, security, GitHub | 2026-08-22 |
+| 2026-08-23-pr-walkthrough-short-urls | [Use 12-character SHA prefixes for PR walkthrough URLs](2026-08-23-pr-walkthrough-short-urls.md) | accepted | workflow, infra | 2026-08-23 |
diff --git a/docs/plans/pr-walkthrough-portable-runner-fix/plan.md b/docs/plans/pr-walkthrough-portable-runner-fix/plan.md
index b91dc2bb7e..ef1ac36e22 100644
--- a/docs/plans/pr-walkthrough-portable-runner-fix/plan.md
+++ b/docs/plans/pr-walkthrough-portable-runner-fix/plan.md
@@ -145,6 +145,10 @@ Wave 2:
 
 - [x] [task-03-prompt-driven-workflow](task-03-prompt-driven-workflow.md)
 
+Wave 3:
+
+- [x] [task-04-public-url-and-shell-presentation](task-04-public-url-and-shell-presentation.md)
+
 Execute tasks sequentially in the primary conversation unless the user
 explicitly authorizes subagents.
 
@@ -159,6 +163,7 @@ explicitly authorizes subagents.
 
 ## Out of Scope
 
-- Changes to R2 object naming, publication, retention, or PR linking.
+- Generic R2 retention or merge-promotion changes beyond the 12-character URL
+  contract recorded in ADR-2026-08-23-pr-walkthrough-short-urls.
 - Generic GitHub automation for Claude or Codex.
 - Walkthrough generation for fork pull requests.
diff --git a/docs/plans/pr-walkthrough-portable-runner-fix/task-04-public-url-and-shell-presentation.md b/docs/plans/pr-walkthrough-portable-runner-fix/task-04-public-url-and-shell-presentation.md
new file mode 100644
index 0000000000..98a16ef655
--- /dev/null
+++ b/docs/plans/pr-walkthrough-portable-runner-fix/task-04-public-url-and-shell-presentation.md
@@ -0,0 +1,43 @@
+---
+id: "04-public-url-and-shell-presentation"
+title: "Public URL and shell presentation"
+status: done
+wave: 3
+depends_on: ["03-prompt-driven-workflow"]
+plan: "plan.md"
+spec: "../../specs/pr-walkthrough/spec.md"
+---
+
+# Task 04: Public URL and Shell Presentation
+
+Shorten hosted walkthrough links and align the generated page with the
+website and documentation shell.
+
+- **Acceptance:** The publication job and PR-body helper use the first 12
+  lowercase hexadecimal characters of the trusted full head SHA.
+- **Acceptance:** The generated shell uses the website brand image, favicon,
+  and documentation dark-gray palette.
+- **Acceptance:** Focused helper, workflow-contract, renderer, and responsive
+  page checks pass.
+- **Verification:**
+
+  ```text
+  python3 scripts/pr-walkthrough-pr-body.test.py
+  python3 .github/scripts/pr-walkthrough-workflow-contract_test.py
+  cd .agents/skills/pr-walkthrough/references && python3 -m unittest test_build
+  git diff --check
+  ```
+
+## Results
+
+- The implementation derives a 12-character public SHA prefix from the full
+  event SHA and retains full-SHA validation for trusted workflow identity.
+- The shell uses the website brand image and favicon links and the docs dark
+  tokens for its shell surfaces, text, and borders.
+- `python3 scripts/pr-walkthrough-pr-body.test.py` passed (8 tests).
+- `python3 .github/scripts/pr-walkthrough-workflow-contract_test.py` passed
+  (20 tests).
+- `python3 -m unittest test_build` passed (59 tests).
+- Context, renderer, harness, action-pinning, and actionlint checks passed.
+- Google Chrome captured the generated page at 390x844 and 1440x1000. Both
+  views showed the brand mark and no topbar overflow.
diff --git a/docs/plans/pr-walkthrough/plan.md b/docs/plans/pr-walkthrough/plan.md
index fe2259c954..515dcb48a0 100644
--- a/docs/plans/pr-walkthrough/plan.md
+++ b/docs/plans/pr-walkthrough/plan.md
@@ -1,7 +1,8 @@
 ---
 spec: docs/specs/pr-walkthrough/spec.md
 created: 2026-08-22
-status: implementing
+status: superseded
+superseded_by: ../pr-walkthrough-portable-runner-fix/plan.md
 ---
 
 # Implementation Plan: Pull Request Walkthrough Generation
@@ -101,7 +102,9 @@ The publication contract is:
 - Secret-key secret: `CLOUDFLARE_R2_SECRET_ACCESS_KEY`.
 - Existing account variable: `CLOUDFLARE_ACCOUNT_ID` remains available for
   endpoint construction and is not a secret.
-- Object key: `pr/<pull-request-number>/<head-sha>.html`.
+- Object key: `pr/<pull-request-number>/<short-head-sha>.html`, where
+  `short-head-sha` is the first 12 lowercase hexadecimal characters of the
+  exact head SHA.
 - Object metadata: `Content-Type: text/html; charset=utf-8` and a short cache
   lifetime that does not outlive lifecycle deletion or same-head reruns.
 
@@ -235,7 +238,7 @@ Completed 2026-08-22:
 Wave 1:
 
 - [x] [task-01-walkthrough-skill-renderer](task-01-walkthrough-skill-renderer.md)
-- [ ] [task-02-agent-rendering-contract](task-02-agent-rendering-contract.md)
+- [x] [task-02-agent-rendering-contract](task-02-agent-rendering-contract.md) (superseded by the portable filesystem contract)
 
 Wave 2:
 
diff --git a/docs/plans/pr-walkthrough/task-02-agent-rendering-contract.md b/docs/plans/pr-walkthrough/task-02-agent-rendering-contract.md
index 0265f5421b..ae1e2288e3 100644
--- a/docs/plans/pr-walkthrough/task-02-agent-rendering-contract.md
+++ b/docs/plans/pr-walkthrough/task-02-agent-rendering-contract.md
@@ -1,7 +1,8 @@
 ---
 id: "02-agent-rendering-contract"
 title: "Provider-neutral agent rendering contract"
-status: in_progress
+status: superseded
+superseded_by: ../pr-walkthrough-portable-runner-fix/task-02-fixed-renderer-contract.md
 wave: 1
 depends_on: ["01-walkthrough-skill-renderer"]
 plan: "plan.md"
diff --git a/docs/plans/pr-walkthrough/task-04-r2-html-publication.md b/docs/plans/pr-walkthrough/task-04-r2-html-publication.md
index 1834671f41..3fb58fb291 100644
--- a/docs/plans/pr-walkthrough/task-04-r2-html-publication.md
+++ b/docs/plans/pr-walkthrough/task-04-r2-html-publication.md
@@ -26,11 +26,13 @@ custom domain as the externally visible URL.
   S3-compatible API using a bucket-scoped Object Read & Write token. It does
   not use the existing Pages `CLOUDFLARE_API_TOKEN`.
 - **Acceptance:** The object key is
-  `pr/<pull-request-number>/<head-sha>.html`, with HTML content type and a
-  short cache policy suitable for label-triggered reruns.
+  `pr/<pull-request-number>/<short-head-sha>.html`, where `short-head-sha` is
+  the first 12 lowercase hexadecimal characters of the exact head SHA. It has
+  HTML content type and a short cache policy suitable for label-triggered
+  reruns.
 - **Acceptance:** The job verifies the object with an R2 metadata request and
   verifies the public URL
-  `https://walkthrough.kandev.ai/pr/<pull-request-number>/<head-sha>.html`
+  `https://walkthrough.kandev.ai/pr/<pull-request-number>/<short-head-sha>.html`
   with an HTTPS GET before reporting publication success.
 - **Acceptance:** The job writes the public URL to the workflow job summary
   and exports it to the dependent trusted link job, but receives no GitHub
diff --git a/docs/specs/pr-walkthrough/spec.md b/docs/specs/pr-walkthrough/spec.md
index 65b9103c06..d7eaabe844 100644
--- a/docs/specs/pr-walkthrough/spec.md
+++ b/docs/specs/pr-walkthrough/spec.md
@@ -21,7 +21,8 @@ lifecycle policy.
 **Decisions:**
 [ADR-2026-08-22-pr-walkthrough-r2-hosting](../../decisions/2026-08-22-pr-walkthrough-r2-hosting.md),
 [ADR-2026-08-22-pr-walkthrough-filesystem-runner](../../decisions/2026-08-22-pr-walkthrough-filesystem-runner.md),
-[ADR-2026-08-22-pr-walkthrough-description-link](../../decisions/2026-08-22-pr-walkthrough-description-link.md)
+[ADR-2026-08-22-pr-walkthrough-description-link](../../decisions/2026-08-22-pr-walkthrough-description-link.md),
+[ADR-2026-08-23-pr-walkthrough-short-urls](../../decisions/2026-08-23-pr-walkthrough-short-urls.md)
 
 **Implementation plan:**
 [Portable PR walkthrough runner fix](../../plans/pr-walkthrough-portable-runner-fix/plan.md)
@@ -43,7 +44,13 @@ lifecycle policy.
 - The generated page contains a vertical reviewer story, a dark and light
   theme, architecture and data diagrams when supplied, highlighted code, diff
   tinting, GitHub file links, an interactive code canvas, and a linear fallback
-  list.
+  list. Canvas edges use separate endpoint and node-pair lanes, and their
+  labels follow the routed edge without stacking. Horizontal code scrollbars
+  stay subtle until a reviewer hovers over or focuses a code block. Patch and
+  explicitly marked diff blocks use diff colors. Plain code blocks remain
+  neutral because they provide context rather than a change. Its top bar uses
+  the website brand mark and favicon, and its dark theme uses the
+  documentation shell's dark-gray palette.
 - The configured workflow agent generates and renders the walkthrough for a
   non-draft same-repository pull request when it is opened, reopened, marked
   ready for review, or updated. OpenCode is the initial runner, but the skill
@@ -64,11 +71,13 @@ lifecycle policy.
 - The workflow preserves the generated JSON and HTML as CI artifacts and
   uploads only the HTML to the `kandev-pr-walkthroughs` R2 bucket.
 - Each published object uses the key
-  `pr/<pull-request-number>/<head-sha>.html` and is served at
-  `https://walkthrough.kandev.ai/pr/<pull-request-number>/<head-sha>.html`.
+  `pr/<pull-request-number>/<short-head-sha>.html`, where `short-head-sha` is
+  the first 12 lowercase hexadecimal characters of the exact head SHA. It is
+  served at
+  `https://walkthrough.kandev.ai/pr/<pull-request-number>/<short-head-sha>.html`.
 - The workflow regenerates on `synchronize` for same-repository pull request
-  updates. Each generated object remains keyed by pull request number and head
-  SHA.
+  updates. Each generated object remains keyed by pull request number and the
+  12-character prefix of the exact head SHA.
 - After public validation succeeds, a separate minimum-permission job prepends
   a prominent marker-owned walkthrough callout to the pull request
   description. A rerun replaces only that callout and preserves the rest of
@@ -167,7 +176,7 @@ not from merge time.
 - **GIVEN** a non-draft same-repository pull request is opened, reopened, or
   marked ready for review, **WHEN** the walkthrough job runs, **THEN** it
   creates non-empty JSON and HTML artifacts and publishes the HTML under the
-  current head SHA in R2.
+  12-character prefix of the current head SHA in R2.
 - **GIVEN** a fetched PR head, **WHEN** the workflow computes the triple-dot
   diff, **THEN** the merge base exists and context preparation succeeds.
 - **GIVEN** a changed file contains bounded UTF-8 text, **WHEN** context is
@@ -203,6 +212,15 @@ not from merge time.
   label contains unsafe markup, **WHEN** the page is rendered, **THEN** the
   source is escaped or sanitized and no executable PR-controlled markup is
   inserted by the renderer.
+- **GIVEN** two canvas edges share an endpoint or node pair, **WHEN** the
+  canvas draws them, **THEN** their paths and labels use separate lanes and do
+  not occupy the same route.
+- **GIVEN** a code block overflows horizontally, **WHEN** it is not hovered or
+  focused, **THEN** its scrollbar thumb is transparent; **WHEN** it is hovered
+  or focused, **THEN** a subtle thumb appears.
+- **GIVEN** a code block uses a patch or explicit diff marker, **WHEN** the
+  page renders it, **THEN** added and removed lines receive diff colors, and a
+  plain code block remains neutral context.
 - **GIVEN** a draft pull request or an unauthorized fork event, **WHEN** the
   workflow is triggered, **THEN** no walkthrough agent job runs.
 - **GIVEN** a successfully generated HTML file, **WHEN** the publishing job
diff --git a/scripts/pr-walkthrough-pr-body b/scripts/pr-walkthrough-pr-body
index d21787ccd3..65397ce10e 100644
--- a/scripts/pr-walkthrough-pr-body
+++ b/scripts/pr-walkthrough-pr-body
@@ -12,6 +12,7 @@ from typing import Any
 START_MARKER = "<!-- kandev-pr-walkthrough-start -->"
 END_MARKER = "<!-- kandev-pr-walkthrough-end -->"
 SHA_PATTERN = re.compile(r"^[0-9a-f]{40}$")
+PUBLIC_SHA_LENGTH = 12
 UNCHANGED = 3
 
 
@@ -49,7 +50,10 @@ def validate_url(url: str, pr_number: int, head_sha: str) -> None:
         raise ValueError("pull request number must be positive")
     if not SHA_PATTERN.fullmatch(head_sha):
         raise ValueError("head SHA must be 40 lowercase hexadecimal characters")
-    expected = f"https://walkthrough.kandev.ai/pr/{pr_number}/{head_sha}.html"
+    expected = (
+        "https://walkthrough.kandev.ai/"
+        f"pr/{pr_number}/{head_sha[:PUBLIC_SHA_LENGTH]}.html"
+    )
     if url != expected:
         raise ValueError(f"expected walkthrough URL {expected}")
 
diff --git a/scripts/pr-walkthrough-pr-body.test.py b/scripts/pr-walkthrough-pr-body.test.py
index ecddeacaf8..912259915a 100644
--- a/scripts/pr-walkthrough-pr-body.test.py
+++ b/scripts/pr-walkthrough-pr-body.test.py
@@ -11,8 +11,9 @@ import unittest
 REPO_ROOT = Path(__file__).resolve().parent.parent
 SCRIPT = REPO_ROOT / "scripts" / "pr-walkthrough-pr-body"
 PR_NUMBER = 2906
-HEAD_SHA = "a" * 40
-URL = f"https://walkthrough.kandev.ai/pr/{PR_NUMBER}/{HEAD_SHA}.html"
+HEAD_SHA = "0123456789abcdef0123456789abcdef01234567"
+SHORT_HEAD_SHA = HEAD_SHA[:12]
+URL = f"https://walkthrough.kandev.ai/pr/{PR_NUMBER}/{SHORT_HEAD_SHA}.html"
 START = "<!-- kandev-pr-walkthrough-start -->"
 END = "<!-- kandev-pr-walkthrough-end -->"