@thenavidm/slipway 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.19, 2026-10-05: what Lemon Squeezy needed
+
+- **`which` answers with a command's help when one fits well ahead of the rest.** An agent asked `which` for the command and then read that command's `--help`, and each request carries the whole conversation. On Lemon Squeezy, `which cancel subscription` and then `cancel-subscription --help` cost Codex a median of 83,076 input tokens, where its 2.x CLI guessed the command's name and read its help in two requests for 61,541. When the first answer scores at least half again as much as the second, its help now follows the list, and three runs took 61,903, 61,913 and 61,908 in two requests. A close second gets the list alone: Gumroad's `which refund` fits refunding a sale and its refund policy alike, and the help shown would be a guess between them.
+
 ## 0.1.18, 2026-10-05: what Wistia and Testimonial.to needed
 
 - **A command's help never lists `--confirm` as the only required flag.** Wistia's import takes its URL as a flag or inside `--payload`, so no flag is required, and its help showed a Required section holding only `--confirm`. That reads as if nothing else were needed: every Codex run then read the command's schema as well, and finding the command and its flags cost a median of 105,140 input tokens, where Wistia's own 2.x CLI cost 86,365. Alone, `--confirm` now closes the options, where 2.x listed it, and the usage line still ends with it; two runs then took 83,069 and 82,817.

package/README.md

@@ -390,7 +390,7 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli>` | Every command, grouped by toolset, writes marked |
 | `<cli> <command> [flags]` | Run one tool |
 | `<cli> <command> --help` | Its flags, choices, defaults, examples and risk |
-| `<cli> which <words>` | Find the command for a task, by what it does. An app's `synonyms` add the words its users type: `{ picture: ["image"] }` |
+| `<cli> which <words>` | Find the command for a task, by what it does, with its help when one fits well ahead of the rest. An app's `synonyms` add the words its users type: `{ picture: ["image"] }` |
 | `<cli> schema <command>` | The JSON Schema an MCP client receives. `--output` for the result's |
 | `<cli> agent-context` | Commands, flags, risk, examples, exit codes and settings as JSON. `--brief` for just the commands, which ones write or need `--confirm`, and the exit codes |
 | `<cli> doctor` | Check the setup. `--network` also calls the service, which an app with `doctorNetwork` does every time |

package/dist/cli/run.js

@@ -257,7 +257,16 @@ async function runBuiltin(app, io, command, rest, globals) {
             }
             if (!matches.length)
                 return print(io, `No command matches '${query}'. Run \`${app.bins.cli}\` to see them all.`);
-            return print(io, matches.map(({ tool }) => toolLine(tool)).join("\n"));
+            const list = matches.map(({ tool }) => toolLine(tool)).join("\n");
+            // One command well ahead of the rest comes with its help, so finding a command and its flags is
+            // one step: on Lemon Squeezy, `which cancel subscription` and then `cancel-subscription --help`
+            // cost Codex a request its 2.x CLI had saved by guessing the name, and each request carries the
+            // whole conversation. A close second gets the list alone: Gumroad's `which refund` fits refunding
+            // a sale and its refund policy alike, and the help shown would be a guess between them.
+            const [first, second] = matches;
+            if (first && (!second || first.score >= second.score * 1.5))
+                return print(io, `${list}\n${renderToolHelp(first.tool, io.bin, app.definition.flagAliases)}`);
+            return print(io, list);
         }
         case "doctor":
             return runDoctor(app, io, { network: rest.includes("--network"), json: globals.format !== "auto" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Slipway, the TypeScript framework for MCP servers and agent-native CLIs. One tool definition ships an MCP server and a CLI, with write safety, typed results and release checks built in.",
   "type": "module",
   "license": "Apache-2.0",