@detergent-software/conductor 1.4.0-dev.4 → 1.4.0-dev.8

package/build/help.js

@@ -1,3 +1,4 @@
+import { styleText } from 'node:util';
 import { ConductorError } from "./errors.js";
 // By task, in the order a reader needs them; the commands inside each are listed A–Z.
 export const GROUPS = [
@@ -11,241 +12,449 @@ export const GROUPS = [
     'Setup',
 ];
 const DEFAULT_WIDTH = 80;
+// Wider than this, a paragraph is too long a line to read.
+const MAX_WIDTH = 100;
 // Narrower than this, a hanging indent leaves no room for the text.
 const MIN_WIDTH = 40;
 // A longer term goes on a line of its own, with its description under it.
 const MAX_TERM = 24;
-const RANGE = 'A <range> is today, yesterday, a date (2026-10-10), A..B (2026-10-10..2026-10-11), or a span (24h, the default; 7d).';
-const WHEN = '<when> is 17:00 (the next one), tomorrow, a day such as monday, or a date and time.';
-const WINDOW = 'A --since or --until <when> is now, today, yesterday, a span ago (30m, 24h, 7d), a date, or a date and time. Give a <range> or --since/--until, not both.';
+const LOOKS = { command: 'cyan', heading: 'bold', placeholder: 'dim' };
+const ITEM = [
+    '--item <item>',
+    "the item, when neither the worktree's name nor its branch carries it",
+];
+const LOST_LOGIN = [5, 'a lost provider login: run conduct wait login <provider>'];
+const PR_REPO = [
+    '--repo <repo>',
+    "github:<owner>/<repo> or ado:<repository>; the profile's code host by default",
+];
+const RANGE = [
+    '<range>',
+    'today, yesterday, a date (2026-10-10), A..B (2026-10-10..2026-10-11), or a span (24h, the default; 7d)',
+];
+const WHEN = [
+    '<when>',
+    '17:00 (the next one), tomorrow, a day such as monday, or a date and time',
+];
+const WINDOW = [
+    '<when>',
+    'for --since or --until: now, today, yesterday, a span ago (30m, 24h, 7d), a date, or a date and time',
+];
+const WORKER = ['<worker>', 'its item (ATK-309) or its name (probe-ATK-309)'];
+const REPORT_OPTIONS = [
+    ['--json', 'print the report as JSON'],
+    ['--project <name>', 'one project only'],
+    ['--since <when>', 'the window starts then'],
+    ['--until <when>', 'the window ends then'],
+];
 export const COMMANDS = [
     {
-        details: [
-            'Posts "approve" on the item as you and wakes its worker. <item> is the item (ATK-312), or the inbox item\'s id as #12.',
-            '--text adds to the comment: "approve: <text>".',
+        arguments: [
+            ['<item>', "the item (ATK-312), or the inbox item's id as '#12' (quoted: a shell reads #12 as a comment)"],
+        ],
+        description: ['Posts "approve" on the item as you and wakes its worker.'],
+        examples: [
+            ["approve ATK-312's plan", 'approve ATK-312'],
+            ['the same, with a word for the worker', 'approve ATK-312 --text "skip the docs"'],
         ],
         group: 'Inbox and approvals',
         name: 'approve',
+        options: [['--text <text>', 'add to the comment: "approve: <text>"']],
+        seeAlso: ['revise', 'inbox'],
         summary: 'approve a plan and wake its worker',
         usage: ['approve <item> [--text <text>]'],
     },
     {
-        details: ['Wakes a parked worker (with no event text) and opens its session in a tab.'],
+        arguments: [WORKER],
+        description: ['Wakes a parked worker (with no event text) and opens its session in a tab.'],
+        examples: [["open ATK-309's worker in a tab", 'attach ATK-309']],
         group: 'Projects and workers',
         name: 'attach',
+        seeAlso: ['launch', 'retire', 'status'],
         summary: 'wake a parked worker and open it in a tab',
         usage: ['attach <worker>'],
     },
     {
-        details: [
-            "Renames the worktree's branch (worktree-ATK-454) to <type>/<key>-<slug>, such as feat/atk-454-code-host-writes, with the item from the worktree's name (or --item). <type> is a conventional commit type.",
+        arguments: [
+            ['<type>', 'a conventional commit type: feat, fix, chore, docs…'],
+            ['<slug>', 'a few words for the branch, joined by dashes'],
+        ],
+        description: [
+            "Renames the worktree's branch (worktree-ATK-454) to <type>/<key>-<slug>, such as feat/atk-454-code-host-writes, with the item from the worktree's name (or --item).",
             'Prints JSON. Runs here, with or without a conductor.',
         ],
+        examples: [['in the ATK-454 worktree: feat/atk-454-code-host-writes', 'branch feat code-host-writes']],
         group: 'Used by work skills',
         name: 'branch',
+        options: [ITEM],
+        seeAlso: ['checkout', 'state'],
         summary: "rename the worktree's branch after its item",
         usage: ['branch <type> <slug> [--item <item>]'],
     },
     {
-        details: [
+        arguments: [['<item>', 'the item (ATK-312)']],
+        description: [
             "The item's context for a worker's orient step, read by the conductor from the tracker (no MCP): title, status, project, Area and labels, blockers, the items it blocks and related items, its phase notes, the approve or revise: after the newest Plan, and the description.",
-            "Also the work skill's phase (orient, plan, awaiting-approval, implement, wait, land, done, abandoned, canceled), from the status, the notes and the PR; and the PR (its worker's, else the newest PR opened note's) as its code host has it, with its verdict. --comments adds every comment's words.",
-            'A brief is kept for 30 seconds, and anything the conductor sees happen to the item (a note, an approve or revise it posted, a wait resolved) drops it. --fresh reads the tracker again, as a check for an approval after a wake should.',
+            "Also the work skill's phase (orient, plan, awaiting-approval, implement, wait, land, done, abandoned, canceled), from the status, the notes and the PR; and the PR (its worker's, else the newest PR opened note's) as its code host has it, with its verdict.",
+            'A brief is kept for 30 seconds, and anything the conductor sees happen to the item (a note, an approve or revise it posted, a wait resolved) drops it.',
             "With no conductor, it is read here from this checkout's project, as its account.",
-            "Exit 3 when nobody gave it (no conductor and this isn't the item's project checkout, or the conductor couldn't read the tracker): read the item from the tracker then.",
+        ],
+        examples: [
+            ['orient on ATK-312', 'brief ATK-312'],
+            ['check for an approval after a wake', 'brief ATK-312 --fresh'],
+        ],
+        exitCodes: [
+            [
+                3,
+                "nobody gave it (no conductor and this isn't the item's project checkout, or the conductor couldn't read the tracker): read the item from the tracker then",
+            ],
         ],
         group: 'Used by work skills',
         name: 'brief',
+        options: [
+            ['--comments', "add every comment's words"],
+            ['--fresh', 'read the tracker again, as a check for an approval after a wake should'],
+            ['--json', 'print it as JSON'],
+        ],
+        seeAlso: ['note', 'wait'],
         summary: "an item's status, phase, PR, links, notes and approval",
         usage: ['brief <item> [--json] [--fresh] [--comments]'],
     },
     {
-        details: [
+        arguments: [
+            ['<owner>/<repo>', 'the GitHub repo'],
+            ['<type>', 'a conventional commit type for the branch'],
+            ['<slug>', 'a few words for the branch, joined by dashes'],
+        ],
+        description: [
             'Clones another GitHub repo into the worktree at .scratch/repos/<repo>, on <type>/<key>-<slug> from its default branch, with no upstream until the first push. Again on an existing checkout, it says where it is and changes nothing.',
             "The clone stays out of the worktree's git status, and conduct retire checks it for unpushed work.",
             'Prints JSON. Runs here.',
         ],
+        examples: [
+            ['clone the registry for a skill fix', 'checkout EmergentSoftware/agentic-toolkit-registry fix lock-path'],
+        ],
         group: 'Used by work skills',
         name: 'checkout',
+        options: [ITEM],
+        seeAlso: ['branch', 'state', 'pr'],
         summary: 'clone another repo into the worktree for the item',
         usage: ['checkout <owner>/<repo> <type> <slug> [--item <item>]'],
     },
     {
-        details: [
-            "Opens the console, the Claude session the conductor mod serves, in a Windows Terminal tab in the project's main checkout. --here runs it in this terminal.",
+        description: [
+            "Opens the console, the Claude session the conductor mod serves, in a Windows Terminal tab in the project's main checkout.",
             'The tab needs Windows Terminal, and refuses while CONDUCTOR_HOME is set (a tab would not see it): use --here then.',
             'Also how to get it back after it closed: it keeps no state of its own.',
-            'One at a time: it refuses while a console is open, or started in the last minute and not yet following the events; --force opens another anyway (each escalation then wakes both).',
+            'One at a time: it refuses while a console is open, or started in the last minute and not yet following the events.',
+        ],
+        examples: [
+            ['open the console in a new tab', 'console'],
+            ['run it in this terminal', 'console --here'],
         ],
         group: 'Console and rules',
         name: 'console',
+        options: [
+            ['--force', 'open another console anyway; each escalation then wakes both'],
+            ['--here', 'run it in this terminal, not a tab'],
+            ['--project <name>', 'the project whose checkout it runs in; needed when several are registered'],
+        ],
+        seeAlso: ['escalations', 'inbox', 'install-mod'],
         summary: 'open the console, the session the conductor mod serves',
         usage: ['console [--project <name>] [--here] [--force]'],
     },
     {
-        details: [
-            'For a physical action, or one you handled yourself. <id> is the inbox id as conduct inbox prints it (#12, or 12).',
-        ],
+        arguments: [['<id>', 'the inbox id as conduct inbox prints it (#12, or 12)']],
+        description: ['For a physical action, or one you handled yourself.'],
+        examples: [['you approved the npm stage of inbox item #12 yourself', 'done 12']],
         group: 'Inbox and approvals',
         name: 'done',
+        seeAlso: ['inbox', 'approve'],
         summary: 'mark an inbox item done',
         usage: ['done <id>'],
     },
     {
-        details: [
+        commands: [
+            ['escalations [--json]', "what rules escalated to the console in the last 14 days and it hasn't handled"],
             [
-                ['escalations [--json]', "what rules escalated to the console in the last 14 days and it hasn't handled"],
-                [
-                    'done <id> [--ask] <text>',
-                    'log the console\'s finding on escalation #<id>; --ask also puts it in the inbox for you (a "console" item). Every word after <id> is the text',
-                ],
+                'done <id> [--ask] <text>',
+                "log the console's finding on escalation #<id>. Every word after <id> is the text, quoted or not",
             ],
         ],
+        description: ["The console's work: what the rules escalated to it, and its findings on them."],
+        examples: [
+            ['what waits on the console', 'escalations'],
+            ['log a finding on #7 and put it in the inbox', 'escalations done 7 --ask the PR needs a merge of develop'],
+        ],
         group: 'Console and rules',
         name: 'escalations',
+        options: [
+            ['--ask', 'with done: also put the finding in the inbox for you (a "console" item)'],
+            ['--json', 'print the escalations as JSON'],
+        ],
+        seeAlso: ['console', 'rules', 'why'],
         summary: "what rules escalated to the console and it hasn't handled",
         usage: ['escalations [--json]', 'escalations done <id> [--ask] <text>'],
     },
     {
-        details: [
-            'The event log after <id> (all of it without --since), one JSON event per line.',
-            '--follow keeps following it (live without --since), reconnecting when the conductor restarts; the state lines conduct.connected and conduct.disconnected say so.',
-            "--console (or CONDUCTOR_CONSOLE=1) marks the console's stream, as the conductor mod runs it: with none open, escalations raise an inbox item after 30 s.",
+        description: ['The event log, one JSON event per line.'],
+        examples: [
+            ['every event after 4200', 'events --since 4200'],
+            ['follow the log live', 'events --follow'],
         ],
         group: 'Logs and reports',
         name: 'events',
+        options: [
+            [
+                '--console',
+                "mark the stream as the console's, as the conductor mod runs it (or CONDUCTOR_CONSOLE=1): with none open, escalations raise an inbox item after 30 s",
+            ],
+            [
+                '--follow',
+                'keep following it (live without --since), reconnecting when the conductor restarts; the state lines conduct.connected and conduct.disconnected say so',
+            ],
+            ['--since <id>', 'the events after <id>; all of them without it'],
+        ],
+        seeAlso: ['history', 'why'],
         summary: 'the event log, one JSON event per line',
         usage: ['events [--since <id>]', 'events --follow [--since <id>] [--console]'],
     },
     {
-        details: [
-            "Files a follow-up of this checkout's item (or --item) on its tracker: in Backlog, in the item's project, with --area (one of the tracker's Areas: a label of the Area group, a path below a board's root, or the name after a GitHub Issues area prefix), the profile's triage label, and the human label too with --human. It is related to the item and to each --related, and waits on each --blocked-by. Both take keys, repeated or comma-separated.",
+        description: [
+            "Files a follow-up of this checkout's item (or --item) on its tracker: in Backlog, in the item's project, with its Area, the profile's triage label, and the human label too with --human. It is related to the item and to each --related, and waits on each --blocked-by.",
             "Search the tracker for a duplicate first: this only files. An Area outside the group, or a key of another project, is refused before anything is written. On Linear a relation that fails once the issue exists (such as an item it doesn't have) is a warning; on ADO Boards the item and its links are one request, so a bad link refuses the whole filing. On GitHub Issues the related items are a Related: line in its body, and a dependency that fails is a warning.",
-            'With a conductor, the daemon files it for the worker that owns this checkout and records it; without one it is filed here. Prints JSON with "via". Exit 1 when refused or failed; 5 for a lost login.',
+            'With a conductor, the daemon files it for the worker that owns this checkout and records it; without one it is filed here. Prints JSON with "via".',
         ],
+        examples: [
+            [
+                'a follow-up in apps/conductor that waits on ATK-480',
+                'file --title "conductor: color the status" --body-file follow-up.md --area apps/conductor --blocked-by ATK-480',
+            ],
+        ],
+        exitCodes: [[1, 'refused or failed'], LOST_LOGIN],
         group: 'Used by work skills',
         name: 'file',
+        options: [
+            [
+                '--area <area>',
+                "one of the tracker's Areas: a label of the Area group, a path below a board's root, or the name after a GitHub Issues area prefix",
+            ],
+            ['--blocked-by <item>…', 'the items it waits on; repeated or comma-separated'],
+            ['--body-file <file>', 'its description'],
+            ['--human', 'add the human label too'],
+            ['--item <item>', "the item it follows up, when neither the worktree's name nor its branch carries it"],
+            ['--related <item>…', 'more items it is related to; repeated or comma-separated'],
+            ['--title <title>', 'its title'],
+        ],
+        seeAlso: ['brief', 'note'],
         summary: 'file a follow-up of the item, in Backlog with its Area',
         usage: [
             'file --title <title> --body-file <file> --area <area> [--related <item>…] [--blocked-by <item>…] [--human] [--item <item>]',
         ],
     },
     {
-        details: [
-            "--slots and --weight set the project's slots or ordering weight (-100 to 100) until <when>; with neither, its items go first (weight 100).",
-            WHEN,
+        arguments: [['<project>', 'a registered project'], WHEN],
+        description: [
+            "Sets the project's slots or ordering weight until <when>; with neither, its items go first (weight 100).",
+        ],
+        examples: [
+            ['work atk first until 17:00', 'focus atk --until 17:00'],
+            ['six slots for atk until tomorrow', 'focus atk --slots 6 --until tomorrow'],
         ],
         group: 'Scheduling',
         name: 'focus',
+        options: [
+            ['--slots <n>', "the project's slots"],
+            ['--until <when>', 'when the focus ends (required)'],
+            ['--weight <n>', 'its ordering weight, -100 to 100'],
+        ],
+        seeAlso: ['pause', 'queue'],
         summary: 'more slots or weight for a project, for a while',
         usage: ['focus <project> [--slots <n>] [--weight <n>] --until <when>'],
     },
     {
-        details: [
+        arguments: [RANGE, WINDOW],
+        description: [
             'What a window of the log says: shipped items, time in each phase by tier, plan latency, waits by kind, stalls, failures, inbox, slot use, rules and spend.',
-            RANGE,
-            WINDOW,
+            'Give a <range> or --since/--until, not both.',
+        ],
+        examples: [
+            ['the last 24 hours', 'history'],
+            ['a week of atk', 'history 7d --project atk'],
+            ['the last 30 minutes', 'history --since 30m'],
         ],
         group: 'Logs and reports',
         name: 'history',
+        options: REPORT_OPTIONS,
+        seeAlso: ['retro', 'events'],
         summary: 'what a window of the log says, from shipped items to spend',
         usage: ['history [<range>] [--since <when>] [--until <when>] [--project <name>] [--json]'],
     },
     {
-        details: ['Each open item with its age, its commands and its links.'],
+        description: ['Each open item with its age, its commands and its links.'],
+        examples: [['what waits on you', 'inbox']],
         group: 'Inbox and approvals',
         name: 'inbox',
+        options: [['--json', 'print the items as JSON']],
+        seeAlso: ['approve', 'done', 'notify'],
         summary: 'what waits on you',
         usage: ['inbox [--json]'],
     },
     {
-        details: [
+        description: [
             'Installs the conductor mod from this package in Claude Code (user scope): the inbox band, pane and commands in the console (a session started with CONDUCTOR_CONSOLE=1).',
-            '--remove uninstalls it.',
+        ],
+        examples: [
+            ['install the mod', 'install-mod'],
+            ['uninstall it', 'install-mod --remove'],
         ],
         group: 'Setup',
         name: 'install-mod',
+        options: [['--remove', 'uninstall it']],
+        seeAlso: ['console'],
         summary: 'install the conductor mod in Claude Code',
         usage: ['install-mod', 'install-mod --remove'],
     },
     {
-        details: [
+        description: [
             "Registers a Windows Task Scheduler task that runs conduct supervise at logon, which restarts the daemon if it dies. Run it from the main checkout: a worktree's build goes away.",
-            '--remove removes that logon task.',
         ],
+        examples: [['start the daemon at every logon', 'install-startup']],
         group: 'Setup',
         name: 'install-startup',
+        options: [['--remove', 'remove that logon task']],
+        seeAlso: ['supervise', 'start'],
         summary: 'start the daemon at logon (Windows Task Scheduler)',
         usage: ['install-startup', 'install-startup --remove'],
     },
     {
-        details: [
+        arguments: [['<pr>', 'the PR number']],
+        description: [
             "Sets the worker's PR up to land, then gives its first verdict. Safe to repeat. A brake already on the PR (a comment, a failed build, conflicts) is reported and nothing is armed. Otherwise it arms the host's own landing: on Azure DevOps a +10 vote (auto mode) and auto-complete with noFastForward; on GitHub, auto-merge with a merge commit (auto mode, where the repo allows it, refused with the reason where it doesn't). Then it posts the Landing note.",
-            "--mode is held to the profile's landing rules for the PR's files and the plan's tier: auto where they allow it, else refused. Without --mode the rules pick it. The daemon takes the tier from the item's Plan note; without a conductor, pass --tier.",
             'A Landing note with auto-complete or auto-merge gone means someone cancelled it: auto-merge-cancelled, until --rearm.',
             'With a conductor, the daemon records the landing and keeps it armed while the worker waits (conduct wait pr <pr>): it queues an expired build again and restores a cleared vote.',
-            'Prints JSON with the verdict and "via". Exit 1 when refused; 5 for a lost login.',
+            'Prints JSON with the verdict and "via".',
         ],
+        examples: [
+            ['land PR 1850 by itself', 'land 1850 --mode auto --reason "S fix, no review paths"'],
+            ['arm it again after a cancel', 'land 1850 --rearm --reason "Jason said go on"'],
+        ],
+        exitCodes: [[1, 'refused'], LOST_LOGIN],
         group: 'Used by work skills',
         name: 'land',
+        options: [
+            ITEM,
+            [
+                '--mode auto|review',
+                "held to the profile's landing rules for the PR's files and the plan's tier: auto where they allow it, else refused; without it the rules pick",
+            ],
+            ['--reason <why>', 'why this mode, for the Landing note (required)'],
+            ['--rearm', 'arm it again after someone cancelled it'],
+            PR_REPO,
+            ['--tier S|M|L', "the plan's tier without a conductor; the daemon takes it from the item's Plan note"],
+        ],
+        seeAlso: ['wait', 'pr', 'runs'],
         summary: "arm the worker's PR to land, and its first verdict",
         usage: ['land <pr> --reason <why> [--mode auto|review] [--rearm] [--tier S|M|L] [--repo <repo>] [--item <item>]'],
     },
     {
-        details: [
+        arguments: [['<item>', 'the item to work (ATK-312)']],
+        description: [
             "Starts a worker on the item: its worktree, a background session running the project's work skill, and a tab.",
-            [
-                ['--project <name>', 'the project the item belongs to'],
-                ['--probe', "a probe that works no issue: its session and worktree are probe-<item>, out of the fleet's way"],
-                ['--prompt <text>', "the session's first prompt instead of the work skill (or the probe prompt)"],
-                ['--conductor <name>', 'passed to the work skill as --conductor'],
-            ],
+        ],
+        examples: [
+            ['start a worker on ATK-312', 'launch ATK-312'],
+            ['a probe with its own prompt', 'launch ATK-312 --probe --prompt "time the test suite"'],
         ],
         group: 'Projects and workers',
         name: 'launch',
+        options: [
+            ['--conductor <name>', 'passed to the work skill as --conductor'],
+            ['--probe', "a probe that works no issue: its session and worktree are probe-<item>, out of the fleet's way"],
+            ['--project <name>', 'the project the item belongs to'],
+            ['--prompt <text>', "the session's first prompt instead of the work skill (or the probe prompt)"],
+        ],
+        seeAlso: ['attach', 'retire', 'status'],
         summary: 'start a worker: its worktree, a background session, a tab',
         usage: ['launch <item> [--project <name>] [--probe] [--prompt <text>] [--conductor <name>]'],
     },
     {
-        details: [
-            'acquire, release or show a lock every project shares, such as chrome for verify runs. It goes stale 30 minutes after its holder last acquired it: acquire it again to keep it.',
-            "The owner is this checkout's worker's item unless --owner gives one. --wait polls for up to that many minutes.",
-            'Prints JSON. Exit 3 when no conductor answers.',
+        commands: [
+            ['acquire <name>', 'take the lock, or keep it when you hold it'],
+            ['release <name>', 'let it go'],
+            ['status <name>', 'who holds it'],
+        ],
+        description: [
+            'A lock every project shares, such as chrome for verify runs. It goes stale 30 minutes after its holder last acquired it: acquire it again to keep it.',
+            'Prints JSON.',
+        ],
+        examples: [
+            ['take the browser, waiting up to 30 minutes for it', 'lock acquire chrome --wait 30'],
+            ['give it back', 'lock release chrome'],
         ],
+        exitCodes: [[3, 'no conductor answered']],
         group: 'Used by work skills',
         name: 'lock',
+        options: [
+            ['--owner <id>', "who holds it; this checkout's worker's item by default"],
+            ['--wait <minutes>', 'poll for the lock for up to that many minutes'],
+        ],
+        seeAlso: ['ports', 'status'],
         summary: 'a lock every project shares, such as chrome',
         usage: ['lock acquire|release|status <name> [--owner <id>] [--wait <minutes>]'],
     },
     {
-        details: [
-            'Posts the file as a phase note on the item ("## <work skill> · <Phase>") and records its phase on the worker: this checkout\'s, or --worker <worker>.',
+        arguments: [
+            ['<item>', 'the item (ATK-312)'],
+            ['<file>', 'the note, its heading first'],
+        ],
+        description: [
+            'Posts the file as a phase note on the item ("## <work skill> · <Phase>") and records its phase on the worker: this checkout\'s, or --worker.',
             "A Started, PR opened or Landed note also moves the item, to the profile's tracker.transitions (by default In Progress and assigned, In Review, Done on Linear), and PR opened links the worker's PR (else the note's). A Started never reopens a closed item. A state the tracker won't take is a warning: the note stands.",
             "With no conductor, it is posted from this checkout as its project's account, and the item moves the same way.",
-            "Exit 3 when nobody posted it (the tracker refused it, or no conductor and this isn't the item's project checkout).",
-            'Exit 4 when it held the note back because Jason revised an approved plan (by him or by the conductor): re-plan with his words (printed) and wait for approval.',
+        ],
+        examples: [['post the Plan note', 'note ATK-312 plan.md']],
+        exitCodes: [
+            [3, "nobody posted it (the tracker refused it, or no conductor and this isn't the item's project checkout)"],
+            [
+                4,
+                'held back because Jason revised an approved plan (by him or by the conductor): re-plan with his words (printed) and wait for approval',
+            ],
         ],
         group: 'Used by work skills',
         name: 'note',
+        options: [['--worker <worker>', "the worker whose phase it records; this checkout's by default"]],
+        seeAlso: ['brief', 'file', 'wait'],
         summary: 'post a phase note on the item and record the phase',
         usage: ['note <item> <file> [--worker <worker>]'],
     },
     {
-        details: [
+        commands: [
+            ['notify [--json]', "the notification profile, quiet hours, and each channel's state"],
+            [
+                'profile [<name>]',
+                'switch the profile now (built in: default, away, focus); without <name>, the same as conduct notify',
+            ],
             [
-                ['notify [--json]', "the notification profile, quiet hours, and each channel's state"],
-                [
-                    'profile [<name>]',
-                    'switch the profile now (built in: default, away, focus); --until 17:00 or a date and time hands back to the one before it then. Without <name>, the same as conduct notify',
-                ],
-                [
-                    'test',
-                    "push a sample item (default npm-otp) on the profile's channels now; --raise puts a real item in the inbox instead, routed by the profile (quiet hours, reminders), so it takes no --channel",
-                ],
+                'test',
+                "push a sample item on the profile's channels now, or with --raise put a real item in the inbox, routed by the profile (quiet hours, reminders)",
             ],
         ],
+        description: ['The notification profile and its channels: see them, switch the profile, or test it.'],
+        examples: [
+            ['away for the afternoon', 'notify profile away --until 17:00'],
+            ['push a sample npm-otp item', 'notify test'],
+        ],
         group: 'Inbox and approvals',
         name: 'notify',
+        options: [
+            ['--channel remote-control|pushover', 'with test: push on that channel'],
+            ['--json', 'print the state as JSON'],
+            ['--kind <kind>', 'with test: the kind of item (npm-otp by default)'],
+            ['--raise', 'with test: put a real item in the inbox instead; it takes no --channel'],
+            ['--until <when>', 'with profile: hand back to the profile before it then (17:00, or a date and time)'],
+        ],
+        seeAlso: ['inbox'],
         summary: 'the notification profile and channels; switch or test them',
         usage: [
             'notify [--json]',
@@ -254,36 +463,74 @@ export const COMMANDS = [
         ],
     },
     {
-        details: [
-            'No new launches in the project, or in every project without one, until <when> or conduct unpause.',
-            WHEN,
+        arguments: [['<project>', 'a registered project; every project without it'], WHEN],
+        description: ['No new launches in the project, or in every project without one, until <when> or conduct unpause.'],
+        examples: [
+            ['pause every project until tomorrow', 'pause --until tomorrow'],
+            ['pause atk until you unpause it', 'pause atk'],
         ],
         group: 'Scheduling',
         name: 'pause',
+        options: [['--until <when>', 'when the pause ends']],
+        seeAlso: ['unpause', 'focus', 'queue'],
         summary: 'no new launches, until a time or unpause',
         usage: ['pause [<project>] [--until <when>]'],
     },
     {
-        details: [
-            "The checkout's dev ports from the port broker: its project's base ports plus its slot, which no other project's worktree shares (a main checkout: slot 0). --prefer asks for a slot first. Without <path>, every worktree's.",
-            'Exit 3 when no conductor brokered it, so the caller keeps its own ports.',
+        arguments: [['<path>', "the checkout; without it, every worktree's"]],
+        description: [
+            "The checkout's dev ports from the port broker: its project's base ports plus its slot, which no other project's worktree shares (a main checkout: slot 0).",
+        ],
+        examples: [
+            ["this checkout's ports", 'ports .'],
+            ["every worktree's", 'ports'],
         ],
+        exitCodes: [[3, 'no conductor brokered it, so the caller keeps its own ports']],
         group: 'Used by work skills',
         name: 'ports',
+        options: [
+            ['--json', 'print them as JSON'],
+            ['--prefer <slot>', 'ask for this slot first'],
+        ],
+        seeAlso: ['lock'],
         summary: "a checkout's dev ports, from the port broker",
         usage: ['ports [<path>] [--prefer <slot>] [--json]'],
     },
     {
-        details: [
-            "pr create: checks the title carries the item key, the branch carries it too, the description fits the host, no PR is open from the branch, nothing is uncommitted, the branch is ahead of its base, and commitlint passes, all before anything is pushed. Then it pushes and opens the PR into the base branch (--repo: into the other repo's default branch, from its checkout).",
+        commands: [
+            [
+                'create',
+                "check the title carries the item key, the branch carries it too, the description fits the host, no PR is open from the branch, nothing is uncommitted, the branch is ahead of its base, and commitlint passes, all before anything is pushed. Then push and open the PR into the base branch (--repo: into the other repo's default branch, from its checkout)",
+            ],
+            [
+                'threads <pr>',
+                "the PR's threads (on GitHub each comment and review), each with needsAnswer: a person's, open, with no note after it, and asking for something. A read, so it runs here",
+            ],
+        ],
+        description: [
+            "Opens the worker's PR, checked and pushed, or reads its threads.",
             "The description ends with the tracker's reference when it has one (AB#<id> for an ADO Boards item on a GitHub PR, so the Boards GitHub app links it), counted in its length.",
-            'With a conductor, the daemon opens it for the worker that owns this checkout, checking the ownership again, and records the PR on the worker. Without one (or an older one) it opens it here. --dry-run stops before the push.',
-            "pr threads: the PR's threads (on GitHub each comment and review), each with needsAnswer: a person's, open, with no note after it, and asking for something. A read, so it runs here.",
-            "--repo takes github:<owner>/<repo> or ado:<repository>; the profile's code host by default.",
-            'Prints JSON with "via": "daemon" or "local". Exit 1 when refused or failed; 5 for a lost login: run conduct wait login <provider>.',
+            'With a conductor, the daemon opens it for the worker that owns this checkout, checking the ownership again, and records the PR on the worker. Without one (or an older one) it opens it here.',
+            'Prints JSON with "via": "daemon" or "local".',
         ],
+        examples: [
+            [
+                'check everything, push nothing',
+                'pr create --title "feat(conductor): help sections (ATK-478)" --body-file pr.md --dry-run',
+            ],
+            ["PR 1850's threads", 'pr threads 1850'],
+        ],
+        exitCodes: [[1, 'refused or failed'], LOST_LOGIN],
         group: 'Used by work skills',
         name: 'pr',
+        options: [
+            ['--body-file <file>', 'with create: its description'],
+            ['--dry-run', 'with create: stop before the push'],
+            ITEM,
+            PR_REPO,
+            ['--title <title>', 'with create: its title, with the item key'],
+        ],
+        seeAlso: ['land', 'reply', 'state'],
         summary: "open the worker's PR, checked and pushed; read its threads",
         usage: [
             'pr create --title <title> --body-file <file> [--repo <repo>] [--item <item>] [--dry-run]',
@@ -291,250 +538,401 @@ export const COMMANDS = [
         ],
     },
     {
-        details: [
-            [
-                [
-                    'add <path>',
-                    'register the project whose checkout holds .claude/conductor.json (again after changing it); works without the daemon',
-                ],
-                ['list [--json]', 'the registered projects'],
-            ],
+        commands: [
+            ['add <path>', 'register the project whose checkout holds .claude/conductor.json; works without the daemon'],
+            ['list [--json]', 'the registered projects'],
+        ],
+        description: [
+            'Registers a project, or lists the registered ones.',
+            'After that the daemon takes the profile from disk when it starts and each time the file is saved.',
+        ],
+        examples: [
+            ['register the checkout you are in', 'project add .'],
+            ['the registered projects', 'project list'],
         ],
         group: 'Projects and workers',
         name: 'project',
+        options: [['--json', 'with list: print them as JSON']],
+        seeAlso: ['launch', 'status'],
         summary: 'register a project, or list the registered ones',
         usage: ['project add <path>', 'project list [--json]'],
     },
     {
-        details: ["--fresh asks every project's tracker now, instead of using the last read."],
+        description: ['What the scheduler picks next, and why the rest wait.'],
+        examples: [
+            ['what launches next', 'queue'],
+            ['the same, after a change in the tracker', 'queue --fresh'],
+        ],
         group: 'Scheduling',
         name: 'queue',
+        options: [
+            ['--fresh', "ask every project's tracker now, instead of using the last read"],
+            ['--json', 'print it as JSON'],
+        ],
+        seeAlso: ['focus', 'pause', 'status'],
         summary: 'what the scheduler picks next, and why the rest wait',
         usage: ['queue [--json] [--fresh]'],
     },
     {
-        details: [
+        arguments: [
+            ['<pr>', 'the PR number'],
+            ['<thread>', 'the Azure DevOps thread; without it, a note on the PR'],
+        ],
+        description: [
             'Answers on the worker\'s PR: in the Azure DevOps thread named, or as a note on the PR (GitHub, which has no threads, or no thread given). The text is headed "## <work skill> · Reply" unless it already starts with a note heading, so the PR reads it as the worker\'s.',
-            "With a conductor, the daemon posts it for the worker that owns this checkout, checking the PR is the worker's. Prints JSON. Exit 1 when refused; 5 for a lost login.",
+            "With a conductor, the daemon posts it for the worker that owns this checkout, checking the PR is the worker's. Prints JSON.",
         ],
+        examples: [['answer thread 4411 on PR 1850', 'reply 1850 4411 --body-file answer.md']],
+        exitCodes: [[1, 'refused'], LOST_LOGIN],
         group: 'Used by work skills',
         name: 'reply',
+        options: [['--body-file <file>', 'the answer'], ITEM, PR_REPO],
+        seeAlso: ['pr', 'land'],
         summary: "answer a comment on the worker's PR",
         usage: ['reply <pr> [<thread>] --body-file <file> [--repo <repo>] [--item <item>]'],
     },
     {
-        details: [
-            "Stops the worker's session and removes its worktree. It refuses while the worker's turn runs or its worktree has unfinished work (uncommitted or unpushed); --force retires it anyway and throws that work away.",
+        arguments: [WORKER],
+        description: [
+            "Stops the worker's session and removes its worktree. It refuses while the worker's turn runs or its worktree has unfinished work (uncommitted or unpushed).",
         ],
+        examples: [['retire ATK-309 once it is done', 'retire ATK-309']],
         group: 'Projects and workers',
         name: 'retire',
+        options: [['--force', 'retire it anyway and throw that work away']],
+        seeAlso: ['launch', 'attach', 'status'],
         summary: 'stop a worker and remove its worktree and session',
         usage: ['retire <worker> [--force]'],
     },
     {
-        details: ['The same report as conduct history, as Markdown.', RANGE, WINDOW],
+        arguments: [RANGE, WINDOW],
+        description: ['The same report as conduct history, as Markdown.', 'Give a <range> or --since/--until, not both.'],
+        examples: [
+            ["yesterday's retro", 'retro yesterday'],
+            ['a week of atk, to a file', 'retro 7d --project atk > retro.md'],
+        ],
         group: 'Logs and reports',
         name: 'retro',
+        options: REPORT_OPTIONS,
+        seeAlso: ['history'],
         summary: 'the history report as Markdown',
         usage: ['retro [<range>] [--since <when>] [--until <when>] [--project <name>] [--json]'],
     },
     {
-        details: [
+        arguments: [
+            ['<item>', "the item (ATK-312), or the inbox item's id as '#12' (quoted: a shell reads #12 as a comment)"],
+            ['<text>', 'what to change in the plan'],
+        ],
+        description: [
             'Posts "revise: <text>" on the item as you and wakes its worker. Every word after <item> is the text, quoted or not.',
         ],
+        examples: [['ask for a smaller plan', 'revise ATK-312 put the web change in a PR of its own']],
         group: 'Inbox and approvals',
         name: 'revise',
+        seeAlso: ['approve', 'inbox'],
         summary: 'ask for a revised plan and wake its worker',
         usage: ['revise <item> <text>'],
     },
     {
-        details: [
+        commands: [
+            [
+                'rules [--json]',
+                'the rules in force (project, machine, built-in defaults), what replaces what, and any rules file refused. Machine rules are ~/.conductor/rules.json',
+            ],
             [
-                [
-                    'rules [--json]',
-                    'the rules in force (project, machine, built-in defaults), what replaces what, and any rules file refused. Machine rules are ~/.conductor/rules.json',
-                ],
-                [
-                    'test <file> [--json]',
-                    "dry-run the rules on a sample JSON file (no event: a state rule's subject); acts on nothing",
-                ],
+                'test <file> [--json]',
+                "dry-run the rules on a sample JSON file (no event: a state rule's subject); acts on nothing",
             ],
-            'A sample:',
+        ],
+        description: [
+            'The rules in force, and a dry run of them on a sample. A sample for rules test:',
             { pre: ['{ "event": "pr.comment", "project": "atk",', '  "fields": { "wait.kind": "merge" } }'] },
         ],
+        examples: [
+            ['the rules in force', 'rules'],
+            ['what the rules would do with that sample', 'rules test sample.json'],
+        ],
         group: 'Console and rules',
         name: 'rules',
+        options: [['--json', 'print it as JSON']],
+        seeAlso: ['why', 'escalations'],
         summary: 'the rules in force; dry-run them on a sample',
         usage: ['rules [--json]', 'rules test <file> [--json]'],
     },
     {
-        details: [
+        arguments: [['<sha>', 'the merge commit']],
+        description: [
             "One look at a merge's runs: on Azure Pipelines for the project's Azure DevOps repo (the pipelines whose YAML trigger the merge fires, read in this worktree), on GitHub Actions for a GitHub repo (the runs the merge's push started). The outcome is succeeded, failed, cancelled, waiting-for-approval, missing, none (nothing ran: at once on Azure Pipelines, after 5 minutes on GitHub) or waiting (look again, or conduct wait merge).",
-            [
-                [
-                    '--for <a,b>',
-                    'the outcome comes from these pipelines alone (YAML file name such as deploy-api, its path, or its name); the rest are listed under others',
-                ],
-                [
-                    '--repo <repo>',
-                    "github:<owner>/<repo> for another repo, such as the registry; the profile's code host by default",
-                ],
-            ],
             "Each failed run comes with its failed tasks and the end of its log (logs). For the project's repo, each release in the profile (releases, else work.releases) whose run succeeded gives what it staged (stages): package, version, stageId, the npm stage approve line, and whether npm has it (published).",
-            'Prints JSON. A read, so it runs here. Exit 1 when refused or failed; 5 for a lost login.',
+            'Prints JSON. A read, so it runs here.',
+        ],
+        examples: [
+            ['the runs of the merge a1b2c3d', 'runs a1b2c3d'],
+            ['its API deploy alone', 'runs a1b2c3d --for deploy-api'],
         ],
+        exitCodes: [[1, 'refused or failed'], LOST_LOGIN],
         group: 'Used by work skills',
         name: 'runs',
+        options: [
+            [
+                '--for <a,b>',
+                'the outcome comes from these pipelines alone (YAML file name such as deploy-api, its path, or its name); the rest are listed under others',
+            ],
+            [
+                '--repo <repo>',
+                "github:<owner>/<repo> for another repo, such as the registry; the profile's code host by default",
+            ],
+        ],
+        seeAlso: ['wait', 'land'],
         summary: "a merge's runs, their verdict, failed logs and npm stages",
         usage: ['runs <sha> [--for <pipeline>[,<pipeline>…]] [--repo <repo>]'],
     },
     {
-        details: ['One daemon per machine. conduct start runs it detached instead.'],
+        description: ['One daemon per machine. conduct start runs it detached instead.'],
+        examples: [['run the daemon in this terminal', 'serve']],
         group: 'Daemon',
         name: 'serve',
+        seeAlso: ['start', 'supervise', 'stop'],
         summary: 'run the daemon in this process',
         usage: ['serve'],
     },
     {
-        details: [
+        description: [
             'Starts the logon task when it runs this build, else a detached conduct supervise --fail-fast, and waits until the daemon answers. Does nothing when one runs already.',
         ],
+        examples: [['start the daemon', 'start']],
         group: 'Daemon',
         name: 'start',
+        seeAlso: ['stop', 'status', 'serve'],
         summary: 'start the daemon detached and wait until it answers',
         usage: ['start'],
     },
     {
-        details: [
-            "The worktree's branch, how far it is ahead of and behind its base, its uncommitted files, its branch's PR, and the same for each repo checked out under .scratch/repos. --repo shows one.",
-            "Prints JSON. Runs here; the PR is read as the project's account. Exit 5 for a lost login.",
+        description: [
+            "The worktree's branch, how far it is ahead of and behind its base, its uncommitted files, its branch's PR, and the same for each repo checked out under .scratch/repos.",
+            "Prints JSON. Runs here; the PR is read as the project's account.",
+        ],
+        examples: [
+            ['where this worktree stands', 'state'],
+            ['the registry checkout alone', 'state --repo EmergentSoftware/agentic-toolkit-registry'],
         ],
+        exitCodes: [LOST_LOGIN],
         group: 'Used by work skills',
         name: 'state',
+        options: [['--repo <repo>', 'one checked-out repo only']],
+        seeAlso: ['brief', 'checkout', 'pr'],
         summary: "the worktree's branch, changes and PR",
         usage: ['state [--repo <repo>]'],
     },
     {
-        details: [
-            '--json prints it as JSON. With no daemon running, that JSON says running: false, lists the workers from the store, and exits 1.',
+        description: [
+            "The daemon's pid, port, projects, workers and held locks. With no daemon running, --json says running: false, lists the workers from the store, and exits 1.",
         ],
+        examples: [['is the daemon up, and what it runs', 'status']],
         group: 'Daemon',
         name: 'status',
+        options: [['--json', 'print it as JSON']],
+        seeAlso: ['start', 'queue', 'inbox'],
         summary: "the daemon's pid, port, projects, workers and held locks",
         usage: ['status [--json]'],
     },
     {
-        details: [
+        description: [
             'Stops the daemon through its API. When none answers, a conduct supervise may be waiting to restart one: stop asks it to end through supervisor.stop in the conductor home and waits up to 10 s for its answer, then removes the request. A supervisor heeds only a request written after it started and in the last 30 s.',
         ],
+        examples: [['stop the daemon', 'stop']],
         group: 'Daemon',
         name: 'stop',
+        seeAlso: ['start', 'upgrade'],
         summary: 'stop the running daemon',
         usage: ['stop'],
     },
     {
-        details: [
+        description: [
             'Runs conduct serve and starts it again when it dies (a crash, a kill, a start that fails), after 1 s, 5 s, 15 s, 30 s, then every minute, and every 5 minutes once it has pushed. A daemon down 2 minutes sends one Pushover push, held through quiet hours. A stop (conduct stop, upgrade, Ctrl+C), or another daemon holding the lock, ends it. The logon task runs it.',
-            [['--fail-fast', 'end when the first serve exits before it comes up, as conduct start runs it']],
         ],
+        examples: [['what the logon task runs', 'supervise']],
         group: 'Daemon',
         name: 'supervise',
+        options: [['--fail-fast', 'end when the first serve exits before it comes up, as conduct start runs it']],
+        seeAlso: ['install-startup', 'start', 'serve'],
         summary: 'run the daemon and restart it when it dies',
         usage: ['supervise [--fail-fast]'],
     },
     {
-        details: [
+        arguments: [['<project>', "a registered project; without it, the checkout you're in"]],
+        description: [
             'Several skill publishes in one merge (the profile\'s "train"). A worker marks its registry PR with a "<work skill> · Train" note ("· Train · urgent: <why>" asks for one now); the daemon asks you once enough wait.',
             "Takes each marked PR that targets the default branch, has passed its checks and shares no file with another, merges their heads into one train/<stamp> branch on GitHub's side, opens one PR and notes its link on each. Merge it with a merge commit: each member then shows as merged and its worker wakes.",
-            "<project> is a registered project; without it, the checkout you're in. --dry-run only reads: what waits, and what a train would take and leave out.",
+        ],
+        examples: [
+            ['what a train would take and leave out', 'train --dry-run'],
+            ["merge atk's waiting publishes", 'train atk'],
         ],
         group: 'Projects and workers',
         name: 'train',
+        options: [['--dry-run', 'only read: what waits, and what a train would take and leave out']],
+        seeAlso: ['pr', 'land'],
         summary: 'merge waiting skill publishes into one registry PR',
         usage: ['train [<project>] [--dry-run]'],
     },
     {
-        details: [
+        arguments: [['<project>', 'a registered project; every project without it']],
+        description: [
             "Ends the project's pause, or without <project> the pause of every project. Unpausing one project leaves a pause of every project in force.",
         ],
+        examples: [
+            ['launch again everywhere', 'unpause'],
+            ['launch again in atk', 'unpause atk'],
+        ],
         group: 'Scheduling',
         name: 'unpause',
+        seeAlso: ['pause', 'focus'],
         summary: 'launch again after a pause',
         usage: ['unpause [<project>]'],
     },
     {
-        details: [
-            'Stops the daemon, installs the newest version on the tag with npm, and starts the daemon again. The tag defaults to the one the installed version came from.',
-            "--allow-downgrade installs the tag's version even when it is older than the installed one.",
+        description: ['Stops the daemon, installs the newest version on the tag with npm, and starts the daemon again.'],
+        examples: [
+            ['the newest version on the same tag', 'upgrade'],
+            ['move to the dev tag', 'upgrade --tag dev'],
         ],
         group: 'Daemon',
         name: 'upgrade',
+        options: [
+            ['--allow-downgrade', "install the tag's version even when it is older than the installed one"],
+            ['--tag dev|latest', 'the npm dist-tag; the one the installed version came from by default'],
+        ],
+        seeAlso: ['stop', 'start', 'install-mod'],
         summary: 'install the newest version and restart the daemon',
         usage: ['upgrade [--tag dev|latest] [--allow-downgrade]'],
     },
     {
-        details: [
-            "In a worker's worktree with the daemon running, registers the wait and exits 0 at once: end the turn, and the daemon resumes the session when the condition holds. Otherwise checks it here and blocks: exit 0 when it holds, 2 at --timeout (minutes, local only; 29 by default). --local checks it here even with the daemon running.",
-            'Conditions:',
+        conditions: [
+            [
+                'pr <n>',
+                "the PR's verdict once it isn't waiting: merged, build-failed, conflicts, review-comment, changes-requested, merge-failed, auto-merge-cancelled or abandoned. The daemon keeps a landing conduct land armed while it waits",
+            ],
+            [
+                'pr <n> merged|checks|comment',
+                'a pull request merged, its checks finished, or a new comment; --repo github:<owner>/<repo> for a GitHub repo',
+            ],
+            [
+                'merge <sha>',
+                "the merge's runs settled, as conduct runs reads them: on Azure Pipelines for the project's repo, on GitHub Actions with --repo github:<owner>/<repo>; --for <a,b> settles on those pipelines alone. The wake names the outcome and each release's staged version; conduct runs has the logs",
+            ],
+            ['run <pipeline> <run id> [done]', 'a pipeline run finished'],
+            [
+                'npm <version>',
+                "a version on npm; --tag <dist-tag> (default latest), --package <name> (default the profile's)",
+            ],
+            ['health <env>', "the environment's health answers --version <x> or --commit <sha>"],
+            ['approval [<item>]', "an approve or revise: comment after the item's newest Plan note"],
+            [
+                'item <item> <state>',
+                'the item reaches a state; item <item> state|label|note <value> for a state, a label or a note of more than one word',
+            ],
+            [
+                'login ado|github|linear',
+                "the project's login to the provider works again (projects.<name> in config.json says which account)",
+            ],
+            ['time <when>', 'such as 17:00 (the next one) or 2026-10-10T09:00 (local)'],
+            ['<full form>', 'such as pr:ado:Emergent.AgenticToolkit#1850:merged'],
+        ],
+        description: [
+            "In a worker's worktree with the daemon running, registers the wait and exits 0 at once: end the turn, and the daemon resumes the session when the condition holds. Otherwise checks it here and blocks until it holds or --timeout passes.",
+        ],
+        examples: [
+            ['wait for PR 1850 to merge', 'wait pr 1850 merged'],
+            ['wait for the plan approval', 'wait approval'],
+            ['wait for a dev release on npm', 'wait npm 8.7.0-dev.8 --tag dev --package @detergent-software/atk'],
+        ],
+        exitCodes: [
+            [0, 'the condition holds, or the daemon registered the wait'],
+            [2, '--timeout passed (local only)'],
             [
-                [
-                    'pr <n>',
-                    "the PR's verdict once it isn't waiting: merged, build-failed, conflicts, review-comment, changes-requested, merge-failed, auto-merge-cancelled or abandoned. The daemon keeps a landing conduct land armed while it waits",
-                ],
-                [
-                    'pr <n> merged|checks|comment',
-                    'a pull request merged, its checks finished, or a new comment; --repo github:<owner>/<repo> for a GitHub repo',
-                ],
-                [
-                    'merge <sha>',
-                    "the merge's runs settled, as conduct runs reads them: on Azure Pipelines for the project's repo, on GitHub Actions with --repo github:<owner>/<repo>; --for <a,b> settles on those pipelines alone. The wake names the outcome and each release's staged version; conduct runs has the logs",
-                ],
-                ['run <pipeline> <run id> [done]', 'a pipeline run finished'],
-                [
-                    'npm <version>',
-                    "a version on npm; --tag <dist-tag> (default latest), --package <name> (default the profile's)",
-                ],
-                ['health <env>', "the environment's health answers --version <x> or --commit <sha>"],
-                ['approval [<item>]', "an approve or revise: comment after the item's newest Plan note"],
-                [
-                    'item <item> <state>',
-                    'the item reaches a state; item <item> state|label|note <value> for a state, a label or a note of more than one word',
-                ],
-                [
-                    'login ado|github|linear',
-                    "the project's login to the provider works again (projects.<name> in config.json says which account)",
-                ],
-                ['time <when>', 'such as 17:00 (the next one) or 2026-10-10T09:00 (local)'],
-                ['<full form>', 'such as pr:ado:Emergent.AgenticToolkit#1850:merged'],
+                5,
+                'not from wait: worker verbs (state, pr, land, reply, runs) exit 5 when they met a lost provider login; the worker then runs conduct wait login <provider> and ends its turn',
             ],
-            'Exit code 5 is for worker verbs (state, pr, land, reply, runs) that met a lost provider login: the worker runs conduct wait login <provider> and ends its turn.',
         ],
         group: 'Used by work skills',
         name: 'wait',
+        options: [
+            ['--commit <sha>', 'with health: the commit to answer'],
+            ['--for <a,b>', 'with merge: settle on these pipelines alone'],
+            ['--item <item>', "the item for the condition; this checkout's worker's by default"],
+            ['--local', 'check it here even with the daemon running'],
+            ['--package <name>', "with npm: the package; the profile's by default"],
+            ['--repo <repo>', 'with pr and merge: github:<owner>/<repo> for a GitHub repo'],
+            ['--tag <dist-tag>', 'with npm: the dist-tag; latest by default'],
+            ['--timeout <minutes>', 'local only: give up after this many minutes; 29 by default'],
+            ['--version <x>', 'with health: the version to answer'],
+            ['--worker <worker>', "the worker whose wait it is, by name or item; this checkout's by default"],
+        ],
+        seeAlso: ['land', 'runs', 'brief'],
         summary: 'wait for an outside event, such as a merge or an approval',
         usage: ['wait <condition> [--local] [--timeout <minutes>] [--worker <worker>] [--item <item>]'],
     },
     {
-        details: [
-            "With an event id, that event's rule and the events that led to it; with an item (ATK-312), the same for each of its newest actions.",
+        arguments: [['<event id | item>', 'an event id (4200) or an item (ATK-312)']],
+        description: [
+            "With an event id, that event's rule and the events that led to it; with an item, the same for each of its newest actions.",
+        ],
+        examples: [
+            ['why the conductor acted on ATK-312', 'why ATK-312'],
+            ['the rule behind event 4200', 'why 4200'],
         ],
         group: 'Console and rules',
         name: 'why',
+        options: [['--json', 'print it as JSON']],
+        seeAlso: ['rules', 'events', 'escalations'],
         summary: 'the rule behind an action, and the events that led to it',
         usage: ['why <event id | item> [--json]'],
     },
 ];
-// The rows under the groups, which share their column.
+// The listing's last rows: help itself and the CLI's global options.
 const HELP_ROWS = [
-    ['help [<command>]', "this listing, or one command's help (also <command> --help)"],
-    ['--version', 'the installed version'],
+    ['help [<command>]', "this listing, or one command's help"],
+    ['-h, --help', 'the same: conduct --help, or conduct <command> --help'],
+    ['-v, --version', 'the installed version'],
 ];
-// `conduct help <command>`: the summary, every form, then the details.
-export function commandHelp(name, width = terminalWidth()) {
+const FOOTER = [
+    'Run conduct help <command> for its options and examples.',
+    'A <worker> is its item (ATK-309) or its name (probe-ATK-309).',
+    'Files live in ~/.conductor (CONDUCTOR_HOME overrides it).',
+];
+// A placeholder, `conduct <command>`, or a flag: what prose styles.
+const TOKENS = /(<[^<>]+>)|\b(conduct [a-z][a-z-]*)|(?<![\w-])(--?[a-z][a-z-]*)/g;
+// The text as written: tests, a pipe, NO_COLOR.
+export const plain = (_look, text) => text;
+// `conduct help <command>`: the headline, then each section the command has.
+export function commandHelp(name, width = terminalWidth(), paint = plain) {
     const command = find(name);
-    const lines = [...hang(`conduct ${name}: `, command.summary.split(' '), width), '', ...usageLines(command, width)];
-    for (const detail of command.details)
-        lines.push('', ...detailLines(detail, width));
+    const lines = hang(`conduct ${name} — `, words(command.summary), width).map((l) => prose(l, paint));
+    lines.push('', paint('heading', 'USAGE'), ...formLines(command, width, paint));
+    for (const paragraph of command.description)
+        lines.push('', ...paragraphLines(paragraph, width, paint));
+    const table = (heading, rows) => {
+        if (rows?.length)
+            lines.push('', paint('heading', heading), ...rowLines(rows, width, paint));
+    };
+    table('COMMANDS', command.commands);
+    table('CONDITIONS', command.conditions);
+    table('ARGUMENTS', command.arguments);
+    table('OPTIONS', command.options);
+    lines.push('', paint('heading', 'EXAMPLES'));
+    command.examples.forEach(([comment, example], i) => {
+        if (i > 0)
+            lines.push('');
+        const [verb = '', ...args] = words(example);
+        const text = [...hang('  # ', words(comment), width), ...hang(`  conduct ${verb} `, args, width)];
+        lines.push(...text.map((l) => prose(l, paint)));
+    });
+    table('EXIT CODES', command.exitCodes?.map(([code, text]) => [String(code), text]));
+    if (command.seeAlso?.length) {
+        const names = command.seeAlso.map((n, i, all) => `conduct ${n}${i < all.length - 1 ? ',' : ''}`);
+        lines.push('', paint('heading', 'SEE ALSO'), ...hang('  ', names, width).map((l) => prose(l, paint)));
+    }
     return lines.join('\n');
 }
 // The text after `prefix`, word by word, with every line after the first indented to the prefix's
@@ -559,46 +957,63 @@ export function hang(prefix, words, width) {
 export function isCommand(name) {
     return COMMANDS.some((c) => c.name === name);
 }
-// `conduct` and `conduct help`: one line per command under its group, A–Z, then the help rows.
-export function listing(width = terminalWidth()) {
+// `conduct` and `conduct help`: what conduct is, then one line per command under its group, A–Z,
+// then help and the global options.
+export function listing(about, width = terminalWidth(), paint = plain) {
     const column = Math.max(...[...COMMANDS.map((c) => c.name), ...HELP_ROWS.map(([term]) => term)].map((t) => t.length)) + 4;
-    const row = (term, text) => hang(`  ${term}`.padEnd(column), text.split(' '), width);
-    const lines = ['Usage: conduct <command> [options]'];
+    const header = `conduct ${about.version}${about.description ? ` · ${about.description}` : ''}`;
+    const lines = hang('', words(header), width).map((l) => prose(l, paint));
+    lines.push('', paint('heading', 'USAGE'), `  ${term('conduct <command> [options]', paint)}`);
     for (const group of GROUPS) {
-        const names = COMMANDS.filter((c) => c.group === group).toSorted((a, b) => a.name.localeCompare(b.name));
-        lines.push('', group, ...names.flatMap((c) => row(c.name, c.summary)));
+        const rows = COMMANDS.filter((c) => c.group === group)
+            .toSorted((a, b) => a.name.localeCompare(b.name))
+            .map((c) => [c.name, c.summary]);
+        lines.push('', paint('heading', group.toUpperCase()), ...rowLines(rows, width, paint, column));
     }
-    lines.push('', 'Help', ...HELP_ROWS.flatMap(([term, text]) => row(term, text)));
-    lines.push('', ...hang('', 'A <worker> is its item (ATK-309) or its name (probe-ATK-309).'.split(' '), width));
-    lines.push(...hang('', 'Files live in ~/.conductor (CONDUCTOR_HOME overrides it).'.split(' '), width));
+    lines.push('', paint('heading', 'HELP'), ...rowLines(HELP_ROWS, width, paint, column));
+    lines.push('', ...FOOTER.flatMap((text) => hang('', words(text), width).map((l) => prose(l, paint))));
     return lines.join('\n');
 }
-// The width to wrap to: the terminal's, or 80 when it isn't one.
+// Styled for `stream`: bold headings, cyan command names and flags, dim placeholders. With
+// validateStream (always, but in a test), plain unless the stream takes color, as NO_COLOR and
+// FORCE_COLOR say.
+export function terminalStyle(stream, validateStream = true) {
+    return (look, text) => styleText(LOOKS[look], text, { stream, validateStream });
+}
+// The width to wrap to: the terminal's up to 100, or 80 when it isn't one (a pipe has no columns,
+// and some pseudo-terminals say 0).
 export function terminalWidth(stream = process.stdout) {
-    return Math.max(stream.columns ?? DEFAULT_WIDTH, MIN_WIDTH);
+    const columns = stream.columns ?? 0;
+    return Math.min(Math.max(columns > 0 ? columns : DEFAULT_WIDTH, MIN_WIDTH), MAX_WIDTH);
 }
-// What `conduct help <name>` refuses for a name that is no command.
+// What `conduct help <name>` refuses for a name that is no command, with the nearest command when
+// one is a typo away.
 export function unknownCommand(name) {
-    return new ConductorError(`unknown command "${name}"`, ['run `conduct help` for the commands']);
+    const near = nearest(name);
+    return new ConductorError(`unknown command "${name}"`, [
+        ...(near === undefined ? [] : [`did you mean \`conduct ${near}\`?`]),
+        'run `conduct help` for the commands',
+    ]);
 }
 // A usage error for one command: the message, then its forms and where its help is. Never the
-// whole listing. The CLI prints the details indented by two.
+// whole listing, and never styled: workers read it. The CLI prints the details indented by two.
 export function usageError(name, message = `wrong or missing arguments for conduct ${name}`) {
     return new ConductorError(message, [
         ...usageLines(find(name), terminalWidth(process.stderr) - 2),
         `run \`conduct help ${name}\` for the details`,
     ]);
 }
-function detailLines(detail, width) {
-    if (typeof detail === 'string')
-        return hang('', detail.split(' '), width);
-    if ('pre' in detail)
-        return detail.pre.map((line) => `  ${line}`);
-    const short = detail.map(([term]) => term.length).filter((n) => n <= MAX_TERM);
-    const column = 2 + Math.max(0, ...short) + 2;
-    return detail.flatMap(([term, text]) => term.length <= MAX_TERM
-        ? hang(`  ${term}`.padEnd(column), text.split(' '), width)
-        : [`  ${term}`, ...hang(' '.repeat(column), text.split(' '), width)]);
+// Levenshtein: the fewest single-character edits from `a` to `b`.
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (const [i, ca] of [...a].entries()) {
+        const current = [i + 1];
+        for (const [j, cb] of [...b].entries()) {
+            current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (ca === cb ? 0 : 1)));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
 }
 function find(name) {
     const command = COMMANDS.find((c) => c.name === name);
@@ -606,6 +1021,59 @@ function find(name) {
         throw new Error(`no help for ${name}`);
     return command;
 }
+// USAGE: each form under the heading.
+function formLines(command, width, paint) {
+    return forms(command, width, () => '  ').flatMap(([first = '', ...more]) => [
+        `  ${term(first.slice(2), paint)}`,
+        ...more.map((l) => prose(l, paint)),
+    ]);
+}
+// Each form as `<head>conduct <form>`, a long one wrapped under its first argument.
+function forms(command, width, head) {
+    return command.usage.map((form, i) => {
+        const [name = '', ...rest] = synopsisWords(form);
+        return hang(`${head(i)}conduct ${name} `, rest, width);
+    });
+}
+// The command a typo is closest to, within 2 edits and fewer edits than it has letters.
+function nearest(name) {
+    let best;
+    for (const candidate of [...COMMANDS.map((c) => c.name), 'help'].toSorted()) {
+        const distance = editDistance(name, candidate);
+        if (distance <= 2 && distance < name.length && (best === undefined || distance < best.distance))
+            best = { distance, name: candidate };
+    }
+    return best?.name;
+}
+function paragraphLines(paragraph, width, paint) {
+    if (typeof paragraph === 'string')
+        return hang('  ', words(paragraph), width).map((l) => prose(l, paint));
+    return paragraph.pre.map((line) => `    ${line}`);
+}
+// Text with its placeholders dim, and `conduct <command>` and flags cyan.
+function prose(text, paint) {
+    return text.replace(TOKENS, (match, placeholder, command, flag) => {
+        if (placeholder !== undefined)
+            return paint('placeholder', placeholder);
+        if (flag !== undefined)
+            return paint('command', flag);
+        const name = command?.slice('conduct '.length);
+        return name === 'help' || isCommand(name) ? paint('command', match) : match;
+    });
+}
+// Rows of a term and its description, the descriptions in one column: the listing's, else two past
+// the longest term up to MAX_TERM. A term too long for it stands on its own line, with its
+// description under it in that column.
+function rowLines(rows, width, paint, column) {
+    const at = column ?? 2 + Math.max(0, ...rows.map(([t]) => t.length).filter((n) => n <= MAX_TERM)) + 2;
+    return rows.flatMap(([t, text]) => {
+        if (t.length > at - 4) {
+            return [`  ${term(t, paint)}`, ...hang(' '.repeat(at), words(text), width).map((l) => prose(l, paint))];
+        }
+        const [first = '', ...more] = hang(`  ${t}`.padEnd(at), words(text), width);
+        return [`  ${term(t, paint)}${prose(first.slice(2 + t.length), paint)}`, ...more.map((l) => prose(l, paint))];
+    });
+}
 // A form split at its top-level spaces, so `[--since <when>]` stays on one line.
 function synopsisWords(form) {
     const words = [];
@@ -626,12 +1094,20 @@ function synopsisWords(form) {
     }
     return [...words, word];
 }
-// `usage: conduct <form>`, one line per form, a long form wrapped under its first argument.
+// A term, such as a form or a row's: its leading words (the command and sub-command names) cyan,
+// then the rest as prose.
+function term(text, paint) {
+    const parts = synopsisWords(text);
+    const lead = parts.findIndex((w) => !/^[a-z]/.test(w));
+    const names = parts.slice(0, lead === -1 ? parts.length : lead).join(' ');
+    const rest = parts.slice(lead === -1 ? parts.length : lead).join(' ');
+    return [names === '' ? '' : paint('command', names), prose(rest, paint)].filter((p) => p !== '').join(' ');
+}
+// `usage: conduct <form>`, then the other forms under it.
 function usageLines(command, width) {
-    return command.usage.flatMap((form, i) => {
-        const [name = '', ...words] = synopsisWords(form);
-        const head = `${i === 0 ? 'usage: ' : '       '}conduct ${name} `;
-        return hang(head, words, width);
-    });
+    return forms(command, width, (i) => (i === 0 ? 'usage: ' : '       ')).flat();
+}
+function words(text) {
+    return text.split(' ');
 }
 //# sourceMappingURL=help.js.map