@gethmy/mcp 3.8.0 → 3.9.0

package/dist/cli.js

@@ -18,8 +18,9 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/config.ts
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join, parse, resolve } from "node:path";
 function noteLegacyConfigDir(path) {
   if (warnedLegacyConfigDir)
@@ -36,6 +37,23 @@ function noteLegacyLocalPin(path) {
 function noteLocalPinRename(from, to) {
   console.error(`Harmony: wrote the repo pin to ${to} (the pre-#1082 ${from} is now ignored and can be deleted).`);
 }
+function noteUntrackedLocalPin(path) {
+  if (warnedUntrackedLocalPin)
+    return;
+  warnedUntrackedLocalPin = true;
+  console.error(`Harmony: ${path} is ignored by git, so it will not travel with a branch — ` + `a fresh clone, and every worktree the agent daemon cuts, will not have it. ` + `Commit it if you want it to describe this repo everywhere.`);
+}
+function isGitIgnored(path) {
+  try {
+    execFileSync("git", ["check-ignore", "--quiet", path], {
+      cwd: dirname(path),
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
 function getHmyRootDir() {
   return join(homedir(), CONFIG_DIR_NAME);
 }
@@ -150,19 +168,96 @@ function saveLocalConfig(config, cwd) {
   if (foundPath !== null && foundPath !== localConfigPath) {
     noteLocalPinRename(foundPath, localConfigPath);
   }
-  const existingConfig = loadLocalConfig(cwd) || {
-    workspaceId: null,
-    projectId: null
-  };
-  const newConfig = { ...existingConfig, ...config };
-  const cleanConfig = {};
-  if (newConfig.workspaceId)
-    cleanConfig.workspaceId = newConfig.workspaceId;
-  if (newConfig.projectId)
-    cleanConfig.projectId = newConfig.projectId;
-  writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
+  const existing = readRawLocalConfig(foundPath ?? localConfigPath);
+  const merged = { ...existing };
+  if ("workspaceId" in config) {
+    if (config.workspaceId)
+      merged.workspaceId = config.workspaceId;
+    else
+      delete merged.workspaceId;
+  }
+  if ("projectId" in config) {
+    if (config.projectId)
+      merged.projectId = config.projectId;
+    else
+      delete merged.projectId;
+  }
+  writeFileSync(localConfigPath, `${JSON.stringify(merged, null, localIndent(localConfigPath))}
+`);
+  if (isGitIgnored(localConfigPath))
+    noteUntrackedLocalPin(localConfigPath);
   return localConfigPath;
 }
+function readRawLocalConfig(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  noteUnparsableLocalPin(path, text);
+  return {};
+}
+function noteUnparsableLocalPin(path, contents) {
+  let backup = null;
+  try {
+    backup = join(tmpdir(), `hmy-pin-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json.bak`);
+    writeFileSync(backup, contents);
+  } catch {
+    backup = null;
+  }
+  console.error(`Harmony: ${path} could not be parsed as JSON, so the pin write REPLACED it. ` + (backup ? `The previous contents are in ${backup}.` : "The previous contents could not be backed up and are gone.") + ` If it carried a "commands" block, re-add it.`);
+}
+function localIndent(configPath) {
+  const root = dirname(configPath);
+  for (const name of ["biome.json", "biome.jsonc"]) {
+    const parsed = readJsonish(join(root, name));
+    if (!parsed || typeof parsed !== "object")
+      continue;
+    const formatter = parsed.formatter;
+    if (formatter?.indentStyle === "space") {
+      const width = formatter.indentWidth;
+      return typeof width === "number" && width > 0 ? width : 2;
+    }
+    return "\t";
+  }
+  const editorconfig = readTextSafely(join(root, ".editorconfig"));
+  if (editorconfig) {
+    if (/^\s*indent_style\s*=\s*tab\s*$/im.test(editorconfig))
+      return "\t";
+    const size = editorconfig.match(/^\s*indent_size\s*=\s*(\d+)\s*$/im);
+    if (size) {
+      const width = Number(size[1]);
+      if (width > 0)
+        return width;
+    }
+  }
+  return 2;
+}
+function readJsonish(path) {
+  const text = readTextSafely(path);
+  if (text === null)
+    return null;
+  try {
+    const stripped = text.replace(/^\s*\/\/.*$/gm, "").replace(/,(\s*[}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch {
+    return null;
+  }
+}
+function readTextSafely(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
 function hasLocalConfig(cwd) {
   return findLocalConfigPath(cwd) !== null;
 }
@@ -296,7 +391,7 @@ function getMemoryDir() {
     return config.memoryDir;
   return join(homedir(), ".harmony", "memory");
 }
-var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false;
+var DEFAULT_API_URL = "https://app.gethmy.com/api", LOCAL_CONFIG_FILENAME = ".hmy.json", LEGACY_LOCAL_CONFIG_FILENAME = ".harmony-mcp.json", CONFIG_DIR_NAME = ".hmy", CONFIG_DIR_SUBDIR = "agent", LEGACY_CONFIG_DIR_NAME = ".harmony-mcp", warnedLegacyConfigDir = false, warnedLegacyLocalPin = false, warnedUntrackedLocalPin = false;
 var init_config = () => {};
 
 // src/prompt-builder.ts
@@ -726,7 +821,7 @@ var init_prompt_builder = __esm(() => {
   };
   VARIANT_INSTRUCTIONS = {
     analysis: `ANALYSIS MODE: Analyze this task thoroughly. Identify requirements, constraints, edge cases, and potential challenges. Do NOT implement anything yet - focus on understanding and planning.`,
-    draft: `DRAFT MODE: Create a detailed implementation plan with code structure, key decisions, and approach. Include pseudocode or skeleton code where helpful. This is for review before full implementation.`,
+    draft: `DRAFT MODE: Draft the approach for review before implementing. Cover the key decisions with their reasons, the data model and the API contracts, and success criteria a test can check. A short signature or schema sketch is fine wherever an interpretation gap would otherwise remain; function bodies, control flow and test code are not - an implementer transcribes a plan faithfully, defects included.`,
     execute: `EXECUTE MODE: Implement this task completely. Write production-ready code following best practices. Include necessary tests and documentation.`
   };
 });
@@ -1037,7 +1132,7 @@ __export(exports_run_state, {
   RUN_STATE_DIR_ENV: () => RUN_STATE_DIR_ENV,
   MAX_POINTER_AGE_MS: () => MAX_POINTER_AGE_MS
 });
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import {
   existsSync as existsSync3,
   mkdirSync as mkdirSync3,
@@ -1094,7 +1189,7 @@ function psParentTable() {
     return psTableCache;
   const table = new Map;
   try {
-    const out = execFileSync("ps", ["-Ao", "pid=,ppid="], {
+    const out = execFileSync2("ps", ["-Ao", "pid=,ppid="], {
       encoding: "utf-8",
       timeout: 2000,
       stdio: ["ignore", "pipe", "ignore"]
@@ -4686,81 +4781,6 @@ function parseHmyConfig(text) {
 }
 
 // src/skills.ts
-var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
-
-Start work on a Harmony card. Card reference: $ARGUMENTS
-
-## 1. Find & Fetch Card
-
-Parse the reference and fetch the card:
-- \`#42\` or \`42\` → \`harmony_get_card\` with \`shortId: 42\`
-- UUID → \`harmony_get_card\` with \`cardId\`
-- Name/text → \`harmony_search_cards\` with \`query\`
-
-## 2. Get Board State
-
-Call \`harmony_get_board\` to get columns and labels. From the response:
-- Find the "In Progress" (or "Progress") column ID
-- Find the "agent" label ID
-
-## 3. Setup Card for Work
-
-Execute these in sequence:
-1. \`harmony_move_card\` → Move to "In Progress" column
-2. \`harmony_add_label_to_card\` → Add "agent" label
-3. \`harmony_start_agent_session\`:
-   - \`cardId\`: Card UUID
-   - \`agentIdentifier\`: Your agent identifier
-   - \`agentName\`: Your agent name
-   - \`currentTask\`: "Analyzing card requirements"
-
-## 4. Generate Work Prompt
-
-Call \`harmony_generate_prompt\` with:
-- \`cardId\` or \`shortId\` (+ \`projectId\` if using shortId)
-- \`variant\`: Select based on task:
-  - \`"execute"\` (default) → Clear tasks, bug fixes, well-defined work
-  - \`"analysis"\` → Complex features, unclear requirements
-  - \`"draft"\` → Medium complexity, want feedback first
-
-The generated prompt provides role framing, focus areas, subtasks, linked cards, and suggested outputs.
-
-## 5. Display Card Summary
-
-Show the user: Card title, short ID, role, priority, labels, due date, description, and subtasks.
-
-## 6. Implement Solution
-
-Work on the card following the generated prompt's guidance. Update progress at milestones:
-- \`harmony_update_agent_progress\` with \`progressPercent\` (0-100), \`currentTask\`, \`status\`, \`blockers\`
-
-**Progress checkpoints:** 20% (exploration), 50% (implementation), 80% (testing), 100% (done)
-
-## 7. Complete Work
-
-When finished:
-1. \`harmony_end_agent_session\` with \`status: "completed"\`, \`progressPercent: 100\`
-2. \`harmony_move_card\` to "Review" column
-3. Summarize accomplishments
-
-If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
-
-## Key Tools Reference
-
-**Cards:** \`harmony_get_card\` (by \`cardId\`, \`shortId\`, or \`shortIds\`), \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
-
-**Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
-
-**Labels:** \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\`, \`harmony_create_label\`
-
-**Links:** \`harmony_add_link_to_card\`, \`harmony_remove_link_from_card\`, \`harmony_get_card_links\`
-
-**Board:** \`harmony_get_board\`, \`harmony_list_projects\`, \`harmony_get_context\`, \`harmony_set_project_context\`
-
-**Sessions:** \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\`, \`harmony_get_agent_session\`
-
-**AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
-`;
 function buildSkillFile(skill) {
   const content = stripSkillPreamble(skill.content);
   if (skill.skillVersion !== undefined && !hasMetadataVersion(content)) {
@@ -6615,7 +6635,7 @@ var TOOLS = {
     }
   },
   harmony_create_plan: {
-    description: "Create a new project plan. Use this to upload implementation plans created during planning. Returns a URL where the plan can be viewed and edited in Harmony.",
+    description: "Create a new project plan. Use this to upload a plan written during planning. Returns a URL where the plan can be viewed and edited in Harmony.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6638,7 +6658,10 @@ var TOOLS = {
           items: {
             type: "object",
             properties: {
-              content: { type: "string", description: "Task description" },
+              content: {
+                type: "string",
+                description: 'One success criterion, as a statement about the finished product that a test can check ("the mirror matches the migration chain"), never a work package ("write the mirror script"). One criterion may take several cards.'
+              },
               priority: {
                 type: "string",
                 enum: ["high", "medium", "low"],
@@ -6652,7 +6675,7 @@ var TOOLS = {
             },
             required: ["content"]
           },
-          description: "Optional list of tasks to create with the plan"
+          description: "The plan's success criteria, one entry each - what must be true when the plan is done, not a breakdown of the work to do it."
         }
       },
       required: ["title"]
@@ -6673,7 +6696,7 @@ var TOOLS = {
     }
   },
   harmony_update_plan: {
-    description: "Update an existing plan. Can update title, content, or status.",
+    description: "Update an existing plan: its title, content, status, or the timeline dates its bar spans. " + "`startDate`/`endDate` are the plan's OWN schedule, the same pair a person sets by dragging the bar in the timeline view. " + "A plan is pinned on both or on neither: send both to schedule it, or both as null to return it to the span derived from its linked cards. " + "Sending one alone is refused unless the plan is already pinned. " + "They are never adjusted automatically — a card running past `endDate` is drawn as an overrun, and only a person extends the plan.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6687,6 +6710,16 @@ var TOOLS = {
           type: "string",
           enum: ["draft", "active", "archived"],
           description: "New status"
+        },
+        startDate: {
+          type: "string",
+          nullable: true,
+          description: "Timeline start as YYYY-MM-DD, or null to unpin (send endDate null too)."
+        },
+        endDate: {
+          type: "string",
+          nullable: true,
+          description: "Timeline end as YYYY-MM-DD, or null to unpin (send startDate null too). Must not precede startDate."
         }
       },
       required: ["planId"]
@@ -8671,6 +8704,13 @@ ${options}
       if (args.status !== undefined) {
         updates.status = z.enum(["draft", "active", "archived"]).parse(args.status);
       }
+      const planDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+        message: "expected a date as YYYY-MM-DD"
+      });
+      if (args.startDate !== undefined)
+        updates.startDate = planDate.nullable().parse(args.startDate);
+      if (args.endDate !== undefined)
+        updates.endDate = planDate.nullable().parse(args.endDate);
       const result = await client3.updatePlan(planId, updates);
       return { success: true, plan: result.plan };
     }
@@ -8970,6 +9010,7 @@ class HarmonyMCPServer {
 }
 
 // src/tui/setup.ts
+import { spawnSync } from "node:child_process";
 import { createHash as createHash5 } from "node:crypto";
 import {
   existsSync as existsSync9,
@@ -8984,6 +9025,288 @@ import * as p4 from "@clack/prompts";
 init_config();
 init_oauth_login();
 
+// src/tui/agent-instructions.ts
+var HARMONY_PLAN_RULE = `**A plan says what must be true and why. It does not contain the code.** In it: the architecture
+and technology decisions with their reasons, the data model and the API contracts, a short
+signature or schema sketch wherever an interpretation gap would otherwise remain, and success
+criteria a test can check. Not in it: function bodies, control flow, error handling, test code.
+Detail follows risk — a throwaway script gets a rough plan, while auth, money, migrations and
+anything security-relevant get their contracts and edge cases written out.
+
+Code in a plan carries the authority of a plan and the quality of a draft that no compiler, test
+or review has read, and an implementer transcribes it faithfully, defects included. So when the
+plan and the code disagree, the code is the evidence: check it, record the decision as a comment,
+and correct the plan as well as the code.`;
+var HARMONY_AGENTS_SECTION = `## Harmony
+
+This project uses Harmony for task management. The \`harmony_*\` MCP tools are in your tool
+listing with live schemas — read them there. This section covers only what the schemas do not say.
+
+### Identify as yourself
+
+Every session call takes \`agentIdentifier\` + \`agentName\`. Use your OWN, never a value copied
+from this file. The board shows agents as teammates, so a session attributed to the wrong runtime
+misattributes the work in front of the whole team.
+
+Known values: \`claude-code\` / "Claude Code" · \`codex\` / "OpenAI Codex" · \`cursor\` / "Cursor" ·
+\`claude-desktop\` / "Claude Desktop". If you are none of these, use your own name.
+
+### Starting work — one call, not three
+
+\`harmony_start_agent_session\` moves the card and adds the labels itself. Do not call
+\`harmony_move_card\` or \`harmony_add_label_to_card\` first, and do not fetch the board for a
+column id or a label id — both arguments match by name.
+
+\`\`\`
+harmony_start_agent_session({
+  cardId,
+  agentIdentifier, agentName,   // your own
+  currentTask: "Reading the auth middleware to find the affected routes",
+  moveToColumn: "In Progress",
+  addLabels: ["agent"],
+  steerable: true,              // only if you will poll for steering — see below
+})
+\`\`\`
+
+**Then read the reply, because the setup half fails quietly.** \`movedTo\` names the column it
+actually moved to and \`labelsAdded\` the labels it actually added; a miss leaves them null or
+empty and raises no error. The column match is a case-insensitive **substring**, so a board with
+"Ready for Review" ahead of "Review" can take the wrong one. If \`movedTo\` is null or not the
+column you meant, call \`harmony_move_card\` — it matches exactly first and fails loudly, listing
+the columns.
+
+Keep the returned \`session.id\`; the steering poll needs it. Then call
+\`harmony_generate_prompt\` for role framing and focus areas — \`variant\` is \`execute\`
+(default), \`analysis\`, or \`draft\`.
+
+### Progress — \`actions\` is what survives as evidence
+
+On the card itself, \`progressPercent\` and \`currentTask\` each overwrite one field, so the live
+status shows only your latest checkpoint. The timeline keeps more: a checkpoint that carries both
+a \`progressPercent\` and a \`currentTask\` different from the last one leaves a row saying what you
+were **about to do**, and **each entry in \`actions\` leaves a row saying what you actually did**.
+Report four checkpoints with no \`actions\` and a two-hour run reads as four intentions and no
+evidence.
+
+Name what you DID since the last checkpoint: the file you edited and why, the gate you ran and
+what it said, the approach you ruled out and on what evidence.
+
+\`\`\`
+harmony_update_agent_progress({
+  cardId, agentIdentifier, agentName,
+  progressPercent: 50,
+  currentTask: "Extracting refreshIfExpired() in auth.ts",
+  actions: [
+    { description: "Read auth.ts and middleware/session.ts — the refresh path is duplicated in both, which is the actual bug" },
+    { description: "Ruled out patching verifyToken(): three routes depend on its current behaviour" },
+    { description: "Ran bun run lint — green, exit 0" },
+  ],
+})
+\`\`\`
+
+Three to six entries per checkpoint, one sentence each; past 512 characters an entry is silently truncated. Facts, not
+intentions — one vague entry is worse than none. Checkpoints: 20% explored · 50% implementing ·
+80% verifying · 100% done. \`currentTask\` is what you are doing now — never leave it generic.
+
+### Steering and Stop
+
+If you passed \`steerable: true\`, poll right after every progress update:
+
+\`\`\`
+harmony_get_pending_messages({ cardId, sessionId, sinceSeq })   // sinceSeq starts at 0
+\`\`\`
+
+Messages come back oldest first. Fold them into the next step and advance \`sinceSeq\` to the
+largest \`seq\` returned, so each is handled exactly once.
+
+Two flags come back and mean opposite things:
+
+| flag | meaning | what to do |
+|---|---|---|
+| \`stopped: true\` | a human pressed Stop | **Terminal.** Make no further edits, commits, pushes, card moves, comments or progress writes. Report what is finished and where any uncommitted work lives. |
+| \`sessionStale: true\` | your session id is no longer live — usually the inactivity sweep | **Nobody stopped you.** Carry on — with a new id. |
+
+\`harmony_update_agent_progress\` reports the same two flags, and the recovery from a stale session
+differs by which call told you:
+
+- From the **progress** call, a replacement session has already been opened for you and inherited
+  the steering channel. Take the new \`session.id\` from that reply and keep going.
+- From the **poll**, nothing was opened. Call \`harmony_start_agent_session\` yourself and poll
+  with the id it returns.
+
+If the two flags ever disagree, the stop wins.
+
+### Finishing
+
+\`\`\`
+harmony_end_agent_session({ cardId, status: "completed", progressPercent: 100, moveToColumn: "Review" })
+\`\`\`
+
+One call: it moves the card, and on \`status: "completed"\` it also removes the \`agent\` label. Use
+\`status: "paused"\` when you stop mid-flight — that leaves the label on, which is what you want.
+
+Attach a PR **after** the session end has moved the card, both ways: \`harmony_add_external_link\`
+(durable — it survives a later description edit) and a \`PR: <url>\` line in the description.
+
+### Writing a plan
+
+${HARMONY_PLAN_RULE}
+
+### Traps
+
+- **A \`shortId\` is project-scoped, and the two ways it can miss are opposites.** With **no**
+  active project the number is resolved across every project you can reach, so it may come back
+  \`needsDisambiguation\` with \`candidates\` — ask which one is meant. With an active project the
+  number resolves only inside it, and a card that lives elsewhere fails with an error naming the
+  projects it is really in — switch with \`harmony_set_project_context\` or pass \`projectId\`.
+  Either way, check \`resolvedProject\` matches the card you meant before starting work.
+- **Fetch many cards in one call:** \`harmony_get_card({ shortIds: [400, 401, 402] })\`, max 100.
+- **Moving a card to a terminal column ends your session** — a column that marks cards done, or
+  one named \`done\`, \`completed\` or \`review\`. The response says \`sessionEnded\`.
+- **Read \`harmony_get_comments\` before you act.** Steering messages do not include comments, and
+  a later comment outranks an earlier one it contradicts.
+- **Report findings and decisions as comments, not description edits.** \`harmony_add_comment\`
+  takes a \`commentType\`: \`question\` and \`blocker\` signal that you need a human; \`decision\`,
+  \`finding\`, \`summary\`, \`progress\` and \`message\` are the rest.`;
+var HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
+
+Work a Harmony card. Card reference: $ARGUMENTS
+
+The \`harmony_*\` MCP tools are in your tool listing with live schemas — read them there. This
+prompt covers only what the schemas do not say.
+
+## 1. Fetch the card
+
+- \`#42\` or \`42\` → \`harmony_get_card({ shortId: 42 })\`
+- UUID → \`harmony_get_card({ cardId })\`
+- A name or phrase → \`harmony_search_cards({ query })\`
+- Several at once → \`harmony_get_card({ shortIds: [40, 41, 42] })\`, max 100
+
+A \`shortId\` is project-scoped, and the two ways it can miss are opposites. With **no** active
+project the number is resolved across every project you can reach, so it may come back
+\`needsDisambiguation\` with \`candidates\` — ask which one is meant. With an active project the
+number resolves only inside it, and a card that lives elsewhere fails with an error naming the
+projects it is really in; switch with \`harmony_set_project_context\` or pass \`projectId\`.
+Either way, check \`resolvedProject\` before you start.
+
+Read \`harmony_get_comments\` too: a later comment outranks an earlier one it contradicts.
+
+## 2. Start the session — one call, not three
+
+\`harmony_start_agent_session\` moves the card and adds the labels itself. Do not call
+\`harmony_move_card\` or \`harmony_add_label_to_card\` first, and do not fetch the board for a
+column id or a label id — both arguments match by name.
+
+\`\`\`
+harmony_start_agent_session({
+  cardId,
+  agentIdentifier: "$AGENT_IDENTIFIER",
+  agentName: "$AGENT_NAME",
+  currentTask: "Reading the auth middleware to find the affected routes",
+  moveToColumn: "In Progress",
+  addLabels: ["agent"],
+  steerable: true,
+})
+\`\`\`
+
+\`currentTask\` says what you are about to do, specifically. Never "Analyzing card requirements".
+Keep the returned \`session.id\` — step 4 needs it.
+
+**Read the reply, because the setup half fails quietly.** \`movedTo\` names the column it actually
+moved to and \`labelsAdded\` the labels it actually added; a miss leaves them null or empty and
+raises no error. The column match is a case-insensitive **substring**, so a board with "Ready for
+Review" ahead of "Review" can take the wrong one. If \`movedTo\` is null or not the column you
+meant, call \`harmony_move_card\` — it matches exactly first and fails loudly, listing the columns.
+
+## 3. Get the work prompt
+
+\`harmony_generate_prompt\` with \`cardId\` (or \`shortId\` plus \`projectId\`) and a \`variant\`:
+\`execute\` (default) for well-defined work, \`analysis\` for unclear requirements, \`draft\` when
+you want feedback on a design first. It returns role framing, focus areas, subtasks and links.
+
+Then show the user the card: title, short id, priority, labels, due date, description, subtasks.
+
+## 4. Implement, and check in at every milestone
+
+Checkpoints: 20% explored · 50% implementing · 80% verifying · 100% done.
+
+On the card itself, \`progressPercent\` and \`currentTask\` each overwrite one field, so the live
+status shows only your latest checkpoint. The timeline keeps more: a checkpoint that carries both
+a \`progressPercent\` and a \`currentTask\` different from the last one leaves a row saying what you
+were **about to do**, and **each entry in \`actions\` leaves a row saying what you actually did** —
+that is the evidence the team can still read afterwards.
+
+\`\`\`
+harmony_update_agent_progress({
+  cardId, agentIdentifier: "$AGENT_IDENTIFIER", agentName: "$AGENT_NAME",
+  progressPercent: 50,
+  currentTask: "Extracting refreshIfExpired() in auth.ts",
+  actions: [
+    { description: "Read auth.ts and middleware/session.ts — the refresh path is duplicated in both, which is the actual bug" },
+    { description: "Ruled out patching verifyToken(): three routes depend on its current behaviour" },
+    { description: "Ran bun run lint — green, exit 0" },
+  ],
+  status: "working",   // or blocked / waiting / paused
+  blockers: [],
+})
+\`\`\`
+
+Three to six entries per checkpoint, one sentence each; past 512 characters an entry is silently truncated. Say what you did,
+not what you intend to do.
+
+Right after each update, poll for steering:
+
+\`\`\`
+harmony_get_pending_messages({ cardId, sessionId, sinceSeq })   // sinceSeq starts at 0
+\`\`\`
+
+Fold any messages into the next step and advance \`sinceSeq\` to the largest \`seq\` returned. Two
+flags come back and mean opposite things:
+
+- \`stopped: true\` — a human pressed Stop. **Terminal.** Make no further edits, commits, pushes,
+  card moves, comments or progress writes; report what is finished and where any uncommitted work
+  lives.
+- \`sessionStale: true\` — your session id is no longer live, usually the inactivity sweep. **Nobody stopped you.**
+  Carry on, with a new id: the **poll** opens nothing, so call \`harmony_start_agent_session\`
+  yourself; the **progress** call has already opened a replacement that inherited the steering
+  channel, so just take the new \`session.id\` from its reply.
+
+If the two flags ever disagree, the stop wins.
+
+Report findings and decisions with \`harmony_add_comment\` (\`commentType\`: \`question\` and
+\`blocker\` signal that you need a human; \`decision\`, \`finding\`, \`summary\`, \`progress\`,
+\`message\`), not by editing the card description.
+
+## 5. Finish
+
+\`\`\`
+harmony_end_agent_session({ cardId, status: "completed", progressPercent: 100, moveToColumn: "Review" })
+\`\`\`
+
+One call: it moves the card, and on \`status: "completed"\` it also removes the \`agent\` label. Use
+\`status: "paused"\` when you stop mid-flight — that leaves the label on, which is what you want.
+
+Opened a PR? Attach it **after** the session end has moved the card, both ways:
+\`harmony_add_external_link\` (durable — it survives a later description edit) and a
+\`PR: <url>\` line in the description.
+
+Then summarise what changed.
+
+## Writing a plan
+
+${HARMONY_PLAN_RULE}
+
+## Worth knowing
+
+- Moving a card to a terminal column ends your session — a column that marks cards done, or one
+  named \`done\`, \`completed\` or \`review\`. The response says \`sessionEnded\`.
+- \`harmony_add_label_to_card\` and \`harmony_start_agent_session\`'s \`addLabels\` both CREATE a
+  label that does not exist yet. Check the spelling.
+- \`harmony_add_comment\` works on any card you can see, including one you hold no session on.`;
+function renderWorkflowPrompt(opts) {
+  return HARMONY_WORKFLOW_PROMPT.replaceAll("$ARGUMENTS", opts.cardArgument).replaceAll("$AGENT_IDENTIFIER", opts.agentIdentifier).replaceAll("$AGENT_NAME", opts.agentName);
+}
+
 // src/tui/agents.ts
 import { existsSync as existsSync6 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
@@ -9883,6 +10206,67 @@ function appendToToml(filePath, section, content, options = {}) {
     };
   }
 }
+var MARKDOWN_SECTION_START = "<!-- harmony:start -->";
+var MARKDOWN_SECTION_END = "<!-- harmony:end -->";
+function findSection(text) {
+  let from = 0;
+  while (true) {
+    const start = text.indexOf(MARKDOWN_SECTION_START, from);
+    if (start === -1)
+      return null;
+    const bodyFrom = start + MARKDOWN_SECTION_START.length;
+    const end = text.indexOf(MARKDOWN_SECTION_END, bodyFrom);
+    if (end === -1)
+      return null;
+    const nextStart = text.indexOf(MARKDOWN_SECTION_START, bodyFrom);
+    if (nextStart === -1 || nextStart > end)
+      return { start, end };
+    from = nextStart;
+  }
+}
+function mergeMarkdownSection(filePath, content, options = {}) {
+  const section = `${MARKDOWN_SECTION_START}
+${content.trim()}
+${MARKDOWN_SECTION_END}
+`;
+  if (!existsSync8(filePath)) {
+    try {
+      ensureDir(dirname3(filePath));
+      writeFileSync5(filePath, section, { mode: 420 });
+      return { path: filePath, action: "create" };
+    } catch (error) {
+      return {
+        path: filePath,
+        action: "skip",
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  try {
+    const existing = readFileSync7(filePath, "utf-8");
+    const found = findSection(existing);
+    if (found) {
+      if (!options.force)
+        return { path: filePath, action: "skip" };
+      const updated = existing.slice(0, found.start) + section.trimEnd() + existing.slice(found.end + MARKDOWN_SECTION_END.length);
+      writeFileSync5(filePath, updated, { mode: 420 });
+      return { path: filePath, action: "update" };
+    }
+    const separator = existing.endsWith(`
+`) ? `
+` : `
+
+`;
+    writeFileSync5(filePath, existing + separator + section, { mode: 420 });
+    return { path: filePath, action: "merge" };
+  } catch (error) {
+    return {
+      path: filePath,
+      action: "skip",
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
 async function writeFilesWithProgress(files, options = {}) {
   const results = [];
   const home = homedir6();
@@ -9895,6 +10279,8 @@ async function writeFilesWithProgress(files, options = {}) {
       result = mergeJsonFile(file.path, jsonContent, options);
     } else if (file.type === "toml" && file.tomlSection) {
       result = appendToToml(file.path, file.tomlSection, file.content, options);
+    } else if (file.type === "markdown") {
+      result = mergeMarkdownSection(file.path, file.content, options);
     } else {
       result = writeFile(file.path, file.content, {
         ...options,
@@ -9912,7 +10298,7 @@ async function writeFilesWithProgress(files, options = {}) {
     } else if (result.action === "skip") {
       console.log(messages.fileSkipped(displayPath));
     } else {
-      const actionLabel = result.action === "merge" ? "updated" : "created";
+      const actionLabel = result.action === "create" ? "created" : result.action === "merge" ? "merged" : "updated";
       console.log(`  ${colors.success("✓")} ${colors.dim(displayPath)} ${colors.dim(`(${actionLabel})`)}`);
     }
   }
@@ -9940,7 +10326,6 @@ function getWriteSummary(files, options = {}) {
 // src/tui/setup.ts
 var SAFE_HARMONY_TOOLS = [
   "harmony_get_card",
-  "harmony_get_card_by_short_id",
   "harmony_search_cards",
   "harmony_get_board",
   "harmony_get_context",
@@ -9952,12 +10337,17 @@ var SAFE_HARMONY_TOOLS = [
   "harmony_get_comments",
   "harmony_get_plan",
   "harmony_list_plans",
+  "harmony_get_playbook",
+  "harmony_list_playbook",
   "harmony_get_agent_session",
+  "harmony_get_pending_messages",
   "harmony_get_workspace_members",
   "harmony_list_agents",
   "harmony_resolve_links",
+  "harmony_suggest_relations",
   "harmony_recall",
   "harmony_memory_search",
+  "harmony_vault_index",
   "harmony_generate_prompt",
   "harmony_create_card",
   "harmony_update_card",
@@ -9965,6 +10355,7 @@ var SAFE_HARMONY_TOOLS = [
   "harmony_assign_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
+  "harmony_update_subtask",
   "harmony_add_label_to_card",
   "harmony_remove_label_from_card",
   "harmony_create_label",
@@ -9972,6 +10363,8 @@ var SAFE_HARMONY_TOOLS = [
   "harmony_update_comment",
   "harmony_add_link_to_card",
   "harmony_remove_link_from_card",
+  "harmony_add_external_link",
+  "harmony_remove_external_link",
   "harmony_start_agent_session",
   "harmony_update_agent_progress",
   "harmony_end_agent_session",
@@ -9984,6 +10377,7 @@ var SAFE_HARMONY_TOOLS = [
   "harmony_remember",
   "harmony_relate",
   "harmony_update_memory",
+  "harmony_recall_feedback",
   "harmony_process_command",
   "harmony_sync"
 ];
@@ -10197,63 +10591,10 @@ ${summary}`);
       break;
     }
     case "codex": {
-      const agentsContent = `# Harmony Integration
-
-This project uses Harmony for task management. When working on tasks:
-
-## Agent identity — always identify as yourself
-
-Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
-identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
-more than one kind of agent will read it; the board shows agents as teammates, and a session
-attributed to the wrong runtime misattributes the work in front of the whole team.
-
-- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
-- \`agentName\` — its human-readable name
-
-Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
-\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
-than borrowing the closest entry.
-
-## Starting Work on a Card
-
-When given a card reference (e.g., #42 or a card name), follow this workflow:
-
-1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
-2. Move the card to "In Progress" using \`harmony_move_card\`
-3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
-   \`agentName\` (see "Agent identity" above)
-5. Show the card details to the user
-6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
-7. Update progress periodically with \`harmony_update_agent_progress\`
-8. When done, call \`harmony_end_agent_session\` and move to "Review"
-
-## Auto-Detect Card for Implementation Tasks
-
-Before implementing a plan or feature, check if it maps to an existing Harmony card:
-
-1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
-   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
-3. Update progress with \`harmony_update_agent_progress\` at milestones
-4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"
-
-Skip if: work was already started with a card reference, or no matching card exists.
-
-## Available Harmony Tools
-
-- \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\` - Find cards
-- \`harmony_move_card\` - Move cards between columns
-- \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\` - Manage labels
-- \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\` - Track work
-- \`harmony_get_board\` - Get board state
-- \`harmony_generate_prompt\` - Get role-based guidance and focus areas for the card
-`;
       files.push({
         path: join9(cwd, "AGENTS.md"),
-        content: agentsContent,
-        type: "text"
+        content: HARMONY_AGENTS_SECTION,
+        type: "markdown"
       });
       const promptContent = `---
 name: hmy
@@ -10264,7 +10605,7 @@ arguments:
     required: true
 ---
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "{{card}}").replace("Your agent identifier", "codex").replace("Your agent name", "OpenAI Codex")}
+${renderWorkflowPrompt({ cardArgument: "{{card}}", agentIdentifier: "codex", agentName: "OpenAI Codex" })}
 `;
       if (installMode === "global") {
         files.push({
@@ -10321,7 +10662,7 @@ alwaysApply: false
 
 When the user asks you to work on a Harmony card (references like #42, card names, or UUIDs):
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "cursor").replace("Your agent name", "Cursor AI")}
+${renderWorkflowPrompt({ cardArgument: "the card reference", agentIdentifier: "cursor", agentName: "Cursor" })}
 `;
       if (installMode === "global") {
         files.push({
@@ -10366,7 +10707,7 @@ description: Activate when user asks to work on a Harmony card (references like
 
 When working on a Harmony card:
 
-${HARMONY_WORKFLOW_PROMPT.replace("$ARGUMENTS", "the card reference").replace("Your agent identifier", "windsurf").replace("Your agent name", "Windsurf AI")}
+${renderWorkflowPrompt({ cardArgument: "the card reference", agentIdentifier: "windsurf", agentName: "Windsurf" })}
 `;
       if (installMode === "global") {
         files.push({
@@ -10963,6 +11304,7 @@ Specify the workspace with --workspace <id>, or select one below.`);
         projectId: selectedProjectId ?? null
       }, { global: true });
     }
+    await offerCommandScan(dirname4(writtenLocalConfigPath), assumeYes);
   }
   console.log("");
   p4.outro(colors.success("Setup complete!"));
@@ -11010,6 +11352,39 @@ Specify the workspace with --workspace <id>, or select one below.`);
   }
   console.log("");
 }
+var SCAN_ARGV = ["--yes", "@gethmy/agent@latest", "scan-commands"];
+function scanTip() {
+  console.log(`  ${colors.dim("Tip: run")} ${colors.highlight(`npx ${SCAN_ARGV.slice(1).join(" ")}`)} ${colors.dim("to have the daemon prove which build, test and dev commands this repo has, and write them into the pin.")}`);
+}
+async function offerCommandScan(repoDir, assumeYes) {
+  if (assumeYes) {
+    scanTip();
+    return;
+  }
+  const scan = await confirmOrDefault(assumeYes, {
+    message: "Scan this repo's commands now? It runs your build, test and dev scripts once to prove which ones exist. Nothing is written.",
+    initialValue: true
+  });
+  if (p4.isCancel(scan)) {
+    p4.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  if (!scan) {
+    scanTip();
+    return;
+  }
+  console.log(`  ${colors.dim("Running")} ${colors.highlight(`npx ${SCAN_ARGV.slice(1).join(" ")}`)}${colors.dim(" …")}`);
+  const result = spawnSync("npx", [...SCAN_ARGV], {
+    cwd: repoDir,
+    stdio: "inherit"
+  });
+  if (result.error || result.status !== 0) {
+    console.log(`  ${colors.dim("The scan did not run — your installed @gethmy/agent may predate it.")}`);
+    scanTip();
+    return;
+  }
+  console.log(`  ${colors.dim("Re-run it with")} ${colors.highlight("--write")} ${colors.dim("to merge that block into the pin.")}`);
+}
 
 // src/cli.ts
 var require2 = createRequire2(import.meta.url);