@stevecastaneda/paseo-progress 1.13.1 → 1.14.1

package/server/store.ts

@@ -5,30 +5,24 @@
 import { execFile } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { appendFile, mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, normalize, resolve } from "node:path";
+import { basename, dirname, join, normalize, resolve, sep } from "node:path";
 import { promisify } from "node:util";
-import { LEGACY_FOLDER, PANEL_OPENED_NAME, PROGRESS_FILE_NAME } from "../shared/events.ts";
-import { withLock } from "./lock.ts";
-import { outside } from "./paths.ts";
+import { latestRun, parseProgress } from "../shared/dashboard.ts";
+import { hasGitEntry, inGitFolder, outside } from "./paths.ts";
 
-const LOCK_NAME = `${PROGRESS_FILE_NAME}.lock`;
 const SAVE_RUNS_KEY = "paseo-progress.saveRuns";
-// Exactly what 0.1.x wrote into .scratch/.gitignore. Only this is ever removed.
-const LEGACY_GITIGNORE = `# Added by the progress plugin for Paseo so its files stay out of git.
-${PROGRESS_FILE_NAME}
-${LOCK_NAME}/
-${PANEL_OPENED_NAME}
-.gitignore
-`;
 
 // `directory` holds the working files. `shown` names it for people.
 export type Store = { directory: string; shown: string };
 
-export async function git(cwd: string, args: string[]): Promise<{ code: number; stdout: string }> {
+// Git runs in the worktree through -C, started from the folder Node itself
+// lives in: Windows looks for a program in the folder it starts in before
+// PATH, and a cloned repo can commit a git.exe.
+export async function git(root: string, args: string[]): Promise<{ code: number; stdout: string }> {
   try {
-    const { stdout } = await promisify(execFile)("git", args, { cwd });
+    const { stdout } = await promisify(execFile)("git", ["-C", resolve(root), ...args], { cwd: dirname(process.execPath) });
     return { code: 0, stdout };
   } catch (error) {
     const failed = error as { code?: number | string; stdout?: string };
@@ -36,10 +30,6 @@ export async function git(cwd: string, args: string[]): Promise<{ code: number;
   }
 }
 
-async function exists(path: string): Promise<boolean> {
-  return Boolean(await stat(path).catch(() => null));
-}
-
 // The plugin's per-user folder on this computer.
 export function stateRoot(home = homedir()): string {
   return join(home, ".local", "state", "paseo-progress");
@@ -68,76 +58,37 @@ export function outsideDirectory(root: string, home = homedir()): string {
   return join(stateRoot(home), `${basename(real)}-${hash}`);
 }
 
-// Whether git tracks a 0.1.x progress file, per worktree, until the file changes.
-const trackedLegacy = new Map<string, { mtimeMs: number; tracked: boolean }>();
-
-async function legacyTracked(root: string, mtimeMs: number): Promise<boolean> {
-  const cached = trackedLegacy.get(root);
-  if (cached && cached.mtimeMs === mtimeMs) return cached.tracked;
-  const { code } = await git(root, ["ls-files", "--error-unmatch", "--", `${LEGACY_FOLDER}/${PROGRESS_FILE_NAME}`]);
-  trackedLegacy.set(root, { mtimeMs, tracked: code === 0 });
-  return code === 0;
-}
-
-// The worktree's working files. A run 0.1.x left in .scratch moves outside the
-// first time anything asks, unless git tracks it: then it stays and is used in
-// place, so nothing changes for a repo that commits it.
-export async function findStore(root: string, home = homedir()): Promise<Store> {
+// The worktree's working files, always outside the repo. Progress never reads
+// a repo's .scratch, where 0.1.x kept them: a cloned repo could put anything there.
+export function findStore(root: string, home = homedir()): Store {
   const directory = outsideDirectory(root, home);
-  const store = { directory, shown: directory.startsWith(home) ? `~${directory.slice(home.length)}` : directory };
-  const legacy = join(root, LEGACY_FOLDER);
-  const info = await stat(join(legacy, PROGRESS_FILE_NAME)).catch(() => null);
-  if (!info) return store;
-  if (await legacyTracked(root, info.mtimeMs)) return { directory: legacy, shown: LEGACY_FOLDER };
-  await moveLegacy(legacy, directory);
-  return store;
-}
-
-// Appends the old file's lines to the new one rather than replacing it, so a
-// command that wrote to the old place mid-move loses nothing: the next move
-// picks those lines up. Then tidies what 0.1.x left behind.
-async function moveLegacy(legacy: string, directory: string): Promise<void> {
-  await mkdir(directory, { recursive: true });
-  await withLock(join(legacy, LOCK_NAME), async () => {
-    const text = await readFile(join(legacy, PROGRESS_FILE_NAME), "utf8").catch(() => null);
-    if (text === null) return;
-    await withLock(join(directory, LOCK_NAME), async () => {
-      const current = await readFile(join(directory, PROGRESS_FILE_NAME), "utf8").catch(() => "");
-      const lead = current && !current.endsWith("\n") ? "\n" : "";
-      await appendFile(join(directory, PROGRESS_FILE_NAME), `${lead}${text}`);
-    });
-    await rm(join(legacy, PROGRESS_FILE_NAME));
-    if (await exists(join(legacy, PANEL_OPENED_NAME))) {
-      await writeFile(join(directory, PANEL_OPENED_NAME), "");
-      await rm(join(legacy, PANEL_OPENED_NAME));
-    }
-  });
-  const ignore = await readFile(join(legacy, ".gitignore"), "utf8").catch(() => null);
-  if (ignore === LEGACY_GITIGNORE) await rm(join(legacy, ".gitignore"));
-  // Only if nothing else is in there; the user's own files keep the folder.
-  await rmdir(legacy).catch(() => {});
+  return { directory, shown: directory.startsWith(home) ? `~${directory.slice(home.length)}` : directory };
 }
 
 // The repo's saved-history folder, kept in its local git config, which every
 // worktree of the repo shares and nothing commits. Polls cost one stat; git
-// runs again only when the config file changes.
-const configFiles = new Map<string, string | null>();
+// runs again only when the config file changes. A worktree with no .git
+// entry is no repo; when git fails in one that has it, the next poll asks again.
+const configFiles = new Map<string, string>();
 const savedFolders = new Map<string, { mtimeMs: number; folder: string | null }>();
 
 async function configFile(root: string): Promise<string | null> {
+  if (!hasGitEntry(root)) return null;
   if (!configFiles.has(root)) {
     const { code, stdout } = await git(root, ["rev-parse", "--git-common-dir"]);
-    configFiles.set(root, code === 0 ? join(resolve(root, stdout.trim()), "config") : null);
+    if (code !== 0) return null;
+    configFiles.set(root, join(resolve(root, stdout.trim()), "config"));
   }
   return configFiles.get(root)!;
 }
 
-// Whether the worktree is in a git repo, which saving run history needs.
+// Whether git answers for the worktree's repo, which saving run history needs.
 export async function inGitRepo(root: string): Promise<boolean> {
   return (await configFile(root)) !== null;
 }
 
-// The folder runs are saved to, relative to the worktree root, or null.
+// The folder runs are saved to, relative to the worktree root, or null. A
+// folder set outside Paseo gets the same check as one picked in it.
 export async function historyFolder(root: string): Promise<string | null> {
   const file = await configFile(root);
   if (file === null) return null;
@@ -145,7 +96,8 @@ export async function historyFolder(root: string): Promise<string | null> {
   const cached = savedFolders.get(file);
   if (cached && cached.mtimeMs === mtimeMs) return cached.folder;
   const { stdout } = await git(root, ["config", "--get", SAVE_RUNS_KEY]);
-  const folder = stdout.trim() || null;
+  const checked = checkFolder(stdout);
+  const folder = "folder" in checked ? checked.folder : null;
   savedFolders.set(file, { mtimeMs, folder });
   return folder;
 }
@@ -156,7 +108,7 @@ export function checkFolder(raw: string): { folder: string } | { error: string }
   if (!trimmed) return { error: "Choose a folder" };
   const folder = normalize(trimmed);
   if (outside(folder) || folder === ".") return { error: "Choose a folder inside the repo" };
-  if (folder === ".git" || folder.startsWith(".git/")) return { error: "Choose a folder outside .git" };
+  if (inGitFolder(folder)) return { error: "Choose a folder outside .git" };
   return { folder };
 }
 
@@ -189,27 +141,32 @@ export function runFileName(startedAt: string, title: string): string {
 export async function saveRunCopy(root: string, text: string): Promise<void> {
   const folder = await historyFolder(root);
   if (!folder) return;
-  const lines = text.split("\n").filter((line) => line.trim());
-  let start = -1;
-  let event: { ts?: string; title?: string } | null = null;
-  for (let index = lines.length - 1; index >= 0; index--) {
-    try {
-      const parsed = JSON.parse(lines[index]);
-      if (parsed?.type === "run.start") {
-        start = index;
-        event = parsed;
-        break;
-      }
-    } catch {}
+  // The run the dashboard shows. A start line it can't read is no run.
+  const [start] = latestRun(parseProgress(text).events);
+  if (start?.event.type !== "run.start") return;
+  const lines = text.split("\n").slice(start.line - 1).filter((line) => line.trim());
+  const directory = await runsFolder(root, folder);
+  if (!directory) return;
+  // A rename replaces a link at the run's file instead of writing through it.
+  await writeAtomic(join(directory, runFileName(start.event.ts, start.event.title)), `${lines.join("\n")}\n`);
+}
+
+// The saved-runs folder in the real worktree, made one step at a time, or null
+// when any step is a link or a file: a cloned repo can commit a link that leads
+// out of it.
+async function runsFolder(root: string, folder: string): Promise<string | null> {
+  let directory = await realpath(root);
+  for (const name of folder.split(sep)) {
+    directory = join(directory, name);
+    const info = await lstat(directory).catch(() => null);
+    if (!info) await mkdir(directory);
+    else if (!info.isDirectory()) return null;
   }
-  if (start < 0 || !event?.ts || !event.title) return;
-  const directory = join(root, folder);
-  await mkdir(directory, { recursive: true });
-  await writeFile(join(directory, runFileName(event.ts, event.title)), `${lines.slice(start).join("\n")}\n`);
+  return directory;
 }
 
 // The folders directly inside one folder of the worktree ("" is the top), for
-// the folder picker. .git is left out; so are links, which could leave the repo.
+// the folder picker. .git folders are left out; so are links, which could leave the repo.
 export async function listFolders(root: string, folder: string): Promise<{ folder: string; folders: string[] }> {
   const checked = folder === "" ? { folder: "" } : checkFolder(folder);
   if ("error" in checked) throw new Error(checked.error);
@@ -217,6 +174,6 @@ export async function listFolders(root: string, folder: string): Promise<{ folde
     if (error.code === "ENOENT") return [];
     throw error;
   });
-  const folders = entries.filter((entry) => entry.isDirectory() && !(checked.folder === "" && entry.name === ".git")).map((entry) => entry.name);
+  const folders = entries.filter((entry) => entry.isDirectory() && !inGitFolder(entry.name)).map((entry) => entry.name);
   return { folder: checked.folder, folders: folders.sort((a, b) => a.localeCompare(b)) };
 }

package/server/tool.ts

@@ -0,0 +1,174 @@
+import type { AgentToolContext, AgentToolDefinition, AgentToolResult, PluginHandlerContext, PluginServerContext } from "@getpaseo/plugin/server";
+import * as sdk from "@getpaseo/plugin/server";
+import { z } from "zod";
+import { DELIVERABLE_KINDS, ticketStatusSchema } from "../shared/events.ts";
+import type { ToolsState } from "../shared/rpc.ts";
+import { PROGRESS_TOOL_NAMES, type ProgressToolName } from "../shared/tools.ts";
+import { commandSummary, runCli } from "./cli.ts";
+
+// Paseo supplies this SDK at runtime. Paseo 0.13's has no defineAgentTool and
+// can't give agents plugin tools; reading the name calls nothing, so it's safe there.
+export const agentToolsSupported = "defineAgentTool" in sdk;
+
+// Importing defineAgentTool would stop Progress loading on Paseo 0.13. This
+// mirrors its typing; Paseo validates the input before execute.
+type Tool = Omit<AgentToolDefinition, "name">;
+
+function agentTool<Input extends z.ZodType>(tool: Omit<Tool, "input" | "execute"> & {
+  input: Input;
+  execute(input: z.output<Input>, context: AgentToolContext): Promise<AgentToolResult>;
+}): Tool {
+  return { ...tool, execute: (input, context) => tool.execute(input as z.output<Input>, context) };
+}
+
+async function run(args: string[], { agent }: AgentToolContext): Promise<AgentToolResult> {
+  const lines: string[] = [];
+  const code = await runCli(args, { cwd: agent.cwd, agentId: agent.id, out: (line) => lines.push(line) });
+  return { text: lines.join("\n"), isError: code !== 0 };
+}
+
+type Flags = Record<string, string | number | string[] | undefined>;
+
+// Flags go as --name=value so a value starting with "-" stays a value, and the
+// positionals follow "--" so a title starting with "-" isn't read as a flag.
+function commandArgs(command: string, positionals: string[], flags: Flags = {}): string[] {
+  const options = Object.entries(flags).flatMap(([name, value]) => (value === undefined ? [] : [value].flat().map((entry) => `--${name}=${entry}`)));
+  return [...command.split(" "), ...options, "--", ...positionals];
+}
+
+// The command's --help summary, with its flags renamed to this tool's fields.
+const FIELD_FOR_FLAG: Record<string, string> = { estimate: "estimateMinutes", option: "options", file: "files" };
+function toolSummary(command: string): string {
+  return commandSummary(command).replace(/--([a-z]+(?:-[a-z]+)*)/g, (_, flag: string) =>
+    FIELD_FOR_FLAG[flag] ?? flag.replace(/-([a-z])/g, (_m, letter: string) => letter.toUpperCase()));
+}
+
+function commandTool<Input extends z.ZodType>(title: string, command: string, input: Input, args: (input: z.output<Input>) => string[], extra = "") {
+  return agentTool({
+    title: `Progress: ${title}`,
+    description: `Progress dashboard for this worktree in Paseo. ${toolSummary(command)}${extra}`,
+    input,
+    execute: (value, context) => run(args(value), context),
+  });
+}
+
+const ticketId = (what: string) => z.string().describe(`${what}, like T03`);
+const estimate = z.number().int().describe("Whole minutes, like 90");
+const source = z.string().describe("Spec file path or http(s) link where the ticket is written up");
+
+// Keyed by name, so the compiler holds this to the shared list.
+const tools: Record<ProgressToolName, Tool> = {
+  progress_show: commandTool("Show", "show", z.object({}), () => ["show"]),
+  progress_start: commandTool("Start run", "start",
+    z.object({
+      title: z.string(),
+      subtitle: z.string().optional(),
+      itemLabel: z.string().optional().describe('What to call each item instead of "Ticket", like Step'),
+    }),
+    ({ title, subtitle, itemLabel }) => commandArgs("start", [title], { subtitle, "item-label": itemLabel })),
+  progress_ticket_add: commandTool("Add ticket", "ticket add",
+    z.object({
+      title: z.string().describe('Like "Ticket 01: Export button"'),
+      estimateMinutes: estimate,
+      status: ticketStatusSchema.optional(),
+      waitsFor: ticketId("A ticket this one can't start before").optional(),
+      source: source.optional(),
+    }),
+    ({ title, estimateMinutes, status, waitsFor, source }) => commandArgs("ticket add", [title], { estimate: estimateMinutes, status, "waits-for": waitsFor, source })),
+  progress_ticket_update: commandTool("Update ticket", "ticket update",
+    z.object({
+      id: ticketId("The ticket"),
+      status: ticketStatusSchema.optional(),
+      stage: z.string().optional().describe('The step in progress, like Build or Fixes; "" clears it'),
+      title: z.string().optional(),
+      estimateMinutes: estimate.optional(),
+      note: z.string().optional(),
+      waitsFor: z.string().optional().describe('A ticket this one can\'t start before, like T02; "" clears it'),
+      source: z.string().optional().describe('Spec file path or http(s) link where the ticket is written up; "" clears it'),
+    }),
+    ({ id, status, stage, title, estimateMinutes, note, waitsFor, source }) =>
+      commandArgs("ticket update", [id], { status, stage, title, estimate: estimateMinutes, note, "waits-for": waitsFor, source })),
+  progress_question_ask: commandTool("Ask question", "question ask",
+    z.object({
+      title: z.string().describe("A short title"),
+      question: z.string(),
+      options: z.array(z.object({
+        letter: z.string().describe("A, B, C, ..."),
+        label: z.string(),
+        consequence: z.string().describe("What picking it means for the user"),
+      })),
+      recommend: z.string().describe("The option letter you would pick"),
+      big: z.string().optional().describe("Only for a big question: which test it meets, in a few plain words"),
+      background: z.string().optional(),
+      files: z.array(z.object({
+        target: z.string().describe("A file path or http(s) link, like a screenshot"),
+        label: z.string().optional(),
+      })).optional(),
+      ticket: ticketId("The ticket it's about").optional(),
+    }),
+    ({ title, question, options, recommend, big, background, files, ticket }) => commandArgs("question ask", [title, question], {
+      option: options.map(({ letter, label, consequence }) => `${letter}=${label} | ${consequence}`),
+      recommend,
+      big,
+      background,
+      file: files?.map(({ target, label }) => (label ? `${target}=${label}` : target)),
+      ticket,
+    })),
+  progress_question_answer: commandTool("Record answer", "question answer",
+    z.object({
+      id: z.string().describe("The question, like Q2"),
+      choice: z.string().describe("An option letter, or the user's own short answer"),
+      words: z.string().optional().describe("What the user said"),
+    }),
+    ({ id, choice, words }) => commandArgs("question answer", [id, choice], { words })),
+  progress_deliverable_add: commandTool("Add deliverable", "deliverable add",
+    z.object({
+      title: z.string(),
+      target: z.string().describe("A file or folder path, or an http(s) link"),
+      ticket: ticketId("The ticket it belongs to").optional(),
+      kind: z.enum(DELIVERABLE_KINDS).optional(),
+    }),
+    ({ title, target, ticket, kind }) => commandArgs("deliverable add", [title, target], { ticket, kind })),
+  progress_activity_add: commandTool("Log activity", "activity add",
+    z.object({ text: z.string(), ticket: ticketId("The ticket it's about").optional() }),
+    ({ text, ticket }) => commandArgs("activity add", [text], { ticket })),
+  progress_ticker: commandTool("Set ticker", "ticker set",
+    z.object({ text: z.string() }),
+    ({ text }) => (text.trim() ? commandArgs("ticker set", [text]) : commandArgs("ticker clear", [])),
+    ' Pass "" to hide it.'),
+  progress_finish: commandTool("Finish run", "finish",
+    z.object({ outcome: z.string().describe("One line") }),
+    ({ outcome }) => commandArgs("finish", [outcome])),
+  paseo_progress: agentTool({
+    title: "Progress",
+    description: [
+      "Record progress for this worktree on the Progress panel in Paseo. Works like the paseo-progress command:",
+      'pass its arguments as a list, like ["ticket", "add", "Fix login", "--estimate", "30"].',
+      'Pass ["--help"] to list the commands, or add "--help" after any command for its options.',
+    ].join(" "),
+    input: z.object({ args: z.array(z.string()).min(1).describe("Arguments for paseo-progress, one per item") }),
+    execute: ({ args }, context) => run(args, context),
+  }),
+};
+
+export const progressTools: AgentToolDefinition[] = PROGRESS_TOOL_NAMES.map((name) => ({ name, ...tools[name] }));
+
+export function attachProgressTools(server: PluginServerContext): void {
+  server.before("agent.session_open", ({ request }) => {
+    // Paseo 0.13 has no tools list and fails the session open if a plugin adds one.
+    if (!Array.isArray(request.tools)) return;
+    return { ...request, tools: [...request.tools, ...progressTools] };
+  });
+}
+
+// Tools reach agents only while the host's "Enable Paseo tools" setting is on,
+// which needs Paseo's tools (mcp.enabled) on as well.
+export async function toolsState(supported: boolean, paseo: PluginHandlerContext["paseo"]): Promise<ToolsState> {
+  if (!supported) return "unsupported";
+  const { config } = await paseo.config.get();
+  return config.mcp.enabled !== false && config.mcp.injectIntoAgents ? "on" : "off";
+}
+
+export async function handleToolsStatus(_input: unknown, { paseo }: PluginHandlerContext): Promise<{ state: ToolsState }> {
+  return { state: await toolsState(agentToolsSupported, paseo) };
+}

package/shared/events.ts

@@ -7,8 +7,6 @@ import { QUESTION_MODES } from "./question-modes.ts";
 export const PROGRESS_FILE_NAME = "progress.jsonl";
 // Present once someone has opened the Progress panel for this worktree.
 export const PANEL_OPENED_NAME = "progress-panel-opened";
-// Where 0.1.x kept each worktree's files. store.ts moves them out.
-export const LEGACY_FOLDER = ".scratch";
 export const EVENT_VERSION = 1;
 
 export const TICKET_STATUSES = ["not_started", "working", "blocked", "done", "skipped"] as const;

package/shared/rpc.ts

@@ -69,6 +69,17 @@ export const installLauncher = defineRpc({
   output: launcherStatus,
 });
 
+// Whether agents get the Progress tools: "unsupported" before Paseo 0.14, then
+// whether the host's "Enable Paseo tools" setting is "on" or "off".
+export const TOOLS_STATES = ["unsupported", "off", "on"] as const;
+export type ToolsState = (typeof TOOLS_STATES)[number];
+
+export const getToolsStatus = defineRpc({
+  name: "progress.tools.status",
+  input: z.object({}),
+  output: z.object({ state: z.enum(TOOLS_STATES) }),
+});
+
 // The paseo-progress skill, linked into each agent's skills folder.
 const skillState = z.enum(["missing", "current", "outdated", "foreign"]);
 const skillStatus = z.object({

package/shared/tools.ts

@@ -0,0 +1,23 @@
+// The tools Progress hands agents on Paseo 0.14 and later. The server defines
+// one tool per name, and the chat draws Progress's own row for a call to any of them.
+export const PROGRESS_TOOL_NAMES = [
+  "progress_show",
+  "progress_start",
+  "progress_ticket_add",
+  "progress_ticket_update",
+  "progress_question_ask",
+  "progress_question_answer",
+  "progress_deliverable_add",
+  "progress_activity_add",
+  "progress_ticker",
+  "progress_finish",
+  "paseo_progress",
+] as const;
+
+export type ProgressToolName = (typeof PROGRESS_TOOL_NAMES)[number];
+
+// Chats record a tool under the agent's own prefix: Claude Code's
+// mcp__paseo__progress_ticket_add, or Codex's paseo.progress_ticket_add.
+export function progressToolName(name: string): ProgressToolName | undefined {
+  return PROGRESS_TOOL_NAMES.find((tool) => name === tool || name.endsWith(`__${tool}`) || name.endsWith(`.${tool}`));
+}

package/skills/paseo-progress/SKILL.md

@@ -1,15 +1,19 @@
 ---
 name: paseo-progress
-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.
+description: Keep the Paseo Progress dashboard live with the Progress tools or 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 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 watches a live dashboard in Paseo for this worktree. Keep it live: record each change the moment it happens, so the dashboard is a side effect of the work. Write every line for a product manager, in plain words.
+
+Use the Progress tools when you have them: `progress_show`, `progress_start`, `progress_ticket_add`, `progress_ticket_update`, `progress_question_ask`, `progress_question_answer`, `progress_deliverable_add`, `progress_activity_add`, `progress_ticker`, `progress_finish`, and `paseo_progress` for any other command. Paseo hands them to agents when the user turns on Paseo tools. Claude Code names them like `mcp__paseo__progress_show` and keeps them hidden until you search, so search your tools for `progress_` before your first update. Otherwise, run the `paseo-progress` command from inside the worktree. When a tool call says the tool isn't found, use the command for the rest of that reply.
+
+The tools and the command take the same values and print the same answers. The steps below use the command's words: `--estimate` is `estimateMinutes` in the tools, `--waits-for` is `waitsFor`. `paseo-progress --help` is the reference for every command and flag.
 
 ## 1. Set up
 
-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 `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:
 
 - 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.
@@ -27,16 +31,20 @@ Move each ticket through `--status working --stage Build`, then the stages `Revi
 - 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:
 
   ```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>"
+  Record progress on the Paseo dashboard as you work. Use the Progress tools if you
+  have them (search your tools for progress_), otherwise the paseo-progress command.
+  If a tool call says the tool isn't found, use the command for the rest of that reply.
+  - at each new stage: progress_ticket_update with id T03 and stage <stage>,
+    or: cd <worktree> && paseo-progress ticket update T03 --stage <stage>
+  - between stages:    progress_ticker with "<what you are doing now>",
+    or: cd <worktree> && paseo-progress ticker set "<what you are doing now>"
   ```
 
 Done when every ticket is done or skipped, or waits on a question.
 
 ## 3. Ask
 
-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 a decision belongs to the user, ask it with `question ask`, lettered `--option`s and your `--recommend`. Read the `progress_question_ask` description or `paseo-progress question ask --help` before your first question. Both define a big question, which you mark with `--big "<the test it meets>"`.
 
 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.
 
@@ -45,6 +53,6 @@ The user picks the question mode in Paseo's Settings, and `question ask` prints
 
 ## 4. Finish
 
-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.
+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 `finish` with a one-line outcome, and settle whatever it lists if it refuses.
 
 Done when `show` says Finished with the right outcome.