@stevecastaneda/paseo-progress 1.5.0 → 1.6.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="The Questions setting in Paseo's Settings, set to Work around" 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,6 +145,17 @@ The progress file, `progress.jsonl`, holds one JSON event per line, each with a
 
 ## Changelog
 
+### 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
+
+- [Improved] **Settings screenshot.** It shows the new Language setting.
+
 ### 1.5.0
 
 - [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.

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.",
@@ -124,6 +125,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 +184,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。",
@@ -124,6 +125,11 @@ export const messages: ProgressMessages = {
   skillForeign: "所有 paseo-progress 技能路径都已被其他内容占用，插件无法安装技能。",
   skillInstalled: "已安装 paseo-progress 技能。新的智能体会话将使用此技能。",
   installSkillFailure: "无法安装技能。",
+  agentSkill: "智能体技能",
+  skillName: "paseo-progress 技能",
+  viewSkill: "查看技能",
+  skillNotInstalled: "未安装",
+  skillLinkOutdated: "链接已过期",
   installing: "安装中…",
   loadingSettings: "正在加载设置…",
   tryAgain: "重试",
@@ -178,6 +184,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;
@@ -106,6 +107,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 +166,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/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.0",
+  "version": "1.6.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;
 }