@stevecastaneda/paseo-progress 1.3.1 → 1.5.0

package/server/whats-new.ts

@@ -0,0 +1,127 @@
+// 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.
+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 { 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 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[] = [];
+  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()}`;
+    }
+  }
+  return notes.length ? notes.map(note) : null;
+}
+
+// A bullet can open with a kind tag, like `[Fixed]`, and then a bold
+// sentence, like `**Title.** Detail.`, which is its title.
+function note(bullet: string): WhatsNewNote {
+  const tag = /^\[([a-z]+)\]\s*(.*)$/i.exec(bullet);
+  const kind = tag ? noteKind(tag[1]) : undefined;
+  const rest = kind ? tag![2] : bullet;
+  const text = rest.split(/(`[^`]+`)/).map((part, index) => index % 2 ? part : curly(part)).join("");
+  const lead = /^\*\*([^*]+?[.!?])\*\*\s*(.*)$/.exec(text);
+  return { ...(kind && { kind }), ...(lead ? { title: plain(lead[1]), body: lead[2] } : { body: text }) };
+}
+
+function noteKind(tag: string): NoteKind | undefined {
+  const key = tag.toLowerCase();
+  return Object.hasOwn(NOTE_KINDS, key) ? key as NoteKind : undefined;
+}
+
+// The README is typed with straight quotes; the panel shows typeset ones. Code keeps its own.
+function curly(text: string): string {
+  return text.replace(/(^|[\s([{])"/g, "$1\u201c").replace(/"/g, "\u201d").replace(/(^|[\s([{])'/g, "$1\u2018").replace(/'/g, "\u2019");
+}
+
+function plain(markdown: string): string {
+  return spans(markdown).map((span) => span.text).join("");
+}
+
+// A note's title, or else the first sentence of its body, without Markdown.
+export function headline(note: WhatsNewNote): string {
+  if (note.title) return note.title;
+  const body = plain(note.body);
+  return /^.*?[.!?](?=\s|$)/.exec(body)?.[0] ?? body;
+}
+
+async function readSeen(home: string): Promise<string | null> {
+  try {
+    return seenSchema.parse(JSON.parse(await readFile(whatsNewPath(home), "utf8"))).seen;
+  } catch {
+    return null;
+  }
+}
+
+export async function markWhatsNewSeen(version: string, home = homedir()): Promise<void> {
+  await writeAtomic(whatsNewPath(home), `${JSON.stringify({ seen: version })}\n`);
+}
+
+// A worktree's folder (see outsideDirectory) means the plugin was in use
+// before this version, so this is an update, not a new install.
+async function usedBefore(home: string): Promise<boolean> {
+  const entries = await readdir(stateRoot(home), { withFileTypes: true }).catch(() => []);
+  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.
+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 };
+}
+
+// The server bundle can't read files beside it, so ask Paseo where the plugin
+// is. Read once per load: an update reloads the bundle, which starts over.
+let release: Promise<Release> | null = null;
+
+function currentRelease(): Promise<Release> {
+  release ??= findPluginDirectory().then(async (directory) => ({
+    version: packageSchema.parse(JSON.parse(await readFile(join(directory, "package.json"), "utf8"))).version,
+    readme: await readFile(join(directory, "README.md"), "utf8").catch(() => null),
+  }));
+  release.catch(() => {
+    release = null;
+  });
+  return release;
+}
+
+export async function handleGetWhatsNew(): Promise<WhatsNew | null> {
+  return whatsNew(await currentRelease());
+}
+
+export async function handleDismissWhatsNew(input: { version: string }) {
+  await markWhatsNewSeen(input.version);
+  return {};
+}

package/shared/dashboard.ts

@@ -1,4 +1,5 @@
 import { EVENT_VERSION, eventSchema, type DELIVERABLE_KINDS, type FileLink, type ProgressEvent, type QuestionOption, type TicketStatus } from "./events.ts";
+import { QUESTION_MODE_RULES, type QuestionState } from "./question-modes.ts";
 
 // One recorded change to a ticket, oldest first. `stage: ""` clears the stage.
 export interface TicketChange {
@@ -43,14 +44,18 @@ export interface Question {
   title: string;
   question: string;
   options: QuestionOption[];
-  // The option the agent leans toward. Nothing is built until the user answers.
+  // The option the agent leans toward.
   recommended: string;
+  // What the agent does while the question is open.
+  state: QuestionState;
+  // Why the question holds even in Keep building mode.
+  big?: string;
   background?: string;
   files: FileLink[];
   raisedBy?: string;
   ticketId?: string;
   askedAt: string;
-  // `changedCourse` only on older answers, from when agents built a default before asking.
+  // `changedCourse`: the agent had built another option and changed course.
   answer?: { choice: string; words?: string; changedCourse?: boolean; at: string };
 }
 
@@ -279,6 +284,8 @@ export function reduceProgress(parsed: { events: ParsedLine[]; issues: FileIssue
           question: event.question,
           options: event.options ?? [],
           recommended: event.recommend ?? event.default ?? "",
+          state: event.mode ? QUESTION_MODE_RULES[event.mode].state(Boolean(event.big)) : event.default !== undefined && !event.waits ? "building" : "waiting",
+          big: event.big,
           background: event.background,
           files: event.files ?? [],
           raisedBy: event.raisedBy,

package/shared/events.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { QUESTION_MODES } from "./question-modes.ts";
 
 // One line of `progress.jsonl`. The command-line tool writes these; the
 // dashboard reducer reads them. `v` lets later versions change a shape without
@@ -77,9 +78,11 @@ export const eventSchema = z.discriminatedUnion("type", [
   // A blocker that is not a ticket status, like a failing external service.
   z.object({ ...base, type: z.literal("stuck.set"), id: text, reason: text, ticket: text.optional() }),
   z.object({ ...base, type: z.literal("stuck.clear"), id: text }),
-  // The agent asks, recommends an option, and builds none of them before the
-  // answer: it works only on what the question doesn't affect. Older questions
-  // carry `default` (the option the agent carried on with) and `waits` instead.
+  // The agent asks and recommends an option. `mode` is the question mode when
+  // asked; without it (0.3.0 to 1.3.x) the agent built nothing before the
+  // answer, like "work-around". `big` says why the question holds even in
+  // "keep-building" mode. Questions from before 0.3.0 carry `default`, the
+  // option the agent carried on with unless it `waits`.
   z.object({
     ...base,
     type: z.literal("question.ask"),
@@ -89,6 +92,8 @@ export const eventSchema = z.discriminatedUnion("type", [
     options: z.array(questionOptionSchema).max(26).optional(),
     // The agent's pick: an option letter, or a word such as "Looks right" when there are no options.
     recommend: text.optional(),
+    mode: z.enum(QUESTION_MODES).optional(),
+    big: text.optional(),
     default: text.optional(),
     waits: z.boolean().optional(),
     background: text.optional(),
@@ -104,7 +109,7 @@ export const eventSchema = z.discriminatedUnion("type", [
     choice: text,
     // The user's own words, quoted under the answer.
     words: text.optional(),
-    // Older answers: true when the agent had to undo work built on its default.
+    // True when the agent had to undo work built on another option.
     changedCourse: z.boolean().optional(),
   }),
   // Adds detail to an open question; its reference and default stay.

package/shared/question-modes.ts

@@ -0,0 +1,45 @@
+// What an agent does when it asks the user a question, picked in Paseo's
+// Settings. The command, the settings page, and the dashboard all read this
+// table. No Paseo imports: the command's bundle includes this file.
+export const QUESTION_MODES = ["stop", "work-around", "keep-building"] as const;
+export type QuestionMode = (typeof QUESTION_MODES)[number];
+
+// Also what a missing or damaged mirror means.
+export const DEFAULT_QUESTION_MODE: QuestionMode = "work-around";
+
+// An open question on the dashboard: the agent stopped all work, holds what the
+// question affects, or builds its recommendation.
+export type QuestionState = "stopped" | "waiting" | "building";
+
+interface QuestionModeRules {
+  label: string;
+  hint: string;
+  // What the agent does until the answer. `question ask` prints it after "Mode: <label>."
+  askRule(question: { recommend: string; big: boolean }): string;
+  state(big: boolean): QuestionState;
+}
+
+const HOLD = "Build no option before the answer, not even your recommendation. Work on everything the question doesn't affect. If nothing else is left, end your turn, tell the user in chat which questions you're waiting on, and leave the run open.";
+
+export const QUESTION_MODE_RULES: Record<QuestionMode, QuestionModeRules> = {
+  stop: {
+    label: "Stop",
+    hint: "Agents stop all work when they ask, until you answer.",
+    askRule: () => "Ask any other questions you already have, then stop all work and resume only after an answer. End your turn now, tell the user in chat which questions you're waiting on, and leave the run open.",
+    state: () => "stopped",
+  },
+  "work-around": {
+    label: "Work around",
+    hint: "Agents hold what your answer affects and keep working on the rest.",
+    askRule: () => HOLD,
+    state: () => "waiting",
+  },
+  "keep-building": {
+    label: "Keep building",
+    hint: "Agents build their recommended option while you decide, and change course if you pick another. Big questions still wait.",
+    askRule: ({ recommend, big }) => big
+      ? `This question is big, so hold it like Work around. ${HOLD}`
+      : `Build ${recommend} now and keep working. If the user picks another option, undo the work built on ${recommend} and build their choice first. If the rest of the work is done while it's still open, leave it open and tell the user in chat; don't withdraw it.`,
+    state: (big) => (big ? "waiting" : "building"),
+  },
+};

package/shared/rpc.ts

@@ -1,6 +1,7 @@
 import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
 import type { Dashboard } from "./dashboard.ts";
+import type { WhatsNew } from "./whats-new.ts";
 
 // `panelOpened`: the Progress panel has been opened for this worktree before.
 // `root`: the worktree root the file was read from, which stored paths are
@@ -163,3 +164,20 @@ export const readDeliverablePiece = defineRpc({
   }),
   output: z.object({ data: z.string(), bytes: z.number() }),
 });
+
+// This version's changelog notes, once after an update; null otherwise.
+// `headline` is the first sentence of the first note, without Markdown.
+// A changelog bullet. `title` is its bold lead without Markdown, when it has
+// one; `body` is the rest, Markdown kept.
+export const getWhatsNew = defineRpc({
+  name: "progress.whats-new.get",
+  input: z.object({}),
+  output: z.custom<WhatsNew | null>(),
+});
+
+// The user closed it; it stays away for this version.
+export const dismissWhatsNew = defineRpc({
+  name: "progress.whats-new.dismiss",
+  input: z.object({ version: z.string().min(1) }),
+  output: z.object({}),
+});

package/shared/settings.ts

@@ -0,0 +1,20 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+import { DEFAULT_QUESTION_MODE, QUESTION_MODES } from "./question-modes.ts";
+
+export const questionSettings = defineSettings({
+  id: "questions",
+  scope: "host",
+  version: 1,
+  schema: z.object({ mode: z.enum(QUESTION_MODES).default(DEFAULT_QUESTION_MODE) }),
+});
+
+export const LANGUAGE_PREFERENCES = ["system", "en", "zh-CN"] as const;
+export type LanguagePreference = (typeof LANGUAGE_PREFERENCES)[number];
+
+export const displaySettings = defineSettings({
+  id: "display",
+  scope: "host",
+  version: 1,
+  schema: z.object({ language: z.enum(LANGUAGE_PREFERENCES).default("system") }),
+});

package/shared/show.ts

@@ -1,8 +1,10 @@
 import type { Dashboard } from "./dashboard.ts";
 import { headlineText, shortTitle } from "./dashboard.ts";
 import { formatAgo, formatClock, formatMinutes, formatWorkDone, minutesSince } from "./format.ts";
+import type { QuestionState } from "./question-modes.ts";
 
 const STATUS: Record<string, string> = { not_started: "Not started", working: "Working", blocked: "Blocked", done: "Done", skipped: "Skipped" };
+const QUESTION_STATE: Record<QuestionState, string> = { stopped: "agent stopped until the answer", waiting: "waiting for the answer", building: "building with it" };
 
 // The dashboard as plain text, so an agent can check what the user sees.
 export function dashboardText(dashboard: Dashboard, nowMs: number): string {
@@ -44,7 +46,7 @@ export function dashboardText(dashboard: Dashboard, nowMs: number): string {
   if (dashboard.questions.open.length) {
     lines.push("", "Questions waiting");
     for (const question of dashboard.questions.open) {
-      lines.push(`  ${question.id} ${question.ticketId ? `[${question.ticketId}] ` : ""}(${question.title}): ${question.question} You recommended ${question.recommended}`);
+      lines.push(`  ${question.id} ${question.ticketId ? `[${question.ticketId}] ` : ""}(${question.title}): ${question.question} You recommended ${question.recommended}, ${QUESTION_STATE[question.state]}${question.big ? `. Big: ${question.big}` : ""}`);
       for (const option of question.options) lines.push(`      ${option.letter}) ${option.label}${option.consequence ? `: ${option.consequence}` : ""}`);
     }
   }

package/shared/ticket-story.ts

@@ -1,12 +1,19 @@
 import type { Activity, Deliverable, Question, Ticket } from "./dashboard.ts";
 import type { TicketStatus } from "./events.ts";
 
+export type TimelineLabel =
+  | { kind: "added" }
+  | { kind: "reset" }
+  | { kind: "stage"; stage: string }
+  | { kind: "status"; status: TicketStatus }
+  | { kind: "waiting"; id: string };
+
 // One span in a ticket's life: from a status or stage change to the next one.
 export interface TimelineStep {
   at: string;
   // When the next step began; null while this one is still going (or it's the end).
   until: string | null;
-  label: string;
+  label: TimelineLabel;
   status: TicketStatus;
   notes: string[];
   // Length of the step; null for a finished ticket's last step, which has no end.
@@ -27,15 +34,10 @@ export interface TicketStory {
 
 const OPEN_ENDED: TicketStatus[] = ["working", "blocked", "not_started"];
 
-function labelFor(status: TicketStatus, stage: string | undefined, first: boolean): string {
-  if (first && status === "not_started") return "Added";
-  switch (status) {
-    case "working": return stage ? `${stage} stage` : "Working";
-    case "blocked": return "Blocked";
-    case "done": return "Done";
-    case "skipped": return "Skipped";
-    default: return "Back to not started";
-  }
+function labelFor(status: TicketStatus, stage: string | undefined, first: boolean): TimelineLabel {
+  if (first && status === "not_started") return { kind: "added" };
+  if (status === "working" && stage) return { kind: "stage", stage };
+  return status === "not_started" ? { kind: "reset" } : { kind: "status", status };
 }
 
 export function ticketTimeline(ticket: Ticket, nowMs: number): TimelineStep[] {

package/shared/whats-new.ts

@@ -0,0 +1,16 @@
+// A changelog bullet can open with a tag, like `- [Fixed] **Title.** Detail.`,
+// that says what kind of change it is. The parser and the dialog both read
+// this table. `tone` is the hue the dialog colors the tag with.
+export const NOTE_KINDS = {
+  new: { label: "New", tone: "green" },
+  improved: { label: "Improved", tone: "violet" },
+  fixed: { label: "Fixed", tone: "amber" },
+} as const;
+
+export type NoteTone = (typeof NOTE_KINDS)[NoteKind]["tone"];
+
+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[] };

package/shared/write-up.ts

@@ -1,9 +1,9 @@
 // A ticket's write-up (its Markdown source file) as simple blocks the dialog
 // can draw without a Markdown renderer: headings, paragraphs, list items and
-// code. Inline marks are kept as spans: `code` stays code, **bold** and
-// _emphasis_ lose their markers, and [links](url) keep only their text.
+// code. Inline marks are kept as spans: `code` stays code, **bold** stays
+// bold, _emphasis_ loses its markers, and [links](url) keep only their text.
 
-export type Span = { text: string; code?: boolean };
+export type Span = { text: string; code?: boolean; strong?: boolean };
 
 export type Block =
   | { kind: "heading"; level: number; spans: Span[] }
@@ -20,11 +20,12 @@ export function spans(text: string): Span[] {
       result.push({ text: part.slice(1, -1), code: true });
       return;
     }
-    const plain = part
-      .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
-      .replace(/(\*\*|__)(.+?)\1/g, "$2")
-      .replace(/(^|[\s(])[*_](\S(?:.*?\S)?)[*_](?=[\s).,;:!?]|$)/g, "$1$2");
-    result.push({ text: plain });
+    part.replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").split(/((?:\*\*|__).+?(?:\*\*|__))/).forEach((piece) => {
+      if (!piece) return;
+      const strong = /^(\*\*|__).+\1$/.test(piece);
+      const text = (strong ? piece.slice(2, -2) : piece).replace(/(^|[\s(])[*_](\S(?:.*?\S)?)[*_](?=[\s).,;:!?]|$)/g, "$1$2");
+      result.push(strong ? { text, strong } : { text });
+    });
   });
   return result;
 }

package/skills/paseo-progress/SKILL.md

@@ -1,92 +1,50 @@
 ---
 name: paseo-progress
-description: Record progress on the Paseo Progress dashboard with the paseo-progress command. Use when implementing a spec or a set of tickets, running any job with more than 5 steps or over 30 minutes, or when the user asks for a progress dashboard.
+description: Keep the Paseo Progress dashboard live with the paseo-progress command. Use when working through a spec or a set of tickets, on any job over 5 steps or 30 minutes, or when the user asks for a progress dashboard.
 ---
 
 # Paseo progress
 
-The user watches a live dashboard in Paseo, drawn from the progress file in this worktree. You keep it true by running `paseo-progress` the moment each change happens: the dashboard is a side effect of the work, never a summary written afterwards. Run it from inside the worktree you are working in: it records to that worktree's dashboard, and `show` names the worktree it read. `paseo-progress --help` lists every command; `paseo-progress <command> --help` gives its options.
+The user watches a live dashboard in Paseo for this worktree. Keep it live: run `paseo-progress` from inside the worktree the moment each change happens, so the dashboard is a side effect of the work. Write every line for a product manager, in plain words. `paseo-progress --help` is the reference for every command and flag.
 
-The user answers questions by reference ("Q7 A") and reads everything else at a glance, so every line you record is written for a product manager: plain words, no jargon.
+## 1. Set up
 
-## 1. Set up the run
+Run `paseo-progress show` and continue an open run for this job. A Finished run is closed, so `start` a new one, then add every ticket in order:
 
-Run `paseo-progress show`. When it shows an open run for this job, continue it. A run marked Finished is closed, even if it looks like your job; start a new one. Otherwise:
-
-1. `paseo-progress start "<job title>"`, with `--subtitle` naming the spec or ticket folder.
-2. Add every ticket in order with `paseo-progress ticket add "Ticket 01: <title>" --estimate <minutes>`, with `--waits-for T02` on any that can't start before another finishes. Keep the "Ticket NN:" prefix: the dashboard shortens titles to it. When a ticket is written up somewhere, a spec file or an issue, pass `--source <path or link>` so the user can open it from the ticket. For a job without tickets, add its steps instead and pass `--item-label Step` to `start`; give a step `--source` only when it has a write-up.
-3. `paseo-progress activity add "<one line: what this run will do>"`.
+- Title each `"Ticket 01: <title>"`. The dashboard shortens titles to that prefix.
+- Give each an `--estimate`, plus `--waits-for` when it can't start before another and `--source` when a spec file or issue describes it.
+- For a job without tickets, add its steps and pass `--item-label Step` to `start`.
 
 Done when `show` lists every ticket with an estimate.
 
-## 2. Work each ticket
-
-Record each change as it happens, on the ticket's id from `show` (T01, T02, ...):
-
-| When | Command |
-| --- | --- |
-| You start a ticket | `ticket update T03 --status working --stage Build` |
-| You move to the next stage | `ticket update T03 --stage Review`, then `Fixes`, then `Verify` |
-| Something reviewable lands (a screenshot folder, a screen recording, a report, a preview URL) | `deliverable add "<what it shows>" <path or URL> --ticket T03` |
-| A milestone the user would want in the story | `activity add "<one line>" --ticket T03` |
-| Between bigger events | `ticker set "<what you are doing right now>"` |
-| The ticket is finished | `ticket update T03 --status done`, then start the next one |
-| The plan drops it | `ticket update T03 --status skipped --note "<why>"` |
-
-Pass `--ticket` on every activity, deliverable and question that belongs to a ticket. The user presses a ticket to see its story: each stage and how long it took, with the activity, deliverables and questions tagged to it. Leave it off only for run-wide notes. Stage changes and notes are timed from your `ticket update` calls, so make them when the change happens.
-
-Other sessions may add tickets (or steps) to the same run. When a command's output says another session added one, it is part of the plan: work it in order after your current one, the same as the ones you added.
-
-A working ticket turns stuck on its own once it goes longer than its estimate without an update: a status, stage or note change, or activity tagged to it. When a ticket will run long, keep updating its stage, or raise its estimate with `--estimate`.
-
-A subagent records the work you hand it. Paseo shows you as idle while you wait on it, so its updates are the only sign the work is still going; after 15 minutes without one, the dashboard warns that the work may have stopped. Mark the ticket working, then put this in the subagent's prompt with this worktree's absolute path and the ticket id filled in:
-
-```text
-Record progress on the Paseo dashboard as you work:
-- at each new stage: cd <worktree> && paseo-progress ticket update T03 --stage <stage>
-- between stages:    cd <worktree> && paseo-progress ticker set "<what you are doing now>"
-```
-
-The `cd` puts the updates on this worktree's dashboard even when the subagent works in another checkout. When the subagent reports back, mark the ticket done.
-
-## 3. Ask questions, and work around them
+## 2. Work
 
-When a decision belongs to the user, ask it, then park everything the answer affects:
+Move each ticket through `--status working --stage Build`, then the stages `Review`, `Fixes` and `Verify`, then `--status done`. Along the way, record what the user would want to see: `deliverable add` for anything reviewable, `activity add` for milestones, `ticker set` for what you are doing right now. Tag each with `--ticket` unless it covers the whole run.
 
-```sh
-paseo-progress question ask "<short title>" "<the question, in one or two sentences>" \
-  --option "A=<choice> | <what happens if they pick it>" \
-  --option "B=<choice> | <what happens if they pick it>" \
-  --recommend <letter> --ticket T03 --raised-by "Ticket 03 design review" \
-  [--background "<what they need to decide without opening the worktree>"] \
-  [--file <path or http(s) URL>=<what it shows>]
-```
+- A ticket past its estimate with no update turns stuck. Keep its stage current, or raise its `--estimate`.
+- A ticket another session adds is part of the plan. Work it in order.
+- `--status blocked` and `stuck set` are for things outside the run, like a service that's down or missing access.
+- Put this in a subagent's prompt, with the worktree path and ticket id filled in. While you wait on it, its updates are the dashboard's only sign the work is moving:
 
-- `--recommend` is the option you would pick, so the user knows which way to lean.
-- Build no option before the user answers, not even the one you recommend. The point of asking is that the user decides before the work is done.
-- Keep working on whatever the question doesn't affect: other tickets, or other parts of this one. If nothing else is left, stop, tell the user in chat which questions you're waiting on, and leave the run open.
-- When the user replies ("Q7 A", or in their own words), run `question answer Q7 A --words "<their words>"`, then build what they chose.
-- When a question is about how something looks, attach the screenshot, mockup or preview link with `--file`. The user opens it from the question: images and videos preview in Paseo, links open in its browser. Add more later with `question update Q7 --file <path>=<what it shows>`.
-- When the user asks about a question, answer in chat and also put the explanation on the question with `question update Q7 --background "<text>"`, so the dashboard carries it too.
-- `question remove Q7` withdraws a question that no longer applies.
+  ```text
+  Record progress on the Paseo dashboard as you work:
+  - at each new stage: cd <worktree> && paseo-progress ticket update T03 --stage <stage>
+  - between stages:    cd <worktree> && paseo-progress ticker set "<what you are doing now>"
+  ```
 
-## 4. Flag what is stuck
+Done when every ticket is done or skipped, or waits on a question.
 
-- A ticket that has to wait for another ticket in this run is not stuck; that's just the order of work. Record it with `ticket add ... --waits-for T03` (or `ticket update T05 --waits-for T03`) and leave its status alone. The dashboard shows it calmly as waiting until T03 is done.
-- A ticket held up by something outside the run (a service, access, a decision nobody has made): `ticket update T03 --status blocked --note "<what it waits on>"`. That shows as stuck. Set it back to `working` when it moves again.
-- A blocker outside any ticket (a failing service, a missing key): `stuck set "<reason>" [--ticket T03]`, then `stuck clear S1` once it is gone.
+## 3. Ask
 
-## 5. Finish
+When a decision belongs to the user, ask it with `question ask`, lettered `--option`s and your `--recommend`. Read `paseo-progress question ask --help` before your first question. It defines a big question, which you mark with `--big "<the test it meets>"`.
 
-When the job is over:
+The user picks the question mode in Paseo's Settings, and `question ask` prints what that mode means for this question. Do what it prints. Record the user's reply ("Q7 A", or their own words) with `question answer Q7 A --words "<their words>"`, and do what that prints too.
 
-1. Mark the last ticket done or skipped.
-2. Settle every open question: record the user's answer, or withdraw it with `question remove` when it no longer applies. Clear flagged blockers with `stuck clear`.
-3. `paseo-progress finish "<one line: the outcome>"`. It refuses, and says what is still open, until the steps above are done.
-4. Run `paseo-progress show`.
+- When the question is about how something looks, attach the screenshot or link with `--file`.
+- When the user asks about a question, answer in chat and add the explanation with `question update Q7 --background`.
 
-The finished run stays on the dashboard, marked Finished with its outcome, until the next `start`. It takes no more updates.
+## 4. Finish
 
-If the job pauses with questions only the user can answer, don't finish: leave the run open so the questions stay in front of them.
+The job is over when every ticket is done or skipped and every question is answered. While questions wait on the user, leave the run open and tell the user in chat which ones. Then run `paseo-progress finish "<one-line outcome>"`, and settle whatever it lists if it refuses.
 
 Done when `show` says Finished with the right outcome.