feat: release-notes deep links across the updater UI (#35)

Adds a harnessReleaseNotesUrl(version) helper plus HARNESS_SITE_URL /
HARNESS_SITE_RELEASES_URL constants, and wires version-anchored
release-notes links throughout:

- site/public/releases.html: every version <h2> is now a self-link
  to its #vX.Y.Z anchor with a hover-revealed link icon; release.sh
  generates the same markup (and id anchor) for new entries.
- Settings → Updates: the current version and the updater status
  messages ("Harness ### available / downloading / ready to install")
  link to that version's release notes.
- The top update-ready banner's "Harness ###" text links too.

Dev tooling: a dev-gated updater:devSimulate handler + buttons in
Settings → Updates to fake updater states (the auto-updater is a
no-op in dev), and `version` added to the 'downloading' updater
status so the link resolves mid-download.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: big-guy

scripts/release.sh

@@ -177,6 +177,8 @@ div opening, before the first existing release section).
 
 Rules:
 - Match the exact HTML structure, CSS classes, and formatting of existing entries.
+- The new <section class=\"release-section py-10\"> MUST include id=\"${TAG}\" (e.g. id=\"v1.2.3\") so it can be deep-linked from the in-app updater UI.
+- The version <h2> MUST wrap its text in a self-link matching existing entries, e.g.: <h2 class=\"text-3xl font-bold tracking-tight\"><a href=\"#${TAG}\" class=\"release-anchor\">${TAG}<span class=\"anchor-icon\">🔗</span></a></h2>
 - Rewrite commit messages into user-facing release notes. Write for users, not developers.
 - Group under h4 headings: \"New features\", \"Improvements\", \"Fixes\" — only include sections that have content.
 - Skip meta commits: version bumps, README updates, CI fixes, squash labels.

site/public/releases.html

@@ -186,8 +186,10 @@ export function startDesktopShell(deps: DesktopShellStartDeps): DesktopShellStar
       log('updater', 'checking for update')
       store.dispatch({ type: 'updater/statusChanged', payload: { state: 'checking' } })
     })
+    let pendingUpdateVersion = ''
     autoUpdater.on('update-available', (info) => {
       log('updater', `update available ${info.version}${manualInstallRequired ? ' (manual install)' : ''}`)
+      pendingUpdateVersion = info.version
       store.dispatch({
         type: 'updater/statusChanged',
         payload: {
@@ -215,7 +217,7 @@ export function startDesktopShell(deps: DesktopShellStartDeps): DesktopShellStar
     autoUpdater.on('download-progress', (p) => {
       store.dispatch({
         type: 'updater/statusChanged',
-        payload: { state: 'downloading', percent: p.percent }
+        payload: { state: 'downloading', percent: p.percent, version: pendingUpdateVersion }
       })
     })
     autoUpdater.on('update-downloaded', (info) => {
@@ -482,6 +484,25 @@ export function startDesktopShell(deps: DesktopShellStartDeps): DesktopShellStar
       }
     })
 
+    if (!app.isPackaged) {
+      transport.onRequest('updater:devSimulate', (_ctx, state: string) => {
+        const version = app.getVersion()
+        if (state === 'available') {
+          store.dispatch({ type: 'updater/statusChanged', payload: { state: 'available', version } })
+        } else if (state === 'downloading') {
+          store.dispatch({
+            type: 'updater/statusChanged',
+            payload: { state: 'downloading', percent: 42, version }
+          })
+        } else if (state === 'downloaded') {
+          store.dispatch({ type: 'updater/statusChanged', payload: { state: 'downloaded', version } })
+        } else {
+          store.dispatch({ type: 'updater/statusChanged', payload: { state: 'not-available' } })
+        }
+        return true
+      })
+    }
+
     transport.onRequest('updater:quitAndInstall', (_ctx) => {
       log('updater', 'quitAndInstall requested — tearing down before handing off to Squirrel')
       try {

src/main/desktop-shell.ts

@@ -42,6 +42,7 @@ import { ErrorBoundary } from './components/ErrorBoundary'
 import { type GroupKey } from './worktree-sort'
 import { useViewport } from './hooks/useViewport'
 import { MobileApp } from './components/MobileApp'
+import { harnessReleaseNotesUrl } from '../shared/constants'
 
 function isPendingId(id: string | null | undefined): id is string {
   return typeof id === 'string' && id.startsWith('pending:')
@@ -1026,7 +1027,13 @@ const setQuestStep = useCallback((next: QuestStep) => {
       {updaterStatus?.state === 'downloaded' && !updateBannerDismissed && (
         <div className="bg-success/15 border-b border-success/30 pl-20 pr-4 py-2.5 drag-region flex items-center gap-3 shrink-0">
           <span className="text-success text-sm flex-1">
-            Harness {updaterStatus.version} is ready to install. Restart to update.
+            <a
+              onClick={() => backend.openExternal(harnessReleaseNotesUrl(updaterStatus.version))}
+              className="underline hover:text-success cursor-pointer no-drag"
+            >
+              Harness {updaterStatus.version}
+            </a>{' '}
+            is ready to install. Restart to update.
           </span>
           <button
             onClick={handleUpdateRestart}

src/renderer/App.tsx

@@ -334,6 +334,8 @@ export function buildBackend(
     readRecentLog: (maxLines?: number) => req('debug:readRecentLog', maxLines),
     checkForUpdates: () => req('updater:checkForUpdates'),
     quitAndInstall: () => req('updater:quitAndInstall'),
+    devSimulateUpdate: (state: 'available' | 'downloading' | 'downloaded' | 'clear') =>
+      req('updater:devSimulate', state),
 
     // Always-local: shell.openExternal opens on the local user's
     // machine, never on the remote backend. Same with debug log paths.

src/renderer/build-backend.ts

@@ -1,7 +1,7 @@
 import { useState, useEffect, useCallback, useRef, useMemo } from 'react'
 import { ArrowLeft, Check, X, Eye, EyeOff, Star, RefreshCw, Download, RotateCw, GitPullRequest, DownloadCloud, Keyboard, RotateCcw, Terminal as TerminalIcon, Palette, BookOpen, Code2, GitBranch, Plus, Trash2, LifeBuoy, Bug, Lightbulb, FlaskConical, Copy, ExternalLink, CalendarDays, FileText, FolderOpen } from 'lucide-react'
 import { openReportIssue } from './ReportIssueScreen'
-import { HARNESS_ISSUES_URL, HARNESS_RELEASES_URL } from '../../shared/constants'
+import { HARNESS_ISSUES_URL, HARNESS_RELEASES_URL, harnessReleaseNotesUrl } from '../../shared/constants'
 import { useSettings, useUpdater, useRepoConfigs, useHooks } from '../store'
 import { useBackend } from '../backend'
 import type { UpdaterStatus, MergeStrategy, RepoConfig } from '../types'
@@ -833,22 +833,47 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
         return (
           <div className="flex items-center gap-2 text-xs text-warning">
             <Download size={12} />
-            Version {updaterStatus.version} available — downloading...
+            <span>
+              <a
+                onClick={() => backend.openExternal(harnessReleaseNotesUrl(updaterStatus.version))}
+                className="underline hover:text-fg-bright cursor-pointer"
+              >
+                Harness {updaterStatus.version}
+              </a>{' '}
+              available — downloading...
+            </span>
           </div>
         )
       case 'downloading':
         return (
           <div className="flex items-center gap-2 text-xs text-warning">
             <Download size={12} />
-            Downloading update... {Math.round(updaterStatus.percent)}%
+            <span>
+              Downloading{' '}
+              <a
+                onClick={() => backend.openExternal(harnessReleaseNotesUrl(updaterStatus.version))}
+                className="underline hover:text-fg-bright cursor-pointer"
+              >
+                Harness {updaterStatus.version}
+              </a>
+              ... {Math.round(updaterStatus.percent)}%
+            </span>
           </div>
         )
       case 'downloaded':
         return (
           <div className="flex flex-col gap-2">
             <div className="flex items-center gap-2 text-xs text-success">
               <Check size={12} />
-              Version {updaterStatus.version} ready to install
+              <span>
+                <a
+                  onClick={() => backend.openExternal(harnessReleaseNotesUrl(updaterStatus.version))}
+                  className="underline hover:text-fg-bright cursor-pointer"
+                >
+                  Harness {updaterStatus.version}
+                </a>{' '}
+                ready to install
+              </span>
             </div>
             <button
               onClick={handleRestart}
@@ -2034,7 +2059,16 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
                   <div>
                     <div className="text-sm text-fg">Current version</div>
                     <div className="text-xs text-dim font-mono mt-0.5">
-                      {version || '...'}
+                      {version ? (
+                        <a
+                          onClick={() => backend.openExternal(harnessReleaseNotesUrl(version))}
+                          className="underline hover:text-fg-bright cursor-pointer"
+                        >
+                          {version}
+                        </a>
+                      ) : (
+                        '...'
+                      )}
                     </div>
                   </div>
                   <button
@@ -2053,6 +2087,25 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
                   </div>
                 )}
 
+                {import.meta.env.DEV && (
+                  <div className="mt-3 pt-3 border-t border-border">
+                    <div className="text-[10px] uppercase tracking-wide text-faint mb-1.5">
+                      Dev: simulate updater state
+                    </div>
+                    <div className="flex gap-1.5">
+                      {(['available', 'downloading', 'downloaded', 'clear'] as const).map((s) => (
+                        <button
+                          key={s}
+                          onClick={() => backend.devSimulateUpdate(s)}
+                          className="px-2 py-1 bg-surface hover:bg-surface-hover rounded text-[11px] text-fg transition-colors cursor-pointer"
+                        >
+                          {s}
+                        </button>
+                      ))}
+                    </div>
+                  </div>
+                )}
+
                 <div className="mt-4 pt-3 border-t border-border">
                   <label className="flex items-start gap-2 cursor-pointer">
                     <input

src/renderer/components/Settings.tsx

@@ -387,6 +387,8 @@ export interface ElectronAPI {
   readRecentLog(maxLines?: number): Promise<string>
   checkForUpdates(): Promise<{ ok: boolean; available?: boolean; version?: string; releaseDate?: string; error?: string }>
   quitAndInstall(): Promise<boolean>
+  /** Dev-only: fakes an updater status so the update UI can be checked in `npm run dev`. */
+  devSimulateUpdate(state: 'available' | 'downloading' | 'downloaded' | 'clear'): Promise<boolean>
 
   getPerfMetrics(): Promise<PerfMetrics>
   perfLogSlowRender(id: string, ms: number, phase: string): void

src/renderer/types.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

src/renderer/vite-env.d.ts

@@ -4,3 +4,11 @@ export const HARNESS_REPO_URL = `https://github.com/${HARNESS_REPO_OWNER}/${HARN
 export const HARNESS_NEW_ISSUE_URL = `${HARNESS_REPO_URL}/issues/new`
 export const HARNESS_ISSUES_URL = `${HARNESS_REPO_URL}/issues`
 export const HARNESS_RELEASES_URL = `${HARNESS_REPO_URL}/releases`
+
+export const HARNESS_SITE_URL = 'https://harness.mikelyons.org'
+export const HARNESS_SITE_RELEASES_URL = `${HARNESS_SITE_URL}/releases.html`
+
+export function harnessReleaseNotesUrl(version: string): string {
+  const v = version.startsWith('v') ? version : `v${version}`
+  return `${HARNESS_SITE_RELEASES_URL}#${v}`
+}

src/shared/constants.ts

@@ -28,9 +28,9 @@ describe('updaterReducer', () => {
     expect(state.status).toEqual({ state: 'available', version: '1.13.0' })
     state = updaterReducer(state, {
       type: 'updater/statusChanged',
-      payload: { state: 'downloading', percent: 42.5 }
+      payload: { state: 'downloading', percent: 42.5, version: '1.13.0' }
     })
-    expect(state.status).toEqual({ state: 'downloading', percent: 42.5 })
+    expect(state.status).toEqual({ state: 'downloading', percent: 42.5, version: '1.13.0' })
     state = updaterReducer(state, {
       type: 'updater/statusChanged',
       payload: { state: 'downloaded', version: '1.13.0' }