@staff0rd/assist 0.373.0 → 0.374.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.373.0",
+  version: "0.374.0",
   type: "module",
   main: "dist/index.js",
   bin: {
@@ -27,7 +27,15 @@ var package_default = {
     build: "tsup",
     start: "node dist/index.js",
     "check:types": "tsc --noEmit",
-    test: "vitest run"
+    test: "vitest run",
+    "verify:lint": "oxlint --config .oxlintrc.json src",
+    "verify:format": "oxfmt .",
+    "verify:knip": "knip --no-progress --treat-config-hints-as-errors",
+    "verify:duplicate-code": 'jscpd --format typescript,tsx,python --exitCode 1 --ignore "**/*.test.*,**/.venv/**" -r consoleFull src',
+    "verify:test": "vitest run --changed --passWithNoTests --reporter dot",
+    "verify:config-keys": "tsx src/index.ts verify config-keys",
+    "verify:react-build": "esbuild src/commands/sessions/web/ui/App.tsx --bundle --minify --format=iife --target=es2020 --outfile=dist/commands/sessions/web/bundle.verify.js --jsx=automatic --jsx-import-source=react --define:process.env.NODE_ENV='production'",
+    "verify:circular-deps": "skott --displayMode=raw --showCircularDependencies --exitCodeOnCircularDependencies=1 src/index.ts"
   },
   overrides: {
     lodash: "^4.18.0",
@@ -107,7 +115,9 @@ var package_default = {
     "react-dom": "^19.2.4",
     "react-router": "^7.14.0",
     "semantic-release": "^25.0.2",
+    skott: "^0.35.11",
     tsup: "^8.5.1",
+    tsx: "^4.23.0",
     vitest: "^4.0.18"
   }
 };
@@ -2583,7 +2593,7 @@ function collectHashComments(content, options2) {
 function collectComments(sourceFile) {
   const seen = /* @__PURE__ */ new Set();
   const comments3 = [];
-  const collect5 = (node) => {
+  const collect6 = (node) => {
     for (const range of [
       ...node.getLeadingCommentRanges(),
       ...node.getTrailingCommentRanges()
@@ -2594,8 +2604,8 @@ function collectComments(sourceFile) {
       comments3.push({ pos, text: range.getText() });
     }
   };
-  collect5(sourceFile);
-  sourceFile.forEachDescendant(collect5);
+  collect6(sourceFile);
+  sourceFile.forEachDescendant(collect6);
   return comments3;
 }
 
@@ -2780,6 +2790,104 @@ Total: ${findings.length} comment(s)`);
   process.exit(1);
 }
 
+// src/shared/configHelp.ts
+var documentedKeys = /* @__PURE__ */ new Set();
+function getDocumentedConfigKeys() {
+  return documentedKeys;
+}
+function renderConfigHelp(entries, preamble) {
+  const width = Math.max(...entries.map((entry) => entry.setter.length));
+  const lines = entries.map(
+    (entry) => `  ${entry.setter.padEnd(width)} # ${entry.note}`
+  );
+  const body = preamble ? ["", preamble, "", "Config:", ...lines] : ["", "Config:", ...lines];
+  return body.join("\n");
+}
+function configHelp(command, entries, preamble) {
+  for (const entry of entries) documentedKeys.add(entry.key);
+  return command.addHelpText(
+    "after",
+    () => renderConfigHelp(entries, preamble)
+  );
+}
+
+// src/shared/enumerateConfigLeafKeys.ts
+var WRAPPER_TYPES = /* @__PURE__ */ new Set([
+  "optional",
+  "default",
+  "nullable",
+  "nullish",
+  "readonly",
+  "catch"
+]);
+function unwrap(node) {
+  let current = node;
+  while (current.def && WRAPPER_TYPES.has(current.def.type ?? "") && current.def.innerType) {
+    current = current.def.innerType;
+  }
+  return current;
+}
+function collect(node, prefix2, out) {
+  const unwrapped = unwrap(node);
+  const shape = unwrapped.def?.shape;
+  if (unwrapped.def?.type === "object" && shape) {
+    for (const [key, child] of Object.entries(shape)) {
+      collect(child, prefix2 ? `${prefix2}.${key}` : key, out);
+    }
+    return;
+  }
+  out.push(prefix2);
+}
+function enumerateConfigLeafKeys(schema2) {
+  const out = [];
+  collect(schema2, "", out);
+  return out.sort();
+}
+
+// src/commands/verify/pendingConfigDocumentation.ts
+var pendingConfigDocumentation = /* @__PURE__ */ new Set();
+
+// src/commands/verify/configKeys.ts
+function section(label2, keys) {
+  if (keys.length === 0) return void 0;
+  const list5 = keys.sort().map((key) => `  ${key}`).join("\n");
+  return `${label2}:
+${list5}`;
+}
+function configKeys() {
+  const schemaKeys = new Set(enumerateConfigLeafKeys(assistConfigSchema));
+  const documented = getDocumentedConfigKeys();
+  const pending = pendingConfigDocumentation;
+  const problems = [
+    section(
+      "Config keys documented by no command (surface them with configHelp)",
+      [...schemaKeys].filter(
+        (key) => !documented.has(key) && !pending.has(key)
+      )
+    ),
+    section(
+      "Documented config keys not present in assistConfigSchema",
+      [...documented].filter((key) => !schemaKeys.has(key))
+    ),
+    section(
+      "Keys now documented but still in pendingConfigDocumentation (remove them)",
+      [...pending].filter((key) => documented.has(key))
+    ),
+    section(
+      "pendingConfigDocumentation lists keys not in assistConfigSchema (remove them)",
+      [...pending].filter((key) => !schemaKeys.has(key))
+    )
+  ].filter((problem) => problem !== void 0);
+  if (problems.length > 0) {
+    console.log(problems.join("\n\n"));
+    process.exit(1);
+  }
+  console.log(
+    `All ${schemaKeys.size} config keys are surfaced in --help or pending documentation.`
+  );
+  process.exit(0);
+}
+
 // src/commands/verify/forbiddenStrings/index.ts
 import { existsSync as existsSync12, readFileSync as readFileSync9 } from "fs";
 
@@ -4082,6 +4190,13 @@ function registerBackup(program2) {
   scheduleCommand.command("remove").description(
     "Remove the marked backup schedule block, leaving other crontab lines intact"
   ).action(scheduleRemove);
+  configHelp(backupCommand, [
+    {
+      key: "backup.dir",
+      setter: "assist config set backup.dir ~/.assist/backups",
+      note: "directory dumps are written to (default: ~/.assist/backups)"
+    }
+  ]);
 }
 
 // src/commands/backlog/next.ts
@@ -7855,6 +7970,20 @@ async function web2(options2) {
   });
 }
 
+// src/commands/backlog/backlogConfigHelp.ts
+var backlogConfigHelp = [
+  {
+    key: "database.url",
+    setter: "assist config set database.url postgresql://...",
+    note: "Postgres connection string for backlog storage (or ASSIST_DATABASE_URL)"
+  },
+  {
+    key: "subtasks",
+    setter: 'assist config set subtasks.0.title "Review"',
+    note: "default sub-tasks seeded onto every new backlog item"
+  }
+];
+
 // src/commands/backlog/addActivity.ts
 import chalk60 from "chalk";
 async function addActivity(id, kind, ref, options2) {
@@ -8114,7 +8243,7 @@ function parseDump(dump) {
 function validateDump({ header, sections }) {
   const tables = header.tables ?? [];
   const missing = tables.find(({ name }) => !sections.has(name))?.name;
-  const checks = [
+  const checks2 = [
     [
       header.format === DUMP_FORMAT,
       `Unrecognised dump format "${header.format}" (expected "${DUMP_FORMAT}").`
@@ -8126,7 +8255,7 @@ function validateDump({ header, sections }) {
     [tables.length > 0, "Dump header lists no tables; cannot restore."],
     [!missing, `Invalid dump: missing data section for "${missing}".`]
   ];
-  const failure = checks.find(([ok]) => !ok);
+  const failure = checks2.find(([ok]) => !ok);
   if (failure) throw new Error(failure[1]);
 }
 
@@ -9598,11 +9727,11 @@ function resolveChecks(o, current) {
     CHECK_FLAGS
   );
 }
-function buildFields(name, tasks, checks) {
+function buildFields(name, tasks, checks2) {
   const fields = {
     name,
     task: tasks.items,
-    manualCheck: checks.items
+    manualCheck: checks2.items
   };
   if (!fields.name && !fields.task && !fields.manualCheck) {
     return {
@@ -9615,9 +9744,9 @@ function buildFields(name, tasks, checks) {
 function resolvePhaseFields(options2, current) {
   const tasks = resolveTasks(options2, current);
   if (!tasks.ok) return tasks;
-  const checks = resolveChecks(options2, current);
-  if (!checks.ok) return checks;
-  return buildFields(options2.name, tasks, checks);
+  const checks2 = resolveChecks(options2, current);
+  if (!checks2.ok) return checks2;
+  return buildFields(options2.name, tasks, checks2);
 }
 
 // src/commands/backlog/updatePhase.ts
@@ -9646,14 +9775,14 @@ async function updatePhase(id, phase, options2) {
 }
 
 // src/commands/backlog/registerUpdatePhaseCommand.ts
-function collect(value, previous) {
+function collect2(value, previous) {
   return [...previous, value];
 }
 function registerUpdatePhaseCommand(cmd) {
-  cmd.command("update-phase <id> <phase>").description("Modify a plan phase on a backlog item").option("--name <name>", "New phase name").option("--task <task...>", "Replace tasks (repeatable)").option("--manual-check <check...>", "Replace manual checks (repeatable)").option("--add-task <text>", "Append one task (repeatable)", collect, []).option("--edit-task <n> <text...>", "Replace task n (1-based) in place").option("--remove-task <n>", "Remove task n (1-based)").option(
+  cmd.command("update-phase <id> <phase>").description("Modify a plan phase on a backlog item").option("--name <name>", "New phase name").option("--task <task...>", "Replace tasks (repeatable)").option("--manual-check <check...>", "Replace manual checks (repeatable)").option("--add-task <text>", "Append one task (repeatable)", collect2, []).option("--edit-task <n> <text...>", "Replace task n (1-based) in place").option("--remove-task <n>", "Remove task n (1-based)").option(
     "--add-check <text>",
     "Append one manual check (repeatable)",
-    collect,
+    collect2,
     []
   ).option(
     "--edit-check <n> <text...>",
@@ -9772,7 +9901,7 @@ async function update(id, options2) {
 }
 
 // src/commands/backlog/registerUpdateCommands.ts
-function collect2(value, previous) {
+function collect3(value, previous) {
   return [...previous, value];
 }
 function registerUpdateCommands(cmd) {
@@ -9782,7 +9911,7 @@ function registerUpdateCommands(cmd) {
   ).option("--type <type>", "New type (story or bug)").option("--ac <criterion...>", "Replace acceptance criteria (repeatable)").option(
     "--add-ac <text>",
     "Append one acceptance criterion (repeatable)",
-    collect2,
+    collect3,
     []
   ).option(
     "--edit-ac <n> <text...>",
@@ -9830,6 +9959,7 @@ function registerBacklog(program2) {
   for (const register of registrars) {
     register(cmd);
   }
+  configHelp(cmd, backlogConfigHelp);
 }
 
 // src/commands/branch/validateSlug.ts
@@ -9878,19 +10008,27 @@ async function branch(slug, options2) {
 
 // src/commands/registerBranch.ts
 function registerBranch(program2) {
-  program2.command("branch <slug>").description(
+  const branchCommand = program2.command("branch <slug>").description(
     "Create and switch to a branch off the fresh remote default branch"
-  ).option("--jira <key>", "Jira issue key to include in the branch name").addHelpText(
-    "after",
-    `
-Branch name is assembled as [<prefix>/][<JIRA>-]<slug>, e.g. sw/BAD-671-add-login-form.
-
-Config:
-  assist config set branch.prefix sw          # optional; prepends "<prefix>/" (omitted when unset)
-  assist config set branch.defaultBranch main # optional; overrides the live remote default branch`
-  ).action(
+  ).option("--jira <key>", "Jira issue key to include in the branch name").action(
     (slug, options2) => branch(slug, options2)
   );
+  configHelp(
+    branchCommand,
+    [
+      {
+        key: "branch.prefix",
+        setter: "assist config set branch.prefix sw",
+        note: 'optional; prepends "<prefix>/" (omitted when unset)'
+      },
+      {
+        key: "branch.defaultBranch",
+        setter: "assist config set branch.defaultBranch main",
+        note: "optional; overrides the live remote default branch"
+      }
+    ],
+    "Branch name is assembled as [<prefix>/][<JIRA>-]<slug>, e.g. sw/BAD-671-add-login-form."
+  );
 }
 
 // src/commands/cliHook/index.ts
@@ -10943,6 +11081,13 @@ function denyRemove(pattern2, options2) {
 // src/commands/registerDeny.ts
 function registerDeny(parent) {
   const denyCommand = parent.command("deny").description("Manage command deny rules").action(denyList);
+  configHelp(denyCommand, [
+    {
+      key: "deny",
+      setter: "assist deny add <pattern> <message>",
+      note: "command patterns blocked with a correction message"
+    }
+  ]);
   denyCommand.command("add").description("Add a deny rule for a command pattern").argument("<pattern>", "Command prefix to deny").argument("<message>", "Correction message shown to the agent").option("-g, --global", "Write to global ~/.assist.yml").action(denyAdd);
   denyCommand.command("remove").description("Remove a deny rule by pattern").argument("<pattern>", "Command prefix to remove").option("-g, --global", "Remove from global ~/.assist.yml").action(denyRemove);
   denyCommand.command("list").description("List all deny rules").action(denyList);
@@ -10953,6 +11098,13 @@ function registerCliHook(program2) {
   const cmd = program2.command("cli-hook").description("PreToolUse hook for auto-approving read-only CLI commands").action(() => {
     cliHook();
   });
+  configHelp(cmd, [
+    {
+      key: "cliReadVerbs",
+      setter: 'assist config set cliReadVerbs.git "status"',
+      note: "extra per-CLI verbs treated as read-only for auto-approval"
+    }
+  ]);
   cmd.command("check <command>").description("Check whether a command would be auto-approved").option("--tool <tool>", "Tool name to check against", "Bash").action((command, options2) => {
     cliHookCheck(command, options2.tool);
   });
@@ -11698,6 +11850,15 @@ async function analyze(pattern2) {
   await maintainability(searchPattern);
 }
 
+// src/commands/complexity/complexityConfigHelp.ts
+var complexityConfigHelp = [
+  {
+    key: "complexity.ignore",
+    setter: 'assist config set complexity.ignore "**/*test.ts*"',
+    note: "globs excluded from maintainability (default: **/*test.ts*)"
+  }
+];
+
 // src/commands/registerComplexity.ts
 function registerComplexity(program2) {
   const complexityCommand = program2.command("complexity").description("Analyze TypeScript code complexity metrics").argument("[pattern]").action((pattern2) => {
@@ -11720,6 +11881,7 @@ function registerComplexity(program2) {
     []
   ).action(maintainability);
   complexityCommand.command("sloc [pattern]").description("Count source lines of code per file").option("--threshold <number>", "Max lines threshold", Number.parseInt).action(sloc);
+  configHelp(complexityCommand, complexityConfigHelp);
 }
 
 // src/commands/config/index.ts
@@ -12421,6 +12583,25 @@ function version() {
   console.log(`${chalk127.bold("next:")} ${nextVersion ?? chalk127.dim("none")}`);
 }
 
+// src/commands/devlog/devlogConfigHelp.ts
+var devlogConfigHelp = [
+  {
+    key: "devlog.name",
+    setter: "assist config set devlog.name my-repo",
+    note: "override the repo name reported in devlog entries"
+  },
+  {
+    key: "devlog.ignore",
+    setter: 'assist config set devlog.ignore "**/*.lock"',
+    note: "globs excluded when grouping commits"
+  },
+  {
+    key: "devlog.skip",
+    setter: "assist devlog skip 2026-07-10",
+    note: "dates (per repo) omitted from devlog output"
+  }
+];
+
 // src/commands/registerDevlog.ts
 function registerDevlog(program2) {
   const devlogCommand = program2.command("devlog").description("Development log utilities");
@@ -12437,6 +12618,7 @@ function registerDevlog(program2) {
     "Only show repos pushed within N days (default: 30)",
     Number.parseInt
   ).option("--all", "Show all non-archived repos regardless of push date").action(repos);
+  configHelp(devlogCommand, devlogConfigHelp);
 }
 
 // src/commands/dotnet/checkBuildLocks.ts
@@ -13062,6 +13244,13 @@ function registerDotnet(program2) {
   cmd.command("check-locks").description("Check if build output files are locked by a debugger").action(checkBuildLocksCommand);
   cmd.command("deps").description("Show .csproj project dependency tree and solution membership").argument("<csproj>", "Path to a .csproj file").option("--json", "Output as JSON").action(deps);
   cmd.command("in-sln").description("Check whether a .csproj is referenced by any .sln file").argument("<csproj>", "Path to a .csproj file").action(inSln);
+  configHelp(cmd, [
+    {
+      key: "dotnet.inspect.suppress",
+      setter: "assist config set dotnet.inspect.suppress CSharpWarnings::CS0168",
+      note: "inspection issue-type IDs suppressed by default"
+    }
+  ]);
 }
 
 // src/commands/editHook/index.ts
@@ -13879,6 +14068,13 @@ function registerJira(program2) {
   jiraCommand.command("auth").description("Authenticate with Jira via API token").action(() => jiraAuth());
   jiraCommand.command("ac <issue-key>").description("Print acceptance criteria for a Jira issue").action((issueKey) => acceptanceCriteria(issueKey));
   jiraCommand.command("view <issue-key>").description("Print the title and description of a Jira issue").action((issueKey) => viewIssue(issueKey));
+  configHelp(jiraCommand, [
+    {
+      key: "jira.acField",
+      setter: "assist config set jira.acField customfield_11937",
+      note: "custom field holding acceptance criteria (default: customfield_11937)"
+    }
+  ]);
 }
 
 // src/commands/reviewComments.ts
@@ -14066,6 +14262,13 @@ function registerMermaid(program2) {
   ).action(
     (file, options2) => mermaidExport(file, options2)
   );
+  configHelp(cmd, [
+    {
+      key: "mermaid.krokiUrl",
+      setter: "assist config set mermaid.krokiUrl https://kroki.io",
+      note: "Kroki server used to render diagrams (default: https://kroki.io)"
+    }
+  ]);
 }
 
 // src/commands/netcap/netcap.ts
@@ -15026,9 +15229,9 @@ function parsePrBody(body) {
   return sections;
 }
 function serializePrBody(sections) {
-  return sections.map((section2) => `## ${section2.heading}
+  return sections.map((section3) => `## ${section3.heading}
 
-${section2.content}`).join("\n\n");
+${section3.content}`).join("\n\n");
 }
 
 // src/commands/prs/editPrBody.ts
@@ -15076,11 +15279,11 @@ function countSentences(paragraph) {
 }
 function splitParagraphs(body) {
   const paragraphs = [];
-  let section2 = "(intro)";
+  let section3 = "(intro)";
   let lines = [];
   const flush = () => {
     if (lines.length > 0) {
-      paragraphs.push({ section: section2, lines });
+      paragraphs.push({ section: section3, lines });
       lines = [];
     }
   };
@@ -15088,7 +15291,7 @@ function splitParagraphs(body) {
     const heading = line.match(/^#{1,6}\s+(.*)$/);
     if (heading) {
       flush();
-      section2 = heading[1].trim();
+      section3 = heading[1].trim();
     } else if (line.trim() === "") {
       flush();
     } else {
@@ -15748,8 +15951,22 @@ function wontfix(commentId, reason) {
   }
 }
 
+// src/commands/prs/prsConfigHelp.ts
+var prsConfigHelp = [
+  {
+    key: "prs.slack",
+    setter: 'assist config set prs.slack "#pull-requests"',
+    note: "Slack channel PRs are announced to (used by /prs-slack)"
+  },
+  {
+    key: "prs.required",
+    setter: "assist config set prs.required true",
+    note: "require a branch when running a backlog item"
+  }
+];
+
 // src/commands/registerPrsEdit.ts
-function collect3(value, previous) {
+function collect4(value, previous) {
   return previous.concat([value]);
 }
 function registerPrsEdit(prsCommand) {
@@ -15758,13 +15975,13 @@ function registerPrsEdit(prsCommand) {
   ).option("-t, --title <title>", "New title for the pull request").option("--what <what>", "Replace the ## What section").option("--why <why>", "Replace the ## Why section").option("--how <how>", "Replace the ## How section").option(
     "--resolves <key>",
     "Jira issue key resolved by this PR, appended to ## Why (repeatable)",
-    collect3,
+    collect4,
     []
   ).action(edit);
 }
 
 // src/commands/registerPrsRaise.ts
-function collect4(value, previous) {
+function collect5(value, previous) {
   return previous.concat([value]);
 }
 function registerPrsRaise(prsCommand) {
@@ -15773,20 +15990,20 @@ function registerPrsRaise(prsCommand) {
   ).option("-t, --title <title>", "Title for the pull request").option("--what <what>", "What the change does (## What section)").option("--why <why>", "Why the change is needed (## Why section)").option("--how <how>", "How the change works (optional ## How section)").option(
     "--resolves <key>",
     "Jira issue key resolved by this PR, appended to ## Why (repeatable)",
-    collect4,
+    collect5,
     []
   ).option(
     "--force",
     "Overwrite the title and body of an existing pull request"
-  ).option("-B, --base <branch>", "Branch into which the pull request merges").option("-H, --head <branch>", "Branch that contains the commits").option("-d, --draft", "Mark the pull request as a draft").option("-w, --web", "Open the browser to create the pull request").option("-l, --label <label>", "Add a label (repeatable)", collect4, []).option(
+  ).option("-B, --base <branch>", "Branch into which the pull request merges").option("-H, --head <branch>", "Branch that contains the commits").option("-d, --draft", "Mark the pull request as a draft").option("-w, --web", "Open the browser to create the pull request").option("-l, --label <label>", "Add a label (repeatable)", collect5, []).option(
     "-a, --assignee <login>",
     "Assign a person by login (repeatable)",
-    collect4,
+    collect5,
     []
   ).option(
     "-r, --reviewer <handle>",
     "Request a review (repeatable)",
-    collect4,
+    collect5,
     []
   ).option("-m, --milestone <name>", "Add the pull request to a milestone").action(raise);
 }
@@ -15811,6 +16028,7 @@ function registerPrs(program2) {
   prsCommand.command("comment <path> <line> <body>").description("Add a line comment to the pending review").action((path58, line, body) => {
     comment2(path58, Number.parseInt(line, 10), body);
   });
+  configHelp(prsCommand, prsConfigHelp);
 }
 
 // src/commands/ravendb/ravendbAuth.ts
@@ -16145,6 +16363,20 @@ async function ravendbCollections(connectionName) {
   }
 }
 
+// src/commands/ravendb/ravendbConfigHelp.ts
+var ravendbConfigHelp = [
+  {
+    key: "ravendb.connections",
+    setter: "assist ravendb auth add",
+    note: "named RavenDB connections (add/list/remove via ravendb auth)"
+  },
+  {
+    key: "ravendb.defaultConnection",
+    setter: "assist ravendb set-connection <name>",
+    note: "connection used when none is passed"
+  }
+];
+
 // src/commands/ravendb/ravendbQuery.ts
 import chalk164 from "chalk";
 
@@ -16233,6 +16465,7 @@ function registerRavendb(program2) {
     (connection, collection, options2) => ravendbQuery(connection, collection, options2)
   );
   cmd.command("collections [connection]").description("List collections in a RavenDB database").action((connection) => ravendbCollections(connection));
+  configHelp(cmd, ravendbConfigHelp);
 }
 
 // src/commands/refactor/check/index.ts
@@ -17017,13 +17250,13 @@ function buildPlan2(functionName, sourceFile, sourcePath, destPath, project) {
 // src/commands/refactor/extract/displayPlan.ts
 import path33 from "path";
 import chalk166 from "chalk";
-function section(title) {
+function section2(title) {
   return `
   ${chalk166.cyan(title)}`;
 }
 function displayImporters(plan2, cwd) {
   if (plan2.importersToUpdate.length === 0) return;
-  console.log(section("Update importers:"));
+  console.log(section2("Update importers:"));
   for (const imp of plan2.importersToUpdate) {
     const rel = path33.relative(cwd, imp.file.getFilePath());
     console.log(`    ${chalk166.dim(rel)}: \u2192 import from "${imp.relPath}"`);
@@ -17037,18 +17270,18 @@ function displayPlan(functionName, relDest, plan2, cwd) {
     console.log(`    ${name}`);
   }
   if (plan2.imports.length > 0) {
-    console.log(section("Imports to copy:"));
+    console.log(section2("Imports to copy:"));
     for (const imp of plan2.imports) {
       console.log(`    ${formatImportLine(imp)}`);
     }
   }
   if (plan2.exportedDeps.length > 0) {
-    console.log(section("New imports from source:"));
+    console.log(section2("New imports from source:"));
     console.log(
       `    import { ${plan2.exportedDeps.join(", ")} } from "${plan2.sourceRelPath}";`
     );
   }
-  console.log(section("Source file changes:"));
+  console.log(section2("Source file changes:"));
   console.log(`    Remove: ${plan2.extractedNames.join(", ")}`);
   if (plan2.sourceNeedsReimport) {
     console.log(
@@ -17057,7 +17290,7 @@ function displayPlan(functionName, relDest, plan2, cwd) {
   }
   displayImporters(plan2, cwd);
   if (plan2.barrel) {
-    console.log(section("Barrel export:"));
+    console.log(section2("Barrel export:"));
     console.log(
       `    Add: export { ${functionName} } from "${plan2.barrelRelPath}";`
     );
@@ -17826,6 +18059,15 @@ async function restructure(pattern2, options2 = {}) {
   }
 }
 
+// src/commands/refactor/refactorConfigHelp.ts
+var refactorConfigHelp = [
+  {
+    key: "restructure.ignore",
+    setter: 'assist config set restructure.ignore "src/generated/**"',
+    note: "globs excluded from restructure coupling analysis"
+  }
+];
+
 // src/commands/registerRefactor.ts
 function registerCheck(parent) {
   parent.command("check [pattern]").description("Check for files that exceed the maximum line count").option("--modified", "Check only staged and unstaged files").option("--staged", "Check only staged files").option("--unstaged", "Check only unstaged files").option(
@@ -17842,13 +18084,14 @@ function registerRename(parent) {
   ).option("--apply", "Execute the rename (default: dry-run)").action(renameSymbol);
 }
 function registerRestructure(parent) {
-  parent.command("restructure [pattern]").description(
+  const restructureCommand = parent.command("restructure [pattern]").description(
     "Analyze import graph and restructure tightly-coupled files into nested directories"
   ).option("--apply", "Execute the restructuring (default: dry-run)").option(
     "--max-depth <number>",
     "Maximum nesting iterations (default: 3)",
     Number.parseInt
   ).action(restructure);
+  configHelp(restructureCommand, refactorConfigHelp);
 }
 function registerRefactor(program2) {
   const refactorCommand = program2.command("refactor").description("Run refactoring checks for code quality");
@@ -19663,6 +19906,20 @@ var seqAuth = createConnectionAuth({
   onFirst: (c) => setDefaultConnection(c.name)
 });
 
+// src/commands/seq/seqConfigHelp.ts
+var seqConfigHelp = [
+  {
+    key: "seq.connections",
+    setter: "assist seq auth add",
+    note: "named Seq connections (add/list/remove via seq auth)"
+  },
+  {
+    key: "seq.defaultConnection",
+    setter: "assist seq set-connection <name>",
+    note: "connection used when none is passed"
+  }
+];
+
 // src/commands/seq/seqQuery.ts
 import chalk184 from "chalk";
 
@@ -19932,6 +20189,7 @@ function registerSeq(program2) {
     "--to <date>",
     "End of query window (UTC date or relative e.g. 5m, 1h, 2d)"
   ).option("--json", "Output raw JSON").action((filter, options2) => seqQuery(filter, options2));
+  configHelp(cmd, seqConfigHelp);
 }
 
 // src/commands/registerSignal.ts
@@ -20086,6 +20344,20 @@ async function sqlColumns(table, connectionName) {
   }
 }
 
+// src/commands/sql/sqlConfigHelp.ts
+var sqlConfigHelp = [
+  {
+    key: "sql.connections",
+    setter: "assist sql auth add",
+    note: "named MSSQL connections (add/list/remove via sql auth)"
+  },
+  {
+    key: "sql.defaultConnection",
+    setter: "assist sql set-connection <name>",
+    note: "connection used when none is passed"
+  }
+];
+
 // src/commands/sql/sqlMutate.ts
 import chalk189 from "chalk";
 
@@ -20214,6 +20486,7 @@ function registerSql(program2) {
   ).action(
     (table, connection) => sqlColumns(table, connection)
   );
+  configHelp(cmd, sqlConfigHelp);
 }
 
 // src/commands/transcript/shared.ts
@@ -20549,9 +20822,29 @@ function move(file, options2) {
   console.log(`Summary target:       ${summaryPath}`);
 }
 
+// src/commands/transcript/transcriptConfigHelp.ts
+var transcriptConfigHelp = [
+  {
+    key: "transcript.vttDir",
+    setter: "assist transcript configure",
+    note: "pick-up directory scanned for raw .vtt files"
+  },
+  {
+    key: "transcript.transcriptsDir",
+    setter: "assist transcript configure",
+    note: "directory dated markdown transcripts are written to"
+  },
+  {
+    key: "transcript.summaryDir",
+    setter: "assist transcript configure",
+    note: "directory generated transcript summaries are written to"
+  }
+];
+
 // src/commands/registerTranscript.ts
 function registerTranscript(program2) {
   const transcriptCommand = program2.command("transcript").description("Meeting transcript utilities");
+  configHelp(transcriptCommand, transcriptConfigHelp);
   transcriptCommand.command("configure").description("Configure transcript directories").action(configure);
   transcriptCommand.command("list").description("List raw .vtt filenames waiting in the pick-up directory").action(list4);
   transcriptCommand.command("move <file>").description(
@@ -20559,6 +20852,59 @@ function registerTranscript(program2) {
   ).requiredOption("--date <YYYY-MM-DD>", "meeting date").requiredOption("--client <name>", "client name").action(move);
 }
 
+// src/commands/registerVerifyChecks.ts
+var checks = [
+  {
+    name: "hardcoded-colors",
+    description: "Check for hardcoded hex colors in src/",
+    action: hardcodedColors
+  },
+  {
+    name: "block-comments",
+    description: "Fail on any comment on a changed line, whether added or edited",
+    action: blockComments
+  },
+  {
+    name: "no-venv",
+    description: "Check that no venv folders exist in the repo",
+    action: noVenv
+  },
+  {
+    name: "forbidden-strings",
+    description: "Check configured JSON files for values matching forbiddenStrings rules",
+    action: forbiddenStrings
+  },
+  {
+    name: "config-keys",
+    description: "Check every assistConfigSchema key is surfaced in some command's --help via configHelp",
+    action: configKeys
+  }
+];
+function registerVerifyChecks(verifyCommand) {
+  for (const check2 of checks) {
+    verifyCommand.command(check2.name).description(check2.description).action(check2.action);
+  }
+}
+
+// src/commands/verify/verifyConfigHelp.ts
+var verifyConfigHelp = [
+  {
+    key: "blockComments.ignore",
+    setter: 'assist config set blockComments.ignore "**/*.test.ts"',
+    note: "globs exempt from the block-comments check"
+  },
+  {
+    key: "hardcodedColors.ignore",
+    setter: 'assist config set hardcodedColors.ignore "**/theme.ts"',
+    note: "globs exempt from the hardcoded-colors check"
+  },
+  {
+    key: "forbiddenStrings",
+    setter: 'assist config set forbiddenStrings.0.disallowed "secret"',
+    note: "per-file value rules enforced by the forbidden-strings check"
+  }
+];
+
 // src/commands/registerVerify.ts
 function runScope(scope, options2) {
   if (scope && scope !== "all") {
@@ -20580,14 +20926,8 @@ function registerVerify(program2) {
     "--package-json",
     "Write scripts to package.json instead of assist.yml"
   ).action(init3);
-  verifyCommand.command("hardcoded-colors").description("Check for hardcoded hex colors in src/").action(hardcodedColors);
-  verifyCommand.command("block-comments").description(
-    "Fail on any comment on a changed line, whether added or edited"
-  ).action(blockComments);
-  verifyCommand.command("no-venv").description("Check that no venv folders exist in the repo").action(noVenv);
-  verifyCommand.command("forbidden-strings").description(
-    "Check configured JSON files for values matching forbiddenStrings rules"
-  ).action(forbiddenStrings);
+  registerVerifyChecks(verifyCommand);
+  configHelp(verifyCommand, verifyConfigHelp);
 }
 
 // src/commands/voice/devices.ts
@@ -20841,6 +21181,50 @@ function stop2() {
   console.log("Voice daemon stopped");
 }
 
+// src/commands/voice/voiceConfigHelp.ts
+var voiceConfigHelp = [
+  {
+    key: "voice.wakeWords",
+    setter: 'assist config set voice.wakeWords "computer"',
+    note: "wake words that activate the daemon (default: computer)"
+  },
+  {
+    key: "voice.mic",
+    setter: "assist config set voice.mic <device>",
+    note: "audio input device (defaults to the system default)"
+  },
+  {
+    key: "voice.cwd",
+    setter: "assist config set voice.cwd <path>",
+    note: "working directory commands are dispatched from"
+  },
+  {
+    key: "voice.modelsDir",
+    setter: "assist config set voice.modelsDir ~/.assist/voice/models",
+    note: "directory VAD/STT models download to"
+  },
+  {
+    key: "voice.lockDir",
+    setter: "assist config set voice.lockDir <path>",
+    note: "directory holding the daemon lock file"
+  },
+  {
+    key: "voice.submitWindows",
+    setter: 'assist config set voice.submitWindows "Code"',
+    note: "window titles where transcriptions auto-submit"
+  },
+  {
+    key: "voice.models.vad",
+    setter: "assist config set voice.models.vad <path>",
+    note: "override the voice-activity-detection model path"
+  },
+  {
+    key: "voice.models.smartTurn",
+    setter: "assist config set voice.models.smartTurn <path>",
+    note: "override the smart-turn model path"
+  }
+];
+
 // src/commands/registerVoice.ts
 function registerVoice(program2) {
   const voiceCommand = program2.command("voice").description("Voice interaction daemon for hands-free Claude commands");
@@ -20850,6 +21234,7 @@ function registerVoice(program2) {
   voiceCommand.command("status").description("Check voice daemon status").action(status);
   voiceCommand.command("devices").description("List available audio input devices").action(devices);
   voiceCommand.command("logs").description("Tail voice daemon logs").option("-n, --lines <count>", "Number of lines to show", "20").action((options2) => logs(options2));
+  configHelp(voiceCommand, voiceConfigHelp);
 }
 
 // src/commands/roam/auth.ts
@@ -21080,8 +21465,82 @@ function registerRoam(program2) {
   roamCommand.command("stop-claude-code-icon").description("Signal Claude Code session stop to Roam local API").action(stopClaudeCodeIcon);
   roamCommand.command("show-codex-icon").description("Forward Codex hook activity to Roam local API").action(showCodexIcon);
   roamCommand.command("stop-codex-icon").description("Signal Codex session stop to Roam local API").action(stopCodexIcon);
+  configHelp(roamCommand, [
+    {
+      key: "roam.clientId",
+      setter: "assist roam auth",
+      note: "OAuth client ID (written by the auth flow)"
+    },
+    {
+      key: "roam.clientSecret",
+      setter: "assist roam auth",
+      note: "OAuth client secret (written by the auth flow)"
+    },
+    {
+      key: "roam.accessToken",
+      setter: "assist roam auth",
+      note: "OAuth access token (managed by the auth flow)"
+    },
+    {
+      key: "roam.refreshToken",
+      setter: "assist roam auth",
+      note: "OAuth refresh token (managed by the auth flow)"
+    },
+    {
+      key: "roam.tokenExpiresAt",
+      setter: "assist roam auth",
+      note: "access-token expiry epoch (managed by the auth flow)"
+    }
+  ]);
 }
 
+// src/commands/rootConfigHelp.ts
+var rootConfigHelp = {
+  sync: [
+    {
+      key: "sync.autoConfirm",
+      setter: "assist config set sync.autoConfirm true",
+      note: "skip the settings.json overwrite prompt"
+    }
+  ],
+  commit: [
+    {
+      key: "commit.conventional",
+      setter: "assist config set commit.conventional true",
+      note: "enforce conventional commit message format"
+    },
+    {
+      key: "commit.pull",
+      setter: "assist config set commit.pull true",
+      note: "pull before committing"
+    },
+    {
+      key: "commit.push",
+      setter: "assist config set commit.push true",
+      note: "push after committing"
+    },
+    {
+      key: "commit.expectedBranch",
+      setter: "assist config set commit.expectedBranch main",
+      note: "warn when committing off this branch"
+    }
+  ],
+  notify: [
+    {
+      key: "notify.enabled",
+      setter: "assist config set notify.enabled false",
+      note: "enable or disable desktop notifications (default: enabled)"
+    }
+  ],
+  screenshot: [
+    {
+      key: "screenshot.outputDir",
+      setter: "assist config set screenshot.outputDir ./screenshots",
+      note: "directory screenshots are written to (default: ./screenshots)"
+    }
+  ]
+};
+
 // src/commands/run/index.ts
 import { resolve as resolve14 } from "path";
 
@@ -21438,12 +21897,8 @@ function remove() {
   console.log(`Removed run configuration: ${name}`);
 }
 
-// src/commands/run/registerRun.ts
-function registerRun(program2) {
-  const runCommand = program2.command("run").description("Run a configured command from assist.yml").argument("[name]", "Name of the configured command").argument("[args...]", "Arguments to pass to the command").allowUnknownOption().addHelpText(
-    "after",
-    "\nAn a-prefixed item id (e.g. a555) with no matching command is an alias for\n'assist backlog run <id>' (forwards --write/--no-write/-w)."
-  ).addHelpText("after", () => formatConfiguredCommands()).action((name, args) => run3(name, args));
+// src/commands/run/registerRunSubcommands.ts
+function registerRunSubcommands(runCommand) {
   runCommand.command("list").description("List configured run commands").option("-v, --verbose", "Show full command details").action((opts) => listRunConfigs(!!opts.verbose));
   runCommand.command("add").description("Add a new run configuration to assist.yml").argument("<name>", "Name for the run configuration").argument("<command>", "Command to execute").argument("[args...]", "Static args to pass to the command").option(
     "--cwd <dir>",
@@ -21456,6 +21911,25 @@ function registerRun(program2) {
   runCommand.command("remove").description("Remove a run configuration from assist.yml").argument("<name>", "Name of the run configuration to remove").action(() => remove());
 }
 
+// src/commands/run/runConfigHelp.ts
+var runConfigHelp = [
+  {
+    key: "run",
+    setter: "assist run add <name> <command>",
+    note: "configured commands runnable via assist run <name>"
+  }
+];
+
+// src/commands/run/registerRun.ts
+function registerRun(program2) {
+  const runCommand = program2.command("run").description("Run a configured command from assist.yml").argument("[name]", "Name of the configured command").argument("[args...]", "Arguments to pass to the command").allowUnknownOption().addHelpText(
+    "after",
+    "\nAn a-prefixed item id (e.g. a555) with no matching command is an alias for\n'assist backlog run <id>' (forwards --write/--no-write/-w)."
+  ).addHelpText("after", () => formatConfiguredCommands()).action((name, args) => run3(name, args));
+  configHelp(runCommand, runConfigHelp);
+  registerRunSubcommands(runCommand);
+}
+
 // src/commands/screenshot/index.ts
 import { execSync as execSync54 } from "child_process";
 import { existsSync as existsSync51, mkdirSync as mkdirSync22, unlinkSync as unlinkSync19, writeFileSync as writeFileSync39 } from "fs";
@@ -24492,6 +24966,28 @@ function registerSessions(program2) {
   cmd.command("set-status <status>").description(
     "Report the current session's status to the sessions daemon (used by Claude Code hooks)"
   ).action(setSessionStatus);
+  configHelp(cmd, [
+    {
+      key: "sessions.windowsProjectsRoot",
+      setter: "assist config set sessions.windowsProjectsRoot /mnt/c/Users/you/.claude/projects",
+      note: "WSL path to the Windows .claude/projects root to discover"
+    },
+    {
+      key: "sessions.windowsDaemonHost",
+      setter: "assist config set sessions.windowsDaemonHost 127.0.0.1",
+      note: "host the WSL daemon dials to reach the Windows daemon (default: 127.0.0.1)"
+    },
+    {
+      key: "sessions.windowsDaemonPort",
+      setter: "assist config set sessions.windowsDaemonPort 51764",
+      note: "TCP port the Windows daemon listens on (default: 51764)"
+    },
+    {
+      key: "sessions.windowsVersionCheck",
+      setter: "assist config set sessions.windowsVersionCheck block",
+      note: "Windows daemon version mismatch handling: block | warn | off"
+    }
+  ]);
 }
 
 // src/commands/statusLine.ts
@@ -24822,9 +25318,11 @@ function reportCliError(error) {
 // src/index.ts
 var program = new Command();
 program.name("assist").description("CLI application").version(package_default.version).option("--no-open", "Do not open a browser on startup").action((options2) => web({ port: "3100", open: options2.open }));
-program.command("sync").description("Copy command files to ~/.claude/commands").option("-y, --yes", "Overwrite settings.json without prompting").action((options2) => sync(options2));
+var syncCommand = program.command("sync").description("Copy command files to ~/.claude/commands").option("-y, --yes", "Overwrite settings.json without prompting").action((options2) => sync(options2));
+configHelp(syncCommand, rootConfigHelp.sync);
 program.command("init").description("Initialize VS Code and verify configurations").action(init5);
-program.command("commit").description("Create a git commit with validation").argument("<args...>", "status | <message> [files...]").action(commit);
+var commitCommand = program.command("commit").description("Create a git commit with validation").argument("<args...>", "status | <message> [files...]").action(commit);
+configHelp(commitCommand, rootConfigHelp.commit);
 registerConfig(program);
 registerRun(program);
 registerNew(program);
@@ -24833,12 +25331,14 @@ lintCommand.command("init").description("Initialize oxlint with baseline linter
 var vscodeCommand = program.command("vscode").description("VS Code configuration utilities");
 vscodeCommand.command("init").description("Add VS Code configuration files").action(init4);
 program.command("status-line").description("Format Claude Code status line from JSON stdin").action(statusLine);
-program.command("notify").description(
+var notifyCommand = program.command("notify").description(
   "Show notification from Claude Code hook (reads JSON from stdin)"
 ).action(notify);
+configHelp(notifyCommand, rootConfigHelp.notify);
 program.command("update").description("Update assist to the latest version and sync commands").action(update2);
 program.command("coverage").description("Print global statement coverage percentage").action(coverage);
-program.command("screenshot").description("Capture a screenshot of a running application window").argument("<process>", "Name of the running process (e.g. notepad, code)").action(screenshot);
+var screenshotCommand = program.command("screenshot").description("Capture a screenshot of a running application window").argument("<process>", "Name of the running process (e.g. notepad, code)").action(screenshot);
+configHelp(screenshotCommand, rootConfigHelp.screenshot);
 registerActivity(program);
 registerBackup(program);
 registerCliHook(program);