@stevecastaneda/paseo-progress 1.5.1 → 1.7.0

package/README.md

@@ -18,9 +18,9 @@ The dashboard shows:
 
 <img src="images/2-ticket.png" alt="A ticket's story: its status, time against the estimate, the agent on it, and its timeline" width="400"> <img src="images/3-question.png" alt="A question waiting for an answer, with lettered options, the agent's recommendation and Copy buttons" width="400">
 
-<img src="images/5-settings.png" alt="Progress settings in Paseo: the Questions setting set to Work around, and the Language setting set to System" width="600">
+<img src="images/5-settings.png" alt="Progress settings in Paseo: Questions set to Work around, Language set to System, and the Agent Skills section with View skill" width="600">
 
-The panel lives in Explorer, beside the agent chat, so you can watch both. Open it from Command Center with **Open Progress**. The cog at the top right of the panel opens the plugin's Settings. After an update, the panel shows what's new in that version once. When questions are waiting or something is stuck, a pill above the message box says so, for example `3 questions`. With something stuck too, it shortens to `3Q · 1 stuck` to fit. Pressing it opens a popover with each open question, its choices and their Copy buttons, and what is stuck, so you can answer without leaving the chat. **Open Progress** at the bottom opens the panel in Explorer.
+The panel lives in Explorer, beside the agent chat, so you can watch both. Open it from Command Center with **Open Progress**. The cog at the top right of the panel opens the plugin's Settings. After an update, the panel shows what's new once, including any versions you skipped. When questions are waiting or something is stuck, a pill above the message box says so, for example `3 questions`. With something stuck too, it shortens to `3Q · 1 stuck` to fit. Pressing it opens a popover with each open question, its choices and their Copy buttons, and what is stuck, so you can answer without leaving the chat. **Open Progress** at the bottom opens the panel in Explorer.
 
 <img src="images/4-pill.png" alt="The pill above the message box, showing two questions waiting" width="600">
 
@@ -82,7 +82,7 @@ Earlier versions kept progress in `.scratch/` in each worktree, hidden by a `.sc
 
 ## Agent skill
 
-The plugin ships an agent skill, `paseo-progress`, that tells agents when to run each command during a multi-ticket job: set up the run, move tickets through their stages, ask questions, and finish. It stays short and leaves the details to `paseo-progress --help`. Press **Install skill** in the Progress panel. It links `paseo-progress` into `~/.agents/skills`, `~/.claude/skills`, and `~/.codex/skills` (the folders Paseo installs its own skills into), pointing at the copy of the plugin Paseo runs, so plugin updates reach agents. On Windows the links are junctions, which don't need admin rights or Developer Mode. If Paseo later runs the plugin from somewhere else, the button changes to **Update skill**. It never replaces a skill it didn't link; that folder is skipped.
+The plugin ships an agent skill, `paseo-progress`, that tells agents when to run each command during a multi-ticket job: set up the run, move tickets through their stages, ask questions, and finish. It stays short and leaves the details to `paseo-progress --help`. Press **Install skill** in the Progress panel. It links `paseo-progress` into `~/.agents/skills`, `~/.claude/skills`, and `~/.codex/skills` (the folders Paseo installs its own skills into), pointing at the copy of the plugin Paseo runs, so plugin updates reach agents. On Windows the links are junctions, which don't need admin rights or Developer Mode. Paseo puts each plugin update in a new folder, so when Progress starts it repoints the links it made to that folder. If it can't, the button changes to **Update skill**. It never replaces a skill it didn't link; that folder is skipped. To read what agents get, open **View skill** under Agent Skills in Progress settings.
 
 From a terminal instead:
 
@@ -145,9 +145,20 @@ The progress file, `progress.jsonl`, holds one JSON event per line, each with a
 
 ## Changelog
 
+### 1.7.0
+
+- [New] **See screenshots full screen.** In an image preview, press **Full screen** or click the image to fill the window with it. Esc takes you back to the preview, still open. The arrow keys still move between images. A long screenshot also gets **Fit to width**, which fills the width so you can scroll down it.
+- [Fixed] **A preview that can't load says why right away.** A missing file, one too large to preview, or one outside the worktree showed a spinner for several seconds before the reason.
+
+### 1.6.0
+
+- [New] **Read the skill in Settings.** Progress settings has an Agent Skills section. **View skill** shows the instructions agents get, and **Install skill** appears there when the skill isn't installed.
+- [Fixed] **The skill stays linked after updates.** Paseo puts each plugin update in a new folder, so after every update Progress asked you to press **Update skill**, even when the skill hadn't changed. Progress now fixes the link itself.
+- [Improved] **What's new catches you up.** If you skip an update, What's new now shows the changes from every version you missed, newest first.
+- [Fixed] **Code inside lists.** A code block inside a list item in a write-up no longer shows shifted to the right.
+
 ### 1.5.1
 
-- [New] **Simplified Chinese.** Progress now comes in English and Simplified Chinese. Pick one under Display in Progress settings, or let it follow each device's language. Thanks to @xzthemeofsss for the translation.
 - [Improved] **Settings screenshot.** It shows the new Language setting.
 
 ### 1.5.0

package/client/deliverables.tsx

@@ -62,7 +62,7 @@ export function DeliverablesList({ colors, deliverables, now, workspaceId, works
       ))}
       <ShowMoreRow colors={colors} total={deliverables.length} paged={paged} />
       <StackedDialog colors={colors} now={now} onClose={() => setPreviewing(null)} context={{ workspaceId, workspaceDirectory, navigation }}
-        root={previewing ? { kind: "preview", attachment: previewing, group: galleryFiles(deliverables.map(deliverableAttachment)) } : null} />
+        root={previewing ? { kind: "preview", attachment: previewing, group: galleryFiles(deliverables.map(deliverableAttachment)), fullScreen: false } : null} />
     </View>
   );
 }

package/client/dialog-stack.tsx

@@ -5,6 +5,7 @@ import type { Dashboard, Question } from "../shared/dashboard";
 import { type Attachment, attachmentIcon, useAttachmentOpener } from "./attachments";
 import { NarrowProvider } from "./narrow";
 import { BackButton, galleryFiles, PreviewContent } from "./preview";
+import { previewKind } from "../shared/attachments";
 import { QuestionView, useCopy } from "./questions";
 import { TicketStoryView } from "./ticket-dialog";
 import { ProgressLanguageProvider } from "./language";
@@ -12,11 +13,13 @@ import { ProgressLanguageProvider } from "./language";
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 type AttachmentContext = { workspaceId: string; workspaceDirectory: string; navigation?: PluginWorkspacePanelProps["navigation"] };
 
-// What the dialog is showing. A preview keeps the files beside it for Previous and Next.
+// What the dialog is showing. A preview keeps the files beside it for Previous and Next,
+// and whether its image fills the window. `leftFullScreen` puts focus back on the
+// Full screen button; it lives here because leaving can remount the preview.
 export type Step =
   | { kind: "ticket"; id: string }
   | { kind: "question"; id: string }
-  | { kind: "preview"; attachment: Attachment; group: Attachment[] };
+  | { kind: "preview"; attachment: Attachment; group: Attachment[]; fullScreen: boolean; leftFullScreen?: boolean };
 
 // Paseo gives each dialog its own backdrop, so opening a second one darkens
 // the screen while the first fades out; steps swap content inside this one instead.
@@ -43,7 +46,7 @@ export function StackedDialog({ colors, root, onClose, questions = [], dashboard
   const group = useRef<Attachment[]>([]);
   const push = (step: Step) => setSteps((current) => [...current, step]);
   const replaceTop = (step: Step) => setSteps((current) => [...current.slice(0, -1), step]);
-  const opener = useAttachmentOpener({ ...context, onPreview: (attachment) => push({ kind: "preview", attachment, group: galleryFiles(group.current) }) });
+  const opener = useAttachmentOpener({ ...context, onPreview: (attachment) => push({ kind: "preview", attachment, group: galleryFiles(group.current), fullScreen: false }) });
   const openAttachment = (attachment: Attachment, from: Attachment[]) => {
     group.current = from;
     // A link opens elsewhere in Paseo; close first so it isn't left behind the dialog.
@@ -62,6 +65,7 @@ export function StackedDialog({ colors, root, onClose, questions = [], dashboard
   const ticket = top?.kind === "ticket" ? dashboard?.tickets.find((candidate) => candidate.id === top.id) : undefined;
   const question = top?.kind === "question" ? questions.find((candidate) => candidate.id === top.id) : undefined;
   const preview = top?.kind === "preview" ? top : undefined;
+  const setFullScreen = (on: boolean) => preview && replaceTop({ ...preview, fullScreen: on, leftFullScreen: !on });
   // The ticket or question it opened on went away (answered elsewhere, or a new run): close rather than show a blank dialog.
   const rootMissing = root !== null && (root.kind === "ticket" ? !dashboard?.tickets.some((candidate) => candidate.id === root.id)
     : root.kind === "question" ? !questions.some((candidate) => candidate.id === root.id) : false);
@@ -74,9 +78,16 @@ export function StackedDialog({ colors, root, onClose, questions = [], dashboard
 
   return (
     <Modal title={title} icon={<Icon name={icon} size={16} color={colors.foregroundMuted} />}
-      open={Boolean(root)} onOpenChange={(next) => { if (!next) onClose(); }}>
-      {/* One Modal.Content for every step: replacing it would re-present the sheet on phones. */}
-      <Modal.Content scrollable={!(preview && previewLong)}>
+      open={Boolean(root)} onOpenChange={(next) => {
+        if (next) return;
+        // Esc leaves full screen first; the dialog stays open under it.
+        if (preview?.fullScreen) setFullScreen(false);
+        else onClose();
+      }}>
+      {/* One Modal.Content for every step: replacing it would re-present the sheet on phones.
+          Full screen turns its scrolling off. The image's fixed position reaches the window only
+          when no ancestor has a transform, and a scroll view has one. */}
+      <Modal.Content scrollable={!(preview && (previewLong || preview.fullScreen))}>
       <ProgressLanguageProvider>
       {/* A dialog has room for clock times, however narrow the panel that opened it. */}
       <NarrowProvider value={false}>
@@ -84,7 +95,8 @@ export function StackedDialog({ colors, root, onClose, questions = [], dashboard
         <PreviewContent colors={colors} attachment={preview.attachment} workspaceId={context.workspaceId} workspaceDirectory={context.workspaceDirectory}
           onOpenOnHost={() => { onClose(); void opener.openOnHost(preview.attachment); }}
           onCopyPath={() => void opener.copyPath(preview.attachment)} onBack={back}
-          gallery={{ items: preview.group, onSelect: (attachment) => replaceTop({ ...preview, attachment }) }} onLong={setPreviewLong}
+          gallery={{ items: preview.group, onSelect: (attachment) => replaceTop({ ...preview, attachment, fullScreen: preview.fullScreen && previewKind(attachment.path ?? "") === "image", leftFullScreen: false }) }}
+          onLong={setPreviewLong} fullScreen={preview.fullScreen} leftFullScreen={preview.leftFullScreen === true} onFullScreen={setFullScreen}
           onOpenEntry={openAttachment} />
       ) : (
         <>

package/client/launcher.tsx

@@ -70,23 +70,28 @@ export function LauncherBanner({ colors, host }: { colors: Colors; host: PluginW
   return <SetupBanner colors={colors} icon="Terminal" notice={notice} pending={mutation.isPending} onPress={() => mutation.mutate()} />;
 }
 
-export function SkillBanner({ colors, host }: { colors: Colors; host: PluginWorkspacePanelProps["host"] }) {
+// The panel banner and Settings share the status and the install action.
+export function useSkill(hostId: string) {
   const { messages: m } = useProgressLanguage();
   const fetchStatus = useRpc(getSkillStatus);
   const install = useRpc(installSkill);
   const queryClient = useQueryClient();
   const toast = useToast();
-  const status = useQuery({ queryKey: skillQueryKey(host.id), queryFn: () => fetchStatus({}), staleTime: 60_000 });
+  const status = useQuery({ queryKey: skillQueryKey(hostId), queryFn: () => fetchStatus({}), staleTime: 60_000 });
   const mutation = useMutation({
     mutationFn: () => install({}),
     onSuccess: (next) => {
-      queryClient.setQueryData(skillQueryKey(host.id), next);
+      queryClient.setQueryData(skillQueryKey(hostId), next);
       toast.show(m.skillInstalled, { variant: "success" });
     },
     onError: (error) => toast.error(errorText(error, m.installSkillFailure)),
   });
-  const notice = status.data ? skillNotice(status.data, m) : null;
-  return <SetupBanner colors={colors} icon="Sparkles" notice={notice} pending={mutation.isPending} onPress={() => mutation.mutate()} />;
+  return { notice: status.data ? skillNotice(status.data, m) : null, state: status.data?.state, pending: mutation.isPending, install: () => mutation.mutate() };
+}
+
+export function SkillBanner({ colors, host }: { colors: Colors; host: PluginWorkspacePanelProps["host"] }) {
+  const skill = useSkill(host.id);
+  return <SetupBanner colors={colors} icon="Sparkles" notice={skill.notice} pending={skill.pending} onPress={skill.install} />;
 }
 
 function SetupBanner({ colors, icon, notice, pending, onPress }: {

package/client/locales/en.ts

@@ -86,6 +86,7 @@ export const messages: ProgressMessages = {
   showFewer: "Show fewer",
   seeWhatsNew: "See what’s new",
   dismissWhatsNew: "Dismiss what's new",
+  whatsNewAll: "What’s new in Progress",
   gotIt: "Got it",
   loadingPreview: "Loading preview",
   truncatedText: "Showing the first 256 KB.",
@@ -95,6 +96,10 @@ export const messages: ProgressMessages = {
   back: "Back",
   previousFile: "Previous file",
   nextFile: "Next file",
+  fullScreen: "Full screen",
+  exitFullScreen: "Exit full screen",
+  fitToWidth: "Fit to width",
+  fitToScreen: "Fit to screen",
   videoChanged: "the video changed while it was loading. Try again.",
   localHistory: "Run history stays on this computer.",
   historyStopped: "Runs will stay on this computer. Files already saved stay in the repo.",
@@ -124,6 +129,11 @@ export const messages: ProgressMessages = {
   skillForeign: "Something else already exists at every paseo-progress skill path, so the plugin won't install the skill.",
   skillInstalled: "Installed the paseo-progress skill. New agent sessions will use it.",
   installSkillFailure: "Could not install the skill.",
+  agentSkill: "Agent Skills",
+  skillName: "paseo-progress skill",
+  viewSkill: "View skill",
+  skillNotInstalled: "Not installed",
+  skillLinkOutdated: "Link out of date",
   installing: "Installing…",
   loadingSettings: "Loading settings…",
   tryAgain: "Try again",
@@ -178,6 +188,7 @@ export const messages: ProgressMessages = {
   readError: (error: string) => `Couldn't read it here: ${error}`,
   showOlder: (count: number) => `Show ${count} older`,
   newVersion: (version: string) => `New in ${version}:`,
+  updatedTo: (version: string) => `Updated to ${version}:`,
   whatsNewTitle: (version: string) => `What’s new in Progress ${version}`,
   loadingVideo: (percent: number) => `Loading video, ${percent}%`,
   previewError: (error: string) => `Could not preview it: ${error}`,

package/client/locales/zh-CN.ts

@@ -86,6 +86,7 @@ export const messages: ProgressMessages = {
   showFewer: "收起",
   seeWhatsNew: "查看更新",
   dismissWhatsNew: "关闭更新提示",
+  whatsNewAll: "Progress 更新内容",
   gotIt: "知道了",
   loadingPreview: "正在加载预览",
   truncatedText: "仅显示前 256 KB。",
@@ -95,6 +96,10 @@ export const messages: ProgressMessages = {
   back: "返回",
   previousFile: "上一个文件",
   nextFile: "下一个文件",
+  fullScreen: "全屏",
+  exitFullScreen: "退出全屏",
+  fitToWidth: "适应宽度",
+  fitToScreen: "适应屏幕",
   videoChanged: "视频在加载过程中发生了变化。请重试。",
   localHistory: "运行记录保存在这台电脑上。",
   historyStopped: "运行记录将保存在这台电脑上。已保存的文件会保留在仓库中。",
@@ -124,6 +129,11 @@ export const messages: ProgressMessages = {
   skillForeign: "所有 paseo-progress 技能路径都已被其他内容占用，插件无法安装技能。",
   skillInstalled: "已安装 paseo-progress 技能。新的智能体会话将使用此技能。",
   installSkillFailure: "无法安装技能。",
+  agentSkill: "智能体技能",
+  skillName: "paseo-progress 技能",
+  viewSkill: "查看技能",
+  skillNotInstalled: "未安装",
+  skillLinkOutdated: "链接已过期",
   installing: "安装中…",
   loadingSettings: "正在加载设置…",
   tryAgain: "重试",
@@ -178,6 +188,7 @@ export const messages: ProgressMessages = {
   readError: (error: string) => `无法在此读取：${error}`,
   showOlder: (count: number) => `显示更早的 ${count} 项`,
   newVersion: (version: string) => `${version} 的更新：`,
+  updatedTo: (version: string) => `已更新到 ${version}：`,
   whatsNewTitle: (version: string) => `Progress ${version} 更新内容`,
   loadingVideo: (percent: number) => `正在加载视频，${percent}%`,
   previewError: (error: string) => `无法预览：${error}`,

package/client/messages.ts

@@ -68,6 +68,7 @@ export interface ProgressMessages {
   showFewer: string;
   seeWhatsNew: string;
   dismissWhatsNew: string;
+  whatsNewAll: string;
   gotIt: string;
   loadingPreview: string;
   truncatedText: string;
@@ -77,6 +78,10 @@ export interface ProgressMessages {
   back: string;
   previousFile: string;
   nextFile: string;
+  fullScreen: string;
+  exitFullScreen: string;
+  fitToWidth: string;
+  fitToScreen: string;
   videoChanged: string;
   localHistory: string;
   historyStopped: string;
@@ -106,6 +111,11 @@ export interface ProgressMessages {
   skillForeign: string;
   skillInstalled: string;
   installSkillFailure: string;
+  agentSkill: string;
+  skillName: string;
+  viewSkill: string;
+  skillNotInstalled: string;
+  skillLinkOutdated: string;
   installing: string;
   loadingSettings: string;
   tryAgain: string;
@@ -160,6 +170,7 @@ export interface ProgressMessages {
   readError: (error: string) => string;
   showOlder: (count: number) => string;
   newVersion: (version: string) => string;
+  updatedTo: (version: string) => string;
   whatsNewTitle: (version: string) => string;
   loadingVideo: (percent: number) => string;
   previewError: (error: string) => string;

package/client/pill-popover.tsx

@@ -59,7 +59,7 @@ export function AttentionPopover({ theme, host, layout, workspaceId, close, open
         </Text>
       )}
       <StackedDialog colors={colors} now={Date.now()} onClose={() => setPreviewing(null)} context={{ workspaceId, workspaceDirectory: root }}
-        root={previewing ? { kind: "preview", ...previewing } : null} />
+        root={previewing ? { kind: "preview", ...previewing, fullScreen: false } : null} />
       <View style={{ paddingTop: touch ? 12 : 8, borderTopWidth: 1, borderTopColor: colors.border }}>
         {/* A full 44pt touch target on phones; desktop keeps the compact button. */}
         <PressScale accessibilityRole="button" onPress={() => { close(); openPanel(); }}

package/client/preview.tsx

@@ -1,8 +1,8 @@
 import { type PluginWorkspacePanelProps, useRpc } from "@getpaseo/plugin/client";
 import { Icon, ScrollView } from "@getpaseo/plugin/client/react-native";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import React, { useEffect, useRef } from "react";
-import { ActivityIndicator, Image, Platform, Text, useWindowDimensions, View, type ViewStyle } from "react-native";
+import React, { useEffect, useRef, useState } from "react";
+import { ActivityIndicator, Image, Platform, Pressable, Text, useWindowDimensions, View, type ViewStyle } from "react-native";
 import { ATTACHMENT_ROW, type Attachment, AttachmentList, isPreviewable } from "./attachments";
 import { errorText } from "./errors";
 import { folderAttachments, isFolder, previewKind } from "../shared/attachments";
@@ -39,7 +39,12 @@ type PreviewProps = {
 
 // `onLong` says when the file is too tall for the dialog, so the host turns off
 // its own scrolling and the file scrolls with the actions pinned below.
-export function PreviewContent({ colors, attachment, workspaceId, workspaceDirectory, onOpenOnHost, onCopyPath, onBack, gallery, onOpenEntry, onLong }: PreviewProps & { onLong(long: boolean): void }) {
+export function PreviewContent({ colors, attachment, workspaceId, workspaceDirectory, onOpenOnHost, onCopyPath, onBack, gallery, onOpenEntry, onLong, fullScreen, leftFullScreen, onFullScreen }: PreviewProps & {
+  onLong(long: boolean): void;
+  fullScreen: boolean;
+  leftFullScreen: boolean;
+  onFullScreen(on: boolean): void;
+}) {
   const { messages: m } = useProgressLanguage();
   const fetchPreview = useRpc(previewDeliverable);
   const readPiece = useRpc(readDeliverablePiece);
@@ -60,7 +65,7 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
     // and so on, so a tall image made the dialog jump between two sizes until closed.
     queryFn: async () => {
       const data = await fetchPreview({ workspaceId, workspaceDirectory, ref: target.ref });
-      if (data.kind === "image") return { ...data, ratio: await imageRatio(data.dataUri) };
+      if (data.kind === "image") return { ...data, ...await imageSize(data.dataUri) };
       if (data.kind !== "video") return data;
       queryClient.setQueryData(loadingKey(target), 0);
       const video = await loadVideo({
@@ -76,6 +81,9 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
     // Images arrive as data URIs up to ~13 MB and videos run to 200 MB; let them
     // go soon after the dialog moves on.
     gcTime: 30_000,
+    // A file that's missing, too large or outside the worktree fails the same way
+    // every time, so the reason shows at once instead of after seconds of retries.
+    retry: false,
   });
   // Stepping to another file keeps this one on screen (dimmed) until the next loads,
   // so the dialog doesn't collapse to a spinner and back.
@@ -102,15 +110,39 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
   useArrowKeys(canStep ? step : null);
   // Next has focus when the preview opens, so Enter or Space moves on too.
   const nextButton = useRef<View>(null);
+  const fullScreenButton = useRef<View>(null);
+  // Leaving full screen puts focus back on the Full screen button without the ring
+  // Esc would draw, which read as if the arrows now acted on it. Set during render so
+  // the ring never paints, and from `leftFullScreen` because leaving can remount this.
+  const [quiet, setQuiet] = useState(leftFullScreen && !fullScreen);
+  const [wasFullScreen, setWasFullScreen] = useState(fullScreen);
+  if (wasFullScreen !== fullScreen) {
+    setWasFullScreen(fullScreen);
+    setQuiet(!fullScreen && leftFullScreen);
+  }
   useEffect(() => {
-    (nextButton.current as { focus?(): void } | null)?.focus?.();
-  }, []);
+    if (fullScreen) return;
+    const restore = leftFullScreen && fullScreenButton.current !== null;
+    if (!restore) setQuiet(false);
+    focus(restore ? fullScreenButton : nextButton);
+  }, [fullScreen]);
   // Screenshots and recordings vary from phone-tall to full-width; size to the real
   // file. While stepping, the dimmed one on screen keeps its shape until the next arrives.
   const aspectRatio = preview.data && "ratio" in preview.data && preview.data.ratio ? preview.data.ratio : 16 / 10;
   // A video fits the dialog whole, so the controls along its bottom stay in view
   // without scrolling. A tall image scrolls instead, to keep it readable.
-  const { height: windowHeight } = useWindowDimensions();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+  // Phones and narrow windows get Paseo's bottom sheet, whose transforms would
+  // keep the full-screen layer inside it.
+  const fullScreenFits = Platform.OS === "web" && windowWidth >= COMPACT_BELOW;
+  // By the file, not the data: while stepping, the data is still the last file's.
+  const canFullScreen = fullScreenFits && previewKind(attachment.path ?? "") === "image" && preview.data?.kind === "image";
+  // While stepping, the last image fills the layer until the next arrives. A file
+  // that fails to load has no data at all, so full screen ends with it.
+  const showsLayer = fullScreenFits && preview.data?.kind === "image";
+  useEffect(() => {
+    if (fullScreen && !preview.isPending && !showsLayer) onFullScreen(false);
+  }, [fullScreen, preview.isPending, showsLayer]);
   const room = roomForContent(windowHeight);
   const maxMediaHeight = preview.data?.kind === "video" ? Math.min(640, Math.max(200, room)) : 640;
   const mediaStyle = { width: "100%", aspectRatio, maxHeight: maxMediaHeight, borderRadius: 6, ...imageOutline(colors), backgroundColor: colors.surface1, opacity: stepping ? 0.6 : 1 } as const;
@@ -152,7 +184,11 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
           dimmed={stepping} onOpen={onOpenEntry} />
       ) : null}
       {preview.data?.kind === "image" ? (
-        <Image accessibilityLabel={attachment.title} source={{ uri: preview.data.dataUri }} resizeMode="contain" style={mediaStyle} />
+        // The Full screen button is the keyboard's way in, so the image isn't a second tab stop.
+        <Pressable disabled={!canFullScreen} focusable={false} onPress={() => onFullScreen(true)}
+          style={{ width: "100%", cursor: canFullScreen ? "zoom-in" as unknown as ViewStyle["cursor"] : undefined }}>
+          <Image accessibilityLabel={attachment.title} source={{ uri: preview.data.dataUri }} resizeMode="contain" style={mediaStyle} />
+        </Pressable>
       ) : null}
       {preview.data?.kind === "video" ? <VideoPlayer video={preview.data.video} label={attachment.title} style={mediaStyle} /> : null}
     </>
@@ -182,28 +218,136 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
         {onBack ? <BackButton colors={colors} onPress={onBack} /> : null}
       </View>
       {canStep ? <Stepper colors={colors} index={index} count={items.length} onStep={step} nextRef={nextButton} /> : null}
-      <View style={{ flex: 1, alignItems: "flex-end" }}>
+      <View style={{ flex: 1, flexDirection: "row", alignItems: "center", justifyContent: "flex-end", gap: 8 }}>
+        {canFullScreen ? (
+          // An inline outline beats Paseo's :focus-visible ring.
+          <DialogButton ref={fullScreenButton} colors={colors} icon="Maximize2" accessibilityLabel={m.fullScreen} onPress={() => onFullScreen(true)}
+            outerStyle={quiet ? { outlineWidth: 0 } : undefined} onBlur={() => setQuiet(false)} />
+        ) : null}
         {canOpen ? <DialogButton colors={colors} icon="ExternalLink" label={m.open} accessibilityLabel={m.openDefault} onPress={onOpenOnHost} /> : null}
       </View>
     </View>
   );
-  return long ? (
+  const layerShown = fullScreen && showsLayer;
+  // An SVG stays sharp at any size, so only a bitmap stops at its own pixels. An
+  // icon's SVG can say it's 24px wide.
+  const fullScreenLayer = layerShown && preview.data?.kind === "image" ? (
+    <FullScreenImage title={attachment.title} uri={preview.data.dataUri} ratio={aspectRatio} dimmed={stepping} onExit={() => onFullScreen(false)}
+      naturalWidth={preview.data.dataUri.startsWith("data:image/svg+xml") ? null : preview.data.width} />
+  ) : null;
+  // Paseo's focus trap counts the controls under the layer, so Shift+Tab would
+  // reach a hidden Open. Inert takes them out until full screen ends.
+  const body = useRef<View>(null);
+  useEffect(() => {
+    if (!layerShown) return;
+    const element = body.current as unknown as { setAttribute?(name: string, value: string): void; removeAttribute?(name: string): void } | null;
+    element?.setAttribute?.("inert", "");
+    return () => element?.removeAttribute?.("inert");
+  }, [layerShown]);
+  return (
     <>
-      <ScrollView style={{ flex: 1 }} contentContainerStyle={{ gap: 12 }}>{content}</ScrollView>
-      <View style={{ marginTop: 8 }}>{path}</View>
-      {actions}
+      {long ? (
+        <View ref={body} style={{ flex: 1 }}>
+          <ScrollView style={{ flex: 1 }} contentContainerStyle={{ gap: 12 }}>{content}</ScrollView>
+          <View style={{ marginTop: 8 }}>{path}</View>
+          {actions}
+        </View>
+      ) : (
+        <View ref={body} style={{ gap: 20 }}>
+          <View style={{ gap: 8 }}>
+            <View style={{ gap: 12 }}>{content}</View>
+            {path}
+          </View>
+          {actions}
+        </View>
+      )}
+      {fullScreenLayer}
     </>
-  ) : (
-    <View style={{ gap: 20 }}>
-      <View style={{ gap: 8 }}>
-        <View style={{ gap: 12 }}>{content}</View>
-        {path}
+  );
+}
+
+const FULL_SCREEN_MARGIN = 24;
+const FULL_SCREEN_BAR = 52;
+
+// The image over the whole window, never past its own pixels. It fits whole, or a
+// long one can fill the width and scroll.
+function FullScreenImage({ title, uri, naturalWidth, ratio, dimmed, onExit }: { title: string; uri: string; naturalWidth: number | null; ratio: number; dimmed: boolean; onExit(): void }) {
+  const { messages: m } = useProgressLanguage();
+  const { width: windowWidth, height: windowHeight } = useWindowDimensions();
+  const closeButton = useRef<View>(null);
+  const fitButton = useRef<View>(null);
+  const scrollArea = useRef<React.ComponentRef<typeof ScrollView>>(null);
+  useEffect(() => focus(closeButton), []);
+  const [fit, setFit] = useState<"screen" | "width">("screen");
+  const room = windowHeight - 2 * FULL_SCREEN_MARGIN - FULL_SCREEN_BAR;
+  const widthFit = Math.max(0, Math.min(naturalWidth ?? Infinity, windowWidth - 2 * FULL_SCREEN_MARGIN));
+  const screenFit = Math.min(widthFit, room * ratio);
+  // Only an image that fills the width at least half again as large as it fits
+  // whole gets the choice. An ordinary window screenshot gains a little and reads
+  // fine whole; a phone screenshot or a long page doesn't.
+  const long = widthFit >= screenFit * 1.5;
+  const scrolls = long && fit === "width";
+  const toggle = () => setFit(scrolls ? "screen" : "width");
+  // Fit to width hands the keys to the scroll area, so the arrows, Page Up and
+  // Down, Home, End and Space scroll it. When the area goes, focus goes back to the bar.
+  const scrolled = useRef(false);
+  useEffect(() => {
+    if (scrolls) focus(scrollArea);
+    else if (scrolled.current) focus(long ? fitButton : closeButton);
+    scrolled.current = scrolls;
+  }, [scrolls, uri]);
+  const light = "rgba(255, 255, 255, 0.85)";
+  const barButton = ({ pressed, hovered }: { pressed: boolean; hovered: boolean }) => ({
+    height: 36, alignItems: "center", justifyContent: "center", borderRadius: 6,
+    backgroundColor: pressed ? "rgba(255, 255, 255, 0.16)" : hovered ? "rgba(255, 255, 255, 0.1)" : "transparent",
+  }) as const;
+  // A press on the image stops there, so only the black around it exits.
+  // The fit button is the keyboard's way to the toggle, so the image isn't a tab stop.
+  const area = (
+    <Pressable accessible={false} focusable={false} onPress={onExit}
+      style={{ flexGrow: 1, alignItems: "center", justifyContent: "center", padding: FULL_SCREEN_MARGIN }}>
+      <Pressable accessible={false} focusable={false} onPress={long ? toggle : () => {}}
+        style={{ cursor: (long ? (scrolls ? "zoom-out" : "zoom-in") : "default") as unknown as ViewStyle["cursor"] }}>
+        <Image accessibilityLabel={title} source={{ uri }} resizeMode="contain"
+          style={{ width: scrolls ? widthFit : screenFit, aspectRatio: ratio, borderRadius: 6, borderWidth: 1, borderColor: "rgba(255, 255, 255, 0.1)", opacity: dimmed ? 0.6 : 1 }} />
+      </Pressable>
+    </Pressable>
+  );
+  return (
+    <View style={{ position: "fixed" as unknown as ViewStyle["position"], top: 0, right: 0, bottom: 0, left: 0, zIndex: 1000, backgroundColor: "black" }}>
+      <View style={{ height: FULL_SCREEN_BAR, flexDirection: "row", alignItems: "center", gap: 12, paddingStart: FULL_SCREEN_MARGIN, paddingEnd: 12 }}>
+        <Text numberOfLines={1} style={{ flex: 1, minWidth: 0, color: light, fontSize: 13, lineHeight: 18 }}>{title}</Text>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+          {long ? (
+            <PressScale ref={fitButton} accessibilityRole="button" onPress={toggle}
+              style={(state) => ({ ...barButton(state), flexDirection: "row", gap: 6, paddingHorizontal: 10 })}>
+              <Icon name={scrolls ? "Shrink" : "MoveHorizontal"} size={16} color={light} />
+              <Text style={{ color: light, fontSize: 13, lineHeight: 18 }}>{scrolls ? m.fitToScreen : m.fitToWidth}</Text>
+            </PressScale>
+          ) : null}
+          <PressScale ref={closeButton} accessibilityRole="button" accessibilityLabel={m.exitFullScreen} onPress={onExit}
+            style={(state) => ({ ...barButton(state), width: 36 })}>
+            <Icon name="X" size={18} color={light} />
+          </PressScale>
+        </View>
       </View>
-      {actions}
+      {/* Keyed so the next image starts at its top. The fit button stays the visible
+          keyboard control, so the scroll area draws no focus ring. */}
+      {scrolls ? (
+        <ScrollView key={uri} ref={scrollArea} focusable style={{ flex: 1, outlineWidth: 0 }} contentContainerStyle={{ flexGrow: 1 }}>{area}</ScrollView>
+      ) : area}
     </View>
   );
 }
 
+// Only views on web have focus(); elsewhere this does nothing.
+function focus(ref: React.RefObject<unknown>) {
+  (ref.current as { focus?(): void } | null)?.focus?.();
+}
+
+// Paseo draws dialogs as bottom sheets below this window width.
+const COMPACT_BELOW = 720;
+
 // Width left for content: Paseo's 520px dialog less its 24px padding each side.
 const CONTENT_WIDTH = 472;
 // Characters of 12px monospace per line of the text box (10px padding each side).
@@ -232,11 +376,12 @@ function FolderList({ colors, folder, entries, truncated, dimmed, onOpen }: { co
   );
 }
 
-// An image's width over its height, or null if it can't be read. Read from the data
-// because onLoad doesn't report a size for data URIs on every platform.
-function imageRatio(uri: string): Promise<number | null> {
+// An image's pixel width and its width over its height, or nulls if they can't be read.
+// Read from the data because onLoad doesn't report a size for data URIs on every platform.
+function imageSize(uri: string): Promise<{ width: number | null; ratio: number | null }> {
   return new Promise((resolve) => {
-    Image.getSize(uri, (width, height) => resolve(width && height ? width / height : null), () => resolve(null));
+    Image.getSize(uri, (width, height) => resolve(width && height ? { width, ratio: width / height } : { width: null, ratio: null }),
+      () => resolve({ width: null, ratio: null }));
   });
 }
 
@@ -248,9 +393,9 @@ function roomForContent(windowHeight: number): number {
 }
 
 // A dialog footer button: 13px label and 14px icon, 30px tall. Icon-only is a 30px square.
-export function DialogButton({ colors, icon, label, accessibilityLabel, onPress, outerStyle, ref }: { colors: Colors; icon: string; label?: string; accessibilityLabel?: string; onPress(): void; outerStyle?: ViewStyle; ref?: React.Ref<View> }) {
+export function DialogButton({ colors, icon, label, accessibilityLabel, onPress, onBlur, outerStyle, ref }: { colors: Colors; icon: string; label?: string; accessibilityLabel?: string; onPress(): void; onBlur?(): void; outerStyle?: ViewStyle; ref?: React.Ref<View> }) {
   return (
-    <PressScale ref={ref} accessibilityRole="button" accessibilityLabel={accessibilityLabel ?? label} onPress={onPress} outerStyle={outerStyle}
+    <PressScale ref={ref} accessibilityRole="button" accessibilityLabel={accessibilityLabel ?? label} onPress={onPress} onBlur={onBlur} outerStyle={outerStyle}
       style={({ pressed }) => ({
         flexDirection: "row", alignItems: "center", gap: 6,
         paddingVertical: label ? 6 : 8, paddingLeft: label ? 8 : 8, paddingRight: label ? 10 : 8,

package/client/settings.tsx

@@ -1,29 +1,78 @@
-import { type PluginSurfaceProps, useSettings } from "@getpaseo/plugin/client";
-import { SettingsAction, SettingsCard, SettingsSection, SettingsSelect } from "@getpaseo/plugin/client/ui";
-import React from "react";
-import { Text } from "react-native";
+import { type PluginSurfaceProps, useRpc, useSettings } from "@getpaseo/plugin/client";
+import { Icon, Modal } from "@getpaseo/plugin/client/react-native";
+import { SettingsAction, SettingsCard, SettingsSelect } from "@getpaseo/plugin/client/ui";
+import { useQuery } from "@tanstack/react-query";
+import React, { type ReactNode, useState } from "react";
+import { Text, View } from "react-native";
 import { DEFAULT_QUESTION_MODE, QUESTION_MODES } from "../shared/question-modes";
+import { readSkill } from "../shared/rpc";
 import { questionSettings, LANGUAGE_PREFERENCES } from "../shared/settings";
+import { parseWriteUp, withoutTitle } from "../shared/write-up";
+import { errorText } from "./errors";
 import { useProgressLanguage } from "./language";
+import { useSkill } from "./launcher";
+import { BlockView } from "./write-up";
 
-export function QuestionSettings({ theme }: PluginSurfaceProps) {
-  return <><QuestionModeSettings theme={theme} /><DisplaySettings theme={theme} /></>;
+export function QuestionSettings({ theme, host }: PluginSurfaceProps) {
+  return <><QuestionModeSettings theme={theme} /><DisplaySettings theme={theme} /><SkillSettings colors={theme.colors} hostId={host.id} /></>;
 }
 
 type Colors = PluginSurfaceProps["theme"]["colors"];
 
+// Paseo's SettingsSection has no icon slot, so this copies its layout and adds one.
+function Section({ colors, icon, title, children }: { colors: Colors; icon: string; title: string; children: ReactNode }) {
+  return (
+    <View style={{ marginBottom: 24 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 8, marginBottom: 12, marginLeft: 4 }}>
+        <Icon name={icon} size={14} color={colors.foregroundMuted} />
+        <Text style={{ color: colors.foregroundMuted, fontSize: 12, fontWeight: "400" }}>{title}</Text>
+      </View>
+      <View style={{ gap: 12 }}>{children}</View>
+    </View>
+  );
+}
+
 function DisplaySettings({ theme }: Pick<PluginSurfaceProps, "theme">) {
   const { messages: m, settings } = useProgressLanguage();
   const muted = { color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 19 };
   const options = LANGUAGE_PREFERENCES.map((value) => ({ value, label: value === "system" ? m.systemLanguage : value === "en" ? "English" : "简体中文" }));
   return (
-    <SettingsSection title={m.display}>
+    <Section colors={theme.colors} icon="Languages" title={m.display}>
       {settings.status === "loading" ? <Text style={muted}>{m.loadingSettings}</Text>
         : settings.status !== "ready" ? <SettingsRecovery colors={theme.colors} settings={settings} />
         : <SettingsCard><SettingsSelect label={m.language} hint={m.languageHint} value={settings.values.language} options={options}
           disabled={settings.saving} error={settings.saveError}
           onValueChange={(language) => void settings.save({ ...settings.values, language }, settings.revision)} /></SettingsCard>}
-    </SettingsSection>
+    </Section>
+  );
+}
+
+function SkillSettings({ colors, hostId }: { colors: Colors; hostId: string }) {
+  const { messages: m } = useProgressLanguage();
+  const skill = useSkill(hostId);
+  const fetchSkill = useRpc(readSkill);
+  const document = useQuery({ queryKey: ["progress", "skill-document", hostId], queryFn: () => fetchSkill({}), staleTime: 60_000 });
+  const [open, setOpen] = useState(false);
+  const blocks = document.data ? withoutTitle(parseWriteUp(document.data.markdown)) : [];
+  const muted = { color: colors.foregroundMuted, fontSize: 13, lineHeight: 19 };
+  return (
+    <Section colors={colors} icon="Sparkles" title={m.agentSkill}>
+      <SettingsCard>
+        <SettingsAction label={m.skillName} hint={document.data?.description || undefined} actionLabel={m.viewSkill} onPress={() => setOpen(true)} />
+        {skill.notice?.action ? (
+          <SettingsAction label={skill.state === "outdated" ? m.skillLinkOutdated : m.skillNotInstalled} hint={skill.notice.text}
+            actionLabel={skill.pending ? m.installing : skill.notice.action} disabled={skill.pending} onPress={skill.install} />
+        ) : null}
+      </SettingsCard>
+      {/* Paseo draws the modal outside this tree, past the language context, so it only gets finished text. */}
+      <Modal title={m.skillName} icon={<Icon name="Sparkles" size={16} color={colors.foregroundMuted} />} open={open} onOpenChange={setOpen}>
+        <Modal.Content>
+          {document.error ? <Text style={muted}>{m.readError(errorText(document.error, m.unknownError))}</Text>
+            : !document.data ? <Text style={muted}>{m.loading}</Text>
+            : <View style={{ gap: 8 }}>{blocks.map((block, index) => <BlockView key={index} colors={colors} block={block} first={index === 0} />)}</View>}
+        </Modal.Content>
+      </Modal>
+    </Section>
   );
 }
 
@@ -32,13 +81,13 @@ function QuestionModeSettings({ theme }: Pick<PluginSurfaceProps, "theme">) {
   const settings = useSettings(questionSettings);
   const muted = { color: theme.colors.foregroundMuted, fontSize: 13, lineHeight: 19 };
   return (
-    <SettingsSection title={m.questions}>
+    <Section colors={theme.colors} icon="MessageCircleQuestion" title={m.questions}>
       {settings.status === "loading" ? <Text style={muted}>{m.loadingSettings}</Text>
         : settings.status !== "ready" ? <SettingsRecovery colors={theme.colors} settings={settings} resetLabel={m.resetTo(m.questionModes[DEFAULT_QUESTION_MODE].label)} />
         : <SettingsCard><SettingsSelect label={m.questionMode} hint={m.questionModes[settings.values.mode].hint}
           error={settings.saveError} value={settings.values.mode} options={QUESTION_MODES.map((value) => ({ value, label: m.questionModes[value].label }))}
           disabled={settings.saving} onValueChange={(mode) => void settings.save({ ...settings.values, mode }, settings.revision)} /></SettingsCard>}
-    </SettingsSection>
+    </Section>
   );
 }
 

package/client/whats-new.tsx

@@ -4,7 +4,7 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
 import React, { useState } from "react";
 import { Text, View } from "react-native";
 import { dismissWhatsNew, getWhatsNew } from "../shared/rpc";
-import { NOTE_KINDS, type NoteKind, type NoteTone, type WhatsNew, type WhatsNewNote } from "../shared/whats-new";
+import { NOTE_KINDS, type NoteKind, type NoteTone, type WhatsNew, type WhatsNewNote, type WhatsNewRelease } from "../shared/whats-new";
 import { spans } from "../shared/write-up";
 import { PressScale, Presence } from "./motion";
 import { isLight, raised, tint } from "./surfaces";
@@ -13,8 +13,8 @@ import { ProgressLanguageProvider, useProgressLanguage } from "./language";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 
-// Once after an update: this version's headline, with its full notes a press
-// away. Closing either hides both for this version.
+// Once after an update: the headline of what changed, with the full notes a
+// press away. Closing either hides both until the next version.
 export function WhatsNewBanner({ colors, host }: { colors: Colors; host: PluginWorkspacePanelProps["host"] }) {
   const { messages: m } = useProgressLanguage();
   const fetchWhatsNew = useRpc(getWhatsNew);
@@ -42,7 +42,7 @@ export function WhatsNewBanner({ colors, host }: { colors: Colors; host: PluginW
         <View style={{ flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 10, margin: 12, marginBottom: 0, padding: 8, borderRadius: 12, ...raised(colors), backgroundColor: colors.surface1 }}>
           <View style={{ alignSelf: "flex-start", height: 17, justifyContent: "center" }}><Icon name="Gift" size={14} color={colors.foregroundMuted} /></View>
           <Text selectable style={{ flex: 1, minWidth: 200, color: colors.foregroundMuted, fontSize: 12, lineHeight: 17 }}>
-            <Text style={{ color: colors.foreground, fontWeight: "500" }}>{m.newVersion(whatsNew.version)}</Text> {whatsNew.headline}
+            <Text style={{ color: colors.foreground, fontWeight: "500" }}>{whatsNew.releases.length > 1 ? m.updatedTo(whatsNew.version) : m.newVersion(whatsNew.version)}</Text> {whatsNew.headline}
           </Text>
           {/* 8px keeps the close button's 6px hit slop off the button beside it. */}
           <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
@@ -57,11 +57,11 @@ export function WhatsNewBanner({ colors, host }: { colors: Colors; host: PluginW
           </View>
         </View>
       ) : null}</Presence>
-      <Modal title={shown ? m.whatsNewTitle(shown.version) : ""} icon={<Icon name="Gift" size={16} color={colors.foregroundMuted} />}
+      <Modal title={!shown ? "" : shown.releases.length > 1 ? m.whatsNewAll : m.whatsNewTitle(shown.version)} icon={<Icon name="Gift" size={16} color={colors.foregroundMuted} />}
         open={open} onOpenChange={(next) => { if (!next) closeDialog(); }}>
         <Modal.Content>
         <ProgressLanguageProvider>
-          {shown ? <Notes colors={colors} notes={shown.notes} /> : null}
+          {shown ? <Releases colors={colors} releases={shown.releases} /> : null}
           <View style={{ flexDirection: "row", justifyContent: "flex-end", marginTop: 8 }}>
             <PressScale accessibilityRole="button" onPress={closeDialog}
               style={({ pressed, hovered }) => ({ paddingHorizontal: 12, paddingVertical: 6, borderRadius: 6, backgroundColor: colors.accent, opacity: pressed ? 0.7 : hovered ? 0.85 : 1 })}>
@@ -75,6 +75,22 @@ export function WhatsNewBanner({ colors, host }: { colors: Colors; host: PluginW
   );
 }
 
+// One version reads as before. After a skipped update, each version's notes sit
+// under its number, so it's clear which release brought what.
+function Releases({ colors, releases }: { colors: Colors; releases: WhatsNewRelease[] }) {
+  if (releases.length === 1) return <Notes colors={colors} notes={releases[0].notes} />;
+  return (
+    <View style={{ gap: 40 }}>
+      {releases.map((release) => (
+        <View key={release.version} style={{ gap: 12 }}>
+          <Text accessibilityRole="header" selectable style={{ color: colors.foreground, fontSize: 12, lineHeight: 16, fontWeight: "600" }}>{release.version}</Text>
+          <Notes colors={colors} notes={release.notes} />
+        </View>
+      ))}
+    </View>
+  );
+}
+
 // Titled notes read as a short list of headings with their details; a changelog
 // written without titles stays a bulleted list.
 function Notes({ colors, notes }: { colors: Colors; notes: WhatsNewNote[] }) {

package/index.server.ts

@@ -3,9 +3,9 @@ import { handleGetAttention, handleGetDashboard, handleListFolders, handleMarkPa
 import { handleInstallLauncher, handleLauncherStatus } from "./server/launcher";
 import { handleCanOpenOnHost, handleOpenDeliverable, handlePreviewDeliverable, handleReadDeliverablePiece } from "./server/open";
 import { mirrorQuestionMode } from "./server/question-mode";
-import { handleInstallSkill, handleSkillStatus } from "./server/skill";
+import { handleInstallSkill, handleReadSkill, handleSkillStatus, repairSkill } from "./server/skill";
 import { handleDismissWhatsNew, handleGetWhatsNew } from "./server/whats-new";
-import { canOpenOnHost, dismissWhatsNew, getAttention, getDashboard, getLauncherStatus, getSkillStatus, getWhatsNew, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
+import { canOpenOnHost, dismissWhatsNew, getAttention, getDashboard, getLauncherStatus, getSkillStatus, getWhatsNew, installLauncher, installSkill, listFolders, readSkill, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
 import { displaySettings, questionSettings } from "./shared/settings";
 
 export default function contribute(server: PluginServerContext) {
@@ -20,6 +20,7 @@ export default function contribute(server: PluginServerContext) {
   server.handle(readDeliverablePiece, handleReadDeliverablePiece);
   server.handle(getSkillStatus, handleSkillStatus);
   server.handle(installSkill, handleInstallSkill);
+  server.handle(readSkill, handleReadSkill);
   server.handle(listFolders, handleListFolders);
   server.handle(setHistoryFolder, handleSetHistoryFolder);
   server.handle(getWhatsNew, handleGetWhatsNew);
@@ -27,6 +28,7 @@ export default function contribute(server: PluginServerContext) {
   // Settles a new install before any panel opens. Opening one makes a
   // worktree folder, which would look like an earlier version's.
   void handleGetWhatsNew().catch(() => {});
+  void repairSkill();
   server.registerSettings(displaySettings);
   const mirror = mirrorQuestionMode(server.registerSettings(questionSettings));
   return mirror.stop;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the paseo-progress command.",
   "license": "MIT",
   "author": "Steve Castaneda",

package/server/skill.ts

@@ -1,5 +1,5 @@
 import { exec, execFile } from "node:child_process";
-import { lstat, mkdir, readlink, symlink, unlink } from "node:fs/promises";
+import { lstat, mkdir, readFile, readlink, symlink, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
@@ -31,24 +31,41 @@ export async function skillState(path: string, pluginDirectory: string): Promise
   return basename(target) === SKILL_NAME && basename(dirname(target)) === "skills" ? "outdated" : "foreign";
 }
 
+// Repoints each link this plugin made to an old copy at the copy Paseo runs
+// now. Paseo puts every update in a new folder, so this follows each update.
+// Returns whether it wrote.
+export async function relinkSkill(paths: string[], pluginDirectory: string): Promise<boolean> {
+  let wrote = false;
+  for (const path of paths) {
+    if (await skillState(path, pluginDirectory) !== "outdated") continue;
+    await unlink(path);
+    await link(path, pluginDirectory);
+    wrote = true;
+  }
+  return wrote;
+}
+
 // Links the skill wherever it is missing or points at an old copy of the
 // plugin. Leaves alone anything else at those paths. Returns whether it wrote.
 export async function installSkill(paths: string[], pluginDirectory: string): Promise<boolean> {
   const states = await Promise.all(paths.map((path) => skillState(path, pluginDirectory)));
   if (states.every((state) => state === "foreign")) throw new Error(`${paths.join(", ")} already exist and were not linked by this plugin.`);
-  let wrote = false;
+  let wrote = await relinkSkill(paths, pluginDirectory);
   for (const [index, path] of paths.entries()) {
-    if (states[index] !== "missing" && states[index] !== "outdated") continue;
-    if (states[index] === "outdated") await unlink(path);
-    await mkdir(dirname(path), { recursive: true });
-    // A junction on Windows, where a directory symlink needs admin rights or
-    // Developer Mode. Other systems ignore the type and make a symlink.
-    await symlink(skillSource(pluginDirectory), path, "junction");
+    if (states[index] !== "missing") continue;
+    await link(path, pluginDirectory);
     wrote = true;
   }
   return wrote;
 }
 
+async function link(path: string, pluginDirectory: string) {
+  await mkdir(dirname(path), { recursive: true });
+  // A junction on Windows, where a directory symlink needs admin rights or
+  // Developer Mode. Other systems ignore the type and make a symlink.
+  await symlink(skillSource(pluginDirectory), path, "junction");
+}
+
 // "current" once every folder that can take the link has it.
 export async function skillStatus(paths: string[], pluginDirectory: string) {
   const targets = await Promise.all(paths.map(async (path) => ({ path, state: await skillState(path, pluginDirectory) })));
@@ -75,19 +92,45 @@ export async function findPluginDirectory(): Promise<string> {
 }
 
 // On Windows Paseo's command is paseo.cmd, which Node can start, or find on
-// PATH, only through cmd.exe.
+// PATH, only through cmd.exe. A hung CLI must fail so the next one is tried.
 function askPaseo(cli: string) {
+  const options = { timeout: 10_000 };
   return process.platform === "win32"
-    ? promisify(exec)(`"${cli}" plugin ls ${PLUGIN_ID} --json`)
-    : promisify(execFile)(cli, ["plugin", "ls", PLUGIN_ID, "--json"]);
+    ? promisify(exec)(`"${cli}" plugin ls ${PLUGIN_ID} --json`, options)
+    : promisify(execFile)(cli, ["plugin", "ls", PLUGIN_ID, "--json"], options);
+}
+
+// Runs once per load, when the server starts: an update reloads the bundle.
+// Only repoints links the user already asked for; new ones wait for Install
+// skill. A failure leaves the links as they were, and status says so.
+let repair: Promise<unknown> | null = null;
+
+export function repairSkill(): Promise<unknown> {
+  repair ??= findPluginDirectory().then((directory) => relinkSkill(defaultSkillPaths(), directory)).catch(() => {});
+  return repair;
 }
 
 export async function handleSkillStatus() {
+  await repairSkill();
   return skillStatus(defaultSkillPaths(), await findPluginDirectory());
 }
 
-// Runs only when the user presses Install skill in the panel.
+// SKILL.md's frontmatter holds one-line fields; only the description is shown.
+export function skillDocument(text: string): { markdown: string; description: string } {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  const description = /^description:[ \t]*(.*)$/m.exec(frontmatter?.[1] ?? "")?.[1].trim().replace(/^(["'])(.*)\1$/, "$2") ?? "";
+  return { markdown: text.slice(frontmatter?.[0].length ?? 0).trimStart(), description };
+}
+
+export async function handleReadSkill() {
+  return skillDocument(await readFile(join(skillSource(await findPluginDirectory()), "SKILL.md"), "utf8"));
+}
+
+// Runs only when the user presses Install skill. Links that only need to
+// follow an update are repointed on their own (repairSkill), which must finish
+// first: both would unlink the same outdated link.
 export async function handleInstallSkill() {
+  await repairSkill();
   const pluginDirectory = await findPluginDirectory();
   await installSkill(defaultSkillPaths(), pluginDirectory);
   return skillStatus(defaultSkillPaths(), pluginDirectory);

package/server/whats-new.ts

@@ -1,40 +1,56 @@
-// After an update, the panel shows what changed in this version, once. The
-// notes come from the changelog in the plugin's own README, so they're
-// written in one place. Whether they've been seen is kept per user on this
-// computer.
+// After an update, the panel shows what changed since the version last seen,
+// once. The notes come from the changelog in the plugin's own README, so
+// they're written in one place. Which version was seen is kept per user on
+// this computer.
 import { readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
-import { NOTE_KINDS, type NoteKind, type WhatsNew, type WhatsNewNote } from "../shared/whats-new.ts";
+import { NOTE_KINDS, type NoteKind, type WhatsNew, type WhatsNewNote, type WhatsNewRelease } from "../shared/whats-new.ts";
 import { spans } from "../shared/write-up.ts";
 import { findPluginDirectory } from "./skill.ts";
 import { stateRoot, writeAtomic } from "./store.ts";
 
 export type Release = { version: string; readme: string | null };
 
-const seenSchema = z.object({ seen: z.string() });
+const seenSchema = z.object({ seen: z.string().regex(/^\d+\.\d+\.\d+$/) });
 const packageSchema = z.object({ version: z.string() });
 
 export function whatsNewPath(home = homedir()): string {
   return join(stateRoot(home), "whats-new.json");
 }
 
-// The top-level bullets under `### <version>` in the README's `## Changelog`,
-// or null when that version has none.
-export function changelogNotes(readme: string, version: string): WhatsNewNote[] | null {
-  let section: "other" | "changelog" | "version" = "other";
-  const notes: string[] = [];
+// Each `### x.y.z` under the README's `## Changelog` with its top-level
+// bullets, newest first. Versions without bullets are left out.
+export function changelog(readme: string): WhatsNewRelease[] {
+  const releases: { version: string; bullets: string[] }[] = [];
+  let inChangelog = false;
+  let current: string[] | null = null;
   for (const line of readme.replace(/\r\n?/g, "\n").split("\n")) {
-    if (section === "version" && /^#{2,3}\s/.test(line)) break;
-    if (/^##\s/.test(line)) section = line.trim() === "## Changelog" ? "changelog" : "other";
-    else if (section === "changelog" && line.trim() === `### ${version}`) section = "version";
-    else if (section === "version" && /^[-*]\s/.test(line)) notes.push(line.slice(2).trim());
-    else if (section === "version" && notes.length && /^\s+\S/.test(line) && !/^\s+([-*+]|\d+[.)])\s/.test(line)) {
-      notes[notes.length - 1] += ` ${line.trim()}`;
+    if (/^##\s/.test(line)) {
+      inChangelog = line.trim() === "## Changelog";
+      current = null;
+      continue;
+    }
+    if (!inChangelog) continue;
+    if (/^###\s/.test(line)) {
+      const version = /^###\s+(\d+\.\d+\.\d+)\s*$/.exec(line)?.[1];
+      current = null;
+      if (version) releases.push({ version, bullets: (current = []) });
+    } else if (current && /^[-*]\s/.test(line)) current.push(line.slice(2).trim());
+    else if (current?.length && /^\s+\S/.test(line) && !/^\s+([-*+]|\d+[.)])\s/.test(line)) {
+      current[current.length - 1] += ` ${line.trim()}`;
     }
   }
-  return notes.length ? notes.map(note) : null;
+  return releases
+    .filter((release) => release.bullets.length)
+    .map(({ version, bullets }) => ({ version, notes: bullets.map(note) }))
+    .sort((a, b) => compareVersions(b.version, a.version));
+}
+
+function compareVersions(a: string, b: string): number {
+  const [x, y] = [a, b].map((version) => version.split(".").map(Number));
+  return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
 }
 
 // A bullet can open with a kind tag, like `[Fixed]`, and then a bold
@@ -88,18 +104,23 @@ async function usedBefore(home: string): Promise<boolean> {
   return entries.some((entry) => entry.isDirectory() && /-[0-9a-f]{8}$/.test(entry.name));
 }
 
-// What to show, or null. A new install has nothing to catch up on, so it
-// records this version as seen.
+// What to show, or null: every version since the one last seen, newest
+// first. A new install has nothing to catch up on, so it records this version
+// as seen. An update from before versions were recorded can't say where it
+// started, so it shows this version alone rather than the whole history.
 export async function whatsNew({ version, readme }: Release, home = homedir()): Promise<WhatsNew | null> {
-  const notes = readme === null ? null : changelogNotes(readme, version);
-  if (!notes) return null;
   const seen = await readSeen(home);
   if (seen === version) return null;
   if (seen === null && !(await usedBefore(home))) {
     await markWhatsNewSeen(version, home);
     return null;
   }
-  return { version, headline: headline(notes[0]), notes };
+  const releases = (readme === null ? [] : changelog(readme)).filter((release) => seen === null
+    ? release.version === version
+    : compareVersions(release.version, seen) > 0 && compareVersions(release.version, version) <= 0);
+  if (!releases.length) return null;
+  const notes = releases.flatMap((release) => release.notes);
+  return { version, headline: headline(notes.find((note) => note.kind === "new") ?? notes[0]), releases };
 }
 
 // The server bundle can't read files beside it, so ask Paseo where the plugin

package/shared/rpc.ts

@@ -89,6 +89,14 @@ export const installSkill = defineRpc({
   output: skillStatus,
 });
 
+// The skill agents get: its SKILL.md without the frontmatter, and the
+// frontmatter's description.
+export const readSkill = defineRpc({
+  name: "progress.skill.read",
+  input: z.object({}),
+  output: z.object({ markdown: z.string(), description: z.string() }),
+});
+
 // The folders inside one folder of the worktree ("" is the top), for the
 // folder picker.
 export const listFolders = defineRpc({

package/shared/whats-new.ts

@@ -13,4 +13,7 @@ export type NoteKind = keyof typeof NOTE_KINDS;
 
 export type WhatsNewNote = { kind?: NoteKind; title?: string; body: string };
 
-export type WhatsNew = { version: string; headline: string; notes: WhatsNewNote[] };
+export type WhatsNewRelease = { version: string; notes: WhatsNewNote[] };
+
+// `version` is the one running now; `releases` run newest first and are never empty.
+export type WhatsNew = { version: string; headline: string; releases: WhatsNewRelease[] };

package/shared/write-up.ts

@@ -33,7 +33,9 @@ export function spans(text: string): Span[] {
 export function parseWriteUp(markdown: string): Block[] {
   const blocks: Block[] = [];
   let paragraph: string[] = [];
-  let fence: string[] | null = null;
+  // A fence opened inside a list item is indented like the item; its lines
+  // lose up to that much indentation.
+  let fence: { indent: number; lines: string[] } | null = null;
   const flush = () => {
     if (paragraph.length) blocks.push({ kind: "paragraph", spans: spans(paragraph.join(" ")) });
     paragraph = [];
@@ -41,14 +43,14 @@ export function parseWriteUp(markdown: string): Block[] {
   for (const raw of markdown.replace(/\r\n?/g, "\n").split("\n")) {
     if (fence) {
       if (/^\s*(```|~~~)/.test(raw)) {
-        blocks.push({ kind: "code", text: fence.join("\n") });
+        blocks.push({ kind: "code", text: fence.lines.join("\n") });
         fence = null;
-      } else fence.push(raw);
+      } else fence.lines.push(raw.replace(new RegExp(`^[ \\t]{0,${fence.indent}}`), ""));
       continue;
     }
     if (/^\s*(```|~~~)/.test(raw)) {
       flush();
-      fence = [];
+      fence = { indent: /^[ \t]*/.exec(raw)![0].length, lines: [] };
       continue;
     }
     const line = raw.trimEnd();
@@ -69,7 +71,7 @@ export function parseWriteUp(markdown: string): Block[] {
     } else paragraph.push(line.trim().replace(/^>\s?/, ""));
   }
   flush();
-  if (fence) blocks.push({ kind: "code", text: fence.join("\n") });
+  if (fence) blocks.push({ kind: "code", text: fence.lines.join("\n") });
   return blocks;
 }