@prmichaelsen/acp-visualizer 0.5.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prmichaelsen/acp-visualizer",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "type": "module",
   "description": "Browser-based dashboard for visualizing ACP progress.yaml data",
   "bin": {
@@ -29,6 +29,7 @@
   "dependencies": {
     "@cloudflare/vite-plugin": "^1.28.0",
     "@cloudflare/workers-types": "^4.20260313.1",
+    "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.0.6",
     "@tanstack/react-router": "^1.132.0",
     "@tanstack/react-start": "^1.132.0",
@@ -45,7 +46,9 @@
     "lucide-react": "^0.544.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
     "recharts": "^3.8.0",
+    "rehype-highlight": "^7.0.2",
     "tailwindcss": "^4.0.6",
     "typescript": "^5.7.2",
     "vite": "^7.1.7",

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,25 @@
+import { Link } from '@tanstack/react-router'
+
+interface BreadcrumbItem {
+  label: string
+  href?: string
+}
+
+export function Breadcrumb({ items }: { items: BreadcrumbItem[] }) {
+  return (
+    <nav className="flex items-center gap-1.5 text-xs text-gray-500 mb-4">
+      {items.map((item, i) => (
+        <span key={i} className="flex items-center gap-1.5">
+          {i > 0 && <span className="text-gray-700">/</span>}
+          {item.href ? (
+            <Link to={item.href} className="hover:text-gray-300 transition-colors">
+              {item.label}
+            </Link>
+          ) : (
+            <span className="text-gray-400">{item.label}</span>
+          )}
+        </span>
+      ))}
+    </nav>
+  )
+}

package/src/components/DetailHeader.tsx

@@ -0,0 +1,28 @@
+import { StatusBadge } from './StatusBadge'
+import type { Status } from '../lib/types'
+
+interface DetailField {
+  label: string
+  value: React.ReactNode
+}
+
+interface DetailHeaderProps {
+  status: Status
+  fields: DetailField[]
+}
+
+export function DetailHeader({ status, fields }: DetailHeaderProps) {
+  return (
+    <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4 mb-6">
+      <div className="flex flex-wrap items-center gap-3">
+        <StatusBadge status={status} />
+        {fields.map((field, i) => (
+          <div key={i} className="flex items-center gap-1.5 text-xs">
+            <span className="text-gray-500">{field.label}:</span>
+            <span className="text-gray-300">{field.value}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/components/MarkdownContent.tsx

@@ -0,0 +1,29 @@
+import ReactMarkdown from 'react-markdown'
+import rehypeHighlight from 'rehype-highlight'
+
+interface MarkdownContentProps {
+  content: string
+  className?: string
+}
+
+export function MarkdownContent({ content, className }: MarkdownContentProps) {
+  return (
+    <ReactMarkdown
+      rehypePlugins={[rehypeHighlight]}
+      className={`prose prose-invert prose-sm max-w-none
+        prose-pre:bg-gray-900 prose-pre:border prose-pre:border-gray-800
+        prose-code:bg-gray-800 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded prose-code:text-gray-200
+        prose-code:before:content-none prose-code:after:content-none
+        prose-a:text-blue-400 prose-a:no-underline hover:prose-a:underline
+        prose-headings:text-gray-100
+        prose-strong:text-gray-200
+        prose-th:text-gray-300 prose-th:border-gray-700
+        prose-td:border-gray-800
+        prose-hr:border-gray-800
+        prose-blockquote:border-gray-700 prose-blockquote:text-gray-400
+        ${className ?? ''}`}
+    >
+      {content}
+    </ReactMarkdown>
+  )
+}

package/src/components/MilestoneKanban.tsx

@@ -1,3 +1,4 @@
+import { Link } from '@tanstack/react-router'
 import { StatusBadge } from './StatusBadge'
 import { ProgressBar } from './ProgressBar'
 import { TaskList } from './TaskList'
@@ -29,7 +30,13 @@ function KanbanCard({
   return (
     <div className="bg-gray-900/50 border border-gray-800 rounded-lg p-3 hover:border-gray-700 transition-colors">
       <div className="flex items-start justify-between gap-2 mb-2">
-        <h4 className="text-sm font-medium leading-tight">{milestone.name}</h4>
+        <Link
+          to="/milestones/$milestoneId"
+          params={{ milestoneId: milestone.id }}
+          className="text-sm font-medium leading-tight hover:text-blue-400 transition-colors"
+        >
+          {milestone.name}
+        </Link>
       </div>
       <div className="flex items-center gap-2 mb-2">
         <div className="flex-1">

package/src/components/MilestoneTable.tsx

@@ -1,4 +1,5 @@
 import { Fragment, useState } from 'react'
+import { Link } from '@tanstack/react-router'
 import {
   createColumnHelper,
   useReactTable,
@@ -52,7 +53,14 @@ export function MilestoneTable({ milestones, tasks }: MilestoneTableProps) {
     columnHelper.accessor('name', {
       header: 'Milestone',
       cell: (info) => (
-        <span className="text-sm font-medium">{info.getValue()}</span>
+        <Link
+          to="/milestones/$milestoneId"
+          params={{ milestoneId: info.row.original.id }}
+          className="text-sm font-medium text-gray-200 hover:text-blue-400 transition-colors"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {info.getValue()}
+        </Link>
       ),
     }),
     columnHelper.accessor('status', {

package/src/components/MilestoneTree.tsx

@@ -1,4 +1,5 @@
 import { useState } from 'react'
+import { Link } from '@tanstack/react-router'
 import { ChevronDown, ChevronRight } from 'lucide-react'
 import { StatusBadge } from './StatusBadge'
 import { ProgressBar } from './ProgressBar'
@@ -35,7 +36,14 @@ function MilestoneTreeRow({
         ) : (
           <ChevronRight className="w-4 h-4 text-gray-500 shrink-0" />
         )}
-        <span className="flex-1 text-sm font-medium">{milestone.name}</span>
+        <Link
+          to="/milestones/$milestoneId"
+          params={{ milestoneId: milestone.id }}
+          className="flex-1 text-sm font-medium hover:text-blue-400 transition-colors"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {milestone.name}
+        </Link>
         <StatusBadge status={milestone.status} />
         <div className="w-20">
           <ProgressBar value={milestone.progress} size="sm" />

package/src/components/TaskList.tsx

@@ -1,3 +1,4 @@
+import { Link } from '@tanstack/react-router'
 import { StatusDot } from './StatusDot'
 import { ExtraFieldsBadge } from './ExtraFieldsBadge'
 import type { Task } from '../lib/types'
@@ -16,13 +17,15 @@ export function TaskList({ tasks }: { tasks: Task[] }) {
       {tasks.map((task) => (
         <div key={task.id} className="flex items-center gap-2 py-1 text-sm">
           <StatusDot status={task.status} />
-          <span
-            className={
+          <Link
+            to="/tasks/$taskId"
+            params={{ taskId: task.id }}
+            className={`hover:text-blue-400 transition-colors ${
               task.status === 'completed' ? 'text-gray-500' : 'text-gray-200'
-            }
+            }`}
           >
             {task.name}
-          </span>
+          </Link>
           {task.notes && (
             <span className="text-xs text-gray-600 ml-auto truncate max-w-[200px]">
               {task.notes}

package/src/routeTree.gen.ts

@@ -14,6 +14,8 @@ import { Route as SearchRouteImport } from './routes/search'
 import { Route as MilestonesRouteImport } from './routes/milestones'
 import { Route as ActivityRouteImport } from './routes/activity'
 import { Route as IndexRouteImport } from './routes/index'
+import { Route as TasksTaskIdRouteImport } from './routes/tasks.$taskId'
+import { Route as MilestonesMilestoneIdRouteImport } from './routes/milestones.$milestoneId'
 import { Route as ApiWatchRouteImport } from './routes/api/watch'
 
 const TasksRoute = TasksRouteImport.update({
@@ -41,6 +43,16 @@ const IndexRoute = IndexRouteImport.update({
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const TasksTaskIdRoute = TasksTaskIdRouteImport.update({
+  id: '/$taskId',
+  path: '/$taskId',
+  getParentRoute: () => TasksRoute,
+} as any)
+const MilestonesMilestoneIdRoute = MilestonesMilestoneIdRouteImport.update({
+  id: '/$milestoneId',
+  path: '/$milestoneId',
+  getParentRoute: () => MilestonesRoute,
+} as any)
 const ApiWatchRoute = ApiWatchRouteImport.update({
   id: '/api/watch',
   path: '/api/watch',
@@ -50,27 +62,33 @@ const ApiWatchRoute = ApiWatchRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/activity': typeof ActivityRoute
-  '/milestones': typeof MilestonesRoute
+  '/milestones': typeof MilestonesRouteWithChildren
   '/search': typeof SearchRoute
-  '/tasks': typeof TasksRoute
+  '/tasks': typeof TasksRouteWithChildren
   '/api/watch': typeof ApiWatchRoute
+  '/milestones/$milestoneId': typeof MilestonesMilestoneIdRoute
+  '/tasks/$taskId': typeof TasksTaskIdRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/activity': typeof ActivityRoute
-  '/milestones': typeof MilestonesRoute
+  '/milestones': typeof MilestonesRouteWithChildren
   '/search': typeof SearchRoute
-  '/tasks': typeof TasksRoute
+  '/tasks': typeof TasksRouteWithChildren
   '/api/watch': typeof ApiWatchRoute
+  '/milestones/$milestoneId': typeof MilestonesMilestoneIdRoute
+  '/tasks/$taskId': typeof TasksTaskIdRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
   '/activity': typeof ActivityRoute
-  '/milestones': typeof MilestonesRoute
+  '/milestones': typeof MilestonesRouteWithChildren
   '/search': typeof SearchRoute
-  '/tasks': typeof TasksRoute
+  '/tasks': typeof TasksRouteWithChildren
   '/api/watch': typeof ApiWatchRoute
+  '/milestones/$milestoneId': typeof MilestonesMilestoneIdRoute
+  '/tasks/$taskId': typeof TasksTaskIdRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
@@ -81,8 +99,18 @@ export interface FileRouteTypes {
     | '/search'
     | '/tasks'
     | '/api/watch'
+    | '/milestones/$milestoneId'
+    | '/tasks/$taskId'
   fileRoutesByTo: FileRoutesByTo
-  to: '/' | '/activity' | '/milestones' | '/search' | '/tasks' | '/api/watch'
+  to:
+    | '/'
+    | '/activity'
+    | '/milestones'
+    | '/search'
+    | '/tasks'
+    | '/api/watch'
+    | '/milestones/$milestoneId'
+    | '/tasks/$taskId'
   id:
     | '__root__'
     | '/'
@@ -91,14 +119,16 @@ export interface FileRouteTypes {
     | '/search'
     | '/tasks'
     | '/api/watch'
+    | '/milestones/$milestoneId'
+    | '/tasks/$taskId'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   ActivityRoute: typeof ActivityRoute
-  MilestonesRoute: typeof MilestonesRoute
+  MilestonesRoute: typeof MilestonesRouteWithChildren
   SearchRoute: typeof SearchRoute
-  TasksRoute: typeof TasksRoute
+  TasksRoute: typeof TasksRouteWithChildren
   ApiWatchRoute: typeof ApiWatchRoute
 }
 
@@ -139,6 +169,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/tasks/$taskId': {
+      id: '/tasks/$taskId'
+      path: '/$taskId'
+      fullPath: '/tasks/$taskId'
+      preLoaderRoute: typeof TasksTaskIdRouteImport
+      parentRoute: typeof TasksRoute
+    }
+    '/milestones/$milestoneId': {
+      id: '/milestones/$milestoneId'
+      path: '/$milestoneId'
+      fullPath: '/milestones/$milestoneId'
+      preLoaderRoute: typeof MilestonesMilestoneIdRouteImport
+      parentRoute: typeof MilestonesRoute
+    }
     '/api/watch': {
       id: '/api/watch'
       path: '/api/watch'
@@ -149,12 +193,34 @@ declare module '@tanstack/react-router' {
   }
 }
 
+interface MilestonesRouteChildren {
+  MilestonesMilestoneIdRoute: typeof MilestonesMilestoneIdRoute
+}
+
+const MilestonesRouteChildren: MilestonesRouteChildren = {
+  MilestonesMilestoneIdRoute: MilestonesMilestoneIdRoute,
+}
+
+const MilestonesRouteWithChildren = MilestonesRoute._addFileChildren(
+  MilestonesRouteChildren,
+)
+
+interface TasksRouteChildren {
+  TasksTaskIdRoute: typeof TasksTaskIdRoute
+}
+
+const TasksRouteChildren: TasksRouteChildren = {
+  TasksTaskIdRoute: TasksTaskIdRoute,
+}
+
+const TasksRouteWithChildren = TasksRoute._addFileChildren(TasksRouteChildren)
+
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   ActivityRoute: ActivityRoute,
-  MilestonesRoute: MilestonesRoute,
+  MilestonesRoute: MilestonesRouteWithChildren,
   SearchRoute: SearchRoute,
-  TasksRoute: TasksRoute,
+  TasksRoute: TasksRouteWithChildren,
   ApiWatchRoute: ApiWatchRoute,
 }
 export const routeTree = rootRouteImport

package/src/routes/milestones.$milestoneId.tsx

@@ -0,0 +1,149 @@
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { useState, useEffect } from 'react'
+import { useProgressData } from '../contexts/ProgressContext'
+import { Breadcrumb } from '../components/Breadcrumb'
+import { DetailHeader } from '../components/DetailHeader'
+import { ProgressBar } from '../components/ProgressBar'
+import { StatusDot } from '../components/StatusDot'
+import { MarkdownContent } from '../components/MarkdownContent'
+import { getMarkdownContent, resolveMilestoneFile } from '../services/markdown.service'
+import type { MarkdownResult, ResolveFileResult } from '../services/markdown.service'
+
+export const Route = createFileRoute('/milestones/$milestoneId')({
+  component: MilestoneDetailPage,
+})
+
+/** Read ?repo=owner/repo from URL */
+function getGitHubParams(): { owner: string; repo: string } | undefined {
+  if (typeof window === 'undefined') return undefined
+  const params = new URLSearchParams(window.location.search)
+  const repo = params.get('repo')
+  if (!repo) return undefined
+  const parts = repo.split('/')
+  if (parts.length < 2) return undefined
+  return { owner: parts[0], repo: parts[1] }
+}
+
+function MilestoneDetailPage() {
+  const { milestoneId } = Route.useParams()
+  const data = useProgressData()
+  const [markdown, setMarkdown] = useState<string | null>(null)
+  const [markdownError, setMarkdownError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  const milestone = data?.milestones.find((m) => m.id === milestoneId)
+  const tasks = data?.tasks[milestoneId] || []
+
+  useEffect(() => {
+    if (!milestoneId) return
+
+    setLoading(true)
+    setMarkdown(null)
+    setMarkdownError(null)
+
+    const github = getGitHubParams()
+
+    resolveMilestoneFile({ data: { milestoneId, github } })
+      .then((resolveResult: ResolveFileResult) => {
+        if (!resolveResult.ok) {
+          setMarkdownError(resolveResult.error)
+          setLoading(false)
+          return
+        }
+
+        return getMarkdownContent({ data: { filePath: resolveResult.filePath, github } })
+          .then((mdResult: MarkdownResult) => {
+            if (mdResult.ok) {
+              setMarkdown(mdResult.content)
+            } else {
+              setMarkdownError(mdResult.error)
+            }
+          })
+      })
+      .catch((err: Error) => {
+        setMarkdownError(err.message)
+      })
+      .finally(() => {
+        setLoading(false)
+      })
+  }, [milestoneId])
+
+  if (!data || !milestone) {
+    return (
+      <div className="p-6">
+        <p className="text-gray-500 text-sm">Milestone not found: {milestoneId}</p>
+      </div>
+    )
+  }
+
+  const fields = [
+    ...(milestone.started ? [{ label: 'Started', value: milestone.started }] : []),
+    ...(milestone.completed ? [{ label: 'Completed', value: milestone.completed }] : []),
+    { label: 'Est', value: `${milestone.estimated_weeks} week${milestone.estimated_weeks === '1' ? '' : 's'}` },
+    { label: 'Tasks', value: `${milestone.tasks_completed}/${milestone.tasks_total}` },
+  ]
+
+  return (
+    <div className="p-6 max-w-4xl">
+      <Breadcrumb
+        items={[
+          { label: 'Milestones', href: '/milestones' },
+          { label: `${milestone.id.replace('milestone_', 'M')} — ${milestone.name}` },
+        ]}
+      />
+
+      <h1 className="text-xl font-semibold text-gray-100 mb-3">{milestone.name}</h1>
+
+      <div className="flex items-center gap-3 mb-4">
+        <div className="flex-1 max-w-xs">
+          <ProgressBar value={milestone.progress} size="sm" />
+        </div>
+        <span className="text-xs text-gray-500">{milestone.progress}%</span>
+      </div>
+
+      <DetailHeader status={milestone.status} fields={fields} />
+
+      {milestone.notes && (
+        <p className="text-sm text-gray-400 mb-6">{milestone.notes}</p>
+      )}
+
+      {/* Markdown content */}
+      {loading ? (
+        <p className="text-sm text-gray-600">Loading document...</p>
+      ) : markdown ? (
+        <MarkdownContent content={markdown} />
+      ) : markdownError ? (
+        <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4 text-sm text-gray-500">
+          No document found — {markdownError}
+        </div>
+      ) : null}
+
+      {/* Task list */}
+      {tasks.length > 0 && (
+        <div className="mt-8">
+          <h2 className="text-sm font-semibold text-gray-400 uppercase tracking-wider mb-3">
+            Tasks
+          </h2>
+          <div className="bg-gray-900/50 border border-gray-800 rounded-xl divide-y divide-gray-800">
+            {tasks.map((task) => (
+              <Link
+                key={task.id}
+                to="/tasks/$taskId"
+                params={{ taskId: task.id }}
+                className="flex items-center gap-2 px-4 py-2.5 text-sm hover:bg-gray-800/50 transition-colors first:rounded-t-xl last:rounded-b-xl"
+              >
+                <StatusDot status={task.status} />
+                <span className={task.status === 'completed' ? 'text-gray-500' : 'text-gray-200'}>
+                  {task.name}
+                </span>
+                {task.estimated_hours && (
+                  <span className="text-xs text-gray-600 ml-auto">{task.estimated_hours}h</span>
+                )}
+              </Link>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/routes/tasks.$taskId.tsx

@@ -0,0 +1,169 @@
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { useState, useEffect, useMemo } from 'react'
+import { useProgressData } from '../contexts/ProgressContext'
+import { Breadcrumb } from '../components/Breadcrumb'
+import { DetailHeader } from '../components/DetailHeader'
+import { MarkdownContent } from '../components/MarkdownContent'
+import { getMarkdownContent } from '../services/markdown.service'
+import { resolveTaskFile } from '../services/markdown.service'
+import type { MarkdownResult } from '../services/markdown.service'
+
+export const Route = createFileRoute('/tasks/$taskId')({
+  component: TaskDetailPage,
+})
+
+/** Read ?repo=owner/repo from URL */
+function getGitHubParams(): { owner: string; repo: string } | undefined {
+  if (typeof window === 'undefined') return undefined
+  const params = new URLSearchParams(window.location.search)
+  const repo = params.get('repo')
+  if (!repo) return undefined
+  const parts = repo.split('/')
+  if (parts.length < 2) return undefined
+  return { owner: parts[0], repo: parts[1] }
+}
+
+function TaskDetailPage() {
+  const { taskId } = Route.useParams()
+  const data = useProgressData()
+  const [markdown, setMarkdown] = useState<string | null>(null)
+  const [markdownError, setMarkdownError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  // Find the task and its parent milestone
+  const { task, milestone, siblings } = useMemo(() => {
+    if (!data) return { task: null, milestone: null, siblings: { prev: null, next: null } }
+
+    for (const ms of data.milestones) {
+      const msTaskList = data.tasks[ms.id] || []
+      const idx = msTaskList.findIndex((t) => t.id === taskId)
+      if (idx !== -1) {
+        return {
+          task: msTaskList[idx],
+          milestone: ms,
+          siblings: {
+            prev: idx > 0 ? msTaskList[idx - 1] : null,
+            next: idx < msTaskList.length - 1 ? msTaskList[idx + 1] : null,
+          },
+        }
+      }
+    }
+    return { task: null, milestone: null, siblings: { prev: null, next: null } }
+  }, [data, taskId])
+
+  useEffect(() => {
+    if (!task) return
+
+    setLoading(true)
+    setMarkdown(null)
+    setMarkdownError(null)
+
+    const filePath = resolveTaskFile(task)
+    if (!filePath) {
+      setMarkdownError('No file path for this task')
+      setLoading(false)
+      return
+    }
+
+    const github = getGitHubParams()
+
+    getMarkdownContent({ data: { filePath, github } })
+      .then((result: MarkdownResult) => {
+        if (result.ok) {
+          setMarkdown(result.content)
+        } else {
+          setMarkdownError(result.error)
+        }
+      })
+      .catch((err: Error) => {
+        setMarkdownError(err.message)
+      })
+      .finally(() => {
+        setLoading(false)
+      })
+  }, [task])
+
+  if (!data || !task || !milestone) {
+    return (
+      <div className="p-6">
+        <p className="text-gray-500 text-sm">Task not found: {taskId}</p>
+      </div>
+    )
+  }
+
+  const fields = [
+    { label: 'Est', value: `${task.estimated_hours}h` },
+    ...(task.completed_date ? [{ label: 'Completed', value: task.completed_date }] : []),
+    {
+      label: 'Milestone',
+      value: (
+        <Link
+          to="/milestones/$milestoneId"
+          params={{ milestoneId: milestone.id }}
+          className="text-blue-400 hover:underline"
+        >
+          {milestone.id.replace('milestone_', 'M')} — {milestone.name}
+        </Link>
+      ),
+    },
+  ]
+
+  return (
+    <div className="p-6 max-w-4xl">
+      <Breadcrumb
+        items={[
+          { label: 'Milestones', href: '/milestones' },
+          { label: `${milestone.id.replace('milestone_', 'M')} — ${milestone.name}`, href: `/milestones/${milestone.id}` },
+          { label: task.name },
+        ]}
+      />
+
+      <h1 className="text-xl font-semibold text-gray-100 mb-3">{task.name}</h1>
+
+      <DetailHeader status={task.status} fields={fields} />
+
+      {task.notes && (
+        <p className="text-sm text-gray-400 mb-6">{task.notes}</p>
+      )}
+
+      {/* Markdown content */}
+      {loading ? (
+        <p className="text-sm text-gray-600">Loading document...</p>
+      ) : markdown ? (
+        <MarkdownContent content={markdown} />
+      ) : markdownError ? (
+        <div className="bg-gray-900/50 border border-gray-800 rounded-xl p-4 text-sm text-gray-500">
+          No document found — {markdownError}
+        </div>
+      ) : null}
+
+      {/* Prev / Next navigation */}
+      {(siblings.prev || siblings.next) && (
+        <div className="mt-8 flex items-center justify-between border-t border-gray-800 pt-4">
+          {siblings.prev ? (
+            <Link
+              to="/tasks/$taskId"
+              params={{ taskId: siblings.prev.id }}
+              className="text-sm text-gray-400 hover:text-gray-200 transition-colors"
+            >
+              ← {siblings.prev.name}
+            </Link>
+          ) : (
+            <span />
+          )}
+          {siblings.next ? (
+            <Link
+              to="/tasks/$taskId"
+              params={{ taskId: siblings.next.id }}
+              className="text-sm text-gray-400 hover:text-gray-200 transition-colors"
+            >
+              {siblings.next.name} →
+            </Link>
+          ) : (
+            <span />
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/services/markdown.service.ts

@@ -0,0 +1,239 @@
+import { createServerFn } from '@tanstack/react-start'
+
+export type MarkdownResult =
+  | { ok: true; content: string; filePath: string }
+  | { ok: false; content: null; error: string }
+
+export type ResolveFileResult =
+  | { ok: true; filePath: string }
+  | { ok: false; filePath: null; error: string }
+
+/**
+ * Derives the project base path from PROGRESS_YAML_PATH.
+ * e.g. "/home/user/project/agent/progress.yaml" → "/home/user/project"
+ */
+function getBasePath(): string {
+  const progressPath = process.env.PROGRESS_YAML_PATH || './agent/progress.yaml'
+  // Strip "agent/progress.yaml" (or similar trailing segment) to get project root
+  return progressPath.replace(/\/agent\/progress\.yaml$/, '') || '.'
+}
+
+// ---------- getMarkdownContent ----------
+
+export const getMarkdownContent = createServerFn({ method: 'GET' })
+  .inputValidator((input: { filePath: string; github?: { owner: string; repo: string; branch?: string; token?: string } }) => input)
+  .handler(async ({ data: input }): Promise<MarkdownResult> => {
+    // GitHub mode
+    if (input.github) {
+      return fetchMarkdownFromGitHub(input.filePath, input.github)
+    }
+
+    // Local mode
+    return readMarkdownFromDisk(input.filePath)
+  })
+
+async function readMarkdownFromDisk(relativePath: string): Promise<MarkdownResult> {
+  try {
+    const fs = await import('fs')
+    const path = await import('path')
+
+    const basePath = getBasePath()
+    const fullPath = path.resolve(basePath, relativePath)
+
+    if (!fs.existsSync(fullPath)) {
+      return { ok: false, content: null, error: `File not found: ${relativePath}` }
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf-8')
+    return { ok: true, content, filePath: relativePath }
+  } catch (err: any) {
+    if (err?.code === 'ENOENT') {
+      return { ok: false, content: null, error: `File not found: ${relativePath}` }
+    }
+    if (err?.code === 'EACCES') {
+      return { ok: false, content: null, error: `Permission denied: ${relativePath}` }
+    }
+    return { ok: false, content: null, error: `Failed to read file: ${relativePath}` }
+  }
+}
+
+async function fetchMarkdownFromGitHub(
+  filePath: string,
+  github: { owner: string; repo: string; branch?: string; token?: string },
+): Promise<MarkdownResult> {
+  try {
+    let branch = github.branch
+    if (!branch) {
+      try {
+        const metaRes = await fetch(`https://api.github.com/repos/${github.owner}/${github.repo}`, {
+          headers: github.token ? { Authorization: `token ${github.token}` } : {},
+        })
+        if (metaRes.ok) {
+          const meta = (await metaRes.json()) as { default_branch?: string }
+          branch = meta.default_branch || 'main'
+        } else {
+          branch = 'main'
+        }
+      } catch {
+        branch = 'main'
+      }
+    }
+
+    const url = `https://api.github.com/repos/${github.owner}/${github.repo}/contents/${filePath}?ref=${branch}`
+    const headers: Record<string, string> = {
+      Accept: 'application/vnd.github.v3+json',
+    }
+    if (github.token) {
+      headers['Authorization'] = `token ${github.token}`
+    }
+
+    const response = await fetch(url, { headers })
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        return { ok: false, content: null, error: `File not found: ${filePath}` }
+      }
+      if (response.status === 403) {
+        return { ok: false, content: null, error: `GitHub rate limit or permission denied for: ${filePath}` }
+      }
+      return { ok: false, content: null, error: `GitHub returned ${response.status}: ${response.statusText}` }
+    }
+
+    const json = (await response.json()) as { content?: string; encoding?: string }
+    if (!json.content) {
+      return { ok: false, content: null, error: `No content returned for: ${filePath}` }
+    }
+
+    const content = Buffer.from(json.content, 'base64').toString('utf-8')
+    return { ok: true, content, filePath }
+  } catch (err) {
+    return {
+      ok: false,
+      content: null,
+      error: err instanceof Error ? err.message : `Failed to fetch from GitHub: ${filePath}`,
+    }
+  }
+}
+
+// ---------- resolveMilestoneFile ----------
+
+export const resolveMilestoneFile = createServerFn({ method: 'GET' })
+  .inputValidator((input: { milestoneId: string; github?: { owner: string; repo: string; branch?: string; token?: string } }) => input)
+  .handler(async ({ data: input }): Promise<ResolveFileResult> => {
+    // Extract numeric part: "milestone_1" → "1"
+    const match = input.milestoneId.match(/milestone_(\d+)/)
+    if (!match) {
+      return { ok: false, filePath: null, error: `Invalid milestone id format: ${input.milestoneId}` }
+    }
+    const num = match[1]
+    const dirPath = 'agent/milestones'
+
+    if (input.github) {
+      return resolveMilestoneFromGitHub(num, dirPath, input.github)
+    }
+
+    return resolveMilestoneFromDisk(num, dirPath)
+  })
+
+async function resolveMilestoneFromDisk(num: string, dirPath: string): Promise<ResolveFileResult> {
+  try {
+    const fs = await import('fs')
+    const path = await import('path')
+
+    const basePath = getBasePath()
+    const fullDir = path.resolve(basePath, dirPath)
+
+    if (!fs.existsSync(fullDir)) {
+      return { ok: false, filePath: null, error: `Milestones directory not found: ${dirPath}` }
+    }
+
+    const files = fs.readdirSync(fullDir)
+    const matched = files.find(
+      (f: string) => f.startsWith(`milestone-${num}-`) && f.endsWith('.md') && !f.includes('template'),
+    )
+
+    if (!matched) {
+      return { ok: false, filePath: null, error: `No milestone file found for milestone_${num}` }
+    }
+
+    return { ok: true, filePath: `${dirPath}/${matched}` }
+  } catch (err: any) {
+    if (err?.code === 'EACCES') {
+      return { ok: false, filePath: null, error: `Permission denied: ${dirPath}` }
+    }
+    return { ok: false, filePath: null, error: `Failed to scan milestones directory` }
+  }
+}
+
+async function resolveMilestoneFromGitHub(
+  num: string,
+  dirPath: string,
+  github: { owner: string; repo: string; branch?: string; token?: string },
+): Promise<ResolveFileResult> {
+  try {
+    let branch = github.branch
+    if (!branch) {
+      try {
+        const metaRes = await fetch(`https://api.github.com/repos/${github.owner}/${github.repo}`, {
+          headers: github.token ? { Authorization: `token ${github.token}` } : {},
+        })
+        if (metaRes.ok) {
+          const meta = (await metaRes.json()) as { default_branch?: string }
+          branch = meta.default_branch || 'main'
+        } else {
+          branch = 'main'
+        }
+      } catch {
+        branch = 'main'
+      }
+    }
+
+    const url = `https://api.github.com/repos/${github.owner}/${github.repo}/contents/${dirPath}?ref=${branch}`
+    const headers: Record<string, string> = {
+      Accept: 'application/vnd.github.v3+json',
+    }
+    if (github.token) {
+      headers['Authorization'] = `token ${github.token}`
+    }
+
+    const response = await fetch(url, { headers })
+
+    if (!response.ok) {
+      if (response.status === 404) {
+        return { ok: false, filePath: null, error: `Milestones directory not found on GitHub: ${dirPath}` }
+      }
+      if (response.status === 403) {
+        return { ok: false, filePath: null, error: `GitHub rate limit or permission denied` }
+      }
+      return { ok: false, filePath: null, error: `GitHub returned ${response.status}: ${response.statusText}` }
+    }
+
+    const entries = (await response.json()) as Array<{ name: string; path: string; type: string }>
+    const matched = entries.find(
+      (e) => e.name.startsWith(`milestone-${num}-`) && e.name.endsWith('.md') && !e.name.includes('template'),
+    )
+
+    if (!matched) {
+      return { ok: false, filePath: null, error: `No milestone file found for milestone_${num}` }
+    }
+
+    return { ok: true, filePath: matched.path }
+  } catch (err) {
+    return {
+      ok: false,
+      filePath: null,
+      error: err instanceof Error ? err.message : `Failed to list milestones from GitHub`,
+    }
+  }
+}
+
+// ---------- resolveTaskFile ----------
+
+/**
+ * Resolves the markdown file path for a task.
+ * This is a plain function (not a server function) since task data
+ * including the `file` field is already available client-side.
+ */
+export function resolveTaskFile(task: { file?: string } | null | undefined): string | null {
+  return task?.file || null
+}

package/src/styles.css

@@ -1,4 +1,6 @@
 @import "tailwindcss";
+@plugin "@tailwindcss/typography";
+@import "highlight.js/styles/github-dark.css";
 
 html {
   @apply bg-gray-950;