@thenavidm/slipway 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.9, 2026-10-05: what Substack needed
+
+- **A resource can wait for an account.** `listed(env)` leaves a resource out until it returns true. Substack 2.2.3 offered its two resources only once a publication was connected; on Slipway they were always offered, and Claude Code then adds its own two resource tools to every message: 40 tokens in tool search, for reads that could only fail.
+- **The general help keeps its columns narrow.** Commands and settings each line up on their own, and an entry longer than 40 characters puts its help on the next line instead of pushing every other row out to its width. Substack's `login [<publication>] [--paste | --playwriter | --playwright]` started every description in the help at column 80, past the edge of a standard terminal; they now start at 34.
+
+## 0.1.8, 2026-10-05: what Midjourney and Substack needed
+
+- **HTTP checks Origin.** A request whose `Origin` is another site is refused unless `<PREFIX>_HTTP_ALLOWED_ORIGINS` lists it, as the MCP transport spec asks: a page in a browser can send a request to a localhost server, and only that header says where it came from. Clients that are not browsers send none and are unaffected. Substack's own server did this before it moved.
+- **`spends`: a call that costs money.** A paid generation needs confirming, `<PREFIX>_ALLOW_DESTRUCTIVE=0` refuses it, the CLI marks it `$`, and its refusal says it spends money that cannot be refunded, while clients still see a plain write, because making an image destroys nothing. Midjourney's ten generating tools are this.
+- **`flagAliases`: the spellings people already use.** `{ ar: "aspect" }` lets `--ar 16:9` set `aspect` on every command that has it, and help shows the alias beside the flag. `slipway check` fails an alias no input takes.
+- **`synonyms`, stopwords and exact names in search.** An app can map the words its users type onto the words its tools use, for `which` and the search surface; a query of filler words finds nothing instead of everything; and a term that is a tool's name, or a synonym pointing at it, wins outright. Midjourney's "make a picture" finds `imagine`, not `vary_image`.
+- **`--select` reaches into a result list.** When no path starts at the top and a result holds one list of records, the fields are selected inside it and the rest is kept: `--select id` on `{ count, jobs: [...] }` keeps the count and each job's id.
+- **An app command can own a flag Slipway also has.** `flags: ["--out"]` hands `--out` to the command instead of taking it as the global output flag. Midjourney's `capture --out` needs it.
+- **`login --help` prints the steps** for an app whose login is printed steps, not the general help.
+- **A command's own `--help` page reads as a sentence.** The line written for the command table, such as "capture a session for your publication once", starts with a capital and ends with a period on `login --help` and an app command's `--help`.
+- **Every command's `--help` is 10 tokens shorter.** `--select` and `--agent` say what they do in fewer words, and a read says `Risk: read`. Midjourney's `list-jobs --help` had grown 10 tokens on the move and is now the size 1.3.1's was.
+- **The unknown-command hint names one binary.** Typed at the MCP binary it said to list commands with `substack-cli` and find one with `substack-mcp which`; both now name the CLI binary.
+- **`install` says where settings go, not that they must be set.** Most settings are optional, and the notes no longer read as an order to set every one.
+
 ## 0.1.7, 2026-10-05: what Threads and ThriveCart needed, and what Substack and WordPress will
 
 - **`riskFor`: a write whose arguments decide its risk.** Publishing is destructive and saving a draft is a write, from the same tool. `risk` stays the highest a call can be, which is what clients see in annotations and listings; the guard, the approval and the audit log go by the call, and only a destructive call needs confirming. WordPress's post tools need it: 1.1 confirmed publishing and not drafting.

package/README.md

@@ -214,6 +214,7 @@ The context is built on the first call that needs it, never at startup, and so i
 | `risk` | `read`, `write` (easy to undo) or `destructive` (public, irreversible, or both) |
 | `requireConfirm` | Defaults to true for destructive tools. Set it on a write that spends money |
 | `riskFor` | `(args) => risk`, when the arguments decide it: publishing is destructive, saving a draft is a write. `risk` stays the highest, which clients see; the guard, confirmation and audit log go by the call |
+| `spends` | The call spends money or credits, a paid generation: it needs confirming, `<PREFIX>_ALLOW_DESTRUCTIVE=0` refuses it, and the CLI marks it `$`, while clients still see a write |
 | `consequence` | What a confirmed call does, in the tool's own words for the refusal and the approval form: "moves money and cannot be undone". Defaults to "is public or cannot be undone" |
 | `idempotent`, `openWorld` | Annotation hints. Reads are idempotent by default; every tool is open world unless it never leaves the machine |
 | `tags` | Toolsets this tool belongs to. A tool with no tags is always on |
@@ -387,7 +388,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 |
+| `<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> 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 |
@@ -397,7 +398,7 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli> <command>` from `commands` | A terminal command the app adds, such as `logout`. Listed in help and `agent-context`, never sent to an MCP client |
 | `<cli> completion bash` | Tab completion for bash, zsh or fish |
 
-Flags come from the schema: `--flag value`, `--flag=value`, the underscore spelling, `--no-flag` for a boolean, repeated or comma-separated lists of numbers and choices, and JSON or `@file.json` for an object. `--input` takes every argument as one JSON object, from the flag, a file or stdin, and flags on the same line override it.
+Flags come from the schema: `--flag value`, `--flag=value`, the underscore spelling, any name an app's `flagAliases` gives (`{ ar: "aspect" }` for `--ar 16:9`), `--no-flag` for a boolean, repeated or comma-separated lists of numbers and choices, and JSON or `@file.json` for an object. `--input` takes every argument as one JSON object, from the flag, a file or stdin, and flags on the same line override it.
 
 | Output flag | Shape |
 |---|---|
@@ -406,7 +407,7 @@ Flags come from the schema: `--flag value`, `--flag=value`, the underscore spell
 | `--jsonl` | One JSON value per line, for lists |
 | `--csv`, `--tsv` | A table, for lists of records |
 | `--quiet` | One value per line: ids, or the one `--select` field |
-| `--select a,b.c` | Keep only these fields. Dotted paths descend into arrays |
+| `--select a,b.c` | Keep only these fields. Dotted paths descend into arrays, and a field not at the top selects inside the one list a result holds, keeping the rest |
 | `--out <file>` | Write to a new file, readable only by you, never over an existing one |
 | `--wait` | For a job: wait until it finishes |
 | `--refresh` | Skip the local cache and fetch again |
@@ -431,7 +432,7 @@ Errors are JSON on stderr, always, with `error`, `code` and a `hint` that names
 | `<mcp>` | MCP over stdio, what a client launches |
 | `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health`. The app's `httpPort` replaces 8787, for a server that shipped another default |
 
-HTTP binds `127.0.0.1` and checks the Host header, so a web page cannot reach it through a name that resolves to localhost. It refuses to listen on any other address without `<PREFIX>_HTTP_TOKEN`, because anyone who reached the port would act as your account.
+HTTP binds `127.0.0.1` and checks the Host header, so a web page cannot reach it through a name that resolves to localhost, and it refuses a request whose Origin is another site unless `<PREFIX>_HTTP_ALLOWED_ORIGINS` lists it, as the MCP transport spec asks. It refuses to listen on any other address without `<PREFIX>_HTTP_TOKEN`, because anyone who reached the port would act as your account.
 
 Work that belongs to a running server goes in `onServe(ctx, log)`, which runs once the server is answering over either transport and never for a CLI command: a queue that publishes on time, or a warning that a token expires this week. A throw there is logged and the server keeps serving.
 
@@ -560,6 +561,7 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 | `<PREFIX>_HTTP_PORT` | `8787`, or the app's `httpPort` | For `--http` |
 | `<PREFIX>_HTTP_HOST` | `127.0.0.1` | For `--http`. Any other address needs a token |
 | `<PREFIX>_HTTP_TOKEN` | none | Bearer token required by `--http` |
+| `<PREFIX>_HTTP_ALLOWED_ORIGINS` | none | Browser origins beyond localhost that may call `--http`, comma-separated |
 | `<PREFIX>_DEBUG` | `0` | `1` prints debug lines on stderr |
 
 ## Versions
@@ -572,7 +574,10 @@ See [CHANGELOG.md](CHANGELOG.md).
 | --- | --- | --- |
 | [Bluesky](https://github.com/thenavidm/bluesky-mcp-cli) | [`@thenavidm/bluesky-mcp-cli`](https://www.npmjs.com/package/@thenavidm/bluesky-mcp-cli) 2.0.0 | Posting, threads, replies, the timeline, search, feeds, lists, notifications and the social graph |
 | [Mastodon](https://github.com/thenavidm/mastodon-mcp-cli) | [`@thenavidm/mastodon-mcp-cli`](https://www.npmjs.com/package/@thenavidm/mastodon-mcp-cli) 2.0.0 | Posting, editing, threads, timelines, search, lists, notifications and following, on any instance |
+| [Midjourney](https://github.com/thenavidm/midjourney-mcp-cli) | [`@thenavidm/midjourney-mcp-cli`](https://www.npmjs.com/package/@thenavidm/midjourney-mcp-cli) 2.0.0 | Generating images and video, following jobs, downloads, moodboards, the account's library and the explore feeds, through a signed-in browser |
 | [Teachable](https://github.com/thenavidm/teachable-mcp-cli) | [`@thenavidm/teachable-mcp-cli`](https://www.npmjs.com/package/@thenavidm/teachable-mcp-cli) 3.0.0 | Courses, users, enrollments, pricing, coupons and transactions |
+| [Threads](https://github.com/thenavidm/threads-mcp-cli) | [`@thenavidm/threads-mcp-cli`](https://www.npmjs.com/package/@thenavidm/threads-mcp-cli) 2.0.0 | Posting, threads, carousels, replies and reply approvals, insights and keyword search |
+| [ThriveCart](https://github.com/thenavidm/thrivecart-mcp-cli) | [`@thenavidm/thrivecart-mcp-cli`](https://www.npmjs.com/package/@thenavidm/thrivecart-mcp-cli) 3.0.0 | Products and pricing, transactions and revenue, customers, subscriptions and affiliates, across several carts |
 
 Each server was measured against its previous release before it moved: startup, what a client receives, CLI exit codes, and tokens in Claude Code and Codex. Its README has the numbers.
 

package/dist/app.d.ts

@@ -23,6 +23,12 @@ export type ResourceDefinition<Ctx> = {
     mimeType?: string;
     /** A string is sent as text; anything else as JSON. */
     read: (ctx: Ctx) => unknown | Promise<unknown>;
+    /**
+     * False leaves the resource out of the list, such as one that reads an account
+     * nobody has connected yet. A client that sees a resource may list it to the
+     * model on every message, so one that can only fail costs tokens for nothing.
+     */
+    listed?: (env: NodeJS.ProcessEnv) => boolean;
 };
 export type PromptDefinition<Ctx> = {
     name: string;
@@ -79,6 +85,11 @@ export type CliCommand = {
     usage?: string;
     /** One line: what it does. */
     help: string;
+    /**
+     * Flags the command reads itself, such as `--out`, which would otherwise be
+     * taken as Slipway's global flag of the same name before the command sees it.
+     */
+    flags?: readonly string[];
     run: (io: CliIO, args: string[]) => number | Promise<number>;
 };
 export type AppDefinition<Ctx> = {
@@ -147,6 +158,19 @@ export type AppDefinition<Ctx> = {
         help: string;
         run: LoginFlow;
     };
+    /**
+     * Other names a flag answers to, on every command that has the input:
+     * `{ ar: "aspect" }` lets `--ar 16:9` set `aspect`, as Midjourney's own
+     * syntax spells it. Help shows each beside its flag, and `slipway check`
+     * fails one that no tool's input can take.
+     */
+    flagAliases?: Readonly<Record<string, string>>;
+    /**
+     * Words people type, mapped onto words the tools use, for `which` and the
+     * search surface: `{ picture: ["image"] }`. Without them a lookup works only
+     * for someone who already knows the vocabulary.
+     */
+    synonyms?: Readonly<Record<string, readonly string[]>>;
     /**
      * Terminal commands beyond the tools, such as `logout`, `auth` or `refresh`.
      * An MCP client never sees them. Each is listed in help and `agent-context`,

package/dist/check.js

@@ -55,6 +55,20 @@ export async function checkApp(app, options = {}) {
             add("error", "names", `The terminal command '${command.name}' has the name of a built-in or a tool. Rename it.`);
         }
     }
+    for (const [alias, key] of Object.entries(app.definition.flagAliases ?? {})) {
+        const takes = app.allTools.some((tool) => Object.keys(tool.jsonSchema.properties ?? {}).includes(key));
+        if (!takes)
+            add("error", "names", `--${alias} points at '${key}', which no tool's input has.`);
+    }
+    // A synonym pointing at a word no tool uses is a redirect to nowhere that quietly stops matching.
+    const vocabulary = new Set(app.allTools.flatMap((tool) => `${tool.name} ${tool.title} ${tool.description}`.toLowerCase().split(/[^a-z0-9]+/)));
+    for (const [word, targets] of Object.entries(app.definition.synonyms ?? {})) {
+        for (const target of targets) {
+            if (!vocabulary.has(target.toLowerCase()) && !app.allTools.some((tool) => tool.name === target)) {
+                add("warn", "synonyms", `'${word}' points at '${target}', which no tool's name, title or description uses.`);
+            }
+        }
+    }
     const httpPort = app.definition.httpPort;
     if (httpPort !== undefined && (!Number.isInteger(httpPort) || httpPort < 1 || httpPort > 65535)) {
         add("error", "http", `httpPort is ${httpPort}, which is not a port number from 1 to 65535.`);

package/dist/cli/context.d.ts

@@ -34,6 +34,7 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
         title: string;
         risk?: "destructive" | "write" | undefined;
         requires_confirm?: boolean | undefined;
+        spends?: boolean | undefined;
     }[];
 } | {
     name: string;
@@ -96,6 +97,7 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
         description: string;
         risk: import("../tool.js").Risk;
         requires_confirm: boolean;
+        spends?: boolean | undefined;
         toolsets?: readonly string[] | undefined;
         positional?: readonly string[] | undefined;
         flags: {

package/dist/cli/context.js

@@ -51,6 +51,7 @@ export function agentContext(app, env, bin, options = {}) {
                 title: tool.title,
                 ...(tool.risk !== "read" ? { risk: tool.risk } : {}),
                 ...(tool.requireConfirm ? { requires_confirm: true } : {}),
+                ...(tool.spends ? { spends: true } : {}),
             })),
         };
     }
@@ -78,7 +79,7 @@ export function agentContext(app, env, bin, options = {}) {
                 description: setting.description,
             })),
             { env: names.readOnly, value: policy.readOnly, description: "hide and refuse every write" },
-            { env: names.allowDestructive, value: policy.allowDestructive, description: "allow public or irreversible writes" },
+            { env: names.allowDestructive, value: policy.allowDestructive, description: app.allTools.some((tool) => tool.spends) ? "allow public or irreversible writes and paid calls" : "allow public or irreversible writes" },
             ...(app.allTools.some((tool) => tool.tags.length > 0)
                 ? [{ env: names.toolsets, value: policy.toolsets === "all" ? "all" : [...policy.toolsets], description: "toolsets that are on" }]
                 : []),
@@ -89,6 +90,7 @@ export function agentContext(app, env, bin, options = {}) {
             { env: `${app.envPrefix}_HTTP_PORT`, value: env[`${app.envPrefix}_HTTP_PORT`] ?? null, description: `port for --http, ${app.definition.httpPort ?? 8787} when unset` },
             { env: `${app.envPrefix}_HTTP_HOST`, value: env[`${app.envPrefix}_HTTP_HOST`] ?? null, description: "address for --http, 127.0.0.1 when unset; any other needs a token" },
             { env: `${app.envPrefix}_HTTP_TOKEN`, set: Boolean(env[`${app.envPrefix}_HTTP_TOKEN`]), secret: true, description: "bearer token --http requires" },
+            { env: `${app.envPrefix}_HTTP_ALLOWED_ORIGINS`, value: env[`${app.envPrefix}_HTTP_ALLOWED_ORIGINS`] ?? null, description: "browser origins beyond localhost that may call --http, comma-separated" },
             { env: `${app.envPrefix}_DEBUG`, value: /^(1|true|yes)$/i.test(env[`${app.envPrefix}_DEBUG`] ?? ""), description: "print debug lines on stderr" },
         ],
         ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
@@ -101,6 +103,7 @@ export function agentContext(app, env, bin, options = {}) {
             description: tool.description,
             risk: tool.risk,
             requires_confirm: tool.requireConfirm,
+            ...(tool.spends ? { spends: true } : {}),
             ...(tool.tags.length ? { toolsets: tool.tags } : {}),
             ...(tool.positional.length ? { positional: tool.positional } : {}),
             flags: flagsFor(tool.jsonSchema)

package/dist/cli/data.js

@@ -64,7 +64,7 @@ export async function runData(app, io, tokens, options) {
                 const lists = app.allTools.filter((candidate) => candidate.sync).map((candidate) => candidate.command);
                 throw new UsageError(`${tool.command} is not a list that can be synced.`, { hint: `Lists that can: ${lists.join(", ") || "none"}.` });
             }
-            const args = await app.parse(tool, parseToolArgs(flags, flagsFor(tool.jsonSchema), tool.positional));
+            const args = await app.parse(tool, parseToolArgs(flags, flagsFor(tool.jsonSchema), tool.positional, app.definition.flagAliases));
             const report = await syncTool(app, tool, args, {
                 surface: "cli",
                 env: io.env,

package/dist/cli/flags.d.ts

@@ -31,5 +31,5 @@ export declare function parseJsonValue(raw: string, label: string): unknown;
  * positional arguments. The schema validates the result afterwards; this only
  * gets values into the right types and reports mistakes in terms of flags.
  */
-export declare function parseToolArgs(argv: readonly string[], flags: readonly Flag[], positional: readonly string[]): Record<string, unknown>;
+export declare function parseToolArgs(argv: readonly string[], flags: readonly Flag[], positional: readonly string[], aliases?: Readonly<Record<string, string>>): Record<string, unknown>;
 export declare function missingRequired(flags: readonly Flag[], args: Record<string, unknown>): Flag[];

package/dist/cli/flags.js

@@ -118,7 +118,7 @@ function splits(flag) {
  * positional arguments. The schema validates the result afterwards; this only
  * gets values into the right types and reports mistakes in terms of flags.
  */
-export function parseToolArgs(argv, flags, positional) {
+export function parseToolArgs(argv, flags, positional, aliases = {}) {
     const out = {};
     const bare = [];
     const byName = new Map();
@@ -126,6 +126,12 @@ export function parseToolArgs(argv, flags, positional) {
         byName.set(flag.flag, flag);
         byName.set(`--${flag.key}`, flag);
     }
+    // An alias never shadows a real flag of the same name.
+    for (const [alias, key] of Object.entries(aliases)) {
+        const flag = flags.find((candidate) => candidate.key === key);
+        if (flag && !byName.has(`--${alias}`))
+            byName.set(`--${alias}`, flag);
+    }
     const assign = (flag, value) => {
         if (flag.repeatable) {
             const values = Array.isArray(value) ? value : [value];

package/dist/cli/help.d.ts

@@ -12,7 +12,7 @@ export declare const GLOBAL_FLAGS: Array<[string, string]>;
 export declare function renderList(app: App, tools: readonly Tool[], bin: string, env?: NodeJS.ProcessEnv): string;
 /** An example's arguments as the command someone would type. */
 export declare function exampleCommand(bin: string, tool: Tool, args: Record<string, unknown>): string;
-export declare function renderToolHelp(tool: Tool, bin: string): string;
+export declare function renderToolHelp(tool: Tool, bin: string, aliases?: Readonly<Record<string, string>>): string;
 export declare function renderGeneralHelp(app: App, bin: string): string;
 /** One line per tool, for search results and listings. */
 export declare function toolLine(tool: Tool): string;

package/dist/cli/help.js

@@ -9,6 +9,8 @@ import { policyEnvNames, riskMark, visibility } from "../policy.js";
 import { firstSentence } from "../search.js";
 import { flagsFor } from "./flags.js";
 const COLUMN = 30;
+/** The widest entry the general help aligns the others to. */
+const WIDE = 40;
 /** The words the CLI owns, which no tool command may take. */
 export const BUILTINS = ["help", "tools", "schema", "agent-context", "which", "doctor", "login", "completion", "version", "data", "install"];
 export const GLOBAL_FLAGS = [
@@ -17,8 +19,8 @@ export const GLOBAL_FLAGS = [
     ["--jsonl", "one JSON value per line, for lists"],
     ["--csv / --tsv", "a table, for lists of records"],
     ["--quiet", "one value per line: ids, or the one --select field"],
-    ["--select <a,b.c>", "keep only these fields; dotted paths descend"],
-    ["--agent", "JSON, compact, no prompts, no color. Never confirms anything"],
+    ["--select <a,b.c>", "keep only these fields"],
+    ["--agent", "compact JSON, no prompts, never confirms"],
     ["--out <file>", "write the output to a new file instead of stdout"],
     ["--input <json|@file|->", "all arguments as one JSON object; flags override it"],
     ["--dry-run", "check everything and print what would run, without running it"],
@@ -32,7 +34,9 @@ function line(left, help) {
     return left.length < COLUMN ? [`${left.padEnd(COLUMN)}${help}`] : [left, `${" ".repeat(COLUMN)}${help}`];
 }
 function riskWords(tool) {
-    return tool.risk === "read" ? "read only" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
+    if (tool.spends)
+        return "spends money, needs --confirm";
+    return tool.risk === "read" ? "read" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
 }
 /** The output flags a command can use: the four every command takes, and those its kind adds. */
 function outputFlagsFor(tool) {
@@ -92,11 +96,12 @@ export function renderList(app, tools, bin, env = process.env) {
         if (grouped)
             lines.push(``, `  ${group || "general"}${group && toolsets[group] ? `: ${toolsets[group]}` : ""}`);
         for (const tool of members)
-            lines.push(`  ${riskMark(tool.risk)} ${tool.command.padEnd(width)}${tool.title}`);
+            lines.push(`  ${riskMark(tool)} ${tool.command.padEnd(width)}${tool.title}`);
     }
     // The legend says `!` needs --confirm only when that holds for every listed command.
-    const confirmByRisk = tools.every((tool) => tool.requireConfirm === (tool.risk === "destructive"));
-    lines.push(``, `  * writes    ! public or irreversible${confirmByRisk ? ", needs --confirm" : ""}`, ``, `  ${bin} <command> --help    what one takes, with examples`, `  ${bin} which <words>       find the command for a task`, `  ${bin} --help              flags, settings and setup`, ``, ...hiddenNote(app, env));
+    const confirmByRisk = tools.every((tool) => tool.requireConfirm === (tool.risk === "destructive" || tool.spends));
+    const paid = tools.some((tool) => tool.spends) ? "    $ spends money, needs --confirm" : "";
+    lines.push(``, `  * writes    ! public or irreversible${confirmByRisk ? ", needs --confirm" : ""}${paid}`, ``, `  ${bin} <command> --help    what one takes, with examples`, `  ${bin} which <words>       find the command for a task`, `  ${bin} --help              flags, settings and setup`, ``, ...hiddenNote(app, env));
     return lines.join("\n");
 }
 function shellQuote(value) {
@@ -136,7 +141,8 @@ function placeholder(flag) {
         return flag.choices.length <= 6 ? ` <${flag.choices.join("|")}>` : " <choice>";
     return ` <${flag.kind === "json" ? "json|@file" : flag.kind}>`;
 }
-export function renderToolHelp(tool, bin) {
+export function renderToolHelp(tool, bin, aliases = {}) {
+    const aliasOf = (key) => Object.entries(aliases).filter(([, target]) => target === key).map(([alias]) => `, --${alias}`).join("");
     const flags = flagsFor(tool.jsonSchema).filter((flag) => flag.key !== "confirm");
     const required = flags.filter((flag) => flag.required);
     const optional = flags.filter((flag) => !flag.required);
@@ -159,7 +165,7 @@ export function renderToolHelp(tool, bin) {
             const extra = [flag.repeatable ? "Repeatable." : "", flag.default !== undefined ? `Default ${JSON.stringify(flag.default)}.` : ""]
                 .filter(Boolean)
                 .join(" ");
-            lines.push(...line(`  ${flag.flag}${placeholder(flag)}`, [flag.help, extra].filter(Boolean).join(" ")));
+            lines.push(...line(`  ${flag.flag}${aliasOf(flag.key)}${placeholder(flag)}`, [flag.help, extra].filter(Boolean).join(" ")));
         }
         lines.push(...after, ``);
     };
@@ -183,6 +189,15 @@ export function renderToolHelp(tool, bin) {
     lines.push(``, `Risk: ${riskWords(tool)}`, ``);
     return lines.join("\n");
 }
+/**
+ * Two aligned columns. An entry longer than WIDE, such as a login that takes three
+ * flags, puts its help on the next line instead of padding every other row out to
+ * its width: on Substack that padding was a third of the general help's tokens.
+ */
+function table(rows) {
+    const width = Math.max(0, ...rows.map(([left]) => left.length).filter((length) => length <= WIDE)) + 3;
+    return ([left, help]) => (left.length <= WIDE ? `  ${left.padEnd(width)}${help}` : `  ${left}\n  ${" ".repeat(width)}${help}`);
+}
 export function renderGeneralHelp(app, bin) {
     const names = policyEnvNames(app.envPrefix);
     const cache = app.allTools.some((tool) => tool.cache);
@@ -215,7 +230,7 @@ export function renderGeneralHelp(app, bin) {
     const settings = [
         ...(app.definition.settings ?? []).filter((setting) => !setting.tuning).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
-        [`${names.allowDestructive}=0`, "refuse the irreversible writes"],
+        [`${names.allowDestructive}=0`, app.allTools.some((tool) => tool.spends) ? "refuse the irreversible writes and paid calls" : "refuse the irreversible writes"],
         // With no tagged tool every tool is always on, so the switch would do nothing.
         ...(app.allTools.some((tool) => tool.tags.length > 0) ? [[`${names.toolsets}=a,b`, "only these toolsets, or all"]] : []),
         [`${names.surface}=search`, "MCP lists three finder tools instead"],
@@ -224,24 +239,24 @@ export function renderGeneralHelp(app, bin) {
         [`${names.confirm}=model`, "confirm: true alone confirms over MCP"],
         ...(cache ? [[`${names.cache}=0`, "never answer from the local cache"]] : []),
         ...(cache || sync ? [[`${names.dataDir}=<dir>`, "keep local data in this folder"]] : []),
-        [`${app.envPrefix}_HTTP_PORT / _HOST / _TOKEN`, "for --http"],
+        [`${app.envPrefix}_HTTP_PORT / _HOST / _TOKEN / _ALLOWED_ORIGINS`, "for --http"],
         [`${app.envPrefix}_DEBUG=1`, "debug lines on stderr"],
     ];
     // 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 !== "--wait" || jobs) && (flag !== "--refresh" || cache));
-    const width = Math.max(...[...commands, ...settings].map(([left]) => left.length)) + 3;
-    const row = ([left, help]) => `  ${left.padEnd(width)}${help}`;
+    const commandRow = table(commands);
+    const settingRow = table(settings);
     const lines = [
         ``,
         `${app.title} ${app.version}`,
         ``,
-        ...commands.map(row),
+        ...commands.map(commandRow),
         `  Also: schema <command>, agent-context [--brief] (all of this as JSON), completion <shell>.`,
         ``,
         `Flags: ${flags.join(", ")}, and --agent: compact JSON, no prompts, never confirms a write.`,
         ``,
         `Settings:`,
-        ...settings.map(row),
+        ...settings.map(settingRow),
         ...(tuning.length ? [`  Also: ${tuning.join(", ")}, described in agent-context.`] : []),
         ``,
         `Exit codes: ${EXIT.ok} ok, ${EXIT.error} unexpected, ${EXIT.usage} usage or refused, ${EXIT.notFound} not found, ${EXIT.auth} auth, ${EXIT.api} API, ${EXIT.rateLimited} rate limited, ${EXIT.notConfigured} not configured`,
@@ -253,5 +268,5 @@ export function renderGeneralHelp(app, bin) {
 }
 /** One line per tool, for search results and listings. */
 export function toolLine(tool) {
-    return `${riskMark(tool.risk)} ${tool.command}  ${tool.title}: ${firstSentence(tool.description, 80)}`;
+    return `${riskMark(tool)} ${tool.command}  ${tool.title}: ${firstSentence(tool.description, 80)}`;
 }

package/dist/cli/output.js

@@ -16,6 +16,19 @@ export function selectFields(data, paths) {
         return data.map((item) => selectFields(item, paths));
     if (data === null || typeof data !== "object")
         return data;
+    const record = data;
+    // `--select id,status` on `{ count, jobs: [...] }` means the jobs' fields. When no path
+    // starts at the top and the result holds one list of records, select inside it and keep
+    // the rest as it is. A list of plain values, such as image URLs, is not a result set.
+    const heads = paths.map((path) => path.split(".")[0]).filter((head) => Boolean(head));
+    if (heads.length && heads.every((head) => !(head in record))) {
+        const isRecord = (item) => item !== null && typeof item === "object" && !Array.isArray(item);
+        const arrays = Object.entries(record).filter(([, value]) => Array.isArray(value));
+        const lists = arrays.filter(([, value]) => value.length > 0 && value.every(isRecord));
+        const only = lists.length === 1 ? lists[0] : lists.length === 0 && arrays.length === 1 && arrays[0][1].length === 0 ? arrays[0] : undefined;
+        if (only)
+            return { ...record, [only[0]]: only[1].map((item) => selectFields(item, paths)) };
+    }
     // Grouped by first segment: assigning one path at a time let the last path win,
     // so `--select posts.uri,posts.text` returned only the text.
     const byHead = new Map();

package/dist/cli/run.js

@@ -142,7 +142,7 @@ export async function runCli(app, argv, partial = {}) {
     const builtin = command !== undefined && BUILTINS.includes(command);
     const custom = command !== undefined && !builtin ? app.definition.commands?.find((candidate) => candidate.name === command) : undefined;
     const tool = command !== undefined && !builtin && !custom ? app.find(command) : undefined;
-    const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : []);
+    const reserved = new Set(tool ? flagsFor(tool.jsonSchema).map((flag) => flag.flag) : (custom?.flags ?? []));
     let agent = argv.includes("--agent");
     try {
         const { globals, rest } = extractGlobals(at === -1 ? argv : [...argv.slice(0, at), ...argv.slice(at + 1)], reserved);
@@ -158,14 +158,14 @@ export async function runCli(app, argv, partial = {}) {
             return await runBuiltin(app, io, command, rest, globals);
         if (custom) {
             if (globals.help)
-                return print(io, `\nUsage: ${io.bin} ${custom.usage ?? custom.name}\n\n${custom.help}\n`);
+                return print(io, `\nUsage: ${io.bin} ${custom.usage ?? custom.name}\n\n${sentence(custom.help)}\n`);
             return await custom.run(io, rest);
         }
         if (!tool) {
             const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS, ...(app.definition.commands ?? []).map((c) => c.name)];
             const guess = didYouMean(command, candidates);
             throw new UsageError(`Unknown command '${command}'.${guess ? ` Did you mean '${guess}'?` : ""}`, {
-                hint: `Run \`${app.bins.cli}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
+                hint: `Run \`${app.bins.cli}\` to list commands, or \`${app.bins.cli} which <words>\` to find one.`,
             });
         }
         const seen = visibility(tool, app.policy(io.env));
@@ -176,14 +176,14 @@ export async function runCli(app, argv, partial = {}) {
                 : `${tool.command} is in a toolset that is off: ${tool.tags.join(", ")}.`, { hint: seen.reason === "read-only" ? `Unset ${names.readOnly} to allow writes.` : `Add one of them to ${names.toolsets}, or set ${names.toolsets}=all.` });
         }
         if (globals.help)
-            return print(io, renderToolHelp(tool, io.bin));
+            return print(io, renderToolHelp(tool, io.bin, app.definition.flagAliases));
         return await runTool(app, io, tool, rest, globals);
     }
     catch (error) {
         const failure = toSlipwayError(error);
         emitError(io, app, failure, agent);
         if (failure.code === "usage" && tool && !agent && io.isTTY)
-            io.stderr(renderToolHelp(tool, io.bin));
+            io.stderr(renderToolHelp(tool, io.bin, app.definition.flagAliases));
         return failure.exitCode;
     }
 }
@@ -204,7 +204,10 @@ async function runBuiltin(app, io, command, rest, globals) {
         return print(io, (await import("./install.js")).installHelp(app, io.bin));
     const login = app.definition.login;
     if (globals.help && command === "login" && typeof login === "object")
-        return print(io, `\nUsage: ${io.bin} ${login.usage ?? "login"}\n\n${login.help}\n`);
+        return print(io, `\nUsage: ${io.bin} ${login.usage ?? "login"}\n\n${sentence(login.help)}\n`);
+    // Printed steps are their own help.
+    if (globals.help && command === "login" && typeof login === "string")
+        return print(io, login);
     if (globals.help && command !== "help")
         return print(io, renderGeneralHelp(app, io.bin));
     const target = rest.find((token) => !token.startsWith("-"));
@@ -219,7 +222,7 @@ async function runBuiltin(app, io, command, rest, globals) {
             const tool = app.find(target);
             if (!tool)
                 throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
-            return print(io, renderToolHelp(tool, io.bin));
+            return print(io, renderToolHelp(tool, io.bin, app.definition.flagAliases));
         }
         case "schema": {
             const tool = target ? app.find(target) : undefined;
@@ -240,7 +243,7 @@ async function runBuiltin(app, io, command, rest, globals) {
                 throw new UsageError("which expects the words for what you want to do: which schedule a post");
             // Only the close matches: on Threads the right command scored 20 and the eighth 9, and the
             // ten-line list cost an agent more to read than the answer was worth.
-            const found = searchTools(app.tools(io.env), query, 10);
+            const found = searchTools(app.tools(io.env), query, 10, app.definition.synonyms);
             const best = found[0]?.score ?? 0;
             const matches = found.filter(({ score }, index) => index < 3 || score >= best / 2);
             if (globals.format !== "auto") {
@@ -285,7 +288,7 @@ async function readInput(io, raw) {
 async function runTool(app, io, tool, rest, globals) {
     const flags = flagsFor(tool.jsonSchema);
     const base = globals.input ? await readInput(io, globals.input) : {};
-    const args = { ...base, ...parseToolArgs(rest, flags, tool.positional) };
+    const args = { ...base, ...parseToolArgs(rest, flags, tool.positional, app.definition.flagAliases) };
     if (globals.confirm && tool.requireConfirm)
         args.confirm = true;
     const missing = missingRequired(flags, args).filter((flag) => !(globals.all && tool.paginate && flag.key === tool.paginate.cursorArg));
@@ -361,3 +364,10 @@ function writeOut(io, globals, tool, result) {
     io.stdout(`${JSON.stringify({ saved: globals.out, bytes: Buffer.byteLength(text) })}\n`);
     return EXIT.ok;
 }
+/** A help line written for the command table reads as a sentence on its own `--help` page. */
+function sentence(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return trimmed;
+    return `${trimmed[0].toUpperCase()}${trimmed.slice(1)}${/[.!?:]$/.test(trimmed) ? "" : "."}`;
+}

package/dist/confirm.d.ts

@@ -64,7 +64,7 @@ export declare const verifyApprovalState: (state: string, ctx: ServerContext) =>
  * form by itself (Codex accepts a form that has no fields), and one that fills
  * in defaults would otherwise approve with them.
  */
-export declare function approvalForm(appTitle: string, tool: Pick<Tool, "risk">, summary: string): {
+export declare function approvalForm(appTitle: string, tool: Pick<Tool, "risk" | "consequence" | "spends">, summary: string): {
     message: string;
     requestedSchema: {
         type: "object";

package/dist/docs.js

@@ -52,7 +52,7 @@ export function settingsTable(app) {
         "|---|---|",
         ...(app.definition.settings ?? []).map((setting) => `| \`${setting.env}\` | ${cell(setting.description)}${setting.secret ? " Keep it private." : ""} |`),
         `| \`${names.readOnly}=1\` | Hide and refuse every write |`,
-        `| \`${names.allowDestructive}=0\` | Keep writes, refuse the public or irreversible ones |`,
+        `| \`${names.allowDestructive}=0\` | Keep writes, refuse the public or irreversible ones${app.allTools.some((tool) => tool.spends) ? " and paid calls" : ""} |`,
         `| \`${names.toolsets}\` | Comma-separated toolsets to turn on, or \`all\` |`,
         `| \`${names.surface}=search\` | List three tools that find, describe and run the rest |`,
         `| \`${names.auditLog}\` | File that records every attempted write |`,

package/dist/doctor.js

@@ -16,7 +16,8 @@ export async function runDoctor(app, io, options) {
     const major = Number(process.versions.node.split(".")[0]);
     checks.push({ name: "Node.js", ok: major >= 22, detail: `v${process.versions.node}`, ...(major >= 22 ? {} : { fix: "Install Node.js 22 or later." }) });
     checks.push({ name: "Version", ok: true, detail: `${app.name} ${app.version}` });
-    const writes = policy.readOnly ? "off (read-only)" : policy.allowDestructive ? "on" : "on, irreversible ones refused";
+    const paid = app.allTools.some((tool) => tool.spends) ? " and paid" : "";
+    const writes = policy.readOnly ? "off (read-only)" : policy.allowDestructive ? "on" : `on, irreversible${paid} ones refused`;
     checks.push({ name: "Writes", ok: true, detail: writes });
     checks.push({
         name: "Tools",

package/dist/guard.d.ts

@@ -43,4 +43,4 @@ export declare class Guard {
     record(tool: Tool, summary: string, outcome: GuardOutcome | "failed" | "done" | "started", confirmedBy?: ConfirmedBy): void;
 }
 /** Why a tool needs confirming, in the words a refusal and an approval form both use. */
-export declare function consequence(tool: Pick<Tool, "risk" | "consequence">): string;
+export declare function consequence(tool: Pick<Tool, "risk" | "consequence" | "spends">): string;

package/dist/guard.js

@@ -41,10 +41,10 @@ export class Guard {
                 hint: `Unset ${names.readOnly} to allow writes.`,
             });
         }
-        if (tool.risk === "destructive" && !this.policy.allowDestructive) {
+        if ((tool.risk === "destructive" || tool.spends) && !this.policy.allowDestructive) {
             this.record(tool, summary, "blocked: destructive disabled");
             throw new RefusedError(`${tool.name} is unavailable: this server is running with ${names.allowDestructive}=0.`, {
-                hint: `Unset ${names.allowDestructive} to allow irreversible writes.`,
+                hint: `Unset ${names.allowDestructive} to allow irreversible writes${tool.spends ? " and paid calls" : ""}.`,
             });
         }
     }
@@ -87,5 +87,7 @@ export class Guard {
 export function consequence(tool) {
     if (tool.consequence)
         return tool.consequence;
+    if (tool.spends)
+        return "spends money and cannot be refunded";
     return tool.risk === "destructive" ? "is public or cannot be undone" : "has an effect that cannot be taken back";
 }

package/dist/install.js

@@ -215,7 +215,7 @@ export function planInstall(app, options, context) {
     if (client === "claude-code") {
         const entry = { type: "stdio", command: launch.command, args: launch.args };
         if (variables.length)
-            notes.push(`Claude Code passes its own environment to the server: set ${list(variables)} in the shell you start Claude Code from.`);
+            notes.push(`Claude Code passes its own environment to the server, so whichever of ${list(variables)} you use go in the shell you start Claude Code from.`);
         return { client, scope, name, entry, env, notes, run: { command: "claude", args: ["mcp", "add-json", name, JSON.stringify(entry), "--scope", scope] } };
     }
     if (client === "codex") {
@@ -223,7 +223,7 @@ export function planInstall(app, options, context) {
         const before = existsSync(file) ? readFileSync(file, "utf8") : "";
         const text = upsertCodexServer(before, name, launch, variables, usesNpx);
         if (variables.length)
-            notes.push(`Codex passes ${list(variables)} on from its own environment: set ${them(variables)} where you start Codex.`);
+            notes.push(`Codex passes ${list(variables)} on from its own environment, so whichever you use go where you start Codex.`);
         if (scope === "project")
             notes.push("Codex reads a project's .codex/config.toml only once the project is trusted.");
         const entry = upsertCodexServer("", name, launch, variables, usesNpx).trim();
@@ -290,7 +290,7 @@ export function planInstall(app, options, context) {
         if (env.copied.length)
             notes.push(`Copied ${list(env.copied)} from this shell into ${file}, which is now readable by you only.`);
         if (env.toAdd.length) {
-            notes.push(`Claude Desktop does not read a shell's environment. Add ${list(env.toAdd)} to the env of "${name}" in ${file}, or run install again with --copy-env to copy ${them(env.toAdd)} from this shell.`);
+            notes.push(`Claude Desktop does not read a shell's environment, so whichever of ${list(env.toAdd)} you use go in the env of "${name}" in ${file}, or run install again with --copy-env to copy them from this shell.`);
         }
     }
     return { client, scope, name, file, entry: server, text: `${JSON.stringify(next, null, 2)}\n`, env, notes };

package/dist/policy.d.ts

@@ -63,4 +63,7 @@ export type Visibility = {
 };
 /** Whether a tool is on under this policy, and if not, why, so a refusal can say how to turn it on. */
 export declare function visibility(tool: Pick<Tool, "risk" | "tags">, policy: Policy): Visibility;
-export declare function riskMark(risk: Risk): string;
+export declare function riskMark(tool: {
+    risk: Risk;
+    spends?: boolean;
+}): string;

package/dist/policy.js

@@ -69,6 +69,6 @@ export function visibility(tool, policy) {
     }
     return { visible: true };
 }
-export function riskMark(risk) {
-    return risk === "read" ? " " : risk === "destructive" ? "!" : "*";
+export function riskMark(tool) {
+    return tool.spends ? "$" : tool.risk === "read" ? " " : tool.risk === "destructive" ? "!" : "*";
 }

package/dist/search.d.ts

@@ -10,7 +10,7 @@ export type Match = {
     tool: Tool;
     score: number;
 };
-export declare function searchTools(tools: readonly Tool[], query: string, limit?: number): Match[];
+export declare function searchTools(tools: readonly Tool[], query: string, limit?: number, synonyms?: Readonly<Record<string, readonly string[]>>): Match[];
 /** Edit distance, for "did you mean" on a mistyped command. */
 export declare function distance(a: string, b: string): number;
 export declare function didYouMean(input: string, candidates: readonly string[]): string | undefined;

package/dist/search.js

@@ -5,6 +5,11 @@
  * from the words someone would use to ask for it. The same ranking answers
  * `which` in a terminal and `search_tools` for a model.
  */
+/** Words a query carries that say nothing about which tool: "how do I get my images". */
+const STOP_WORDS = new Set([
+    "the", "my", "me", "to", "of", "for", "in", "on", "and", "or", "how", "do", "does", "can", "want",
+    "with", "from", "is", "are", "it", "that", "this", "what", "which", "any", "some", "please", "an",
+]);
 function words(text) {
     return text
         .toLowerCase()
@@ -12,6 +17,13 @@ function words(text) {
         .filter((word) => word.length > 1)
         .map(stem);
 }
+function queryWords(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 1 && !STOP_WORDS.has(word))
+        .map(stem);
+}
 /** Close enough for matching "posts" to "post" and "scheduling" to "schedul". */
 function stem(word) {
     if (word.length > 4 && word.endsWith("ies"))
@@ -48,23 +60,32 @@ const RELATED = new Map();
 for (const group of SYNONYMS)
     for (const word of group)
         RELATED.set(word, [...new Set([...(RELATED.get(word) ?? []), ...group])]);
-function hits(query, haystack) {
+function hits(query, haystack, extra) {
     const direct = exact(query, haystack);
     if (direct > 0)
         return direct;
     // A synonym counts for a little less than the word itself, so an exact match still wins.
-    return (RELATED.get(query) ?? []).some((word) => word !== query && exact(word, haystack) === 1) ? 0.75 : 0;
+    const related = [...(RELATED.get(query) ?? []), ...(extra?.get(query) ?? [])];
+    return related.some((word) => word !== query && exact(word, haystack) === 1) ? 0.75 : 0;
 }
 function exact(query, haystack) {
     if (haystack.includes(query))
         return 1;
     return haystack.some((word) => word.startsWith(query) || query.startsWith(word)) ? 0.5 : 0;
 }
-export function searchTools(tools, query, limit = 10) {
-    const terms = [...new Set(words(query))];
+export function searchTools(tools, query, limit = 10, synonyms = {}) {
+    const terms = [...new Set(queryWords(query))];
     if (terms.length === 0)
         return [];
     const phrase = query.trim().toLowerCase();
+    const extra = new Map();
+    const pointsAt = new Map();
+    for (const [word, targets] of Object.entries(synonyms)) {
+        extra.set(stem(word.toLowerCase()), targets.flatMap(words));
+        pointsAt.set(stem(word.toLowerCase()), targets.map((target) => target.toLowerCase()));
+    }
+    // A synonym can point straight at a tool's name, "redo" at `rerun_job`.
+    const named = (tool, term) => [term, ...(pointsAt.get(term) ?? [])].some((word) => word === tool.name || word === tool.name.replace(/_/g, ""));
     const scored = tools.map((tool) => {
         const name = words(tool.name);
         const title = words(tool.title);
@@ -73,7 +94,8 @@ export function searchTools(tools, query, limit = 10) {
         let score = 0;
         let matched = 0;
         for (const term of terms) {
-            const got = hits(term, name) * 5 + hits(term, title) * 4 + hits(term, tags) * 3 + hits(term, description);
+            // 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, description, extra);
             if (got > 0)
                 matched++;
             score += got;

package/dist/serve.d.ts

@@ -21,6 +21,8 @@ export type HttpOptions = {
     host: string;
     port: number;
     token?: string;
+    /** Browser origins beyond localhost that may call the server, from `<PREFIX>_HTTP_ALLOWED_ORIGINS`. */
+    allowedOrigins?: readonly string[];
 };
 export declare function httpOptions(app: App, env: NodeJS.ProcessEnv, argv: string[]): HttpOptions;
 /**

package/dist/serve.js

@@ -62,9 +62,21 @@ export function httpOptions(app, env, argv) {
         host: env[`${app.envPrefix}_HTTP_HOST`]?.trim() || "127.0.0.1",
         port,
         token: env[`${app.envPrefix}_HTTP_TOKEN`]?.trim() || undefined,
+        allowedOrigins: (env[`${app.envPrefix}_HTTP_ALLOWED_ORIGINS`] ?? "")
+            .split(",")
+            .map((origin) => origin.trim().replace(/\/$/, ""))
+            .filter(Boolean),
     };
 }
 const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+function localOrigin(origin) {
+    try {
+        return LOOPBACK.has(new URL(origin).hostname);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Serve over Streamable HTTP, for a machine that is always on.
  *
@@ -112,6 +124,14 @@ async function handle(app, fetchMcp, options, loopback, req, res) {
         res.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: "forbidden host" }));
         return;
     }
+    // The MCP transport spec asks every server to check Origin: a page on another
+    // site can send a request here that a browser lets through, and only the
+    // Origin header says where it came from. Clients that are not browsers send none.
+    const origin = req.headers.origin;
+    if (origin && !localOrigin(origin) && !(options.allowedOrigins ?? []).includes(origin.replace(/\/$/, ""))) {
+        res.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: `Origin ${origin} is not allowed. Add it to ${app.envPrefix}_HTTP_ALLOWED_ORIGINS if this is deliberate.` }));
+        return;
+    }
     if (url.pathname === "/health") {
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({ ok: true, name: app.name, version: app.version, tools: app.tools().length }));

package/dist/server.js

@@ -69,7 +69,8 @@ export function buildServer(app, env) {
         for (const tool of app.tools(env))
             registerTool(server, app, tool, env, policy);
     for (const resource of app.definition.resources ?? [])
-        registerResource(server, app, resource, env);
+        if (resource.listed?.(env) ?? true)
+            registerResource(server, app, resource, env);
     for (const prompt of app.definition.prompts ?? [])
         registerPrompt(server, app, prompt, env);
     return server;
@@ -146,7 +147,7 @@ function registerSearchSurface(server, app, env, policy) {
         }),
         annotations: { title: "Find a tool", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async ({ query, limit }) => {
-        const matches = searchTools(visible(), query, limit ?? 10).map(({ tool }) => ({
+        const matches = searchTools(visible(), query, limit ?? 10, app.definition.synonyms).map(({ tool }) => ({
             name: tool.name,
             title: tool.title,
             risk: tool.risk,

package/dist/tool.d.ts

@@ -111,6 +111,13 @@ export type ToolDefinition<Ctx, I extends Schema, O extends Schema | undefined>
      * call needs confirming.
      */
     riskFor?: (args: InferOutput<I>) => Risk;
+    /**
+     * The call spends money or credits: a paid generation, a billed send. It
+     * needs confirming, `<PREFIX>_ALLOW_DESTRUCTIVE=0` refuses it, and the CLI
+     * marks it `$`, while clients still see a plain write, because making an
+     * image destroys nothing.
+     */
+    spends?: boolean;
     /**
      * What a confirmed call does that cannot be taken back, as the refusal and
      * the approval form put it: "moves money and cannot be undone". Defaults to
@@ -160,6 +167,8 @@ export type Tool<Ctx = any> = {
     readonly idempotent: boolean;
     readonly openWorld: boolean;
     readonly requireConfirm: boolean;
+    /** The call spends money or credits. */
+    readonly spends: boolean;
     /** The risk of one call, from its arguments. `forCall` applies it. */
     readonly riskFor?: (args: any) => Risk;
     /** What a confirmed call does that cannot be taken back, in the tool's own words. */

package/dist/tool.js

@@ -36,6 +36,8 @@ export function defineTool(definition) {
     }
     if (typeof definition.handler !== "function")
         throw new Error(`${where}: handler is required.`);
+    if (definition.spends && definition.risk === "read")
+        throw new Error(`${where}: a read cannot spend; make it a write.`);
     if (definition.riskFor !== undefined) {
         if (typeof definition.riskFor !== "function")
             throw new Error(`${where}: riskFor must be a function of the arguments.`);
@@ -81,7 +83,7 @@ export function defineTool(definition) {
         if (own.includes(name))
             throw new Error(`${where}: '${name}' is Slipway's own argument. Rename the input property.`);
     }
-    const requireConfirm = definition.requireConfirm ?? definition.risk === "destructive";
+    const requireConfirm = definition.requireConfirm ?? (definition.risk === "destructive" || definition.spends === true);
     const schema = withControls(input, {
         confirm: requireConfirm,
         ...(job ? { wait: { defaultSeconds: waitSecondsFor(job), maxSeconds: MAX_WAIT_SECONDS } } : {}),
@@ -105,6 +107,7 @@ export function defineTool(definition) {
         idempotent: definition.idempotent ?? definition.risk === "read",
         openWorld: definition.openWorld ?? true,
         requireConfirm,
+        spends: definition.spends === true,
         ...(definition.riskFor ? { riskFor: definition.riskFor } : {}),
         ...(definition.consequence?.trim() ? { consequence: definition.consequence.trim().replace(/\.$/, "") } : {}),
         tags: Object.freeze([...(definition.tags ?? [])]),
@@ -178,5 +181,5 @@ export function forCall(tool, args) {
     }
     if (risk === tool.risk)
         return tool;
-    return { ...tool, risk, requireConfirm: tool.requireConfirm && risk === "destructive" };
+    return { ...tool, risk, requireConfirm: tool.requireConfirm && (risk === "destructive" || tool.spends) };
 }

package/package.json

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