docs: sync CALM-TRANSCRIPT + align explanation word-count (PR review)

Second review pass flagged doc drift and a word-count mismatch:

- The `explanation` length was three different numbers — SYSTEM_BASE said 3-10,
  run_command's schema 5-10, read_file/search 3-8, the doc 5-10. Unified to
  **3-8 words** everywhere (prompt, all three schemas, D6). Every example given
  already fits that range.

- D3 claimed "no event schema changes" — but the `agentTool` payload gained
  `label`/`kind`/`path` (types unchanged, fields added, filled by agent.js).
  Reworded to say exactly that.

- "Not doing (yet)" still listed model-written labels for reads/searches as
  unbuilt; this PR implements them (required `explanation`, used as the row
  label). Removed that bullet and updated §1's baseline note to point at D6/S1.

Docs + prompt only; no behavior change. Gate green.

Author: ndemianc

docs/CALM-TRANSCRIPT.md

@@ -37,7 +37,8 @@ Two halves, shipped as separate slices: the **voice** (system prompt) and the **
   subtitle and the run card's italic `cmdwhy`), but the schema text doesn't say what to write and
   the system prompt never asks for it — in practice it's often missing. File ops post derived
   chips ("read X", `search "q"`). There is nothing like Claude Code's semantic command label
-  ("Found exact insertion point in section 10") unless we make `explanation` effectively required.
+  ("Found exact insertion point in section 10") unless we make `explanation` required — which D6/S1
+  now do (schema-required on all three tools).
 - **Diffstat data exists everywhere we need it**: `editApplied` carries per-file `add`/`del`
   (rendered `+N −M` on the edit card); `reviewState` carries the run aggregate. A group header sum
   is arithmetic on data already in the webview.
@@ -63,10 +64,12 @@ stay verbatim. The voice rules are additive: *narrate briefly, then call the too
 turn*. A narration-only turn that promises action remains a stall and still gets nudged. This is
 the difference between "calm" and "chatty but idle".
 
-### D3 — Grouping is a webview-only reducer. The extension host keeps posting the same events.
-No event schema changes, no agent.js changes for grouping. `chat.html` gets a small router:
-consecutive tool-ish entries (`agentTool` chips, `termRun` cards, `editApplied` cards, verify
-cards) are appended into the open group's body instead of `log`; any assistant text bubble,
+### D3 — Grouping is a webview-only reducer; the host keeps posting the same event *types*.
+No new event types and no host-side grouping logic. The `agentTool` payload does gain optional
+metadata — `label` (the model's `explanation`), `kind`, and `path` — so the webview can title and
+categorise rows; `agent.js` fills those fields, but the grouping decisions all live in `chat.html`.
+The router appends consecutive tool-ish entries (`agentTool` chips, `termRun` cards, `editApplied`
+cards, verify cards) into the open group's body instead of `log`; any assistant text bubble,
 `ask_user` card, `agentError`, or `agentDone` **closes** the group. This keeps the diff small,
 rebase-safe, and revertable (one function + CSS).
 
@@ -96,9 +99,9 @@ read+edit merged, summed diffstat, fallback "N steps" when the sentence would ge
 single-member group unwraps and hands the card back **expanded** — no group chrome.
 
 ### D6 — Labels: model-written, for every tool that has a story to tell.
-`run_command`, `read_file` and `search` all take a required `explanation`: "5–10 words, active
-voice, what it does — e.g. 'Find the insertion point in section 10'", and the voice rules require
-it. That sentence titles the row; the raw tool text (`read src/agent.js`) becomes the tooltip. UI
+`run_command`, `read_file` and `search` all take a required `explanation`: "3–8 words, active
+voice, what it does — e.g. 'Find the insertion point in section 10'" (the same range in the prompt
+and all three schemas), and the voice rules require it. That sentence titles the row; the raw tool text (`read src/agent.js`) becomes the tooltip. UI
 falls back to deriving a label from the arguments when absent (older transcripts, weaker models).
 Tense: a small verb map (Run/Ran/Running, Read, Edit, Verify, Search, Create, Delete, Install,
 Check ~a dozen) converts imperative → progressive/past; unknown verbs render as-is. No grammar
@@ -175,8 +178,6 @@ Then re-run with grouping toggled off and confirm the flat timeline is unchanged
 
 ## 6. Not doing (yet)
 
-- Model-written labels for file reads/searches (derived-only is enough parity; revisit if reads
-  dominate groups).
 - Group state across webview rebuilds / session restore.
 - Per-model prompt forks for the voice.
 - Collapsing `ask_user`/approvals into groups — deliberately excluded (D4).

extensions/levelcode-ai/agent.js

@@ -31,7 +31,7 @@ const SYSTEM_BASE = [
 	'- Use delete_file to remove an existing file (e.g. during a refactor). To RENAME/move a file, write_file the new path then delete_file the old one. Deletions are reviewable (Keep/Undo) and restorable from the per-turn checkpoint.',
 	'- Your file edits are APPLIED IMMEDIATELY and the user reviews them afterward in the editor with Keep/Undo — do NOT wait for approval, and do NOT re-edit a file you just edited. Only run_command still needs approval; if the user skips a command, adapt or stop.',
 	'- Commands that do NOT exit on their own (dev servers, file watchers, tail -f) MUST be run with run_command background:true — it returns immediately so you keep working instead of hanging. After starting one, call read_command_output with the returned id to watch for a readiness/port line (e.g. "listening on :3000") before you test against it. Use a normal foreground run_command for things that finish (builds, installs, tests, git, curl). This pairs with verification: bring the app up in the background, confirm it serves, fix, repeat.',
-	'- EVERY run_command, read_file and search MUST include "explanation": 3-10 words, active voice, imperative, saying what you are doing and why ("Run the extension unit tests", "Find the insertion point in section 10", "Read the runAgent call site"). It becomes that action\'s label in the user\'s activity view — never omit it.',
+	'- EVERY run_command, read_file and search MUST include "explanation": 3-8 words, active voice, imperative, saying what you are doing and why ("Run the extension unit tests", "Find the insertion point in section 10", "Read the runAgent call site"). It becomes that action\'s label in the user\'s activity view — never omit it.',
 	'- Paths are relative to the workspace root. In a MULTI-ROOT workspace (several top-level folders), paths from list_files/search are prefixed with the folder name (e.g. "thin.ly/app/models/link.rb") — use them exactly as shown; an unprefixed path resolves against the first folder. To create a file in a specific folder, prefix its name. run_command accepts an optional "folder" to pick which folder it runs in.',
 	'- For a multi-step goal, call update_plan FIRST with a short checklist (3-8 short items, all "pending"), then call it again to set an item "in_progress" when you start it and "done" when finished. Skip the plan for trivial single-step goals.',
 	'- If the goal truly depends on a decision only the user can make (tech stack, scope, where to create files, must-have features), call ask_user ONCE with concise multiple-choice questions (a short header + 2-4 concrete options each) INSTEAD of writing the questions as prose. Put your RECOMMENDED option FIRST and use its description to say why — and, when it matters, what would change your mind. Then act on their answers and do not ask again. Do NOT ask about things you can reasonably decide yourself — prefer a sensible default and proceed.',
@@ -48,7 +48,7 @@ const TOOLS = [
 	{ name: 'edit_file', description: 'Make a targeted edit to an EXISTING file: replace an exact, unique snippet (old_str) with new_str. Applied immediately; the user reviews it with Keep/Undo. old_str must appear exactly once — include enough surrounding context to be unique.', input_schema: { type: 'object', properties: { path: { type: 'string' }, old_str: { type: 'string' }, new_str: { type: 'string' } }, required: ['path', 'old_str', 'new_str'] } },
 	{ name: 'write_file', description: 'Create a new file (or fully overwrite a short one) with the COMPLETE content. For edits to existing files, prefer edit_file. Applied immediately; the user reviews it with Keep/Undo.', input_schema: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] } },
 	{ name: 'delete_file', description: 'Delete an EXISTING workspace file (e.g. removing a file during a refactor). Applied immediately; the user reviews it with Keep/Undo, and the per-turn checkpoint can restore it. To RENAME or move a file: write_file the new path, then delete_file the old one.', input_schema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } },
-	{ name: 'run_command', description: 'Run a shell command in the workspace root (or a named workspace folder via "folder" in multi-root workspaces). Requires approval. Pass background:true for commands that do not exit on their own (servers, watchers) so the agent is not blocked — it returns immediately and you read progress later with read_command_output.', input_schema: { type: 'object', properties: { command: { type: 'string' }, explanation: { type: 'string', description: 'REQUIRED: 5-10 words, active voice, imperative — what this command does ("Run the extension unit tests", "Find the insertion point in section 10"). Shown to the user as this action\'s label.' }, folder: { type: 'string', description: 'multi-root workspaces only: the workspace folder NAME to run in; defaults to the first folder' }, background: { type: 'boolean', description: 'true = start it and keep working without waiting (dev servers, watchers, tail -f). Returns immediately with an id; poll read_command_output for its output/status.' } }, required: ['command', 'explanation'] } },
+	{ name: 'run_command', description: 'Run a shell command in the workspace root (or a named workspace folder via "folder" in multi-root workspaces). Requires approval. Pass background:true for commands that do not exit on their own (servers, watchers) so the agent is not blocked — it returns immediately and you read progress later with read_command_output.', input_schema: { type: 'object', properties: { command: { type: 'string' }, explanation: { type: 'string', description: 'REQUIRED: 3-8 words, active voice, imperative — what this command does ("Run the extension unit tests", "Find the insertion point in section 10"). Shown to the user as this action\'s label.' }, folder: { type: 'string', description: 'multi-root workspaces only: the workspace folder NAME to run in; defaults to the first folder' }, background: { type: 'boolean', description: 'true = start it and keep working without waiting (dev servers, watchers, tail -f). Returns immediately with an id; poll read_command_output for its output/status.' } }, required: ['command', 'explanation'] } },
 	{ name: 'read_command_output', description: 'Read recent output + status of a command started with run_command background:true. Returns a status header ([running on :3000] / [exited 0] / [stopped]) followed by the latest output lines. Poll this to wait for a server to become ready before testing against it.', input_schema: { type: 'object', properties: { id: { type: 'string', description: 'the id returned by a background run_command' }, lines: { type: 'number', description: 'max recent output lines to return (default 80, max 400)' } }, required: ['id'] } },
 	{ name: 'ask_user', description: 'Ask the user one or more multiple-choice questions when the goal genuinely depends on a decision only they can make (tech stack, scope, where to put files, must-have features). The user picks by CLICKING — do NOT write questions as prose. Ask ONCE up front with all your questions, then proceed with the answers and never re-ask. Prefer sensible defaults over asking; only ask when a wrong guess would waste real work.', input_schema: { type: 'object', properties: { questions: { type: 'array', items: { type: 'object', properties: { header: { type: 'string', description: 'a 1-3 word tag for the question' }, question: { type: 'string' }, multiSelect: { type: 'boolean', description: 'true if several options can be picked at once' }, options: { type: 'array', items: { type: 'object', properties: { label: { type: 'string' }, description: { type: 'string' } }, required: ['label'] } } }, required: ['question', 'options'] } } }, required: ['questions'] } },
 	{ name: 'use_skill', description: 'Load an expert playbook (SKILL.md) for a task type, chosen from the "Available skills" list in your system prompt. Returns the skill\'s step-by-step instructions as the tool result — then follow them. Read-only and instant (no approval). Call it once, early, when the goal matches a skill\'s description.', input_schema: { type: 'object', properties: { name: { type: 'string', description: 'the exact skill name from the Available skills list' } }, required: ['name'] } }