@syntax-syllogism/sfd 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -14,6 +14,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   named pipe, finds `sf` with `where` (including npm `sf.cmd` shims), and
   starts without a console window. CI runs on Windows as well as Linux.
 
+## [0.4.0] - 2026-10-22
+
+### Added
+
+- `--limit` and `--csv` options for `sfd query`, with CSV output
+- `sfd agents-snippet` command that generates a snippet for AGENTS.md and CLAUDE.md
+- `sfd org list` command that lists locally authenticated orgs, with optional status checks
+- `sfd list-metadata-types` and `sfd list-metadata` commands for browsing org metadata
+- `sfd discover` command that reports missed opportunities to use `sfd` in place of `sf`
+
 ## [0.3.1] - 2026-10-22
 
 ### Changed

package/README.md

@@ -24,9 +24,11 @@ sfd query "SELECT Id, Name FROM Account LIMIT 5" -o my-org
 
 | Command | Does | `sf` equivalent |
 | --- | --- | --- |
-| `sfd query "<soql>"` | SOQL, all pages, `attributes` stripped. `--tooling`, `--all`, `--raw` for the unstripped result | `sf data query` |
+| `sfd query "<soql>"` | SOQL, all pages by default, `attributes` stripped. `--limit <n>` caps rows; `--csv` prints CSV. `--tooling`, `--all`, `--raw` for the unstripped result | `sf data query` |
 | `sfd apex [file]` | Anonymous Apex from a file, `-f`, or stdin. Prints `USER_DEBUG` and fatal lines; `--log` for the full log | `sf apex run` |
 | `sfd rest <path>` | REST call. `-X <method>`, `--body <json\|@file>` | `sf api request rest` |
+| `sfd list-metadata-types` | Supported metadata types, folder markers and child types; cached per org and API version | `sf org list metadata-types` |
+| `sfd list-metadata -m <Type>[,<Type>…]` | Live member names; `--details` for audit fields, `--folder <name>` for folder contents | `sf org list metadata` |
 | `sfd describe <sobject>` | Compact describe; `--raw` for the full one. `--tooling` | `sf sobject describe` |
 | `sfd deploy -d <path> \| -m <Type[:Name]>` | Deploy source. `--check-only`, `-l <level>`, `-t <test>`, `-w <minutes>` | `sf project deploy start` |
 | `sfd retrieve [-d <path> \| -m <Type[:Name]> \| -x <package.xml>]` | Retrieve source; no selector pulls tracked remote changes. `--ignore-conflicts`, `-w <minutes>` | `sf project retrieve start` |
@@ -34,15 +36,64 @@ sfd query "SELECT Id, Name FROM Account LIMIT 5" -o my-org
 | `sfd test` | Run Apex tests. `-n <class>`, `-t <Class.method>`, `-s <suite>`, `-l <level>`, `-c` (coverage), `-w <minutes>`, `--logs` | `sf apex run test --wait` |
 | `sfd logs [--count 10] [--user <username>]` | Recent debug logs, one line each; `--limit` aliases `--count` | `sf apex list log` |
 | `sfd logs get <id\|latest>` | Debug, exception, validation, Flow error and high limit usage lines. `--full` prints raw text | `sf apex get log` |
+| `sfd org list [--all] [--status]` | Local authenticated orgs; `--all` includes expired scratch orgs, `--status` adds live checks | `sf org list --skip-connection-status` |
 | `sfd org` | Resolved username, org id, instance URL and API version | `sf org display` |
 | `sfd hook <agent>`, `check`, `install`, `uninstall` | Agent integration: rewrite `sf` commands before an agent runs them. See [docs/agent-hooks.md](docs/agent-hooks.md) | |
+| `sfd agents-snippet [--write [file]]` | Print agent instructions, or write them into `AGENTS.md` or `CLAUDE.md`. See [Using sfd with coding agents](#using-sfd-with-coding-agents) | |
+| `sfd discover [--since 30d]` | Report missed sfd opportunities and adoption from local agent transcripts. See [docs/discover.md](docs/discover.md) | |
 | `sfd start \| stop \| status \| reload` | Daemon lifecycle; `reload` drops cached orgs and auth state | |
 
+For agents, `--csv --limit 200` is the cheapest way to read rows. The limit,
+CSV layout, output by flag and truncation trailer are described in
+[docs/query.md](docs/query.md).
+
 `-d`, `-m`, `-n`, `-t` and `-s` repeat or take comma-separated lists. The org
-commands take `-o <alias>`, and `--json` prints the raw daemon response. Without `-o`
+commands take `-o <alias>` (except `org list`), and `--json` prints the raw daemon response. Without `-o`
 the org resolves like `sf`: `SF_TARGET_ORG`, then the nearest
 `.sf/config.json`, then the global config.
 
+`sfd list-metadata-types` sorts supported types, marks folder-based types with
+`(folder)` and shows up to six child names. Its daemon cache is scoped to the org
+and connection API version, and cleared by `sfd reload`, auth changes or session
+reconnection. `--json` includes `result.cached` and `result.apiVersion`.
+
+`sfd list-metadata -m Flow,Layout` lists sorted names grouped by requested type.
+Repeat `-m` to add types. `--details` adds the modification date, modifying user,
+namespace and manageable state, omitting empty fields. Member lists are always
+live; empty groups print `(none)`. Unknown types exit 2 with a suggestion when
+available. Listings have the coverage and limits of the Metadata API
+`listMetadata` operation; they do not enumerate special cases separately.
+
+For folder-based types, omitting `--folder` lists folders with a hint. Choose a
+folder to list its members; `--folder` accepts exactly one metadata type:
+
+```bash
+sfd list-metadata -m Report
+sfd list-metadata -m Report --folder Public_Reports
+sfd list-metadata -m ApexClass --details
+```
+
+`sfd org list` reads local auth without network calls. It shows aliases, usernames,
+`*` for the default org, `H` for the default Dev Hub, org types and scratch expiry.
+Expired scratch orgs are hidden with a count hint; use `--all` to include them.
+`--status` checks non-scratch connections in parallel with a 10-second deadline
+per org, and queries scratch status once per Dev Hub (also bounded to 10 seconds).
+Unavailable Dev Hubs leave scratch status blank. New logins and logouts are picked
+up automatically. This command rejects `-o`.
+
+```bash
+sfd org list
+sfd org list --all --status
+sfd org list --json
+```
+
+For `org list`, `--json` returns `{ "orgs": [...] }` directly, with alias,
+username, orgId, instanceUrl, type, isDefault, isDefaultDevHub, and optional
+expirationDate, expired and status. The command never includes access tokens,
+refresh tokens or client secrets in any output, including `--json`. Primary-user
+filtering, status checks and the JSON allowlist are described in
+[docs/org-list.md](docs/org-list.md).
+
 Exit codes: `0` success, `1` the operation failed (including a compile error,
 a failed deploy, or a failing test), `2` usage error, `3` the daemon could
 not be reached or started, or a request timed out. Unreadable input files are
@@ -81,8 +132,9 @@ it down even if its protocol differs.
 
 ## Behavior notes
 
-- Queries fetch every page without a record cap. Compact results preserve
-  `done` and any continuation URL supplied by Salesforce.
+- Queries fetch every page unless `--limit` is given. Compact results preserve
+  `done` and any continuation URL supplied by Salesforce; see
+  [docs/query.md](docs/query.md) for the limit rules.
 - Deploys, retrieves and `tracking` share one queue per daemon, so they run
   one at a time. Deploys reload `sfdx-project.json` on every call.
 - Retrieve conflicts, changes-only retrieves, and how `tracking` and deploys
@@ -158,6 +210,46 @@ sfd hook install --agent gemini
 ```
 
 Add `--project` to install into the current project instead. Preview a rewrite
-with `sfd hook check '<sf command>'`. The supported commands, adapter details,
-skip rules and the `SFD_HOOK_DISABLE=1` switch are in
+with `sfd hook check '<sf command>'`. Query result format `-r csv` (or
+`--result-format csv`) maps to `sfd query --csv`. The supported commands,
+adapter details, skip rules and the `SFD_HOOK_DISABLE=1` switch are in
 [docs/agent-hooks.md](docs/agent-hooks.md).
+
+## Using sfd with coding agents
+
+`sfd discover` scans local Claude Code, Codex CLI and Gemini CLI transcripts for
+shell tool calls using `sf`, legacy `sfdx`, or `sfd`. It uses the hook's rewrite
+engine to report rewritable calls, skip reasons, unsupported commands and adoption.
+It reads local files only, without an org, daemon, network calls or writes.
+
+```bash
+sfd discover
+sfd discover --since 12h --agent claude --agent codex --project /path/to/project
+sfd discover --top 5 --json
+```
+
+`--since` takes days (`d`) or hours (`h`), default `30d`. `--agent` is repeatable,
+and all three agents are scanned by default. Time and output-token savings are
+estimates from observed timings and output sizes; they are never extrapolated.
+The stores read, how each call is classified, the JSON shape and the limits are
+described in [docs/discover.md](docs/discover.md).
+
+The agent reference includes metadata type discovery and member listing alongside
+query, source and log operations. Print a compact command reference with
+`sfd agents-snippet`, or add it to your project's agent instructions:
+
+```bash
+sfd agents-snippet --write
+sfd agents-snippet --write docs/CLAUDE.md
+```
+
+`--write` uses the first existing `AGENTS.md` or `CLAUDE.md` in the Salesforce
+project root (or the current directory outside a project), creating `AGENTS.md`
+if neither exists. Explicit paths resolve from the current directory. Only the
+block between `<!-- sfd:start -->` and `<!-- sfd:end -->` is replaced on later
+runs; other instructions are preserved. This command needs no org or daemon.
+The block's contents and marker rules are described in
+[docs/agents-snippet.md](docs/agents-snippet.md).
+
+For automatic command rewriting, install a hook with
+`sfd hook install --agent <agent>` (see [Agent integration](#agent-integration)).

package/bin/sfd.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { call, isRunning, startDaemon, DaemonError, VERSION } from "../src/client.mjs";
 import { findProjectDir, resolveTargetOrg } from "../src/project.mjs";
-import { formatApex, formatLog, formatLogList, formatDeploy, formatTests, formatRetrieve, formatTracking } from "../src/format.mjs";
+import { formatMetadataTypes, formatMetadataList, formatOrgList, formatApex, formatLog, formatLogList, formatDeploy, formatTests, formatRetrieve, formatTracking, toCsv } from "../src/format.mjs";
 import { paths } from "../src/paths.mjs";
+import { commandHelp } from "../src/commands.mjs";
+import { snippet, upsertSnippet } from "../src/snippet.mjs";
 import { UsageError } from "../src/usage-error.mjs";
 
 const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm local daemon
@@ -13,24 +15,7 @@ const USAGE = `sfd ${VERSION}: fast Salesforce CLI operations through a warm loc
 Usage: sfd <command> [options]
 
 Commands:
-  query <soql>          Run SOQL (all pages). --tooling, --all (include deleted)
-  apex [file]           Run anonymous Apex from a file, -f <file>, or stdin. --log for the full debug log
-  rest <path>           Call a REST path, e.g. /services/data/v67.0/limits. -X <method>, --body <json|@file>
-  describe <sobject>    Compact describe. --tooling, --raw for the full describe
-  deploy                Deploy source. -d <path> (repeatable), -m <Type[:Name]> (repeatable),
-                        --check-only, -l <test level>, -t <test> (repeatable), -w <minutes>
-  retrieve              Retrieve source. -d <path>, -m <Type[:Name]> or -x <package.xml>,
-                        -w <minutes>, --ignore-conflicts. No selector pulls tracked remote changes
-  tracking              Show source-tracked changes. --local | --remote, --conflicts (conflicts only)
-  test                  Run Apex tests. -n <class> (repeatable), -t <Class.method> (repeatable),
-                        -s <suite> (repeatable), -l <test level>, -c (coverage), -w <minutes>, --logs, --no-trace
-  logs                  List recent debug logs. --count/--limit <10>, --user <username>, --no-trace
-  logs get <id|latest>  Print a filtered log. --full for raw text, --no-trace
-  org                   Show the resolved org (username, id, instance, API version)
-  hook <agent|check|install|uninstall>
-                        Integrate with Claude Code, Codex CLI or Gemini CLI
-  start | stop | status | reload
-                        Manage the daemon. reload drops cached orgs and auth state
+${commandHelp()}
 
 Common options:
   -o, --target-org <alias>  Org alias or username (default: sf target-org config)
@@ -41,10 +26,15 @@ Exit codes: 0 success, 1 operation failed, 2 usage error, 3 daemon error.`;
 
 const options = {
   "target-org": { type: "string", short: "o" },
+  write: { type: "boolean" },
   json: { type: "boolean" },
   help: { type: "boolean", short: "h" },
+  folder: { type: "string" },
+  details: { type: "boolean" },
   tooling: { type: "boolean" },
+  status: { type: "boolean" },
   all: { type: "boolean" },
+  csv: { type: "boolean" },
   raw: { type: "boolean" },
   log: { type: "boolean" },
   logs: { type: "boolean" },
@@ -98,6 +88,13 @@ function wait(values) {
   return minutes;
 }
 
+function queryLimit(value) {
+  if (value === undefined) return undefined;
+  const limit = Number(value);
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new UsageError("--limit must be a positive integer.");
+  return limit;
+}
+
 function print(value) {
   process.stdout.write((typeof value === "string" ? value : JSON.stringify(value, null, 2)) + "\n");
 }
@@ -107,6 +104,19 @@ async function run(argv) {
     const { runHook } = await import("../src/hooks.mjs");
     return runHook(argv.slice(1));
   }
+  if (argv[0] === "discover") {
+    const { values, positionals } = parseArgs({ args: argv.slice(1), options: {
+      since: { type: "string" }, agent: { type: "string", multiple: true },
+      project: { type: "string" }, top: { type: "string" }, json: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }, allowPositionals: true });
+    if (values.help) { print("sfd discover [--since 30d] [--agent claude|codex|gemini]… [--project <path>] [--top 10] [--json]"); return 0; }
+    if (positionals.length) throw new UsageError("discover does not accept positional arguments.");
+    const { discover, discoverOptions, formatReport } = await import("../src/discover/index.mjs");
+    const report = await discover(discoverOptions(values));
+    print(values.json ? report : formatReport(report));
+    return 0;
+  }
   const { values, positionals } = parseArgs({ args: argv, options, allowPositionals: true });
   let [command, ...rest] = positionals;
   if (values.help || !command) { print(USAGE); return 0; }
@@ -119,6 +129,32 @@ async function run(argv) {
     return dir;
   };
 
+  if (command === "agents-snippet") {
+    if (rest.length > 1 || (rest.length && !values.write)) {
+      throw new UsageError("agents-snippet accepts --write [file].");
+    }
+    const block = snippet();
+    if (!values.write) { print(block); return 0; }
+    const root = findProjectDir(cwd) ?? cwd;
+    const file = rest[0] ?? ["AGENTS.md", "CLAUDE.md"].find(name => existsSync(resolve(root, name))) ?? "AGENTS.md";
+    const target = resolve(rest[0] ? cwd : root, file);
+    let original;
+    try { original = readFileSync(target, "utf8"); }
+    catch (e) {
+      if (e.code !== "ENOENT") throw new UsageError(`Cannot read target file ${target}: ${e.message}`);
+    }
+    let updated;
+    try { updated = upsertSnippet(original ?? "", block); }
+    catch (e) { throw new UsageError(`Malformed sfd block in ${file}: ${e.message}`); }
+    if (updated === original) print(`${file} already up to date`);
+    else {
+      try { writeFileSync(target, updated); }
+      catch (e) { throw new UsageError(`Cannot write target file ${target}: ${e.message}`); }
+      print(`${original === undefined ? "Created" : "Updated"} ${file}`);
+    }
+    return 0;
+  }
+
   // Lifecycle commands.
   switch (command) {
     case "start":
@@ -153,7 +189,9 @@ async function run(argv) {
     case "query": {
       const q = rest.join(" ") || readStdin().trim();
       if (!q) throw new UsageError("query needs a SOQL string.");
-      req = { org: org(), q, tooling: values.tooling, all: values.all, raw: values.raw };
+      const limit = queryLimit(values.limit);
+      req = { org: org(), q, tooling: values.tooling, all: values.all, raw: values.raw, limit };
+      if (values.csv) render = result => toCsv(result.records);
       break;
     }
     case "apex": {
@@ -175,6 +213,20 @@ async function run(argv) {
       req = { org: org(), sobject: rest[0], tooling: values.tooling, raw: values.raw };
       break;
     }
+    case "list-metadata-types":
+      command = "listMetadataTypes";
+      req = { org: org() };
+      render = formatMetadataTypes;
+      break;
+    case "list-metadata": {
+      const types = [...new Set(split(values.metadata) ?? [])];
+      if (!types.length) throw new UsageError("list-metadata needs -m <Type>.");
+      if (values.folder !== undefined && types.length > 1) throw new UsageError("--folder requires exactly one metadata type.");
+      command = "listMetadata";
+      req = { org: org(), types, folder: values.folder };
+      render = result => formatMetadataList(result, { details: values.details });
+      break;
+    }
     case "deploy": {
       const dir = projectDir();
       const sourcePaths = split(values["source-dir"])?.map(d => resolve(cwd, d));
@@ -232,7 +284,14 @@ async function run(argv) {
       render = result => formatTests(result, req.org);
       break;
     case "org":
-      req = { org: org() };
+      if (rest[0] === "list") {
+        if (rest.length !== 1 || values["target-org"] !== undefined) throw new UsageError("org list accepts no target org or additional arguments.");
+        command = "orgList";
+        req = { all: values.all, status: values.status };
+        render = formatOrgList;
+      } else {
+        req = { org: org() };
+      }
       break;
     default:
       throw new UsageError(`Unknown command: ${command}. Run sfd --help.`);
@@ -243,12 +302,18 @@ async function run(argv) {
   if (trace) {
     process.stderr.write(`sfd: enabled debug logging for ${trace.username} until ${trace.expires} (TraceFlag ${trace.id})\n`);
   }
-  if (values.json) { print(res); return res.status === 0 ? okStatus(command, res.result) : res.name === "UsageError" ? 2 : 1; }
+  if (values.json) { print(command === "orgList" && res.status === 0 ? { orgs: res.result.orgs } : res); return res.status === 0 ? okStatus(command, res.result) : res.name === "UsageError" ? 2 : 1; }
   if (res.status !== 0) {
     process.stderr.write(`${res.name}: ${res.message}\n`);
     return res.name === "UsageError" ? 2 : 1;
   }
-  print(render(res.result));
+  const output = render(res.result);
+  if (command !== "query" || !values.csv || output) print(output);
+  if (command === "query" && res.result.truncated) {
+    const { totalSize, records } = res.result;
+    const trailer = `… ${(totalSize - records.length).toLocaleString("en-US")} more rows not shown (totalSize ${totalSize.toLocaleString("en-US")}); raise --limit or narrow the query\n`;
+    (values.csv ? process.stderr : process.stdout).write(trailer);
+  }
   return okStatus(command, res.result);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/sfd",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Warm Salesforce CLI daemon: SOQL, anonymous Apex, REST, describe, deploy, and Apex tests without sf startup cost.",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -0,0 +1,132 @@
+export const COMMANDS = [
+  {
+    "name": "query",
+    "args": "<soql>",
+    "summary": "Run SOQL (all pages). --tooling, --all (include deleted), --limit <n>, --csv",
+    "agentTip": "\"<soql>\" --csv --limit 200: SOQL; --tooling, --all"
+  },
+  {
+    "name": "apex",
+    "args": "[file]",
+    "summary": "Run anonymous Apex from a file, -f <file>, or stdin. --log for the full debug log",
+    "agentTip": "-f <file> (or stdin): anonymous Apex; debug and fatal lines"
+  },
+  {
+    "name": "rest",
+    "args": "<path>",
+    "summary": "Call a REST path, e.g. /services/data/v67.0/limits. -X <method>, --body <json|@file>",
+    "agentTip": "<path>: REST; -X <method>, --body <json|@file>"
+  },
+  {
+    "name": "describe",
+    "args": "<sobject>",
+    "summary": "Compact describe. --tooling, --raw for the full describe",
+    "agentTip": "<sobject>: compact describe; --tooling, --raw",
+    "agentGroup": "describe"
+  },
+  {
+    "name": "list-metadata-types",
+    "args": "",
+    "summary": "List supported metadata types (cached per org and API version)",
+    "agentTip": ": supported metadata types (cached)",
+    "agentGroup": "describe"
+  },
+  {
+    "name": "list-metadata",
+    "args": "-m <Type>[,<Type>…]",
+    "summary": "List metadata names. -m repeatable, --folder <name>, --details for audit fields",
+    "agentTip": "-m <Type>: metadata names; --folder <name>, --details",
+    "agentGroup": "describe"
+  },
+  {
+    "name": "deploy",
+    "args": "",
+    "summary": "Deploy source. -d <path> (repeatable), -m <Type[:Name]> (repeatable),\n--check-only, -l <test level>, -t <test> (repeatable), -w <minutes>",
+    "agentTip": "-d <path> | -m <Type:Name>: deploy source",
+    "agentGroup": "source"
+  },
+  {
+    "name": "retrieve",
+    "args": "",
+    "summary": "Retrieve source. -d <path>, -m <Type[:Name]> or -x <package.xml>,\n-w <minutes>, --ignore-conflicts. No selector pulls tracked remote changes",
+    "agentTip": "[-d <path> | -m <Type:Name> | -x <manifest>]: retrieve source",
+    "agentGroup": "source"
+  },
+  {
+    "name": "tracking",
+    "args": "",
+    "summary": "Show source-tracked changes. --local | --remote, --conflicts (conflicts only)",
+    "agentTip": "[--local | --remote] [--conflicts]: source changes"
+  },
+  {
+    "name": "test",
+    "args": "",
+    "summary": "Run Apex tests. -n <class> (repeatable), -t <Class.method> (repeatable),\n-s <suite> (repeatable), -l <test level>, -c (coverage), -w <minutes>, --logs, --no-trace",
+    "agentTip": "-n <class> | -t <Class.method>: Apex tests; --logs, -c"
+  },
+  {
+    "name": "logs",
+    "args": "",
+    "summary": "List recent debug logs. --count/--limit <10>, --user <username>, --no-trace",
+    "agentTip": "[--count 10]: recent debug logs",
+    "agentGroup": "logs"
+  },
+  {
+    "name": "logs get",
+    "args": "<id|latest>",
+    "summary": "Print a filtered log. --full for raw text, --no-trace",
+    "agentTip": "latest: filtered debug log; --full for raw text",
+    "agentGroup": "logs"
+  },
+  {
+    "name": "org",
+    "args": "",
+    "summary": "Show the resolved org (username, id, instance, API version)",
+    "agentTip": ": resolved org details",
+    "agentGroup": "orgs"
+  },
+  {
+    "name": "org list",
+    "args": "[--all] [--status]",
+    "summary": "List authenticated orgs (local; --status pings)",
+    "agentTip": "[--all] [--status]: list local orgs; optional live checks",
+    "agentGroup": "orgs"
+  },
+  {
+    "name": "hook",
+    "args": "<agent|check|install|uninstall>",
+    "summary": "Integrate with Claude Code, Codex CLI or Gemini CLI",
+    "agentTip": "install --agent <claude|codex|gemini>: install rewrite hook",
+    "agentGroup": "agents"
+  },
+  {
+    "name": "agents-snippet",
+    "args": "[--write [file]]",
+    "summary": "Print agent instructions, or update AGENTS.md / CLAUDE.md",
+    "agentTip": "[--write [file]]: print or update agent instructions",
+    "agentGroup": "agents"
+  },
+  {
+    "name": "discover",
+    "args": "[--since 30d]",
+    "summary": "Report missed sfd opportunities in local agent transcripts",
+    "agentTip": "[--since 30d]: local transcript adoption report",
+    "agentGroup": "agents"
+  },
+  {
+    "name": "start | stop | status | reload",
+    "args": "",
+    "summary": "Manage the daemon. reload drops cached orgs and auth state",
+    "agentTip": ": daemon lifecycle"
+  }
+];
+
+export function commandHelp() {
+  return COMMANDS.map(({ name, args, summary }) => {
+    const syntax = [name, args].filter(Boolean).join(" ");
+    const description = summary.replaceAll("\n", "\n                        ");
+    return syntax.length >= 22
+      ? `  ${syntax}\n                        ${description}`
+      : `  ${syntax.padEnd(22)}${description}`;
+  }).join("\n");
+}

package/src/discover/claude.mjs

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { files, lines, matches, complete, candidate, count } from "./shared.mjs";
+
+export async function* read(options) {
+  const { home, since = new Date(0), stats } = options;
+  for await (const file of files(join(home, ".claude/projects"), ".jsonl", since, stats)) {
+    const pending = new Map();
+    for await (const entry of lines(file, stats)) {
+      const content = entry?.message?.content;
+      if (!Array.isArray(content)) { count(stats, "ignoredEntries"); continue; }
+      for (const item of content) {
+        if (item?.type === "tool_use" && item.name === "Bash") {
+          const command = item.input?.command;
+          if (!candidate(command)) continue;
+          const record = { agent: "claude", ts: new Date(entry.timestamp ?? NaN), command, cwd: entry.cwd, session: file };
+          if (matches(record, options)) pending.set(item.id, record);
+        } else if (item?.type === "tool_result" && pending.has(item.tool_use_id)) {
+          yield complete(pending.get(item.tool_use_id), entry.timestamp, item.content);
+          pending.delete(item.tool_use_id);
+        } else count(stats, "ignoredEntries");
+      }
+    }
+    yield* pending.values();
+  }
+}

package/src/discover/codex.mjs

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+import { files, lines, matches, complete, candidate, count, shellCommand } from "./shared.mjs";
+
+export async function* read(options) {
+  const { home, since = new Date(0), stats } = options;
+  for await (const file of files(join(home, ".codex/sessions"), ".jsonl", since, stats)) {
+    const pending = new Map();
+    let cwd;
+    for await (const entry of lines(file, stats)) {
+      const payload = entry?.payload;
+      if (["session_meta", "turn_context"].includes(entry?.type)) { cwd = payload?.cwd ?? cwd; continue; }
+      if (entry?.type !== "response_item" || !payload) { count(stats, "ignoredEntries"); continue; }
+      if (payload.type === "function_call" && ["shell", "shell_command", "exec_command"].includes(payload.name)) {
+        let args;
+        try { args = JSON.parse(payload.arguments); }
+        catch { count(stats, "malformedEntries"); continue; }
+        const command = shellCommand(args);
+        if (!candidate(command)) continue;
+        const record = { agent: "codex", ts: new Date(entry.timestamp ?? NaN), command, cwd: args.workdir ?? cwd, session: file };
+        if (matches(record, options)) pending.set(payload.call_id, record);
+      } else if (payload.type === "function_call_output" && pending.has(payload.call_id)) {
+        yield complete(pending.get(payload.call_id), entry.timestamp, payload.output);
+        pending.delete(payload.call_id);
+      } else count(stats, "ignoredEntries");
+    }
+    yield* pending.values();
+  }
+}

package/src/discover/gemini.mjs

@@ -0,0 +1,32 @@
+import { readFile } from "node:fs/promises";
+import { join, basename, dirname } from "node:path";
+import { files, matches, candidate, count, outputChars } from "./shared.mjs";
+
+export async function* read(options) {
+  const { home, since = new Date(0), stats } = options;
+  for await (const file of files(join(home, ".gemini/tmp"), ".json", since, stats)) {
+    if (basename(dirname(file)) !== "chats" && basename(file) !== "logs.json") continue;
+    let document;
+    // Gemini persists a JSON document, rather than a JSONL stream.
+    try { document = JSON.parse(await readFile(file, "utf8")); }
+    catch (error) { count(stats, error instanceof SyntaxError ? "malformedEntries" : "unreadableFiles"); continue; }
+    const messages = Array.isArray(document) ? document : document?.messages;
+    if (!Array.isArray(messages)) { count(stats, "ignoredEntries"); continue; }
+    for (const message of messages) {
+      if (!Array.isArray(message?.toolCalls)) { count(stats, "ignoredEntries"); continue; }
+      for (const tool of message.toolCalls) {
+        if (tool?.name !== "run_shell_command") { count(stats, "ignoredEntries"); continue; }
+        const command = tool.args?.command;
+        if (!candidate(command)) continue;
+        const record = {
+          agent: "gemini", ts: new Date(tool.timestamp ?? message.timestamp ?? NaN), command,
+          cwd: tool.args?.directory ?? message.cwd ?? document.cwd,
+          session: file
+        };
+        const chars = outputChars(tool.result);
+        if (chars !== undefined) record.outputChars = chars;
+        if (matches(record, options)) yield record;
+      }
+    }
+  }
+}

package/src/discover/index.mjs

@@ -0,0 +1,181 @@
+import { homedir } from "node:os";
+import { basename } from "node:path";
+import { rewrite, lex } from "../rewrite.mjs";
+import { read as claude } from "./claude.mjs";
+import { read as codex } from "./codex.mjs";
+import { read as gemini } from "./gemini.mjs";
+import { UsageError } from "../usage-error.mjs";
+import { Worker } from "node:worker_threads";
+import { COMMANDS } from "../commands.mjs";
+
+const readers = { claude, codex, gemini };
+// Only known command paths may enter the report; trailing words can be private values.
+const sfPaths = [
+  "org list metadata-types", "org list metadata", "org list", "org display",
+  "org create scratch", "org create sandbox", "org login web", "org login jwt",
+  "apex list log", "apex get log", "apex run test", "apex run", "data query",
+  "project retrieve start", "project deploy start", "sobject describe", "api request rest",
+  "plugins"
+];
+const commandPaths = {
+  sf: sfPaths,
+  sfdx: [...sfPaths, "force:org:list", "force:org:display", "force:data:soql:query",
+    "force:apex:execute", "force:apex:test:run", "force:source:deploy", "force:source:retrieve"],
+  sfd: COMMANDS.flatMap(({ name }) => name.split(" | "))
+};
+
+function subcommandName([executable, ...args]) {
+  if (!args.length || args[0].startsWith("-")) return "(no subcommand)";
+  const matches = commandPaths[executable].filter(path =>
+    path.split(" ").every((word, index) => args[index] === word));
+  return matches.sort((a, b) => b.split(" ").length - a.split(" ").length)[0]
+    ?? "(unrecognized subcommand)";
+}
+
+export function discoverOptions(values, now = Date.now()) {
+  const window = values.since ?? "30d";
+  if (!/^\d+[dh]$/.test(window)) throw new UsageError("--since must be a duration such as 30d or 12h.");
+  const since = new Date(now - Number(window.slice(0, -1)) * (window.endsWith("d") ? 86400000 : 3600000));
+  if (!Number.isFinite(+since)) throw new UsageError("--since is too large.");
+  const agents = [...new Set(values.agent ?? Object.keys(readers))];
+  if (agents.some(agent => !Object.hasOwn(readers, agent))) throw new UsageError("--agent must be claude, codex or gemini.");
+  const top = Number(values.top ?? 10);
+  if (!Number.isSafeInteger(top) || top <= 0) throw new UsageError("--top must be a positive integer.");
+  return { since, window, agents, top, project: values.project };
+}
+
+function invocation(command) {
+  let tokens;
+  try { tokens = lex(command); }
+  catch {
+    // The rewriter will retain its exact syntax/expansion skip reason.
+    const match = /^(?:\s*cd\s+\S+\s*&&)?\s*((?:\w+=\S+\s+)*)(sf|sfd|sfdx)\b(.*)/s.exec(command);
+    return match ? [match[2], ...match[3].trim().split(/\s+/)] : undefined;
+  }
+  const found = [];
+  let start = true;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.op) { start = ["&&", "||", ";", "|", "\n", "&"].includes(token.op); continue; }
+    if (!start) continue;
+    if (/^\w+=/.test(token.value) || ["env", "rtk", "proxy", "command"].includes(token.value)) continue;
+    start = false;
+    if (["sf", "sfd", "sfdx"].includes(basename(token.value))) {
+      const words = [basename(token.value)];
+      for (let j = i + 1; j < tokens.length && !tokens[j].op; j++) words.push(tokens[j].value);
+      found.push(words);
+    }
+  }
+  return found.find(words => words[0] !== "sfd") ?? found[0];
+}
+
+function reportReason(reason) {
+  if (reason.startsWith("unsupported result format ")) return "unsupported result format";
+  const flagReason = /^(unsupported flag|duplicate flag|missing value for|unsupported value for|unsupported boolean value) (.*)$/s.exec(reason);
+  if (!flagReason) return reason;
+  const flag = flagReason[2].split("=")[0];
+  return `${flagReason[1]}${/^(?:--[A-Za-z][A-Za-z0-9-]*|-[A-Za-z])$/.test(flag) ? ` ${flag}` : ""}`;
+}
+
+export function classify(command) {
+  const words = invocation(command);
+  if (!words) return;
+  const subcommand = subcommandName(words);
+  if (words[0] === "sfd") return { classification: "adopted", subcommand };
+  if (words[0] === "sfdx" && words[1]?.startsWith("force:")) return { classification: "legacy", subcommand };
+  const result = rewrite(command);
+  if (result.command) return { classification: "rewritable", subcommand };
+  if (result.skip === "unsupported sf command") return { classification: "unsupported", subcommand };
+  return { classification: "skipped", subcommand, reason: reportReason(result.skip) };
+}
+
+const median = values => {
+  if (!values.length) return null;
+  values.sort((a, b) => a - b);
+  const mid = Math.floor(values.length / 2);
+  return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+};
+const ranked = map => [...map].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+
+function scanAgent(agent, options) {
+  // Independent JSON parsers keep large agent histories off one CPU core.
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(new URL("./worker.mjs", import.meta.url), { workerData: { agent, ...options } });
+    let result;
+    worker.on("message", message => { result = message; });
+    worker.on("error", reject);
+    worker.on("exit", code => {
+      if (code !== 0 || !result) reject(new Error(`Discover ${agent} reader exited with code ${code}`));
+      else resolve(result);
+    });
+  });
+}
+
+export async function discover({ home = homedir(), agents = Object.keys(readers), since = new Date(0), window = "all history", project, top = 10 } = {}) {
+  const report = {
+    since: since.toISOString(), window, agents, project: project ?? null, top,
+    sfCalls: 0, sessions: 0,
+    counts: { rewritable: 0, skipped: 0, unsupported: 0, legacy: 0, adopted: 0 },
+    estimates: { timeSavedMs: 0, durationSamples: 0, outputChars: 0, outputSamples: 0, outputTokens: 0 },
+    diagnostics: { malformedEntries: 0, ignoredEntries: 0, unreadableFiles: 0 }
+  };
+  const sessions = new Set(), groups = new Map(), reasons = new Map(), unsupported = new Map(), rewritable = new Map();
+  const scans = await Promise.all(agents.map(agent => scanAgent(agent, { home, since, project })));
+  for (const { observations, stats } of scans) {
+    for (const [key, value] of Object.entries(stats)) report.diagnostics[key] += value;
+    for (const record of observations) {
+      const classification = record.classification;
+      const { classification: kind, subcommand, reason } = classification;
+      report.counts[kind]++;
+      if (kind !== "adopted") report.sfCalls++;
+      sessions.add(`${record.agent}:${record.session}`);
+      const key = JSON.stringify([kind, subcommand, reason]);
+      if (!groups.has(key)) groups.set(key, { ...classification, count: 0, durations: [], sizes: [] });
+      const group = groups.get(key);
+      group.count++;
+      if (record.durationMs !== undefined) group.durations.push(record.durationMs);
+      if (record.outputChars !== undefined) group.sizes.push(record.outputChars);
+      if (kind === "rewritable") {
+        rewritable.set(subcommand, (rewritable.get(subcommand) ?? 0) + 1);
+        if (record.durationMs !== undefined) {
+          report.estimates.durationSamples++;
+          report.estimates.timeSavedMs += Math.max(0, record.durationMs - 300);
+        }
+        if (record.outputChars !== undefined) {
+          report.estimates.outputSamples++;
+          report.estimates.outputChars += record.outputChars;
+        }
+      } else if (kind === "skipped") reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+      else if (["unsupported", "legacy"].includes(kind)) unsupported.set(subcommand, (unsupported.get(subcommand) ?? 0) + 1);
+    }
+  }
+  report.sessions = sessions.size;
+  report.estimates.outputTokens = report.estimates.outputChars / 4;
+  report.commands = [...groups.values()].map(({ durations, sizes, ...group }) => ({
+    ...group, medianDurationMs: median(durations), durationSamples: durations.length,
+    medianOutputChars: median(sizes), medianOutputTokens: sizes.length ? median(sizes) / 4 : null, outputSamples: sizes.length
+  })).sort((a, b) => b.count - a.count || a.subcommand.localeCompare(b.subcommand));
+  report.skipReasons = ranked(reasons);
+  report.unsupported = ranked(unsupported);
+  report.rewritable = ranked(rewritable);
+  return report;
+}
+
+export function formatReport(report) {
+  const list = items => items.slice(0, report.top).map(item => `${item.name} ${item.count}`).join(" · ") || "(none)";
+  const { counts: c, estimates: e, diagnostics: d } = report;
+  const time = e.durationSamples ? `~${(e.timeSavedMs / 60000).toFixed(1)} min saved (${e.durationSamples} samples)` : "time unknown";
+  const output = e.outputSamples ? `~${Math.round(e.outputTokens)} output tokens (${e.outputSamples} samples)` : "output unknown";
+  return [
+    `sfd discover: ${report.window}, ${report.agents.length} agents, ${report.sfCalls} sf/sfdx calls in ${report.sessions} sessions`,
+    `  rewritable now  ${c.rewritable}  (${time}; ${output})`,
+    `  skipped         ${c.skipped}  ${list(report.skipReasons)}`,
+    `  not in sfd      ${c.unsupported + c.legacy}  ${list(report.unsupported)} (legacy ${c.legacy})`,
+    `  already sfd     ${c.adopted}`,
+    `Top rewritable: ${list(report.rewritable)}`,
+    `Scan: ${d.malformedEntries} malformed, ${d.ignoredEntries} ignored entries, ${d.unreadableFiles} unreadable files.`,
+    "Durations include permission wait; savings assume 0.3 s/call. Tokens are chars/4.",
+    "Output tokens are potential savings before sfd output, which is not measured. Missing samples are not extrapolated.",
+    "Counts classify shell tool calls once; compound calls use the first sf/sfdx invocation."
+  ].join("\n");
+}

package/src/discover/shared.mjs

@@ -0,0 +1,79 @@
+import { createReadStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { join, relative, resolve, isAbsolute } from "node:path";
+
+export function count(stats, key) {
+  if (stats) stats[key] = (stats[key] ?? 0) + 1;
+}
+
+export async function* files(root, extension, since, stats) {
+  let entries;
+  try { entries = await readdir(root, { withFileTypes: true }); }
+  catch (error) {
+    if (error.code !== "ENOENT") count(stats, "unreadableFiles");
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) yield* files(path, extension, since, stats);
+    else if (entry.isFile() && entry.name.endsWith(extension)) {
+      try {
+        if ((await stat(path)).mtimeMs >= Number(since)) yield path;
+      } catch { count(stats, "unreadableFiles"); }
+    }
+  }
+}
+
+export async function* lines(file, stats) {
+  const stream = createReadStream(file, { encoding: "utf8", highWaterMark: 1024 * 1024 });
+  const reader = createInterface({ input: stream, crlfDelay: Infinity });
+  // Forward stream errors into the iterator, including files removed mid-scan.
+  stream.on("error", error => reader.close());
+  try {
+    for await (const line of reader) {
+      if (!line.trim()) continue;
+      try { yield JSON.parse(line); }
+      catch { count(stats, "malformedEntries"); }
+    }
+    if (stream.errored) count(stats, "unreadableFiles");
+  } catch { count(stats, "unreadableFiles"); }
+  finally { reader.close(); stream.destroy(); }
+}
+
+export function matches(record, { since, project, stats }) {
+  if (record.ts == null || !Number.isFinite(+record.ts)) {
+    count(stats, "malformedEntries");
+    return false;
+  }
+  if (+record.ts < +since) return false;
+  if (!project) return true;
+  if (typeof record.cwd !== "string") return false;
+  const path = relative(resolve(project), resolve(record.cwd));
+  return !isAbsolute(path) && path !== ".." && !path.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`);
+}
+
+export function outputChars(output) {
+  if (output === undefined || output === null) return undefined;
+  return (typeof output === "string" ? output : JSON.stringify(output)).length;
+}
+
+export function complete(record, timestamp, output) {
+  const duration = +new Date(timestamp) - +record.ts;
+  return {
+    ...record,
+    ...(Number.isFinite(duration) && duration >= 0 ? { durationMs: duration } : {}),
+    ...(outputChars(output) !== undefined ? { outputChars: outputChars(output) } : {})
+  };
+}
+
+export function shellCommand(args) {
+  const command = args?.command ?? args?.cmd;
+  if (typeof command === "string") return command;
+  if (!Array.isArray(command) || !command.every(v => typeof v === "string")) return;
+  if (["bash", "sh", "/bin/bash", "/bin/sh"].includes(command[0]) && ["-lc", "-c"].includes(command[1]) && command.length === 3) return command[2];
+  // Preserve argv boundaries for the literal-shell rewriter.
+  return command.map(v => `'${v.replaceAll("'", "'\\''")}'`).join(" ");
+}
+
+export const candidate = command => typeof command === "string" && /\b(?:sf|sfd|sfdx)\b/.test(command);

package/src/discover/worker.mjs

@@ -0,0 +1,17 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { read as claude } from "./claude.mjs";
+import { read as codex } from "./codex.mjs";
+import { read as gemini } from "./gemini.mjs";
+import { classify } from "./index.mjs";
+
+const stats = {};
+const observations = [];
+const { agent, ...options } = workerData;
+for await (const record of ({ claude, codex, gemini })[agent]({ ...options, stats })) {
+  const classification = classify(record.command);
+  if (classification) observations.push({
+    agent, session: record.session, durationMs: record.durationMs,
+    outputChars: record.outputChars, classification
+  });
+}
+parentPort.postMessage({ observations, stats });

package/src/format.mjs

@@ -2,7 +2,7 @@ import { relative, resolve } from "node:path";
 
 // Compact, token-friendly renderings of Salesforce results.
 
-const asArray = x => (x === undefined || x === null ? [] : Array.isArray(x) ? x : [x]);
+export const asArray = x => (x === undefined || x === null ? [] : Array.isArray(x) ? x : [x]);
 
 export function stripAttributes(value) {
   if (Array.isArray(value)) return value.map(stripAttributes);
@@ -18,6 +18,31 @@ export function compactQuery(result) {
   return { totalSize: result.totalSize, done: result.done, ...(result.nextRecordsUrl ? { nextRecordsUrl: result.nextRecordsUrl } : {}), records: stripAttributes(result.records ?? []) };
 }
 
+export function flattenRecord(record, prefix = "") {
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "attributes") continue;
+    const column = prefix + key;
+    if (value === null || typeof value !== "object") out[column] = value;
+    else if (Array.isArray(value.records)) out[column] = JSON.stringify(stripAttributes(value.records));
+    else Object.assign(out, flattenRecord(value, column + "."));
+  }
+  return out;
+}
+
+export function toCsv(records) {
+  if (!records.length) return "";
+  const rows = records.map(record => flattenRecord(record));
+  const keys = [...new Set(rows.flatMap(row => Object.keys(row)))];
+  // A null parent supplies empty cells for its dotted columns, not an extra column.
+  const columns = keys.filter(key => !keys.some(other => other.startsWith(key + ".")) || rows.some(row => row[key] != null));
+  const escape = value => {
+    const text = value == null ? "" : String(value);
+    return /[",\r\n]/.test(text) ? '"' + text.replaceAll('"', '""') + '"' : text;
+  };
+  return [columns.map(escape).join(","), ...rows.map(row => columns.map(key => escape(row[key])).join(","))].join("\n");
+}
+
 export function compactDescribe(d) {
   return {
     name: d.name, label: d.label, keyPrefix: d.keyPrefix, custom: d.custom,
@@ -239,3 +264,36 @@ export function formatTracking(summary) {
   }
   return lines.join("\n") || "No changes.";
 }
+
+export function formatOrgList({ orgs, hiddenExpired = 0 }) {
+  const aliasWidth = Math.max(1, ...orgs.map(org => (org.alias ?? "-").length));
+  const userWidth = Math.max(1, ...orgs.map(org => org.username.length));
+  const lines = orgs.map(org => {
+    const marker = `${org.isDefault ? "*" : " "}${org.isDefaultDevHub ? "H" : " "}`;
+    const expiry = org.type === "Scratch" ? org.expired ? " EXPIRED" : org.expirationDate ? ` expires ${org.expirationDate.slice(0, 10)}` : "" : "";
+    return `${marker} ${(org.alias ?? "-").padEnd(aliasWidth)} ${org.username.padEnd(userWidth)} ${org.type}${expiry}${org.status ? ` ${org.status}` : ""}`;
+  });
+  if (hiddenExpired) lines.push(`(${hiddenExpired} expired scratch org(s) hidden; use --all)`);
+  if (!lines.length) lines.push("No authenticated orgs. Run: sf org login web -a <alias>");
+  return lines.join("\n");
+}
+
+export function formatMetadataTypes({ types, apiVersion }) {
+  return [`${types.length} metadata types (API v${apiVersion})`, ...types.map(type => {
+    const children = type.children.slice(0, 6);
+    if (type.children.length > 6) children.push(`…+${type.children.length - 6}`);
+    return `${type.name}${type.inFolder ? " (folder)" : ""}${children.length ? ` [${children.join(", ")}]` : ""}`;
+  })].join("\n");
+}
+
+export function formatMetadataList({ groups }, { details = false } = {}) {
+  return groups.map(group => {
+    const header = group.folders
+      ? `${group.folderType} (${group.members.length}): use --folder <name> to list members`
+      : groups.length > 1 ? `${group.type} (${group.members.length}):` : "";
+    const lines = group.members.map(member => details ? [member.fullName, member.lastModifiedDate?.slice(0, 10),
+      member.lastModifiedByName, member.namespacePrefix ? `ns:${member.namespacePrefix}` : "", member.manageableState].filter(Boolean).join("  ") : member.fullName);
+    if (!lines.length) lines.push("(none)");
+    return header ? [header, ...lines.map(line => `  ${line}`)].join("\n") : lines.join("\n");
+  }).join("\n");
+}

package/src/handlers.mjs

@@ -1,9 +1,9 @@
-import { statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { UsageError } from "./usage-error.mjs";
 import { sfRequire } from "./sf-root.mjs";
-import { compactDescribe, compactQuery, summarizeDeploy, summarizeTests, summarizeRetrieve, summarizeChanges } from "./format.mjs";
+import { asArray, compactDescribe, compactQuery, summarizeDeploy, summarizeTests, summarizeRetrieve, summarizeChanges } from "./format.mjs";
 
 const soqlString = value => `'${String(value).replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
 const LOG_FIELDS = "Id, LogUser.Username, Operation, Request, Status, LogLength, StartTime, DurationMilliseconds";
@@ -67,6 +67,16 @@ export async function ensureTrace(conn, userId) {
   return { action: flag ? "extended" : "created", id: flag?.Id ?? result.id, expires: dates.ExpirationDate };
 }
 
+async function withDeadline(fn) {
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(fn),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(Object.assign(new Error(), { name: "Timeout" })), 10000); })
+    ]);
+  } finally { clearTimeout(timer); }
+}
+
 const SESSION_ERRORS = new Set(["INVALID_SESSION_ID", "INVALID_AUTH_HEADER"]);
 
 function authStamp(home) {
@@ -86,6 +96,24 @@ function serial() {
   };
 }
 
+function metadataSuggestion(name, names) {
+  const input = name.toLowerCase();
+  const distance = candidate => {
+    let row = Array.from({ length: input.length + 1 }, (_, i) => i);
+    for (const char of candidate.toLowerCase()) {
+      const next = [row[0] + 1];
+      for (let i = 1; i <= input.length; i++) {
+        next[i] = Math.min(next[i - 1] + 1, row[i] + 1, row[i - 1] + (input[i - 1] === char ? 0 : 1));
+      }
+      row = next;
+    }
+    return row[input.length];
+  };
+  return names.find(n => n.toLowerCase().startsWith(input)) ??
+    names.map(name => ({ name, distance: distance(name) })).filter(n => n.distance <= 2)
+      .sort((a, b) => a.distance - b.distance)[0]?.name;
+}
+
 export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRoot) } = {}) {
   const req = load;
   const core = req("@salesforce/core");
@@ -97,6 +125,7 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
   const projectQueue = serial();
 
   const orgs = new Map();
+  const typeCache = new Map();
   const traces = new Map();
   const traceQueue = serial();
   const traceFor = (conn, alias, user, noTrace) => noTrace ? undefined : traceQueue(async () => {
@@ -108,14 +137,22 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
   });
   let stamp = authStamp(home);
 
-  async function getOrg(alias) {
+  let refreshing;
+  async function refreshIfAuthChanged() {
+    if (refreshing) await refreshing;
     const now = authStamp(home);
     if (now !== stamp) {
       stamp = now;
       orgs.clear();
       traces.clear();
-      await core.StateAggregator.clearInstanceAsync();
+      typeCache.clear();
+      refreshing = core.StateAggregator.clearInstanceAsync();
+      try { await refreshing; } finally { refreshing = undefined; }
     }
+  }
+
+  async function getOrg(alias) {
+    await refreshIfAuthChanged();
     if (!orgs.has(alias)) {
       const pending = core.Org.create({ aliasOrUsername: alias });
       orgs.set(alias, pending);
@@ -133,11 +170,27 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
       if (!SESSION_ERRORS.has(e.errorCode ?? e.name)) throw e;
       orgs.delete(alias);
       traces.delete(alias);
+      typeCache.delete(alias);
       const org = await getOrg(alias);
       return fn(org.getConnection(), org);
     }
   }
 
+  async function metadataTypes(alias, conn) {
+    const apiVersion = conn.getApiVersion();
+    let versions = typeCache.get(alias);
+    if (!versions) typeCache.set(alias, versions = new Map());
+    const cached = versions.has(apiVersion);
+    if (!cached) {
+      const pending = conn.metadata.describe(apiVersion).then(result => asArray(result.metadataObjects)
+        .map(t => ({ name: t.xmlName, inFolder: Boolean(t.inFolder), children: asArray(t.childXmlNames) }))
+        .sort((a, b) => a.name.localeCompare(b.name)));
+      versions.set(apiVersion, pending);
+      pending.catch(() => { if (versions.get(apiVersion) === pending) versions.delete(apiVersion); });
+    }
+    return { types: await versions.get(apiVersion), apiVersion, cached };
+  }
+
   return {
     ping: async () => ({ pong: true }),
 
@@ -150,6 +203,7 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
     reload: async () => {
       orgs.clear();
       traces.clear();
+      typeCache.clear();
       await core.StateAggregator.clearInstanceAsync();
       return { reloaded: true };
     },
@@ -158,17 +212,105 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
       alias: org, username: o.getUsername(), orgId: o.getOrgId(), instanceUrl: conn.instanceUrl, apiVersion: conn.getApiVersion()
     })),
 
-    query: ({ org, q, tooling, all, raw }) => withConn(org, async conn => {
+    orgList: async ({ all = false, status = false } = {}) => {
+      await refreshIfAuthChanged();
+      const state = await core.StateAggregator.getInstance();
+      const config = await core.ConfigAggregator.create();
+      await config.reload();
+      const isDefault = (username, key) => {
+        const value = config.getPropertyValue(key);
+        return value === username || state.aliases.getAll(username).includes(value);
+      };
+      let authorizations;
+      try { authorizations = await core.AuthInfo.listAllAuthorizations() ?? []; }
+      catch (error) {
+        if (error.name !== "NoAuthInfoFound") throw error;
+        authorizations = [];
+      }
+      const entries = await Promise.all(authorizations.map(async ({ username }) => {
+        try {
+          const auth = await core.AuthInfo.create({ username });
+          let fields;
+          try { fields = auth.getFields(true); } catch { fields = auth.getFields(); }
+          const defaultOrg = isDefault(username, "target-org");
+          if (fields.orgId && !defaultOrg) {
+            let primary;
+            try { primary = JSON.parse(readFileSync(join(home, ".sfdx", `${fields.orgId}.json`), "utf8")).usernames?.[0]; }
+            catch (error) { if (error.code !== "ENOENT") throw error; }
+            if (primary && primary !== username) return undefined;
+          }
+          const scratch = Boolean(fields.expirationDate || fields.devHubUsername);
+          const org = {
+            alias: state.aliases.getAll(username)[0] ?? null, username,
+            orgId: fields.orgId, instanceUrl: fields.instanceUrl,
+            type: scratch ? "Scratch" : fields.isDevHub ? "DevHub" : fields.isSandbox ? "Sandbox" : "Org",
+            isDefault: defaultOrg, isDefaultDevHub: isDefault(username, "target-dev-hub")
+          };
+          if (scratch) {
+            if (fields.expirationDate) org.expirationDate = fields.expirationDate;
+            org.expired = Boolean(fields.expirationDate && fields.expirationDate.slice(0, 10) < new Date().toISOString().slice(0, 10));
+          }
+          return { org, devHubUsername: fields.devHubUsername };
+        } catch {
+          // Never log auth fields or vendor error messages, which can contain secrets.
+          console.warn("sfd org list: skipping unreadable local authorization");
+          return undefined;
+        }
+      }));
+      const readable = entries.filter(Boolean);
+      if (status) {
+        const hubs = new Map();
+        const checks = readable.filter(({ org }) => org.type !== "Scratch").map(async ({ org }) => {
+          try {
+            await withDeadline(async () => (await getOrg(org.username)).refreshAuth());
+            org.status = "Connected";
+          } catch (error) {
+            orgs.delete(org.username);
+            org.status = error.name;
+          }
+        });
+        for (const entry of readable) {
+          if (entry.org.type !== "Scratch" || !entry.devHubUsername || !entry.org.orgId) continue;
+          if (!hubs.has(entry.devHubUsername)) hubs.set(entry.devHubUsername, []);
+          hubs.get(entry.devHubUsername).push(entry.org);
+        }
+        await Promise.all([...checks, ...[...hubs].map(async ([hub, scratchOrgs]) => {
+          try {
+            const result = await withDeadline(async () => {
+              const org = await getOrg(hub);
+              return org.getConnection().query(`SELECT ScratchOrg, Status, ExpirationDate FROM ScratchOrgInfo WHERE ScratchOrg IN (${scratchOrgs.map(o => soqlString(o.orgId.slice(0, 15))).join(",")})`);
+            });
+            for (const org of scratchOrgs) {
+              const row = result.records.find(r => r.ScratchOrg?.slice(0, 15) === org.orgId.slice(0, 15));
+              if (!row) continue;
+              org.status = row.Status;
+              if (row.ExpirationDate) org.expirationDate = row.ExpirationDate;
+              org.expired = row.Status === "Expired" || row.Status === "Deleted";
+            }
+          } catch { /* Local scratch details remain useful when a Dev Hub is unavailable. */ }
+        })]);
+      }
+      const listed = readable.map(entry => entry.org);
+      const visible = all ? listed : listed.filter(org => !org.expired);
+      visible.sort((a, b) => (a.alias ?? "").localeCompare(b.alias ?? "") || a.username.localeCompare(b.username));
+      return { orgs: visible, hiddenExpired: listed.length - visible.length };
+    },
+
+    query: ({ org, q, tooling, all, raw, limit }) => withConn(org, async conn => {
       const api = tooling ? conn.tooling : conn;
       const result = await api.query(q, { scanAll: Boolean(all) });
-      while (!result.done) {
+      while (!result.done && (limit === undefined || result.records.length < limit)) {
         if (!result.nextRecordsUrl) throw new Error("Incomplete query result: missing nextRecordsUrl.");
         const page = await api.queryMore(result.nextRecordsUrl);
         result.records.push(...page.records);
         result.done = page.done;
         result.nextRecordsUrl = page.nextRecordsUrl;
       }
-      return raw ? result : compactQuery(result);
+      const truncated = limit !== undefined && (!result.done || result.records.length > limit);
+      if (truncated) result.records = result.records.slice(0, limit);
+      const output = raw ? result : compactQuery(result);
+      if (truncated) output.truncated = true;
+      return output;
     }),
 
     apex: ({ org, body }) => withConn(org, conn => new (apex().ExecuteService)(conn).executeAnonymous({ apexCode: body })),
@@ -183,6 +325,37 @@ export function createHandlers(sfRoot, { home = homedir(), load = sfRequire(sfRo
       return raw ? d : compactDescribe(d);
     }),
 
+    listMetadataTypes: ({ org }) => withConn(org, conn => metadataTypes(org, conn)),
+
+    listMetadata: ({ org, types = [], folder }) => withConn(org, async conn => {
+      types = [...new Set(types)];
+      if (!types.length) throw new UsageError("list-metadata needs -m <Type>.");
+      if (folder !== undefined && types.length > 1) throw new UsageError("--folder requires exactly one metadata type.");
+      const description = await metadataTypes(org, conn);
+      const known = new Set(description.types.flatMap(t => [t.name, ...t.children]));
+      const groups = types.map(type => {
+        if (!known.has(type)) {
+          const suggestion = metadataSuggestion(type, [...known].sort());
+          throw new UsageError(`Unknown metadata type: ${type}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`);
+        }
+        const folders = folder === undefined && Boolean(description.types.find(t => t.name === type)?.inFolder);
+        const folderType = known.has(`${type}Folder`) ? `${type}Folder` : type === "EmailTemplate" ? "EmailFolder" : `${type}Folder`;
+        return { type, ...(folders ? { folders: true, folderType } : {}), members: [] };
+      });
+      const queries = groups.map(group => ({ type: group.folderType ?? group.type, ...(folder !== undefined ? { folder } : {}) }));
+      const chunks = [];
+      for (let i = 0; i < queries.length; i += 3) chunks.push(queries.slice(i, i + 3));
+      const results = await Promise.all(chunks.map(chunk => conn.metadata.list(chunk, description.apiVersion)));
+      const members = results.flatMap(asArray);
+      for (const group of groups) {
+        group.members = members.filter(member => member.type === (group.folderType ?? group.type)).map(member => ({
+          fullName: member.fullName, lastModifiedDate: member.lastModifiedDate, lastModifiedByName: member.lastModifiedByName,
+          namespacePrefix: member.namespacePrefix, manageableState: member.manageableState
+        })).sort((a, b) => a.fullName.localeCompare(b.fullName));
+      }
+      return { groups };
+    }),
+
     deploy: ({ org, projectDir, sourcePaths, metadata, checkOnly, testLevel, tests, waitMinutes = 33 }) =>
       projectQueue(() => withConn(org, async (conn, o) => {
         const { ComponentSetBuilder } = sdr();

package/src/rewrite.mjs

@@ -2,7 +2,7 @@
 const quote = value => `'${value.replaceAll("'", "'\\''")}'`;
 const skip = reason => ({ skip: reason });
 
-function lex(source) {
+export function lex(source) {
   const tokens = [];
   let i = 0;
   while (i < source.length) {
@@ -44,6 +44,8 @@ const wait = ["w wait", "-w", true];
 const level = ["l test-level", "-l", true];
 const tests = ["t tests", "-t", true, true];
 const mappings = [
+  { sf: "org list metadata-types", sfd: "list-metadata-types", flags: [org, json] },
+  { sf: "org list metadata", sfd: "list-metadata", flags: [org, json, ["m metadata-type", "-m", true], ["folder", "--folder", true]] },
   { sf: "apex list log", sfd: "logs", flags: [org, json] },
   { sf: "apex get log", sfd: "logs get", flags: [org, json, ["i log-id", "", true], ["n number", "", true]] },
   { sf: "data query", sfd: "query", flags: [org, json, tooling, ["q query", "", true], ["all-rows", "--all", false], format], required: "q" },
@@ -53,6 +55,7 @@ const mappings = [
   { sf: "project deploy start", sfd: "deploy", flags: [org, json, wait, level, tests, ["d source-dir", "-d", true, true], ["m metadata", "-m", true, true], ["dry-run", "--check-only", false]] },
   { sf: "sobject describe", sfd: "describe", flags: [org, json, tooling, ["s sobject", "", true]], required: "s" },
   { sf: "api request rest", sfd: "rest", flags: [org, ["X method", "-X", true], ["b body", "--body", true]], positional: true },
+  { sf: "org list", sfd: "org list", flags: [["all", "--all", false], ["skip-connection-status", "", false], ["json", "--json", false]] },
   { sf: "org display", sfd: "org", flags: [org, json] }
 ];
 
@@ -82,14 +85,19 @@ function mapArgs(argv) {
       }
     } else if (match[3] !== undefined) return skip(`unsupported boolean value ${arg}`);
     seen.set(key, values);
-    if (key === "r" && !["human", "json"].includes(values[0])) return skip(`unsupported result format ${values[0]}`);
+    if (key === "r") {
+      if (mapping.sfd === "query" && values[0] === "csv") output.push("--csv");
+      else if (!["human", "json"].includes(values[0])) return skip(`unsupported result format ${values[0]}`);
+    }
     if (key === "w" && (!Number.isFinite(Number(values[0])) || Number(values[0]) <= 0)) return skip("wait must be positive");
     if (target) {
       if (takesValue) for (const v of values) output.push(target, quote(v));
       else output.push(target);
     }
   }
+  if (mapping.sfd === "org list" && !seen.has("skip-connection-status")) output.push("--status");
   if (mapping.required && !seen.has(mapping.required)) return skip(`missing required ${mapping.required} flag`);
+  if (mapping.sfd === "list-metadata" && !seen.has("m")) return skip("metadata listing needs metadata-type");
   if (mapping.sfd === "deploy" && !seen.has("d") && !seen.has("m")) return skip("deploy needs source-dir or metadata");
   if (mapping.sfd === "retrieve" && ["d", "m", "x"].filter(key => seen.has(key)).length > 1) return skip("retrieve selectors are mutually exclusive");
   if (mapping.sfd === "test" && !seen.has("w") && !seen.has("y")) return skip("asynchronous tests need --wait or --synchronous");

package/src/snippet.mjs

@@ -0,0 +1,42 @@
+import { COMMANDS } from "./commands.mjs";
+
+const START = "<!-- sfd:start -->";
+const END = "<!-- sfd:end -->";
+
+export function snippet() {
+  const lines = [];
+  let previousGroup;
+  for (const { name, args, summary, agentTip, agentGroup } of COMMANDS) {
+    const tip = agentTip ?? `${args}: ${summary.replaceAll("\n", " ")}`;
+    const separator = tip.indexOf(": ");
+    if (separator === -1) throw new Error(`Invalid agentTip for ${name}: expected ": " separator`);
+    const invocation = ["sfd", name, tip.slice(0, separator).trim()].filter(Boolean).join(" ");
+    const entry = `\`${invocation}\`: ${tip.slice(separator + 2)}`;
+    if (agentGroup && agentGroup === previousGroup) lines[lines.length - 1] += `; ${entry}`;
+    else lines.push(`- ${entry}`);
+    previousGroup = agentGroup;
+  }
+  return [
+    START,
+    'Prefer `sfd` (warm Salesforce daemon, ~0.2 s/call, compact output) over `sf`:',
+    ...lines,
+    'Add `-o <alias>` as with `sf`. Exit: 0 ok, 1 operation failed, 2 usage, 3 daemon. For anything else use `sf … --json`; pipe through `jq` for a few fields.',
+    END
+  ].join("\n");
+}
+
+export function upsertSnippet(text, block) {
+  const start = text.indexOf(START);
+  const end = text.indexOf(END);
+  if (start === -1 && end === -1) {
+    const prefix = text.replace(/\s+$/, "");
+    return `${prefix ? `${prefix}\n\n` : ""}${block}\n`;
+  }
+  if (end === -1) throw new Error("found start marker without end");
+  if (start === -1) throw new Error("found end marker without start");
+  if (end < start) throw new Error("end marker precedes start marker");
+  if (text.indexOf(START, start + START.length) !== -1 || text.indexOf(END, end + END.length) !== -1) {
+    throw new Error("found multiple sfd blocks or nested markers");
+  }
+  return text.slice(0, start) + block + text.slice(end + END.length);
+}