@amdahl/cli 0.4.0 → 0.4.1

package/README.md

@@ -44,9 +44,8 @@ Full steps: https://amdahl.ai/connect
 ## Install
 
 Needs Node.js 22 or later. Node.js 20 reached end of life in April 2026 and
-gets no security fixes. `amdahl` still starts on it, but npm warns when it
-installs. On a Node older than 20, `amdahl` stops before it does anything,
-names the version it found, and links the Node.js download page.
+gets no security fixes. On a Node older than 22, `amdahl` stops before it does
+anything, names the version it found, and links the Node.js download page.
 
 ```sh
 # Run once, with no install
@@ -372,7 +371,7 @@ amdahl open [--no-browser]
 amdahl feedback <run-id> --evidence did_it_myself|reported_to_me|inferred
                 [--outcome used|used_with_edits|not_used|unsure] [--sent-text <file>|-] [--comment <text>]
 amdahl sent <run-id> --provider <provider> --channel <channel> --sent-as returned|edited
-                (--provider-send-id <id> | --recipient <email|url> | --recipient-key-hash <sha256>)
+                [--provider-send-id <id>] [--recipient <email|url> | --recipient-key-hash <sha256>]
                 [--sent-at <time>] [--provider-campaign-id <id>] [--sequence-step <n>]
                 [--provider-variant-id <id>] [--provider-lead-id <id>] [--thread-id <id>]
                 [--sent-text <file>|-]
@@ -399,9 +398,20 @@ amdahl search "What objections came up in lost deals last quarter?"
 (`POST /search/query`, with `answer: true`). It prints a short answer, with
 each citation said in plain words, and the rows it came from under `From:`,
 at most five. With no written answer it prints up to ten rows. Each row is
-one line (its title, who and when) and up to three lines of its text, in 80
-columns. `--limit <n>` asks for at most `n` rows, and `--json` prints the
-server's whole answer, every row included.
+one line (its title, who and when) and up to three lines of its quote (the
+row's `content_preview`, or its text), in 80 columns. `--limit <n>` asks for
+at most `n` rows, and `--json` prints the server's whole answer, every row
+included.
+
+When the server found rows but wrote no answer over them (`not_enough_data`),
+the CLI says so plainly before the rows: "Amdahl couldn't answer that from
+these rows. Try rephrasing the question, or run `amdahl connections` to see
+whether your data is synced." The rows follow under `Rows it read:`. A
+failed answer says it found rows but could not write an answer.
+
+The CLI sends the question as you typed it. A window such as "last month" is
+read by the server from the words (the previous calendar month, in UTC); the
+request has no separate field for a time window.
 
 Research is something search starts, never a command of its own. Search
 hands a statistical or long question to a research job by itself, and
@@ -422,11 +432,11 @@ theme blocks print as plain text (an `<unverified>` figure is marked
 type this version does not know: both point to `--json`, where the whole block
 is. Starting research needs
 `conversations:write` and reading it back `conversations:read`. A CLI
-sign-in has neither, so the server runs the search instead and the CLI adds
-one line:
+sign-in has neither, so the server runs the search instead. The CLI says so
+first, before any row:
 
 ```
-A deeper answer needs a Customer agent key: amdahl keys create --name research --preset agent
+Research needs a Customer agent key: amdahl keys create --name research --preset agent. Here is the search answer instead.
 ```
 
 A workspace with nothing connected answers with `setup_needed`: the CLI
@@ -459,7 +469,10 @@ console's add page,
 `<console>/<workspace>/settings/connections?add=1&connector=hubspot`. The
 `connector` only fills the search box on that page: you pick HubSpot there and
 sign in to it. With no connector it opens the add page with an empty search
-box. The CLI never creates a connection itself. An unknown connector exits 2
+box. If that connector is already connected and healthy, the CLI says so
+first ("HubSpot is already connected and healthy (last sync 2026-11-11).")
+and prints the add page instead of opening it; one that needs attention gets
+its own console page. The CLI never creates a connection itself. An unknown connector exits 2
 and lists the ones you can connect; one that is not offered yet exits 1 and
 says it is coming soon. It opens the browser only for a person at a terminal:
 stdin and stdout are terminals, `AMDAHL_NO_PROMPT=1` is not set, no agent runs
@@ -494,18 +507,23 @@ The list is a CSV file with a header row, or a JSONL file (`.jsonl` or
 `.ndjson`) with one batch item, a JSON object, per line. A CSV has a
 `message` column and may have `item_id`, `channel`, `evidence`,
 `on_unsupported`, `facts` and `rules`; facts and rules take one per line
-inside the cell. Any other column is refused by name before anything is
-sent, so a misspelled column is never dropped without a word (use JSONL for
-any other field a single optimize takes). The optimize flags (`--channel`,
+inside the cell. Any other column (a CRM export has many) is not sent: one
+line names it, and it is copied to the results file in its place. Only a
+missing `message` column, or a column Amdahl reads that appears twice (a
+doubled `message`, say), is refused. A JSONL item takes any field a single
+optimize takes, and the server refuses a key it does not know. The optimize flags (`--channel`,
 `--evidence`, `--on-unsupported`, `--tries`, `--context`) apply to every
 item that does not set its own; a row's facts and a `--context` file's rules
 and voice examples are both sent.
 
-The whole file is read and checked first. A header the CLI does not read, or a
-missing `message` column, says which headers it expects. Progress goes to
-stderr, in place at a terminal. When the batch completes, the results go next
-to the list: `drafts.csv` gets `drafts.optimized.csv` (every input column,
-then `optimized_message`, `status`, `what_changed`, `run_id` and `error`), and
+The whole file is read and checked first. A missing `message` column says
+which columns it reads. Progress goes to stderr, in place at a terminal: a
+queued batch says it is queued, and each line after that says where it stands
+once. When the batch completes, the results go next to the list: `drafts.csv`
+gets `drafts.optimized.csv` (every input column in its original order, then
+`optimized_message`, `status`, `summary`, `run_id` and `error`; a column of
+yours with one of those names keeps it, and Amdahl's takes `amdahl_` in
+front), and
 `x.jsonl` gets `x.optimized.jsonl` (one batch item per line, its `result`
 what a single optimize returns). With `--json`, the batch and every item go
 to stdout and no file is written. A failed item exits 1. A refused list
@@ -513,7 +531,10 @@ names the line of the first item the server refused.
 
 A spreadsheet runs a cell that starts with `=`, `+`, `-` or `@` as a formula,
 so in the results CSV such a cell (and one that starts with a tab or a
-carriage return) starts with a `'`. The CLI does not replace a results file
+carriage return) starts with a `'`. That includes the cells copied through
+from your own columns: a phone number such as `+1 555 0100` or a negative
+number gets the `'` too, and you delete it to use the value. The `'` is the
+guard, so it stays. The CLI does not replace a results file
 that already exists: it exits 2 before it queues anything, and `--force`
 replaces the file.
 
@@ -527,7 +548,7 @@ here. `--no-wait` with `--batch` exits 2: it only queues a new list.
 
 ```sh
 amdahl feedback <run-id> --evidence did_it_myself --outcome used_with_edits --sent-text sent.txt
-amdahl sent <run-id> --provider gmail --channel email --sent-as edited --provider-send-id "<msg-id@mail.gmail.com>"
+amdahl sent <run-id> --provider gmail --channel email --sent-as edited --sent-text sent.txt --provider-send-id "<msg-id@mail.gmail.com>"
 ```
 
 `feedback` says what happened to the message one optimize run returned
@@ -543,16 +564,23 @@ stores two.
 (`POST /messages/report_send`). A report from a CLI sign-in is stored as
 `reported_via: cli`. The flags are the report's fields: `--provider`
 (`lemlist`, `instantly`, `outreach`, `salesloft`, `hubspot`, `salesforce`,
-`gmail`, `heyreach`, `apollo`, `linkedin_manual`, `other`), `--channel`
-(`email`, `linkedin_invite`, `linkedin_message`, `linkedin_inmail`),
+`gmail`, `heyreach`, `apollo`, `linkedin_manual`, `other`; the server's
+list, so use `other` for a sender that is not on it), `--channel` (`email`,
+`linkedin_invite`, `linkedin_message`, `linkedin_inmail`; `linkedin` is
+accepted and means `linkedin_message`, as in `amdahl optimize --channel`),
 `--sent-as` (`returned` or `edited`) and `--sent-at` (a time with a time
-zone; the current time when left out), then the optional ids.
-
-The server stores a report only when it can tell which send it is, so one of
-`--provider-send-id`, `--recipient` (an email address, or a LinkedIn profile
-URL for a LinkedIn channel) or `--recipient-key-hash` (a SHA-256) is required.
-A campaign, a lead and a step are not enough. Without one, the CLI exits 2
-before it sends anything. The id is the provider's own: for gmail, the
+zone; the current time when left out), then the optional ids. `--sent-as
+edited` needs `--sent-text`, the message as you sent it (Amdahl keeps only a
+hash of it), and the file must not be empty. That is the CLI's rule, not the
+server's. A run id given twice, or two run ids, exits 2.
+
+The server stores a report only when it can tell which send it is, so you give
+at least one of `--provider-send-id` and a recipient: `--recipient` (an email
+address, or a LinkedIn profile URL for a LinkedIn channel) or
+`--recipient-key-hash` (a SHA-256), never both. A send id with a recipient is
+fine, and the server then counts a report with and one without the id as one
+send. A campaign, a lead and a step are not enough. Without a send id or a
+recipient, the CLI exits 2 before it sends anything. The id is the provider's own: for gmail, the
 `Message-ID` header with its angle brackets; never an email address (give that
 as `--recipient`; Amdahl stores only a hash of it). The command reports one
 send, so give one run id. To report many at once, call
@@ -580,6 +608,39 @@ lines; `--json` never carries them.
   a connection that needs attention, its console page; a used-up quota, the
   day it resets; a role too low, ask a workspace admin.
 - Bare `amdahl`, signed in, with every tool set up: what to try here.
+- After an optimize (one file, a pasted message, or a list) a line says what
+  to do once the message is sent: two lines, each a command to paste, with
+  the run's own id and the flags it needs as placeholders (`amdahl sent
+  <run-id> --provider <provider> --channel <channel> --sent-as returned
+  --provider-send-id <id>`, then `amdahl feedback <run-id> --evidence
+  did_it_myself --outcome used`). A list prints the first run id of its
+  results. Replace each `<placeholder>` before you run it.
+- `amdahl optimize` no longer prints the server's `what_changed` line. It is
+  the same sentence on every run. It is still in `--json`.
+
+## Help and errors
+
+`amdahl <command> --help` (also `-h`, or `amdahl help <command>`) prints that
+command's usage and nothing else: its flags, what it prints, and its exit
+codes where they matter. `amdahl keys --help` lists the `keys` commands. For
+`optimize --json`, the help says where the message is: `.result.message`, and
+the run id is `.result.run_id`.
+
+Three failures print a plain sentence each. Only the sentence changed from
+0.4.0: the `--json` error `code` is still the server's (or `http_<status>`) and
+its `hint` is the same, because scripts and agents branch on them.
+
+- A credential that lacks a scope says what it cannot do and what to use: `This
+  credential cannot optimize. Use a Customer agent key, or run \`amdahl
+  login\` again.` (exit 4). It never prints the server's `Missing required
+  scope(s)`.
+- A key the server will not take (revoked or expired): `This key isn't valid
+  (revoked or expired).` and the hint, `Run amdahl login, or check
+  AMDAHL_KEY.` (exit 3). An OAuth access token in `AMDAHL_ACCESS_TOKEN` says
+  `This token isn't valid (revoked or expired).` A saved sign-in the server
+  will not take: `Your sign-in is no longer valid.`
+- A file that is not there: `Can't find <file>.` (exit 2), for a draft, a
+  list, `--context` and `--sent-text`.
 
 ## Skills
 

package/bin/amdahl.js

@@ -2,7 +2,7 @@
 // bin/amdahl.js
 //
 // The `amdahl` command. It checks the Node.js version before it loads the
-// CLI: dist/amdahl.js is built for Node 20, and an older Node fails to parse
+// CLI: dist/amdahl.js is built for Node 22, and an older Node fails to parse
 // it or crashes in it, while npx only warns about `engines`. So this file
 // uses no syntax newer than Node 14 (no `??=`, no top-level await, no class
 // fields), and an old Node can run it far enough to say what to do.
@@ -10,9 +10,9 @@
 var version = process.versions.node
 var major = parseInt(version.split('.')[0], 10)
 
-if (!(major >= 20)) {
+if (!(major >= 22)) {
   process.stderr.write(
-    'amdahl needs Node.js 20 or later. This computer has Node.js ' +
+    'amdahl needs Node.js 22 or later. This computer has Node.js ' +
       version +
       '.\nInstall a newer one from https://nodejs.org/en/download, then run the same command again.\n'
   )

package/dist/amdahl.js

@@ -7921,6 +7921,13 @@ var ALIASES = {
   "auth status": "whoami"
 };
 var TWO_WORD = /* @__PURE__ */ new Set(["auth", "keys", "workspace", "skills"]);
+function helpWords(argv) {
+  try {
+    return parseArgs({ args: argv, options: allOptions(), allowPositionals: true, strict: false }).positionals;
+  } catch {
+    return [];
+  }
+}
 function allOptions() {
   const merged = { ...GLOBAL_OPTIONS };
   for (const spec of Object.values(COMMAND_OPTIONS)) Object.assign(merged, spec);
@@ -8022,12 +8029,16 @@ Commands:
   optimize [<file>... | -] [--channel email|linkedin]
            [--evidence off|workspace] [--on-unsupported flag|remove]
            [--tries] [--context <file.json>]
+           --json prints {ok, file, result}: the message is .result.message
+           and the run id is .result.run_id.
   optimize --list <file.csv|file.jsonl> [--no-wait] [--batch <id>] [--force]
            [the optimize flags above, for every message]
-           A CSV has a message column, and may have item_id, channel,
-           evidence, on_unsupported, facts and rules. --batch <id> picks up
-           a batch queued earlier, with the same list. --force replaces an
-           existing results file.
+           A CSV needs a message column, and may have item_id, channel,
+           evidence, on_unsupported, facts and rules. Any other column is
+           copied to the results as it is. --batch <id> picks up a batch
+           queued earlier, with the same list. --force replaces an existing
+           results file. In the results CSV, a cell that starts with =, +, -
+           or @ (a phone number, say) gets a ' in front: it is no formula.
   search "<question>" [--research] [--limit <n>]
            --research  ask for a research job: a deeper, cited answer (needs
                        a Customer agent key, amdahl keys create --preset
@@ -8041,12 +8052,19 @@ Commands:
                                              What happened to a message
   sent <run-id> --provider <provider> --channel <channel>
            --sent-as returned|edited [--sent-at <time>]
-           (--provider-send-id <id> | --recipient <email|url> |
-            --recipient-key-hash <sha256>)
+           [--provider-send-id <id>]
+           [--recipient <email|url> | --recipient-key-hash <sha256>]
            [--provider-campaign-id <id>] [--sequence-step <n>]
            [--provider-variant-id <id>] [--provider-lead-id <id>]
            [--thread-id <id>] [--sent-text <file> | -]
-           One send per command. It needs one of the three in brackets.
+           One send per command. Give --provider-send-id, a recipient, or
+           both (a recipient is --recipient or --recipient-key-hash, not both).
+           --provider: lemlist, instantly, outreach, salesloft, hubspot,
+                       salesforce, gmail, heyreach, apollo, linkedin_manual,
+                       other (any sender not listed)
+           --channel:  email, linkedin (= linkedin_message), linkedin_invite,
+                       linkedin_message, linkedin_inmail
+           --sent-as edited needs --sent-text.
                                              Report that a message went out
   keys create --name <name> [--preset read-only|agent|internal|admin]
               [--expires 30d|90d|365d] [--no-browser]
@@ -8068,6 +8086,7 @@ Commands:
                      (Cancel or Install anyway); -y, --json or no terminal
                      stops (exit 9)
   help                                       Show this help
+           Run \`amdahl <command> --help\` for one command's usage.
 
 Global options:
   --profile <name>   Use a saved profile (default: AMDAHL_PROFILE, then the
@@ -8085,7 +8104,7 @@ Global options:
 `;
 
 // src/version.ts
-var VERSION = "0.4.0";
+var VERSION = "0.4.1";
 
 // src/api.ts
 var CLIENT_HEADER = {
@@ -8093,18 +8112,20 @@ var CLIENT_HEADER = {
   "User-Agent": `amdahl-cli/${VERSION}`
 };
 var AmdahlApiError = class extends Error {
-  constructor(message2, statusCode, path, responseBody, errorCode) {
+  constructor(message2, statusCode, path, responseBody, errorCode, credentialSource) {
     super(message2);
     this.statusCode = statusCode;
     this.path = path;
     this.responseBody = responseBody;
     this.errorCode = errorCode;
+    this.credentialSource = credentialSource;
     this.name = "AmdahlApiError";
   }
   statusCode;
   path;
   responseBody;
   errorCode;
+  credentialSource;
 };
 function extractToolFailure(json) {
   if (!json || typeof json !== "object" || Array.isArray(json)) return null;
@@ -8176,7 +8197,7 @@ function assertUuid(name, value) {
   }
 }
 function createAmdahlClient(config) {
-  const { baseUrl, token } = config;
+  const { baseUrl, token, source } = config;
   async function request(path, options = {}) {
     const { method = "GET", body, headers = {} } = options;
     const allHeaders = { ...headers, ...CLIENT_HEADER, Authorization: `Bearer ${token}` };
@@ -8189,12 +8210,12 @@ function createAmdahlClient(config) {
     if (!response.ok) {
       const errorBody = await response.text().catch(() => "");
       const { message: message2, code } = parseErrorBody(errorBody, response.status);
-      throw new AmdahlApiError(message2, response.status, path, errorBody, code);
+      throw new AmdahlApiError(message2, response.status, path, errorBody, code, source);
     }
     const json = await response.json();
     const toolFailure = extractToolFailure(json);
     if (toolFailure) {
-      throw new AmdahlApiError(toolFailure.message, response.status, path, JSON.stringify(json), toolFailure.code);
+      throw new AmdahlApiError(toolFailure.message, response.status, path, JSON.stringify(json), toolFailure.code, source);
     }
     if (json && typeof json === "object" && !Array.isArray(json) && "data" in json && Object.keys(json).length === 1) {
       return json.data;
@@ -8804,7 +8825,7 @@ async function profileCredential(ctx) {
   return { source: "profile", token: refreshed.access_token, profile: profileName };
 }
 function apiClient(ctx, credential) {
-  return createAmdahlClient({ baseUrl: ctx.apiUrl, token: credential.token });
+  return createAmdahlClient({ baseUrl: ctx.apiUrl, token: credential.token, source: credential.source });
 }
 function errorDetails(body) {
   if (!body) return {};
@@ -8816,6 +8837,28 @@ function errorDetails(body) {
     return {};
   }
 }
+var CALL_VERBS = [
+  ["/messages/optimize/batch", "optimize a list"],
+  ["/messages/optimize/runs/", "record feedback"],
+  ["/messages/optimize", "optimize"],
+  ["/messages/report_send", "report sends"],
+  ["/research/", "read research"],
+  ["/search/query", "search"],
+  ["/connections", "read connections"],
+  ["/setup/status", "read the setup status"]
+];
+function plainMessage(err) {
+  if (err.statusCode === 401 && err.credentialSource) {
+    if (err.credentialSource === "profile") return "Your sign-in is no longer valid.";
+    const noun = err.credentialSource === "env:AMDAHL_ACCESS_TOKEN" ? "token" : "key";
+    return `This ${noun} isn't valid (revoked or expired).`;
+  }
+  if (err.errorCode === "missing_scope" || /^Missing required scope/i.test(err.message)) {
+    const verb = CALL_VERBS.find(([prefix2]) => err.path.includes(prefix2))?.[1] ?? "do this";
+    return `This credential cannot ${verb}. Use a Customer agent key, or run \`${amdahlCommand("login")}\` again.`;
+  }
+  return null;
+}
 function toCliError(err) {
   if (err instanceof CliError) return err;
   if (err instanceof PromptCancelled) return new CliError("cancelled", "Stopped. Nothing changed.", EXIT.cancelled);
@@ -8824,7 +8867,7 @@ function toCliError(err) {
     const details = errorDetails(err.responseBody);
     const retry = details.retry_after_seconds;
     const hint = exit === EXIT.unauthenticated ? `Run \`${amdahlCommand("login")}\`, or check AMDAHL_KEY.` : typeof retry === "number" ? `Try again in ${retry} seconds.` : void 0;
-    return new CliError(err.errorCode ?? `http_${err.statusCode}`, err.message, exit, hint);
+    return new CliError(err.errorCode ?? `http_${err.statusCode}`, plainMessage(err) ?? err.message, exit, hint);
   }
   const message2 = err instanceof Error ? err.message : String(err);
   return new CliError("network_error", `Could not reach the Amdahl API: ${message2}`, EXIT.network, NETWORK_HINT);
@@ -9436,6 +9479,14 @@ function day(iso) {
   const ms = Date.parse(iso);
   return Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : "";
 }
+function hasFactsOrRules(context) {
+  const c = record(context);
+  const some = (list2) => Array.isArray(list2) && list2.some((entry) => typeof entry === "string" ? entry.trim() !== "" : !!record(entry));
+  return !!c && (some(c.facts) || some(c.rules));
+}
+function truthfulSummary(summary, context) {
+  return /facts and rules/i.test(summary) && !hasFactsOrRules(context) ? "" : summary;
+}
 function count(n, one, many = `${one}s`) {
   return `${n} ${n === 1 ? one : many}`;
 }
@@ -9536,7 +9587,10 @@ async function connect(ctx, args) {
     }
   }
   const slug = await workspaceSlug(ctx, credential);
-  const url = connectUrl(consoleUrlFor(ctx.io, ctx.apiUrl), slug, entry?.type);
+  const consoleUrl = consoleUrlFor(ctx.io, ctx.apiUrl);
+  const url = connectUrl(consoleUrl, slug, entry?.type);
+  const existing = entry ? await existingConnection(client, entry.type) : null;
+  if (entry && existing) return alreadyConnected(ctx, entry, existing, url, connectionUrl(consoleUrl, slug, field(existing.id)));
   const opened = await openOrPrint(ctx, url);
   if (ctx.out.json) {
     ctx.out.result({ ok: true, url, opened, connector: entry?.type ?? null });
@@ -9550,6 +9604,33 @@ async function connect(ctx, args) {
   ctx.out.result({}, url);
   return EXIT.ok;
 }
+async function existingConnection(client, type) {
+  try {
+    const body = await client.request(`${PLATFORM2}/connections`);
+    const same = records(Array.isArray(body) ? body : record(body)?.connections).filter((c) => field(c.connector_type) === type || field(record(c.connector)?.type) === type);
+    return same.find((c) => FINE.has(healthOf(c))) ?? same[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function alreadyConnected(ctx, entry, existing, addUrl, pageUrl) {
+  const health = healthOf(existing);
+  const healthy = FINE.has(health);
+  const synced = day(existing.last_synced_at);
+  if (ctx.out.json) {
+    ctx.out.result({ ok: true, url: addUrl, opened: false, connector: entry.type, connected: { id: field(existing.id), health, healthy, url: pageUrl } });
+    return EXIT.ok;
+  }
+  if (healthy) {
+    ctx.out.info(`${entry.name} is already connected and healthy${synced ? ` (last sync ${synced})` : ""}.`);
+    ctx.out.info("To add another one, open this link:");
+    ctx.out.result({}, addUrl);
+    return EXIT.ok;
+  }
+  ctx.out.info(`${entry.name} is already connected, but its health is "${HEALTH[health] ?? health}".`);
+  ctx.out.info(`${health === "needs_reauth" ? "Sign in to it again" : "Fix it"}: ${pageUrl}`);
+  return EXIT.ok;
+}
 function connectionRow(c) {
   const connector = record(c.connector);
   const type = field(connector?.name) || field(c.connector_type);
@@ -9602,13 +9683,27 @@ async function fixLine(ctx, credential, attention, slug) {
   return `Fix them: ${connectionsUrl(consoleUrl, ws)}`;
 }
 
-// src/commands/feedback.ts
+// src/files.ts
 import { readFileSync as readFileSync4 } from "fs";
+function readTextFile(path) {
+  try {
+    return readFileSync4(path, "utf8");
+  } catch (err) {
+    const code = err?.code;
+    if (code === "ENOENT") throw usageError(`Can't find ${path}.`);
+    if (code === "EISDIR") throw usageError(`${path} is a folder, not a file.`);
+    if (code === "EACCES" || code === "EPERM") throw usageError(`Can't read ${path}: permission denied.`);
+    throw usageError(`Can't read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// src/commands/feedback.ts
 var PLATFORM3 = "/api/platform/v1";
 var FEEDBACK_OUTCOMES = ["used", "used_with_edits", "not_used", "unsure"];
 var FEEDBACK_EVIDENCE = ["did_it_myself", "reported_to_me", "inferred"];
 var SEND_PROVIDERS = ["lemlist", "instantly", "outreach", "salesloft", "hubspot", "salesforce", "gmail", "heyreach", "apollo", "linkedin_manual", "other"];
 var SEND_CHANNELS = ["email", "linkedin_invite", "linkedin_message", "linkedin_inmail"];
+var CHANNEL_ALIASES = { linkedin: "linkedin_message" };
 var SENT_AS = ["returned", "edited"];
 var MAX_MESSAGE_CHARS = 1e4;
 var MAX_COMMENT_CHARS = 2e3;
@@ -9633,11 +9728,7 @@ function text(flag, value, max) {
   return value;
 }
 async function readText(ctx, path) {
-  try {
-    return path === "-" ? await ctx.io.readStdin() : readFileSync4(path, "utf8");
-  } catch (err) {
-    throw usageError(`Could not read --sent-text ${path}: ${err instanceof Error ? err.message : String(err)}`);
-  }
+  return path === "-" ? await ctx.io.readStdin() : readTextFile(path);
 }
 async function feedback(ctx, args) {
   const usage = `Usage: ${amdahlCommand("feedback <run-id> --evidence did_it_myself [--outcome used] [--sent-text <file>] [--comment <text>]")}`;
@@ -9675,21 +9766,28 @@ var PROVIDER_IDS = {
   "provider-lead-id": ["provider_lead_id", 256],
   "thread-id": ["thread_id", 512]
 };
-var SEND_KEYS = ["--provider-send-id", "--recipient", "--recipient-key-hash"];
 async function sent(ctx, args) {
   const { flags } = ctx;
   const usage = `Usage: ${amdahlCommand("sent <run-id> --provider <provider> --channel <channel> --sent-as returned|edited --provider-send-id <id>")}`;
   const [rawId, ...rest] = args;
   if (!rawId) throw usageError("Give the run id of the message that was sent.", usage);
+  if (rest.length > 0 && rest.every((r) => r.toLowerCase() === rawId.toLowerCase())) {
+    throw usageError(`${rawId} is there twice.`, "Give each run id once. The command reports one send.");
+  }
   if (rest.length > 0) {
     throw usageError("Report one send at a time: give one run id.", "Each send needs its own --provider-send-id or --recipient, so run it once for each. The API takes up to 100 at once (POST /messages/report_send).");
   }
   const id = runId(rawId, usage);
-  const provider = oneOf("provider", str(flags.provider), SEND_PROVIDERS);
-  const channel = oneOf("channel", str(flags.channel), SEND_CHANNELS);
+  const rawProvider = str(flags.provider);
+  if (rawProvider !== void 0 && !SEND_PROVIDERS.includes(rawProvider)) {
+    throw usageError(`--provider must be one of: ${SEND_PROVIDERS.join(", ")}.`, `"${clip(rawProvider, 40)}" is not on the list. For a sender that is not, use --provider other.`);
+  }
+  const provider = rawProvider;
+  const rawChannel = str(flags.channel);
+  const channel = rawChannel === void 0 ? void 0 : CHANNEL_ALIASES[rawChannel] ?? oneOf("channel", rawChannel, [...SEND_CHANNELS, ...Object.keys(CHANNEL_ALIASES)]);
   const sentAs = oneOf("sent-as", str(flags["sent-as"]), SENT_AS);
   if (!provider) throw usageError(`Say where it went out with --provider: ${SEND_PROVIDERS.join(", ")}.`, usage);
-  if (!channel) throw usageError(`Say what was sent with --channel: ${SEND_CHANNELS.join(", ")}.`, usage);
+  if (!channel) throw usageError(`Say what was sent with --channel: ${[...SEND_CHANNELS, ...Object.keys(CHANNEL_ALIASES)].join(", ")}.`, usage);
   if (!sentAs) throw usageError("Say whether it was sent as Amdahl returned it with --sent-as: returned, edited.", usage);
   const sentAt = str(flags["sent-at"]) ?? new Date(ctx.io.now()).toISOString();
   if (!TIME_WITH_ZONE.test(sentAt) || !Number.isFinite(Date.parse(sentAt))) {
@@ -9726,8 +9824,14 @@ async function sent(ctx, args) {
   }
   const sentPath = str(flags["sent-text"]);
   if (sentPath !== void 0) item.sent_text = text("sent-text", await readText(ctx, sentPath), MAX_MESSAGE_CHARS);
+  if (sentAs === "edited" && sentPath === void 0) {
+    throw usageError("--sent-as edited needs --sent-text <file>: the message as you sent it.", "Amdahl keeps only a hash of the text. Use - to read it from standard input.");
+  }
+  if (sentAs === "edited" && !(typeof item.sent_text === "string" && item.sent_text.trim())) {
+    throw usageError(`${sentPath === "-" ? "Standard input" : `--sent-text ${sentPath}`} is empty. An edited send needs the message as you sent it.`);
+  }
   if (!sendId?.trim() && !recipient?.trim() && !hash?.trim()) {
-    throw usageError(`Say which send this is with one of ${SEND_KEYS.join(", ")}.`, "Amdahl matches a report to a send by its provider's own id, or by the recipient (stored only as a hash).");
+    throw usageError("Say which send this is: give --provider-send-id, a recipient (--recipient or --recipient-key-hash), or both.", "Amdahl matches a report to a send by its provider's own id, by the recipient (stored only as a hash), or both.");
   }
   const credential = await resolveCredential(ctx);
   const result = await call(
@@ -10247,11 +10351,18 @@ async function keysRevoke(ctx, args) {
   return EXIT.ok;
 }
 
-// src/commands/optimize.ts
-import { readFileSync as readFileSync7 } from "fs";
+// src/next-steps.ts
+function sentLines(runId2, lead = "Sent it?") {
+  const id = field(runId2);
+  if (!id) return [];
+  return [
+    `${lead} ${amdahlCommand("sent")} ${id} --provider <provider> --channel <channel> --sent-as returned --provider-send-id <id>`,
+    `Or say how it went: ${amdahlCommand("feedback")} ${id} --evidence did_it_myself --outcome used`
+  ];
+}
 
 // src/commands/batch.ts
-import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5, writeFileSync as writeFileSync4 } from "fs";
 import { basename as basename2, dirname as dirname4, extname, join as join7 } from "path";
 var PLATFORM4 = "/api/platform/v1";
 var BATCH_WAIT_MS = 15e3;
@@ -10329,12 +10440,15 @@ function csvList(path, text3) {
   const [header, ...body] = rows;
   if (!header) throw usageError(`${path} is empty.`);
   const names = header.map((h) => h.trim().toLowerCase());
-  const unknown = names.find((n) => !CSV_COLUMNS.includes(n));
-  const headers = `The first row must name the columns, from: ${CSV_COLUMNS.join(", ")} (message is required). For any other field, use a JSONL file.`;
-  if (unknown !== void 0) {
-    throw usageError(`${path} has a column Amdahl doesn't read: "${clip(unknown, 40)}".`, headers);
+  const twice = CSV_COLUMNS.find((c) => names.indexOf(c) !== names.lastIndexOf(c));
+  if (twice !== void 0) throw usageError(`${path} has the column "${twice}" twice.`);
+  if (!names.includes("message")) {
+    throw usageError(
+      `${path} needs a "message" column.`,
+      `The first row must name the columns. Required: message. Read: ${CSV_COLUMNS.filter((c) => c !== "message").join(", ")}. Any other column is copied to the results as it is.`
+    );
   }
-  if (!names.includes("message")) throw usageError(`${path} needs a "message" column.`, headers);
+  const ignored = header.map((h, i) => ({ name: h.trim(), known: CSV_COLUMNS.includes(names[i] ?? "") })).filter((c) => !c.known && c.name).map((c) => clip(c.name, 30));
   const items = body.map((row, i) => {
     if (row.length !== names.length) {
       throw usageError(`Line ${lines[i + 1]} of ${path} has ${count(row.length, "cell")}; the header has ${names.length}.`);
@@ -10343,14 +10457,14 @@ function csvList(path, text3) {
     const context = {};
     names.forEach((name, j) => {
       const value = row[j] ?? "";
-      if (!value.trim()) return;
+      if (!CSV_COLUMNS.includes(name) || !value.trim()) return;
       if (name === "facts" || name === "rules") context[name] = perLine(value);
       else item[name] = name === "message" ? value : value.trim();
     });
     if (Object.keys(context).length > 0) item.context = context;
     return item;
   });
-  return { path, kind: "csv", items, header, rows: body, lines: lines.slice(1) };
+  return { path, kind: "csv", items, header, rows: body, ignored, lines: lines.slice(1) };
 }
 function jsonlList(path, text3) {
   const items = [];
@@ -10371,12 +10485,7 @@ function jsonlList(path, text3) {
   return { path, kind: "jsonl", items, lines };
 }
 function readList(path) {
-  let text3;
-  try {
-    text3 = readFileSync6(path, "utf8");
-  } catch (err) {
-    throw usageError(`Could not read ${path}: ${err instanceof Error ? err.message : String(err)}`);
-  }
+  const text3 = readTextFile(path);
   const ext = extname(path).toLowerCase();
   const jsonl = ext === ".jsonl" || ext === ".ndjson" || ext !== ".csv" && text3.trimStart().startsWith("{");
   const list2 = jsonl ? jsonlList(path, text3) : csvList(path, text3);
@@ -10398,6 +10507,10 @@ function withDefaults(items, defaults) {
     return merged;
   });
 }
+function progressKey(batch) {
+  const c = record(batch.counts) ?? {};
+  return ["total", "queued", "running", "done", "failed"].map((k) => typeof c[k] === "number" ? c[k] : 0).join("/");
+}
 function progressLine(batch) {
   const c = record(batch.counts) ?? {};
   const n = (k) => typeof c[k] === "number" ? c[k] : 0;
@@ -10409,7 +10522,7 @@ function progressLine(batch) {
   const left = seconds === null || finished === total ? "" : seconds < 90 ? ", about a minute left" : `, about ${Math.round(seconds / 60)} min left`;
   if (finished === 0 && n("running") === 0) {
     const ahead = typeof batch.queue_position === "number" && batch.queue_position > 0 ? ` behind ${count(batch.queue_position, "item")}` : "";
-    return `Queued${ahead}: 0 of ${total} done${left}`;
+    return `Queued${ahead}${left}`;
   }
   return `${n("done")} of ${total} done${failed}${left}`;
 }
@@ -10417,12 +10530,14 @@ async function waitForBatch(ctx, credential, id, first2) {
   const client = apiClient(ctx, credential);
   const tty = ctx.io.stderrIsTTY && !ctx.out.json;
   let last = "";
+  let lastKey = "";
   const show = (batch2) => {
     const line = progressLine(batch2);
     if (line === last) return;
     last = line;
     if (tty) ctx.io.stderr(`\r\x1B[2K${line}`);
-    else ctx.out.info(line);
+    else if (progressKey(batch2) !== lastKey) ctx.out.info(line);
+    lastKey = progressKey(batch2);
   };
   let batch = first2;
   for (; ; ) {
@@ -10454,13 +10569,22 @@ async function allItems(ctx, credential, id) {
 function neutralise(cell2) {
   return /^[=+\-@\t\r]/.test(cell2) ? `'${cell2}` : cell2;
 }
-var RESULT_COLUMNS = ["optimized_message", "status", "what_changed", "run_id", "error"];
-function resultCells(item) {
+var RESULT_COLUMNS = ["optimized_message", "status", "summary", "run_id", "error"];
+function resultColumnNames(header) {
+  const taken = new Set(header.map((h) => h.trim().toLowerCase()));
+  return RESULT_COLUMNS.map((name) => {
+    let candidate = name;
+    while (taken.has(candidate)) candidate = `amdahl_${candidate}`;
+    taken.add(candidate);
+    return candidate;
+  });
+}
+function resultCells(item, context) {
   const result = record(item?.result);
   if (!item || !result) return ["", field(item?.status) || "missing", "", "", ""];
   if (result.ok === false) return ["", "failed", "", field(result.run_id), `${field(result.reason)}: ${field(result.detail)}`.replace(/: $/, "")];
   const message2 = typeof result.message === "string" ? result.message : "";
-  return [message2, result.unchanged === true ? "unchanged" : "done", field(result.what_changed), field(result.run_id), ""];
+  return [message2, result.unchanged === true ? "unchanged" : "done", truthfulSummary(field(result.summary), context), field(result.run_id), ""];
 }
 function resultsFile(list2, id, cwd) {
   if (list2) return resultsPath(list2.path, list2.kind);
@@ -10469,12 +10593,12 @@ function resultsFile(list2, id, cwd) {
 function assertFree(path, force) {
   if (!force && existsSync5(path)) throw usageError(`${path} already exists.`, "Move it, or add --force to replace it.");
 }
-function writeResults(list2, id, items, cwd, force) {
+function writeResults(list2, id, items, cwd, force, contexts) {
   const byIndex = new Map(items.map((i) => [i.index, i]));
   const path = resultsFile(list2, id, cwd);
   const flag = force ? "w" : "wx";
   if (list2?.kind === "csv" && list2.header && list2.rows) {
-    const rows = [[...list2.header, ...RESULT_COLUMNS], ...list2.rows.map((row, i) => [...row, ...resultCells(byIndex.get(i))])];
+    const rows = [[...list2.header, ...resultColumnNames(list2.header)], ...list2.rows.map((row, i) => [...row, ...resultCells(byIndex.get(i), contexts[i])])];
     writeFileSync4(path, toCsv(rows.map((row) => row.map(neutralise))), { flag });
     return path;
   }
@@ -10500,6 +10624,11 @@ async function optimizeList(ctx, defaults) {
     throw usageError("--batch needs a batch id: a UUID like the one `amdahl optimize --list` printed.");
   }
   const list2 = listPath ? readList(listPath) : null;
+  if (list2?.ignored?.length) {
+    const shown = list2.ignored.slice(0, 6).join(", ");
+    const more = list2.ignored.length > 6 ? ` and ${list2.ignored.length - 6} more` : "";
+    out.info(`Not sent, and copied to the results as they are: ${count(list2.ignored.length, "column")} Amdahl does not read (${shown}${more}).`);
+  }
   if (!resume && list2 && list2.items.length > MAX_BATCH_ITEMS) {
     throw usageError(`A batch takes at most ${MAX_BATCH_ITEMS} messages, and ${list2.path} has ${list2.items.length}.`, "Split the list into files of 500 or fewer, and run each one.");
   }
@@ -10546,10 +10675,13 @@ Get the results: ${pickUp}`);
     out.result({ ...batch, ok: failed === 0, items, next_cursor: null });
     return failed === 0 ? EXIT.ok : EXIT.general;
   }
-  const path = writeResults(list2, id, items, ctx.io.cwd, force);
+  const contexts = list2 ? withDefaults(list2.items, defaults).map((item) => item.context) : [];
+  const path = writeResults(list2, id, items, ctx.io.cwd, force, contexts);
   const done = items.length - failed;
   out.info(`${done} of ${count(items.length, "message")} optimized${failed ? `, ${failed} failed` : ""}.`);
   out.result({}, `Results: ${path}`);
+  const runId2 = items.map((i) => field(record(i.result)?.run_id)).find(Boolean);
+  for (const line of sentLines(runId2, "Sent one?")) out.info(line);
   return failed === 0 ? EXIT.ok : EXIT.general;
 }
 
@@ -10565,11 +10697,12 @@ function oneOf2(flag, value, allowed) {
   return value;
 }
 function readContext(path) {
+  const text3 = readTextFile(path);
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync7(path, "utf8"));
+    parsed = JSON.parse(text3);
   } catch (err) {
-    throw usageError(`Could not read --context ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    throw usageError(`--context ${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw usageError("--context must be a JSON object with rules, voice_examples and facts.");
@@ -10688,7 +10821,6 @@ function whatAmdahlDid(result) {
   const more = whys.length > 1 ? ` (${plural(whys.length - 1, "more reason")} in --json)` : "";
   const leftOut = omitted.length ? `Left out ${plural(omitted.length, "thing")}${whys[0] ? `: ${sentence(whys[0])}` : "."}${more}` : "";
   const lines = [
-    { rank: 2, line: sentence(text2(result.what_changed)) },
     { rank: 5, line: checked },
     { rank: 3, line: removed },
     { rank: 6, line: usedLine },
@@ -10800,7 +10932,7 @@ ${nextTimeLine(ctx)}`);
   out.result({}, String(result.message ?? ""));
   const did = whatAmdahlDid(result);
   const connect2 = tipsOn(ctx) && (saysNoData(result) || await noData) ? [noDataLine()] : [];
-  out.info([...did, ...feedbackLines(ctx, result), ...connect2, nextTimeLine(ctx)].join("\n"));
+  out.info([...did, ...feedbackLines(ctx, result), ...sentLines(result.run_id), ...connect2, nextTimeLine(ctx)].join("\n"));
   return EXIT.ok;
 }
 async function optimize(ctx, args) {
@@ -10826,12 +10958,7 @@ async function optimize(ctx, args) {
   const base = requestOptions(ctx);
   const inputs = [];
   for (const file of files) {
-    let message2;
-    try {
-      message2 = file === "-" ? await io.readStdin() : readFileSync7(file, "utf8");
-    } catch (err) {
-      throw usageError(`Could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const message2 = file === "-" ? await io.readStdin() : readTextFile(file);
     if (!message2.trim()) throw usageError(`${file === "-" ? "Stdin" : file} is empty.`);
     inputs.push({ file, message: message2 });
   }
@@ -10851,9 +10978,9 @@ async function optimize(ctx, args) {
     if (!out.json) {
       if (inputs.length > 1) out.info(`== ${file} ==`);
       if (result.unchanged === true) out.info("No rewrite beat your draft; it is returned unchanged.");
-      else if (typeof result.summary === "string") out.info(result.summary);
+      else if (typeof result.summary === "string" && truthfulSummary(result.summary, base.context)) out.info(truthfulSummary(result.summary, base.context));
       out.result({}, String(result.message ?? ""));
-      const lines = [...whatAmdahlDid(result), ...feedbackLines(ctx, result)];
+      const lines = [...whatAmdahlDid(result), ...feedbackLines(ctx, result), ...sentLines(result.run_id)];
       if (lines.length) out.info(lines.join("\n"));
     }
   }
@@ -11005,13 +11132,16 @@ var RESEARCH_TIMEOUT_MS = 15 * 6e4;
 var ROWS_UNDER_ANSWER = 5;
 var ROWS_ALONE = 10;
 function researchKeyLine() {
-  return `A deeper answer needs a Customer agent key: ${amdahlCommand("keys create --name research --preset agent")}`;
+  return `Research needs a Customer agent key: ${amdahlCommand("keys create --name research --preset agent")}`;
+}
+function researchKeyFirst() {
+  return `${researchKeyLine()}. Here is the search answer instead.`;
 }
 var SETTLED = /* @__PURE__ */ new Set(["complete", "failed", "canceled", "needs_input"]);
 var TITLE_FIELDS = ["title", "call_title", "meeting_title", "subject", "deal_name", "account_name", "company_name", "name"];
 var DATE_FIELDS = ["occurred_at", "started_at", "date", "call_date", "call_timestamp", "close_date", "created_at", "updated_at"];
-var TEXT_FIELDS = ["text", "quote", "snippet", "excerpt", "content", "summary", "body", "description"];
-var WHO_FIELDS = ["speaker", "speaker_name", "account_name", "company_name", "owner_name", "deal_stage_label"];
+var TEXT_FIELDS = ["content_preview", "text", "quote", "snippet", "excerpt", "content", "summary", "body", "description"];
+var WHO_FIELDS = ["speaker", "speaker_name", "account_name", "company_name", "owner_name", "deal_stage_label", "speaker_type"];
 var AMOUNT_FIELDS = ["deal_amount", "amount"];
 function first(row, names) {
   for (const name of names) {
@@ -11039,15 +11169,24 @@ function rowLines(row, n) {
 function rowsOf(result) {
   return records(result.results);
 }
+function noAnswerLines(status2, rows) {
+  if (rows === 0) return [];
+  if (status2 === "not_enough_data") {
+    return [...wrap(`Amdahl couldn't answer that from these rows. Try rephrasing the question, or run ${amdahlCommand("connections")} to see whether your data is synced.`), ""];
+  }
+  if (status2 === "failed") return [...wrap(`Amdahl found rows but couldn't write an answer this time. Here are the rows. Try again, or rephrase the question.`), ""];
+  return [];
+}
 function searchLines(result) {
   const lines = [];
   const rows = rowsOf(result);
   const answer = record(result.answer);
   const answered = answer?.status === "answered" && paragraphs(answer.text);
   if (answered) lines.push(...wrap(plainMarkdown(answered)), "");
+  else lines.push(...noAnswerLines(field(answer?.status), rows.length));
   const shown = rows.slice(0, answered ? ROWS_UNDER_ANSWER : ROWS_ALONE);
   if (shown.length > 0) {
-    if (answered) lines.push("From:");
+    if (answered || lines.length > 0) lines.push(answered ? "From:" : "Rows it read:");
     shown.forEach((row, i) => lines.push(...rowLines(row, i + 1)));
     if (rows.length > shown.length) lines.push(`And ${count(rows.length - shown.length, "more row")} (all of them: add --json).`);
   } else if (!answered) {
@@ -11126,13 +11265,12 @@ async function search(ctx, args) {
     out.result({}, [...wrap(field(setup2.message) || "This workspace has no data connected yet."), connectLine()].join("\n"));
     return EXIT.ok;
   }
-  const lines = searchLines(result);
-  out.result({}, lines.join("\n"));
-  if (refusedForScope(notes)) out.info(researchKeyLine());
+  if (refusedForScope(notes)) out.info(wrap(researchKeyFirst()).join("\n"));
   else {
     const refused = notes.find((n) => /ran search instead/i.test(n));
     if (refused) out.info(wrap(refused).join("\n"));
   }
+  out.result({}, searchLines(result).join("\n"));
   return EXIT.ok;
 }
 function printResearch(ctx, search2, job) {
@@ -12112,6 +12250,262 @@ async function workspaceUse(ctx, args) {
   return EXIT.ok;
 }
 
+// src/help.ts
+var GLOBAL = `
+Global options: --profile, --api-url, --api-key, --json, --no-color, --verbose.
+Run \`amdahl --help\` for what each does.
+`;
+var HELP = {
+  setup: `Usage: amdahl [setup] [--no-browser]
+
+The guided setup. In a terminal it asks where Amdahl should work: Claude Code,
+Cursor, Codex or this terminal. Run by an agent, or with no terminal, it sets
+up that agent (or every client it finds) and asks nothing.
+
+  --no-browser   Print the sign-in link instead of opening a browser.
+`,
+  login: `Usage: amdahl login [--workspace <slug>] [--no-browser] [--port <n>]
+
+Sign in through the browser with your console account. Also: amdahl auth login.
+
+  --workspace <slug>   Sign in to this workspace.
+  --no-browser         Print the sign-in link instead of opening a browser.
+  --port <n>           Listen for the browser's answer on this local port.
+`,
+  logout: `Usage: amdahl logout [--all]
+
+Sign out and forget the sign-in on this machine. Also: amdahl auth logout.
+
+  --all   Sign out of every saved profile, not just the current one.
+`,
+  whoami: `Usage: amdahl whoami [--show-token]
+
+Show who you are: the account, workspace, role and which credential won. Also:
+amdahl auth status.
+
+  --show-token   Print the full access token, not its first characters.
+`,
+  "auth token": `Usage: amdahl auth token
+
+Print a fresh access token from your sign-in. It needs your own sign-in: a key
+in AMDAHL_KEY or --api-key wins over it, and then this exits 4.
+`,
+  status: `Usage: amdahl status
+
+Can this workspace optimize, and what blocks it. It shows your role, the
+monthly optimize quota and any connection that needs attention. Each blocked
+item names its fix: the command, the console page, or who to ask.
+
+With --json it prints the server's setup status as one object.
+`,
+  optimize: `Usage: amdahl optimize [<file>... | -] [--channel email|linkedin]
+                       [--evidence off|workspace] [--on-unsupported flag|remove]
+                       [--tries] [--context <file.json>]
+       amdahl optimize --list <file.csv|file.jsonl> [--no-wait] [--force]
+       amdahl optimize --batch <id> [--list <file>] [--force]
+
+Rewrite an outbound email or LinkedIn message. Each file is one message; "-"
+reads standard input. With no file, at a terminal, paste the message.
+
+  --channel email|linkedin     What the message is. Left out, it is inferred.
+  --evidence off|workspace     "workspace" also evaluates each claim against
+                               your customers' own conversations. Slower.
+  --on-unsupported flag|remove What to do with a claim nothing backs.
+  --tries                      Also show every version the run scored.
+  --context <file.json>        Your rules, voice_examples and facts, as JSON.
+  --list <file>                Rewrite a whole list in one batch: a CSV with a
+                               message column (it may also have item_id,
+                               channel, evidence, on_unsupported, facts and
+                               rules; any other column is copied to the
+                               results) or a JSONL file, one item per line.
+                               Up to 500 messages. The results go next to the
+                               list: drafts.csv gets drafts.optimized.csv.
+  --no-wait                    With --list: queue the batch and print its id.
+  --batch <id>                 Pick up a batch queued earlier. With --list, the
+                               same list; the results go next to it.
+  --force                      Replace a results file that already exists.
+
+In the results CSV, a cell that starts with =, +, - or @ gets a ' in front, so
+a spreadsheet does not run it as a formula. That includes a phone number such
+as +1 555 0100 or a negative number you copied through. Delete the ' to use it.
+
+Output: the rewrite goes to stdout. What Amdahl did, and the run id, go to
+stderr. With --json it prints {"ok", "file", "result"}: the rewritten message
+is .result.message and the run id is .result.run_id. Several files give an
+array of those. A list prints the batch, and each item's result, with --json.
+Exit 1 when a message could not be rewritten.
+${GLOBAL}`,
+  search: `Usage: amdahl search "<question>" [--research] [--limit <n>]
+
+Ask a question about your customers, calls and deals. It prints a short answer
+with the rows it came from.
+
+  --research    Start a research job: a deeper, cited answer. It needs a
+                Customer agent key (amdahl keys create --preset agent). With a
+                sign-in you get the search answer and a line that says so.
+  --limit <n>   Ask for at most n rows.
+
+With --json it prints the server's whole answer, every row included.
+${GLOBAL}`,
+  connections: `Usage: amdahl connections [--all]
+
+List the sources this workspace has connected, with each one's health and last
+sync. A source that needs attention gets a link to its console page.
+
+  --all   Also list disconnected and never-synced sources.
+`,
+  connect: `Usage: amdahl connect [<connector>] [--no-browser]
+
+Open the console's add page. The connector only fills its search box: you pick
+it there and sign in to that tool. If that connector is already connected and
+healthy, this says so and prints the page instead of opening it. The CLI never
+creates a connection itself.
+
+  --no-browser   Print the link instead of opening a browser. It also prints
+                 under --json, for an agent, in CI, and when stdin or stdout
+                 is not a terminal.
+`,
+  open: `Usage: amdahl open [--no-browser]
+
+Open this workspace in the console.
+
+  --no-browser   Print the link instead of opening a browser.
+`,
+  feedback: `Usage: amdahl feedback <run-id> --evidence did_it_myself|reported_to_me|inferred
+                       [--outcome used|used_with_edits|not_used|unsure]
+                       [--sent-text <file> | -] [--comment <text>]
+
+Say what happened to the message an optimize run returned. The run id is the
+one \`amdahl optimize\` printed. Amdahl learns your preferences from an edit,
+unless the evidence is "inferred". Each call stores one event.
+
+  --evidence <how>   How you know. Required.
+  --outcome <what>   What happened to it.
+  --sent-text <file> The text as sent (a file, or - for standard input).
+  --comment <text>   Your own words about it.
+
+Give at least one of --outcome, --sent-text and --comment.
+${GLOBAL}`,
+  sent: `Usage: amdahl sent <run-id> --provider <provider> --channel <channel>
+                   --sent-as returned|edited [--sent-at <time>]
+                   [--provider-send-id <id>]
+                   [--recipient <email|url> | --recipient-key-hash <sha256>]
+                   [--provider-campaign-id <id>] [--sequence-step <n>]
+                   [--provider-variant-id <id>] [--provider-lead-id <id>]
+                   [--thread-id <id>] [--sent-text <file> | -]
+
+Report that the system that sent a message sent it. One send per command; the
+API takes up to 100 (POST /messages/report_send).
+
+  --provider <name>   ${SEND_PROVIDERS.slice(0, 4).join(", ")},
+                      ${SEND_PROVIDERS.slice(4, 8).join(", ")},
+                      ${SEND_PROVIDERS.slice(8).join(", ")}.
+                      A sender not on the list: use "other".
+  --channel <kind>    email, linkedin (the same as linkedin_message),
+                      linkedin_invite, linkedin_message or linkedin_inmail.
+  --sent-as <how>     returned (as Amdahl returned it) or edited. An edit needs
+                      --sent-text: the message as you sent it.
+  --sent-at <time>    A time with a zone, like 2026-11-12T09:30:00Z. Default:
+                      now.
+  --provider-send-id  The provider's own id for the send. For gmail, the
+                      Message-ID header with its angle brackets.
+  --recipient         An email address, or a LinkedIn profile URL for a LinkedIn
+                      channel. Amdahl stores only a hash of it.
+  --recipient-key-hash  A SHA-256 you made, instead of --recipient (not both).
+  --provider-campaign-id, --sequence-step, --provider-variant-id,
+  --provider-lead-id, --thread-id   The provider's ids, when you have them.
+  --sent-text <file>  The text as sent (a file, or - for standard input). Only
+                      a hash of it is kept.
+
+Give at least one of --provider-send-id and a recipient (--recipient or
+--recipient-key-hash, not both). A send id with a recipient is fine: Amdahl
+matches a report to a send by the id, the recipient, or both.
+${GLOBAL}`,
+  "keys create": `Usage: amdahl keys create --name <name>
+                          [--preset read-only|agent|internal|admin]
+                          [--expires 30d|90d|365d] [--no-browser]
+
+Make an API key for a server or CI. You approve it in the console, then the key
+is printed once. It needs your own sign-in.
+
+  --name <name>    What to call the key. Required.
+  --preset <kind>  read-only (default), agent (reads, optimize and research),
+                   internal or admin (workspace admins only).
+  --expires <days> 30d, 90d (default) or 365d.
+  --no-browser     Print the approval link instead of opening a browser.
+`,
+  "keys list": `Usage: amdahl keys list
+
+List the workspace's keys, without their secrets. It needs your own sign-in.
+`,
+  "keys revoke": `Usage: amdahl keys revoke <id|prefix> [--yes] [--no-browser]
+
+Revoke a key. You type the key's name, then approve in the console. It needs
+your own sign-in.
+
+  --yes          Skip the question that asks you to type the name.
+  --no-browser   Print the approval link instead of opening a browser.
+`,
+  "workspace list": `Usage: amdahl workspace list
+
+List your saved sign-ins (profiles). One sign-in is one workspace.
+`,
+  "workspace use": `Usage: amdahl workspace use <profile>
+
+Make a saved profile the default.
+`,
+  install: `Usage: amdahl install claude-code|codex|cursor [--print] [--force]
+
+Add the Amdahl MCP server and the Amdahl skill to one AI client. It writes no
+key or token: the client signs in itself the first time it connects.
+
+  --print   Show what it would change, and change nothing.
+  --force   Replace a skill file you have edited.
+`,
+  "skills add": `Usage: amdahl skills add <publisher>/<skill> [-y] [-g] [--agents] [--force]
+                          [--accept-warning] [--site <origin>]
+
+Add a skill from https://amdahl.ai/skills to this project. It needs no sign-in.
+In a terminal it asks where to install it.
+
+  -y, --yes          Add it to this project without asking.
+  -g, --global       Add it for every project (~/.claude/skills).
+  --agents           Also write .agents/skills, for Codex, Cursor and others.
+  --force            Replace a different copy that is already there.
+  --accept-warning   Install a skill amdahl.ai's security review flagged,
+                     after printing the warning. Without it, -y, --json or no
+                     terminal stops (exit 9).
+  --site <origin>    Read from another origin (https, or http for localhost).
+`,
+  help: `Usage: amdahl help [<command>]
+
+Show the help for one command, or all of them. Also: amdahl <command> --help.
+`
+};
+var GROUPS = {
+  keys: ["keys create", "keys list", "keys revoke"],
+  auth: ["login", "logout", "whoami", "auth token"],
+  workspace: ["workspace list", "workspace use"],
+  skills: ["skills add"]
+};
+var ALIASES2 = { "auth login": "login", "auth logout": "logout", "auth status": "whoami" };
+var HELP_COMMANDS = Object.keys(HELP);
+function commandHelp(words) {
+  const key = ALIASES2[words.join(" ")] ?? words.join(" ");
+  const text3 = HELP[key];
+  if (text3) return text3;
+  const group = words.length === 1 ? GROUPS[words[0] ?? ""] : void 0;
+  if (!group) return null;
+  const lines = group.map((name) => `  ${amdahlCommand(name)}`);
+  return `Usage: amdahl ${words[0]} <command>
+
+Commands:
+${lines.join("\n")}
+
+Run \`amdahl ${words[0]} <command> --help\` for one command.
+`;
+}
+
 // src/main.ts
 var COMMANDS = {
   login: (ctx) => login(ctx),
@@ -12134,13 +12528,25 @@ var COMMANDS = {
   install,
   "skills add": skillsAdd
 };
+function helpFor(words) {
+  return commandHelp(words.slice(0, 2)) ?? commandHelp(words.slice(0, 1)) ?? USAGE;
+}
 var NO_ARGS = /* @__PURE__ */ new Set(["setup", "login", "logout", "whoami", "auth token", "status", "connections", "open", "keys create", "keys list", "workspace list"]);
 async function runCli(argv, io) {
   setCommandName(io);
   const json = argv.includes("--json");
   let out = createOutput(io, json, argv.includes("--no-color"));
   try {
-    const parsed = parseCommandLine(argv);
+    let parsed;
+    try {
+      parsed = parseCommandLine(argv);
+    } catch (err) {
+      if (argv.includes("--help") || argv.includes("-h")) {
+        io.stdout(helpFor(helpWords(argv)));
+        return EXIT.ok;
+      }
+      throw err;
+    }
     out = createOutput(io, parsed.flags.json === true, parsed.flags["no-color"] === true);
     if (parsed.flags.version) {
       io.stdout(`${VERSION}
@@ -12148,7 +12554,7 @@ async function runCli(argv, io) {
       return EXIT.ok;
     }
     if (parsed.flags.help || parsed.command === "help") {
-      io.stdout(USAGE);
+      io.stdout(helpFor(parsed.command === "help" ? parsed.args : parsed.command?.split(" ") ?? []));
       return EXIT.ok;
     }
     if (NO_ARGS.has(parsed.command ?? "") && parsed.args.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amdahl/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "The amdahl command line: sign in, check setup, optimize messages, manage API keys, connect MCP clients.",
   "license": "Apache-2.0",