fix: prefer representation-first progress cards (#125613)

docs/tools/progress-card.md

@@ -37,7 +37,7 @@ The tool returns a short receipt such as `Progress card updated (rev 4, 1/3 done
 
 ## Format the note
 
-Markdown accepts ordinary formatting, small tables, links, and optional progress bars:
+Choose the representation that makes the current state easiest to scan: use a table for comparisons or metrics, a progress bar for one long operation, and a checklist only when the work is genuinely sequential. Omit the checklist when a table, bar, or sentence says it better, and do not repeat the same facts across the plan and Markdown. Markdown accepts ordinary formatting, links, and optional progress bars:
 
 ```md
 Tests are running.

src/agents/tools/progress-card-tool.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import { createProgressCardTool } from "./progress-card-tool.js";
 
 const DESCRIPTION =
-  'Maintain this session\'s progress card: the single durable status surface shown next to the session in OpenClaw\'s UIs, for someone who is not reading the transcript. Each call replaces the whole card. Two optional parts: `plan` — an ordered step list (pending | in_progress | completed, at most one in_progress) rendered as a checklist with progress counts; and `markdown` — a compact narrative (what happened, what is blocked, what comes next), plus optional <progress value="3" max="7"></progress> bars and small tables; other raw HTML is stripped. Use plan for multi-step work; keep statuses current. Use markdown when a glanceable note says more than steps; do not duplicate the step list inside it. Call with both parts empty to clear. Update when the picture meaningfully changes — a step completes, a blocker appears, results land — not every message. Max 8 KB markdown, 50 steps.';
+  'Maintain this session\'s progress card: the single durable status surface shown next to the session in OpenClaw\'s UIs, for someone who is not reading the transcript. Keep it current on any task that takes more than a moment — it is how the user watches you work without scrolling. Each call replaces the whole card. Pick the representation that fits the work, using either or both parts: `markdown` — a compact note; tables for comparisons or metrics, <progress value="3" max="7"></progress> bars for one long operation, a bold one-liner for simple state; other raw HTML is stripped. And `plan` — an ordered step checklist (pending | in_progress | completed, at most one in_progress) for genuinely sequential work. The checklist is optional: omit it whenever a table, bar, or sentence says it better, and never repeat the same facts in both parts. Call with both parts empty to clear. Update on meaningful change — a step done, a blocker, results in — not every message. Max 8 KB markdown, 50 steps.';
 
 describe("progress_card tool", () => {
   it("replaces the card and returns compact progress receipts", async () => {

src/agents/tools/progress-card-tool.ts

@@ -32,7 +32,7 @@ export function createProgressCardTool(options: ProgressCardToolOptions = {}): A
     name: "progress_card",
     label: "Progress Card",
     description:
-      'Maintain this session\'s progress card: the single durable status surface shown next to the session in OpenClaw\'s UIs, for someone who is not reading the transcript. Each call replaces the whole card. Two optional parts: `plan` — an ordered step list (pending | in_progress | completed, at most one in_progress) rendered as a checklist with progress counts; and `markdown` — a compact narrative (what happened, what is blocked, what comes next), plus optional <progress value="3" max="7"></progress> bars and small tables; other raw HTML is stripped. Use plan for multi-step work; keep statuses current. Use markdown when a glanceable note says more than steps; do not duplicate the step list inside it. Call with both parts empty to clear. Update when the picture meaningfully changes — a step completes, a blocker appears, results land — not every message. Max 8 KB markdown, 50 steps.',
+      'Maintain this session\'s progress card: the single durable status surface shown next to the session in OpenClaw\'s UIs, for someone who is not reading the transcript. Keep it current on any task that takes more than a moment — it is how the user watches you work without scrolling. Each call replaces the whole card. Pick the representation that fits the work, using either or both parts: `markdown` — a compact note; tables for comparisons or metrics, <progress value="3" max="7"></progress> bars for one long operation, a bold one-liner for simple state; other raw HTML is stripped. And `plan` — an ordered step checklist (pending | in_progress | completed, at most one in_progress) for genuinely sequential work. The checklist is optional: omit it whenever a table, bar, or sentence says it better, and never repeat the same facts in both parts. Call with both parts empty to clear. Update on meaningful change — a step done, a blocker, results in — not every message. Max 8 KB markdown, 50 steps.',
     parameters: ProgressCardToolSchema,
     execute: async (_toolCallId, rawArgs) => {
       const sessionKey = options.agentSessionKey?.trim();