tink-harness 1.9.5 → 1.9.7

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tink",
   "description": "A small harness layer for Claude Code and Codex.",
-  "version": "1.9.5",
+  "version": "1.9.7",
   "author": {
     "name": "dotori"
   }

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to Tink are tracked here.
 
 No unreleased changes yet.
 
+## [1.9.7] - 2026-06-10
+
+### Added
+
+- The harness map now looks like a planetary system: usage/evidence/score satellites orbit their harness slowly (28-63s per revolution, alternating directions) along dashed orbit rings, top harnesses get a Saturn-style ring, and a starfield with twinkling stars sits behind the graph.
+- Selecting a node now dims and blurs everything unrelated (focus mode); clicking the background clears the selection and restores the detail panel.
+
+### Fixed
+
+- Dragging the map no longer triggers text selection on labels and captions (user-select disabled on the map panel).
+
+## [1.9.6] - 2026-06-10
+
+### Added
+
+- The harness map is now fully navigable: wheel zoom toward the cursor (0.4x–5x), drag to pan, +/− and reset controls, and double-click to return to the full view.
+- Nodes render as 3D-style spheres with radial gradients, depth shadows on interactive nodes, and a vignette background for depth.
+- Added a "How to read this map" card to the graph tab's right rail with plain-language explanations of circles, colors, lines, satellites, controls, and edge types.
+
+### Changed
+
+- Reordered the graph right rail: reading guide → selected node → graph overview.
+- Map help text now mentions zoom and drag controls.
+
 ## [1.9.5] - 2026-06-10
 
 ### Added

package/VERSIONING.md

@@ -1,6 +1,6 @@
 # Versioning
 
-Current version: `1.9.5`
+Current version: `1.9.7`
 
 Tink follows semver from `1.0.0` onward.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tink-harness",
-  "version": "1.9.5",
+  "version": "1.9.7",
   "description": "Self-growing harnesses for Claude Code and Codex.",
   "license": "MIT",
   "type": "module",

package/templates/tink/tools/render-harness-health-report.mjs

@@ -48,7 +48,7 @@ const COPY = {
     heroText: 'Every visible Tink run, rule, memory reference, and harness relationship mapped into one local dashboard. This report only prepares suggestions and never edits reusable state.',
     generated: 'GENERATED',
     harnessMap: 'HARNESS MAP',
-    mapHelp: 'Harnesses, rules, memory, and stages are mapped from visible Tink records. Click a node to inspect it.',
+    mapHelp: 'Harnesses, rules, memory, and stages are mapped from visible Tink records. Scroll to zoom, drag to move, click a node to inspect it.',
     graphControls: 'Graph controls',
     full: 'Full',
     core: 'Core',
@@ -146,6 +146,30 @@ const COPY = {
     runWindow: 'Run window',
     totalRuns: 'Runs',
     refCount: 'References',
+    zoomIn: 'Zoom in',
+    zoomOut: 'Zoom out',
+    zoomReset: 'Reset view',
+    mapGuideEyebrow: 'HOW TO READ',
+    mapGuideTitle: 'What is this map?',
+    mapGuideText: 'Each circle is something Tink knows about: a harness, a rule it loads, or a memory file it reads. The map is drawn only from visible local records.',
+    guideItems: [
+      ['Big circle', 'The more a harness is used, the bigger its circle.'],
+      ['Color', 'Blue circles are harnesses; gray ones are rules, memory, and stages.'],
+      ['Line', 'A line means "works together": a harness using a rule, reading memory, or leading to a next step.'],
+      ['Small dots', 'Tiny satellites around a harness are its usage, evidence, and score signals.']
+    ],
+    controlItems: [
+      ['Wheel / + −', 'Zoom in and out'],
+      ['Drag', 'Move around the map'],
+      ['Double-click', 'Back to full view'],
+      ['Click a circle', 'See its details below']
+    ],
+    relationTitle: 'What the lines mean',
+    relationItems: [
+      ['uses_rule', 'This harness loads that rule'],
+      ['uses_memory', 'This harness reads that memory file'],
+      ['sequence', 'This harness is usually followed by that step']
+    ],
     groups: [
       ['keep', 'Healthy harnesses', 'Ready to keep using'],
       ['weave', 'Weave candidates', 'Worth improving next'],
@@ -206,6 +230,30 @@ COPY.ko = {
   runWindow: '기록 기간',
   totalRuns: 'Run 수',
   refCount: '참조 횟수',
+  zoomIn: '확대',
+  zoomOut: '축소',
+  zoomReset: '전체 보기',
+  mapGuideEyebrow: '지도 읽는 법',
+  mapGuideTitle: '이 지도는 무엇인가요?',
+  mapGuideText: '원 하나하나가 Tink가 알고 있는 것입니다: 하네스, 하네스가 쓰는 규칙, 읽는 메모리 파일. 로컬에 보이는 기록만으로 그려집니다.',
+  guideItems: [
+    ['큰 원', '하네스를 많이 쓸수록 원이 커집니다.'],
+    ['색상', '파란 원이 하네스이고, 회색 계열은 규칙·메모리·단계입니다.'],
+    ['선', '"함께 일한다"는 뜻입니다. 하네스가 규칙을 쓰거나, 메모리를 읽거나, 다음 단계로 이어질 때 선이 생깁니다.'],
+    ['작은 점', '하네스 주변의 작은 점들은 사용·근거·점수 신호입니다.']
+  ],
+  controlItems: [
+    ['휠 / + −', '확대·축소'],
+    ['드래그', '지도 이동'],
+    ['더블클릭', '전체 보기로 복귀'],
+    ['원 클릭', '아래에서 상세 보기']
+  ],
+  relationTitle: '선의 의미',
+  relationItems: [
+    ['uses_rule', '이 하네스가 그 규칙을 불러옵니다'],
+    ['uses_memory', '이 하네스가 그 메모리 파일을 읽습니다'],
+    ['sequence', '이 하네스 다음에 그 단계가 자주 이어집니다']
+  ],
   navLabel: '탐색',
   operator: '작업자',
   online: 'Tink 온라인',
@@ -214,7 +262,7 @@ COPY.ko = {
   heroText: '보이는 Tink run, rule, memory reference, harness 관계를 하나의 로컬 대시보드로 보여줍니다. 이 보고서는 제안만 준비하며 재사용 상태를 직접 수정하지 않습니다.',
   generated: '생성 시각',
   harnessMap: '하네스 지도',
-  mapHelp: '보이는 Tink 기록에서 하네스, rule, memory, stage 관계를 그립니다. 노드를 클릭하면 자세히 볼 수 있습니다.',
+  mapHelp: '보이는 Tink 기록에서 하네스, rule, memory, stage 관계를 그립니다. 휠로 확대, 드래그로 이동, 노드를 클릭하면 자세히 볼 수 있습니다.',
   graphControls: '그래프 조작',
   full: '전체',
   core: '핵심',
@@ -570,8 +618,7 @@ function buildGraphLayout(summary) {
       glow: score >= 50 || radius >= 20
     };
   });
-  const augmented = [...positioned];
-  const virtualEdges = [];
+  const orbitSystems = [];
   for (const node of positioned.filter((item) => item.type === 'harness')) {
     const harnessId = shortLabel(node.id);
     const harness = harnessById.get(harnessId);
@@ -579,38 +626,25 @@ function buildGraphLayout(summary) {
     const uses = Number(harness.signals?.uses || 0);
     const evidenceCount = (harness.evidence_handles || []).length;
     const factorCount = (harness.candidate_score?.factors || []).length;
-    const satellites = [
-      ...Array.from({ length: Math.min(14, Math.ceil(uses / 2)) }, (_, index) => ({ kind: 'signal', index, total: Math.min(14, Math.ceil(uses / 2)), radius: 2.8 + Math.min(3.5, uses / 12) })),
-      ...Array.from({ length: Math.min(6, evidenceCount) }, (_, index) => ({ kind: 'evidence', index, total: Math.min(6, evidenceCount), radius: 3.5 })),
-      ...Array.from({ length: Math.min(5, factorCount) }, (_, index) => ({ kind: 'score', index, total: Math.min(5, factorCount), radius: 3.8 }))
-    ];
-    satellites.forEach((satellite, offset) => {
-      const seed = hashString(`${node.id}:${satellite.kind}:${satellite.index}`);
-      const angle = ((seed % 6283) / 1000) + offset * 0.45;
-      const distance = node.radius + 24 + (seed % 42);
-      const child = {
-        id: `${satellite.kind}:${harnessId}:${satellite.index}`,
-        type: satellite.kind,
-        label: satellite.kind,
-        weight: 1,
-        x: clamp(node.x + Math.cos(angle) * distance, 25, 1065),
-        y: clamp(node.y + Math.sin(angle) * distance, 25, 655),
-        radius: satellite.radius,
-        color: TYPE_COLORS[satellite.kind] || TYPE_COLORS.unknown,
-        glow: satellite.kind === 'score'
-      };
-      augmented.push(child);
-      virtualEdges.push({
-        source: node.id,
-        target: child.id,
-        type: satellite.kind,
-        count: 1
-      });
-    });
+    const seed = hashString(node.id);
+    const rings = [
+      { kind: 'signal', count: Math.min(10, Math.ceil(uses / 2)), distance: node.radius + 18, dotRadius: 2.4 },
+      { kind: 'evidence', count: Math.min(6, evidenceCount), distance: node.radius + 29, dotRadius: 2.9 },
+      { kind: 'score', count: Math.min(5, factorCount), distance: node.radius + 40, dotRadius: 3.2 }
+    ]
+      .filter((ring) => ring.count > 0)
+      .map((ring, ringIndex) => ({
+        ...ring,
+        duration: (28 + ((seed >> (ringIndex * 3)) % 36)).toFixed(0),
+        reverse: ringIndex % 2 === 1,
+        phase: ((seed >> (ringIndex * 5)) % 628) / 100
+      }));
+    if (rings.length) {
+      orbitSystems.push({ parentId: node.id, x: node.x, y: node.y, rings });
+    }
   }
-  const byId = new Map(augmented.map((node) => [node.id, node]));
-  const filteredEdges = getRenderableEdges(edges);
-  const drawnEdges = [...filteredEdges, ...virtualEdges]
+  const byId = new Map(positioned.map((node) => [node.id, node]));
+  const drawnEdges = getRenderableEdges(edges)
     .map((edge) => ({
       ...edge,
       sourceNode: byId.get(edge.source),
@@ -619,15 +653,26 @@ function buildGraphLayout(summary) {
     .filter((edge) => edge.sourceNode && edge.targetNode)
     .slice(0, 240);
 
-  return { nodes: augmented, edges: drawnEdges };
+  return { nodes: positioned, edges: drawnEdges, orbitSystems };
 }
 
 function renderGraphCanvas(summary, copy) {
-  const { nodes, edges } = buildGraphLayout(summary);
+  const { nodes, edges, orbitSystems } = buildGraphLayout(summary);
   const strongest = nodes
     .filter((node) => node.type === 'harness')
     .sort((a, b) => Number(b.weight || 0) - Number(a.weight || 0))
     .slice(0, 8);
+  const stars = Array.from({ length: 110 }, (_, index) => {
+    const seed = hashString(`star:${index}`);
+    return {
+      x: seed % 1090,
+      y: (seed >> 4) % 680,
+      r: (0.5 + ((seed >> 8) % 12) / 10).toFixed(1),
+      opacity: (0.1 + ((seed >> 6) % 45) / 100).toFixed(2),
+      twinkle: index % 4 === 0,
+      delay: seed % 5000
+    };
+  });
   const mapTitle = copy.knowledgeGraph || copy.harnessMap || 'Harness map';
   const mapEyebrow = copy.harnessMap && copy.harnessMap !== mapTitle ? copy.harnessMap : '';
   return `
@@ -638,13 +683,40 @@ function renderGraphCanvas(summary, copy) {
           <h2 id="map-title">${escapeHtml(mapTitle)}</h2>
           <p>${escapeHtml(copy.mapHelp)}</p>
         </div>
-        <div class="map-controls" aria-label="${escapeAttr(copy.graphControls)}">
-          <button class="active" type="button" data-mode="full" aria-pressed="true">${escapeHtml(copy.full)}</button>
-          <button type="button" data-mode="core" aria-pressed="false">${escapeHtml(copy.core)}</button>
+        <div class="map-controls-row">
+          <div class="map-controls" aria-label="${escapeAttr(copy.graphControls)}">
+            <button class="active" type="button" data-mode="full" aria-pressed="true">${escapeHtml(copy.full)}</button>
+            <button type="button" data-mode="core" aria-pressed="false">${escapeHtml(copy.core)}</button>
+          </div>
+          <div class="map-controls" aria-label="zoom">
+            <button type="button" data-zoom="in" aria-label="${escapeAttr(copy.zoomIn || 'Zoom in')}" title="${escapeAttr(copy.zoomIn || 'Zoom in')}">+</button>
+            <button type="button" data-zoom="out" aria-label="${escapeAttr(copy.zoomOut || 'Zoom out')}" title="${escapeAttr(copy.zoomOut || 'Zoom out')}">−</button>
+            <button type="button" data-zoom="reset" title="${escapeAttr(copy.zoomReset || 'Reset view')}">${escapeHtml(copy.zoomReset || 'Reset')}</button>
+          </div>
         </div>
       </div>
       <svg class="graph-canvas" viewBox="0 0 1090 680" role="img" aria-label="Harness health graph">
-        <rect width="1090" height="680" fill="var(--bg-card)"/>
+        <defs>
+          <radialGradient id="graph-bg-grad" cx="50%" cy="42%" r="80%">
+            <stop offset="0%" style="stop-color: #11141C"/>
+            <stop offset="60%" style="stop-color: #0A0C12"/>
+            <stop offset="100%" style="stop-color: #06070B"/>
+          </radialGradient>
+          ${Object.entries(TYPE_COLORS).map(([type, color]) => `
+            <radialGradient id="node-grad-${escapeAttr(type)}" cx="32%" cy="28%" r="78%">
+              <stop offset="0%" style="stop-color: #FFFFFF; stop-opacity: 0.42"/>
+              <stop offset="38%" style="stop-color: ${escapeAttr(color)}; stop-opacity: 0.98"/>
+              <stop offset="100%" style="stop-color: ${escapeAttr(color)}; stop-opacity: 0.78"/>
+            </radialGradient>
+          `).join('')}
+        </defs>
+        <rect class="graph-bg" width="1090" height="680" fill="url(#graph-bg-grad)"/>
+        <g class="starfield" aria-hidden="true">
+          ${stars.map((star) => `
+            <circle cx="${star.x}" cy="${star.y}" r="${star.r}" fill="#FFFFFF" opacity="${star.opacity}"${star.twinkle ? ` class="star-twinkle" style="--twinkle-delay: ${star.delay}ms"` : ''}/>
+          `).join('')}
+        </g>
+        <g id="graph-viewport">
         <g class="edges">
         ${edges.map((edge, index) => `
               <line
@@ -662,6 +734,22 @@ function renderGraphCanvas(summary, copy) {
             />
           `).join('')}
         </g>
+        <g class="orbits" aria-hidden="true">
+          ${orbitSystems.map((system) => `
+            <g class="orbit-system" data-parent="${escapeAttr(system.parentId)}" transform="translate(${system.x.toFixed(1)} ${system.y.toFixed(1)})">
+              ${system.rings.map((ring) => {
+                const dots = Array.from({ length: ring.count }, (_, dotIndex) => {
+                  const angle = ring.phase + (dotIndex * Math.PI * 2) / ring.count;
+                  return `<circle class="orbit-dot" cx="${(Math.cos(angle) * ring.distance).toFixed(1)}" cy="${(Math.sin(angle) * ring.distance).toFixed(1)}" r="${ring.dotRadius}" fill="url(#node-grad-${escapeAttr(ring.kind)})"/>`;
+                }).join('');
+                return `
+                  <circle class="orbit-ring" cx="0" cy="0" r="${ring.distance.toFixed(1)}"/>
+                  <g class="orbit-spin${ring.reverse ? ' is-reverse' : ''}" style="--orbit-dur: ${ring.duration}s">${dots}</g>
+                `;
+              }).join('')}
+            </g>
+          `).join('')}
+        </g>
         <g class="nodes">
           ${nodes.map((node, index) => {
             const seed = hashString(node.id);
@@ -671,6 +759,9 @@ function renderGraphCanvas(summary, copy) {
             const floatY = (((seed >> 3) % 7) - 3).toFixed(1);
             return `
             <g class="node-float" style="--float-dur: ${floatDuration}s; --float-delay: ${floatDelay}ms; --float-x: ${floatX}px; --float-y: ${floatY}px">
+            ${node.type === 'harness' && node.radius >= 15 ? `
+              <ellipse class="planet-ring" cx="${node.x.toFixed(1)}" cy="${node.y.toFixed(1)}" rx="${(node.radius * 1.75).toFixed(1)}" ry="${(node.radius * 0.5).toFixed(1)}" transform="rotate(-16 ${node.x.toFixed(1)} ${node.y.toFixed(1)})"/>
+            ` : ''}
             <circle
               class="graph-node ${node.type === 'harness' ? 'is-interactive' : ''}"
               style="--enter-delay: ${Math.min(index * 9, 1100)}ms"
@@ -686,8 +777,8 @@ function renderGraphCanvas(summary, copy) {
               cx="${node.x.toFixed(1)}"
               cy="${node.y.toFixed(1)}"
               r="${node.radius.toFixed(1)}"
-              fill="${escapeAttr(node.color)}"
-              fill-opacity="${node.type === 'harness' ? '0.96' : '0.82'}"
+              fill="url(#node-grad-${escapeAttr(TYPE_COLORS[node.type] ? node.type : 'unknown')})"
+              fill-opacity="${node.type === 'harness' ? '1' : '0.85'}"
               stroke="${escapeAttr('var(--text-secondary)')}"
               stroke-opacity="${node.glow ? '0.9' : '0.18'}"
               stroke-width="${node.glow ? '1.8' : '0.8'}"
@@ -703,6 +794,7 @@ function renderGraphCanvas(summary, copy) {
             <text x="${(node.x + node.radius + 7).toFixed(1)}" y="${(node.y + 4).toFixed(1)}">${escapeHtml(node.label)}</text>
           `).join('')}
         </g>
+        </g>
       </svg>
       <div class="graph-tooltip" id="graph-tooltip" role="status" aria-live="polite"></div>
       <div class="map-caption">
@@ -1008,6 +1100,39 @@ function renderGraphOverview(graph = {}, copy) {
   `;
 }
 
+function renderMapGuide(copy) {
+  const guideItems = Array.isArray(copy.guideItems) ? copy.guideItems : [];
+  const controlItems = Array.isArray(copy.controlItems) ? copy.controlItems : [];
+  const relationItems = Array.isArray(copy.relationItems) ? copy.relationItems : [];
+  return `
+    <section class="insight-card map-guide">
+      <div class="panel-title">
+        <p class="eyebrow">${escapeHtml(copy.mapGuideEyebrow || 'HOW TO READ')}</p>
+        <h2>${escapeHtml(copy.mapGuideTitle || 'What is this map?')}</h2>
+        <p>${escapeHtml(copy.mapGuideText || '')}</p>
+      </div>
+      <ul class="guide-list">
+        ${guideItems.map(([term, text]) => `
+          <li><strong>${escapeHtml(term)}</strong><span>${escapeHtml(text)}</span></li>
+        `).join('')}
+      </ul>
+      <ul class="guide-list guide-controls">
+        ${controlItems.map(([key, text]) => `
+          <li><kbd>${escapeHtml(key)}</kbd><span>${escapeHtml(text)}</span></li>
+        `).join('')}
+      </ul>
+      ${relationItems.length ? `
+        <p class="detail-label">${escapeHtml(copy.relationTitle || 'What the lines mean')}</p>
+        <ul class="guide-list guide-relations">
+          ${relationItems.map(([type, text]) => `
+            <li><code>${escapeHtml(type)}</code><span>${escapeHtml(text)}</span></li>
+          `).join('')}
+        </ul>
+      ` : ''}
+    </section>
+  `;
+}
+
 function renderRoutingCard(copy) {
   const rules = Array.isArray(copy.routeRules) ? copy.routeRules : [];
   return `
@@ -1255,14 +1380,30 @@ function renderScript(harnesses, copy) {
       const setFilterStatus = (value) => {
         if (filterStatus) filterStatus.textContent = value;
       };
+      const graphCanvas = document.querySelector('.graph-canvas');
+      const orbitSystems = Array.from(document.querySelectorAll('.orbit-system'));
+      const defaultSelectedPanel = selectedPanel ? selectedPanel.innerHTML : '';
+      function syncOrbits() {
+        const hasSelection = graphCanvas && graphCanvas.classList.contains('has-selection');
+        orbitSystems.forEach((system) => {
+          const parent = nodeById(system.dataset.parent);
+          const hidden = !parent || parent.classList.contains('is-hidden') || parent.classList.contains('is-filtered-out');
+          system.classList.toggle('is-hidden', hidden);
+          const related = parent && (parent.classList.contains('is-selected') || parent.classList.contains('is-related'));
+          system.classList.toggle('is-dimmed', Boolean(hasSelection && !related));
+        });
+      }
       function clearSelection() {
         nodes.forEach((item) => item.classList.remove('is-selected', 'is-related'));
         edges.forEach((item) => item.classList.remove('is-related'));
         cards.forEach((item) => item.classList.remove('is-selected'));
+        if (graphCanvas) graphCanvas.classList.remove('has-selection');
+        syncOrbits();
       }
       function selectNode(node) {
         clearSelection();
         node.classList.add('is-selected');
+        if (graphCanvas) graphCanvas.classList.add('has-selection');
         const id = node.dataset.nodeId;
         const item = byHarnessId.get(id);
         edges.forEach((edge) => {
@@ -1290,6 +1431,7 @@ function renderScript(harnesses, copy) {
         } else if (selectedPanel) {
           selectedPanel.innerHTML = '<p class="eyebrow">' + esc(copy.selected) + '</p><h2>' + esc(node.dataset.nodeLabel) + '</h2><p>' + esc(id) + '</p><dl><div><dt>' + esc(copy.type) + '</dt><dd>' + esc(displayValue(node.dataset.nodeType)) + '</dd></div><div><dt>' + esc(copy.weight) + '</dt><dd>' + esc(node.dataset.nodeWeight) + '</dd></div></dl>';
         }
+        syncOrbits();
       }
       function selectHarness(id) {
         const node = nodeById('harness:' + id);
@@ -1307,7 +1449,9 @@ function renderScript(harnesses, copy) {
         nodes.forEach((node) => node.classList.toggle('is-hidden', mode === 'core' && node.dataset.core !== 'true'));
         const visibleIds = new Set(nodes.filter((node) => !node.classList.contains('is-hidden')).map((node) => node.dataset.nodeId));
         edges.forEach((edge) => edge.classList.toggle('is-hidden', mode === 'core' && (!visibleIds.has(edge.dataset.source) || !visibleIds.has(edge.dataset.target))));
+        document.querySelectorAll('.orbit-system').forEach((system) => system.classList.toggle('is-mode-hidden', mode === 'core'));
         setStatus(mode === 'core' ? copy.coreMode : copy.showingAll);
+        syncOrbits();
       }
       function filterRecommendation(value, button) {
         const alreadyActive = button.classList.contains('active-filter');
@@ -1321,6 +1465,7 @@ function renderScript(harnesses, copy) {
           cards.forEach((card) => card.classList.remove('is-filtered-out'));
           setStatus(copy.showingAll);
           setFilterStatus(copy.showingAll);
+          syncOrbits();
           return;
         }
         button.classList.add('active-filter');
@@ -1335,6 +1480,7 @@ function renderScript(harnesses, copy) {
         const label = recLabelByFilter[value] || value;
         setStatus(copy.filteredTo + ': ' + label);
         setFilterStatus(copy.filteredTo + ': ' + label);
+        syncOrbits();
       }
       interactiveNodes.forEach((node) => {
         node.addEventListener('click', () => selectNode(node));
@@ -1364,6 +1510,88 @@ function renderScript(harnesses, copy) {
       document.querySelectorAll('[data-mode]').forEach((button) => {
         button.addEventListener('click', () => applyMode(button.dataset.mode));
       });
+      const graphSvg = document.querySelector('.graph-canvas');
+      const graphViewport = document.getElementById('graph-viewport');
+      if (graphSvg && graphViewport) {
+        const view = { x: 0, y: 0, k: 1 };
+        graphViewport.style.transformOrigin = '0 0';
+        const applyView = () => {
+          graphViewport.style.transform = 'translate(' + view.x + 'px, ' + view.y + 'px) scale(' + view.k + ')';
+        };
+        const svgPoint = (event) => {
+          const pt = graphSvg.createSVGPoint();
+          pt.x = event.clientX;
+          pt.y = event.clientY;
+          return pt.matrixTransform(graphSvg.getScreenCTM().inverse());
+        };
+        const zoomAt = (factor, cx, cy) => {
+          const k = Math.min(5, Math.max(0.4, view.k * factor));
+          const real = k / view.k;
+          view.x = cx - (cx - view.x) * real;
+          view.y = cy - (cy - view.y) * real;
+          view.k = k;
+          applyView();
+        };
+        const resetView = () => {
+          graphViewport.classList.add('is-resetting');
+          view.x = 0; view.y = 0; view.k = 1;
+          applyView();
+          setTimeout(() => graphViewport.classList.remove('is-resetting'), 360);
+        };
+        graphSvg.addEventListener('wheel', (event) => {
+          event.preventDefault();
+          const point = svgPoint(event);
+          zoomAt(event.deltaY < 0 ? 1.15 : 1 / 1.15, point.x, point.y);
+        }, { passive: false });
+        let panState = null;
+        graphSvg.addEventListener('pointerdown', (event) => {
+          if (event.button !== 0) return;
+          panState = { x: event.clientX, y: event.clientY, moved: false };
+          graphSvg.setPointerCapture(event.pointerId);
+        });
+        graphSvg.addEventListener('pointermove', (event) => {
+          if (!panState) return;
+          const dx = event.clientX - panState.x;
+          const dy = event.clientY - panState.y;
+          if (!panState.moved && Math.abs(dx) + Math.abs(dy) < 3) return;
+          panState.moved = true;
+          graphSvg.classList.add('is-panning');
+          const scale = 1090 / graphSvg.clientWidth;
+          view.x += dx * scale;
+          view.y += dy * scale;
+          panState.x = event.clientX;
+          panState.y = event.clientY;
+          applyView();
+        });
+        let suppressClick = false;
+        const endPan = () => {
+          suppressClick = Boolean(panState && panState.moved);
+          panState = null;
+          graphSvg.classList.remove('is-panning');
+        };
+        graphSvg.addEventListener('pointerup', endPan);
+        graphSvg.addEventListener('pointercancel', endPan);
+        graphSvg.addEventListener('click', (event) => {
+          if (suppressClick) {
+            suppressClick = false;
+            return;
+          }
+          if (event.target.classList.contains('graph-bg') || event.target.closest('.starfield')) {
+            clearSelection();
+            if (selectedPanel && defaultSelectedPanel) selectedPanel.innerHTML = defaultSelectedPanel;
+          }
+        });
+        graphSvg.addEventListener('dblclick', (event) => {
+          event.preventDefault();
+          resetView();
+        });
+        document.querySelectorAll('[data-zoom]').forEach((button) => {
+          button.addEventListener('click', () => {
+            if (button.dataset.zoom === 'reset') return resetView();
+            zoomAt(button.dataset.zoom === 'in' ? 1.3 : 1 / 1.3, 545, 340);
+          });
+        });
+      }
       const VALID_TABS = ['home', 'harnesses', 'memory', 'graph', 'activity'];
       const navLinks = Array.from(document.querySelectorAll('.nav a[data-tab]'));
       const pages = Array.from(document.querySelectorAll('.page'));
@@ -2020,6 +2248,147 @@ function renderStyles() {
       transition: opacity 160ms ease, transform 160ms ease;
     }
 
+    .map-panel,
+    .graph-canvas,
+    .graph-canvas text {
+      user-select: none;
+      -webkit-user-select: none;
+      -webkit-user-drag: none;
+    }
+
+    .star-twinkle {
+      animation: star-twinkle 3.4s ease-in-out var(--twinkle-delay, 0ms) infinite alternate;
+    }
+
+    @keyframes star-twinkle {
+      from { opacity: 0.08; }
+      to { opacity: 0.6; }
+    }
+
+    .orbit-ring {
+      fill: none;
+      stroke: var(--text-secondary);
+      stroke-opacity: 0.14;
+      stroke-width: 0.7;
+      stroke-dasharray: 2 5;
+    }
+
+    .orbit-spin {
+      animation: orbit-rotate var(--orbit-dur, 40s) linear infinite;
+    }
+
+    .orbit-spin.is-reverse { animation-direction: reverse; }
+
+    @keyframes orbit-rotate {
+      to { transform: rotate(360deg); }
+    }
+
+    .orbit-dot { opacity: 0.85; }
+
+    .orbit-system {
+      transition: opacity 260ms ease;
+    }
+
+    .orbit-system.is-hidden,
+    .orbit-system.is-mode-hidden { opacity: 0; pointer-events: none; }
+    .orbit-system.is-dimmed { opacity: 0.08; }
+
+    .planet-ring {
+      fill: none;
+      stroke: var(--text-secondary);
+      stroke-opacity: 0.4;
+      stroke-width: 1.4;
+      pointer-events: none;
+    }
+
+    .graph-canvas.has-selection .graph-node:not(.is-selected):not(.is-related) {
+      opacity: 0.14;
+      filter: blur(1.2px);
+    }
+
+    .graph-canvas.has-selection .graph-edge:not(.is-related) { opacity: 0.05; }
+
+    .graph-canvas.has-selection .planet-ring { stroke-opacity: 0.1; }
+
+    .graph-canvas.has-selection .labels text { opacity: 0.18; transition: opacity 220ms ease; }
+
+    .map-controls-row {
+      display: flex;
+      gap: var(--space-2);
+      align-items: center;
+      flex-wrap: wrap;
+    }
+
+    .graph-canvas {
+      cursor: grab;
+      touch-action: none;
+    }
+
+    .graph-canvas.is-panning { cursor: grabbing; }
+
+    #graph-viewport {
+      will-change: transform;
+    }
+
+    #graph-viewport.is-resetting {
+      transition: transform 340ms cubic-bezier(0.2, 0.8, 0.2, 1);
+    }
+
+    .graph-node.is-interactive {
+      filter: drop-shadow(0 5px 7px rgba(0, 0, 0, 0.55));
+    }
+
+    .graph-node.is-interactive:hover,
+    .graph-node.is-interactive:focus-visible {
+      filter: drop-shadow(0 9px 14px rgba(0, 0, 0, 0.65));
+    }
+
+    .map-guide .panel-title p:last-child {
+      font-size: 12px;
+      line-height: 1.5;
+    }
+
+    .guide-list {
+      margin: var(--space-3) 0 0;
+      padding: 0;
+      list-style: none;
+      display: grid;
+      gap: var(--space-2);
+    }
+
+    .guide-list li {
+      display: grid;
+      grid-template-columns: 76px 1fr;
+      gap: var(--space-2);
+      align-items: start;
+      font-size: 12px;
+      line-height: 1.45;
+      color: var(--text-secondary);
+    }
+
+    .guide-list strong {
+      color: var(--text-primary);
+      font-size: 12px;
+      font-weight: 500;
+    }
+
+    .guide-list kbd {
+      font-family: var(--font-mono);
+      font-size: 10px;
+      color: var(--accent-text);
+      border: 1px solid var(--border-default);
+      border-radius: var(--radius-sm);
+      background: var(--bg-hover);
+      padding: 2px 5px;
+      text-align: center;
+      white-space: nowrap;
+    }
+
+    .guide-controls { border-top: 1px solid var(--border-default); padding-top: var(--space-3); }
+
+    .guide-relations li { grid-template-columns: 96px 1fr; }
+    .guide-relations code { font-size: 10px; }
+
     .map-legend {
       display: flex;
       gap: var(--space-3);
@@ -2050,6 +2419,8 @@ function renderStyles() {
       .graph-node,
       .graph-edge,
       .graph-canvas text,
+      .orbit-spin,
+      .star-twinkle,
       .page.is-active { animation: none; }
       .graph-node { transition: none; }
     }
@@ -2850,9 +3221,10 @@ function renderReport(summary) {
       <aside class="right-rail" aria-label="Insights">
       <div data-rail="home harnesses memory activity">${renderStats(summary, copy)}</div>
       <div data-rail="home harnesses">${renderConfidence(summary, copy)}</div>
-      <div data-rail="graph">${renderGraphOverview(summary.graph || {}, copy)}</div>
-      <div data-rail="home harnesses">${renderImportantHarnesses(harnesses, copy)}</div>
+      <div data-rail="graph">${renderMapGuide(copy)}</div>
       <div data-rail="graph">${renderSelectedPanel(harnesses, copy)}</div>
+      <div data-rail="home harnesses">${renderImportantHarnesses(harnesses, copy)}</div>
+      <div data-rail="graph">${renderGraphOverview(summary.graph || {}, copy)}</div>
     </aside>
   </div>
   ${renderContractMetadata(copy)}