@thenavidm/slipway 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.
+- **The general help leaves the flags to each command.** Each command's `--help` lists the flags it can use, `--agent` among them, so the general help's line of them repeated what an agent reads one step later, after carrying that line through every step in between. Without it the general help is 35 tokens shorter on every server: Testimonial.to's goes from 324 to 289.
+
 ## 0.1.17, 2026-10-05: what Google Photos needed
 
 - **`which` reads an argument by its own words, not through a synonym.** Since 0.1.14 a tool's argument names count toward finding it, and a synonym reached them too. Google Photos says "photos" means media, so `get_media_item`, which takes a `media_item_id`, drew level with the photo picker for "let me choose photos" and was listed first. An argument now counts only for the words it is made of, so the picker is first again. Buffer's "schedule a post to a channel" still reads `channelId` and `schedulingType`, and the first answer to every task measured on the other servers is unchanged.

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/help.js

@@ -174,8 +174,17 @@ export function renderToolHelp(tool, bin, aliases = {}) {
         }
         lines.push(...after, ``);
     };
-    describe(required, "Required", tool.requireConfirm ? line("  --confirm", "it runs only with this; --agent never adds it") : []);
-    describe(optional, "Options");
+    const confirm = tool.requireConfirm ? line("  --confirm", "it runs only with this; --agent never adds it") : [];
+    // A Required section holding only --confirm reads as if nothing else were needed, when a write's body
+    // often comes as flags or as one --payload: Codex then read Wistia's schema to check, one more step.
+    // Alone, --confirm closes the options instead, and the usage line still ends with it.
+    if (required.length) {
+        describe(required, "Required", confirm);
+        describe(optional, "Options");
+    }
+    else {
+        describe(optional, "Options", confirm);
+    }
     if (tool.paginate) {
         lines.push(`Pages:`, ...line("  --all", "follow every page and print all items"), ...line("  --max-items <n>", "stop after this many items"), ``);
     }
@@ -208,13 +217,12 @@ export function renderGeneralHelp(app, bin) {
     const applies = switchesThatApply(app.allTools);
     const cache = app.allTools.some((tool) => tool.cache);
     const sync = app.allTools.some((tool) => tool.sync);
-    const jobs = app.allTools.some((tool) => tool.job);
     // An agent often reads this first and pays for it again on every later step, so the
     // rarely needed commands share one line, an older name for a command is left out, and
     // Slipway's settings past the two safety switches are named on one line.
     const commands = [
         [app.bins.cli, "list the commands"],
-        [`${bin} <command> --help`, "what one takes"],
+        [`${bin} <command> --help`, "what one takes, and its flags"],
         [`${bin} which <words>`, "find the command for a task"],
         [`${bin} doctor${app.definition.doctorNetwork ? "" : " [--network]"}`, "check the setup"],
         typeof app.definition.login === "object"
@@ -261,16 +269,6 @@ export function renderGeneralHelp(app, bin) {
         ...(app.allTools.some((tool) => tool.tags.length > 0) ? [[`${names.toolsets}=a,b`, "only these toolsets, or all"]] : []),
     ];
     const more = tuning.length + 4;
-    // The list formats appear in the help of the commands that list; flags that cannot apply
-    // here (jobs, the cache) are left out. agent-context lists every one.
-    const flags = GLOBAL_FLAGS.map(([flag]) => flag).filter((flag) => flag !== "--agent" &&
-        flag !== "--jsonl" &&
-        flag !== "--csv / --tsv" &&
-        flag !== "--quiet" &&
-        flag !== "--out <file>" &&
-        flag !== "--timeout <ms>" &&
-        (flag !== "--wait" || jobs) &&
-        (flag !== "--refresh" || cache));
     const commandRow = table(commands);
     const settingRow = table(settings);
     const lines = [
@@ -280,8 +278,8 @@ export function renderGeneralHelp(app, bin) {
         ...commands.map(commandRow),
         `  Also: schema <command>, agent-context (all of this as JSON), completion <shell>.`,
         ``,
-        `Flags: ${flags.join(", ")}, and --agent: compact JSON, no prompts, never confirms a write.`,
-        ``,
+        // No flags line: each command's own --help shows the flags it can use, --agent among them,
+        // and an agent reading this first carried those 44 tokens through every later step.
         `Settings:`,
         ...settings.map(settingRow),
         `  And ${more} more, for tuning and --http: agent-context describes each.`,

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.17",
+  "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",