@thenavidm/slipway 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed in Slipway, newest first.
 
+## 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.
+
 ## 0.1.16, 2026-10-05: what Flodesk needed
 
 - **`which` says a title once.** Each answer line printed a tool's title and then the first sentence of its description, and many descriptions open with the title itself: 24 of Flodesk's 32 tools, 10 of Firefly's 14, and nearly every tool on Beehiiv, Calendly and Circle. Where the sentence opens with the title's words, the line now prints the sentence alone. Flodesk's answer to `which add a subscriber to a segment` goes from 52 tokens to 36 and Firefly's to `which image model 5` from 90 to 77, and an agent carries that answer through each step after it. A description that adds something new still follows its title.

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

@@ -94,12 +94,14 @@ export function searchTools(tools, query, limit = 10, synonyms = {}) {
         const tags = tool.tags.flatMap(words);
         const description = words(tool.description);
         // What a tool takes says what it is for: `channelId` and `schedulingType` find the post tool for "schedule a post to a channel".
+        // Only the words themselves count there. Through a synonym, Google Photos' "photos" read as `media_item_id`
+        // and put get_media_item level with the picker for "let me choose photos".
         const args = Object.keys(tool.jsonSchema.properties ?? {}).filter((key) => key !== "confirm").flatMap(words);
         let score = 0;
         let matched = 0;
         for (const term of terms) {
             // A term that is the tool's name is not a hint, it is the answer.
-            const got = (named(tool, term) ? 20 : 0) + hits(term, name, extra) * 5 + hits(term, title, extra) * 4 + hits(term, tags, extra) * 3 + hits(term, args, extra) * 2 + hits(term, description, extra);
+            const got = (named(tool, term) ? 20 : 0) + hits(term, name, extra) * 5 + hits(term, title, extra) * 4 + hits(term, tags, extra) * 3 + exact(term, args) * 2 + hits(term, description, extra);
             if (got > 0)
                 matched++;
             score += got;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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",