@thenavidm/slipway 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.6, 2026-10-05: what Mastodon's move needed
+
+- **`login` runs the app's own sign-in, with the words after it.** `mastodon-cli login mastodon.social --oob` hands `mastodon.social --oob` to Mastodon's flow, which registers an app on that instance and signs in. A flow given with `usage` and `help` shows them in help, `login --help` and `agent-context`, so nobody has to guess that it takes an instance.
+- **Terminal commands beside the tools.** `commands` adds commands such as `logout` to the CLI only. Each is listed in help, `agent-context` and tab completion, `slipway check` fails one named like a built-in or a tool, and an MCP client never sees it.
+- **Tuning stays out of the way.** A setting marked `tuning: true`, such as a timeout with a working default, is named on one line of help and left out of what `install` writes. On Mastodon, `install claude-code` told people to set 13 variables and now names the 6 that connect an account, and the general help is 64 tokens shorter.
+- **`httpPort` sets the default port for `--http`.** A server that shipped another default, such as 8000, keeps it after the move; `<PREFIX>_HTTP_PORT` and `--port` still override it.
+- **`doctorNetwork` calls the service on every `doctor`.** Doctor stays local unless `--network` is passed, which keeps it quick and spends no requests. Mastodon's most common failure is a token without the `write` scope, which only a request finds, and its docs have always told people to run plain `doctor` for it.
+- **The MCP binary's help names the CLI binary for the command list.** `mastodon-mcp --help` said a bare `mastodon-mcp` lists the commands, when it starts the server. Every hint that says where to list the commands now names the CLI binary.
+- **Advertised schemas leave out Zod 4's safe-integer bounds.** Zod 4 gives every whole number `maximum: 9007199254740991` and its negative unless the schema sets its own. They tell a client nothing, so they are left out of what it receives; three were in Mastodon's tool list. Validation still runs on the full schema.
+
+## 0.1.5, 2026-10-04: what Bluesky's move found
+
+- **A request that never got an answer exits 5.** A failed fetch, a refused connection or a DNS failure mapped to exit 1, "unexpected error", so a script that retries on 5 gave up instead. Bluesky 1.2.3 exited 5 for an unreachable host, 0.1.4 made it 1, and it is 5 again.
+- **`--help` and `agent-context` list every variable Slipway reads**, `<PREFIX>_HTTP_PORT`, `_HOST`, `_TOKEN` and `_DEBUG` included. Bluesky's own help listed the HTTP ones before it moved.
+- **A shorter general help.** An agent often reads it first and pays for it again on every later step. The header drops the description, the rarely needed commands share one line, and Slipway's own settings say only what they do: Bluesky's went from 780 tokens to 667.
+- **The command list says `!` needs `--confirm`** when that is true of every command it lists.
+- **The entry turns on Node's compile cache.** The README's `src/index.ts` loads the app after `module.enableCompileCache()`, so every launch after the first skips compiling it: Bluesky answers a client in 183 ms instead of 204. Node before 22.8 starts as before.
+- **The README says what happens to a piped request after stdin closes.** The server stops without answering, as the MCP stdio binding asks; keep stdin open until you read the answer.
+
 ## 0.1.4, 2026-10-04: faster starts, cheaper results in Codex
 
 - **A JSON Schema compiles on its tool's first call.** `jsonSchema()` compiled its validator as soon as a tool was defined, so a server paid for every schema before it could answer. On Teachable's 123 contract tools that held the first answer back by 118 ms. Building Stripe's 611 OpenAPI tools took 1,745 ms and now takes 69; GitHub's 1,230 took 646 ms and now take 60 (medians of three runs on one Mac). A tool's first call now compiles its own schema, a median of 3 ms on Stripe's and under 1 ms on GitHub's.

package/README.md

@@ -174,11 +174,15 @@ export const app = slipway<Context>({
 
 ```ts
 #!/usr/bin/env node
-import { app } from "./app.js";
+import * as nodeModule from "node:module";
 
+nodeModule.enableCompileCache?.();
+const { app } = await import("./app.js");
 await app.main();
 ```
 
+The app loads after Node's compile cache goes on, so every launch after the first skips compiling it again: Bluesky answers a client in 183 ms instead of 204. Node before 22.8 has no compile cache and starts as before, and `NODE_DISABLE_COMPILE_CACHE=1` turns it off.
+
 **`src/npx.ts`** is what `npx -y @you/notes-mcp-cli` runs:
 
 ```ts
@@ -384,10 +388,11 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli> which <words>` | Find the command for a task, by what it does |
 | `<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 |
-| `<cli> login` | How to connect an account |
+| `<cli> doctor` | Check the setup. `--network` also calls the service, which an app with `doctorNetwork` does every time |
+| `<cli> login` | How to connect an account: printed steps, or the app's own sign-in flow with the words after `login` |
 | `<cli> install <client>` | Add the MCP server to a client. See [Add it to a client](#10-add-it-to-a-client) |
 | `<cli> data` | The local cache and synced lists: `sync`, `search`, `sql`, `clear` |
+| `<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.
@@ -422,7 +427,7 @@ Errors are JSON on stderr, always, with `error`, `code` and a `hint` that names
 | Run | Serves |
 |---|---|
 | `<mcp>` | MCP over stdio, what a client launches |
-| `<mcp> --http [--port 8787]` | Streamable HTTP at `/mcp`, with `/health` |
+| `<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.
 
@@ -453,7 +458,7 @@ notes-cli install cursor --dry-run
 | `vscode` | `.vscode/mcp.json` | VS Code asks for each credential once and stores it securely |
 | `gemini` | `~/.gemini/settings.json`, or `.gemini/settings.json` | `${NAME}` references, which Gemini CLI needs to pass anything named like a key |
 
-A published server is started with `npx --package=<package>@latest <name>-mcp`, so a client picks up every release on its next start, with Codex's startup timeout raised for the download. The binary is named, because npx alone starts whichever binary a package lists first. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup.
+A published server is started with `npx --package=<package>@latest <name>-mcp`, so a client picks up every release on its next start, with Codex's startup timeout raised for the download. The binary is named, because npx alone starts whichever binary a package lists first. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup. A setting marked `tuning: true`, such as a timeout with a working default, stays out of the entry, so it carries only what connects an account.
 
 ## 11. Large catalogs
 
@@ -530,11 +535,12 @@ const mcp = await connect(app, { era: "modern", elicit: () => ({ action: "accept
 | Codex shows the server as failed at startup | The first npx download outlasted 10 seconds | `install codex` sets `startup_timeout_sec = 60`; add it by hand to an older entry |
 | `slipway check` warns about schema size | One tool's schema is large or repeats its definitions | Send the body schema once, or advertise a short one and validate the full one in the handler |
 | `slipway check` cannot load the app | The module starts the server when imported | Export the app from `app.ts` and call `app.main()` only in `index.ts` |
+| A request piped to the server gets no answer | Stdin closed before the answer, and the MCP stdio binding stops a server when its input ends | Keep stdin open until you read the answer, as clients do, or run the command from the CLI |
 | `npx slipway` prints something unexpected | Slipway is not installed in this folder, so npx fetched an unrelated package called `slipway` | Run `npm install @thenavidm/slipway`, or `npx -p @thenavidm/slipway slipway <command>` |
 
 ## Environment variables
 
-Every server reads these, under its own prefix: the app name in capitals, `NOTES` for `notes`, unless `envPrefix` says otherwise. A server's own settings, declared with `settings`, are listed in its help, its `agent-context` and its generated docs.
+Every server reads these, under its own prefix: the app name in capitals, `NOTES` for `notes`, unless `envPrefix` says otherwise. A server's own settings, declared with `settings`, are listed in its help, its `agent-context` and its generated docs, and `install` passes on every one not marked `tuning`.
 
 | Variable | Default | What it does |
 |---|---|---|
@@ -547,7 +553,7 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 | `<PREFIX>_TOOLSETS` | `all` | Comma-separated toolsets to turn on |
 | `<PREFIX>_SURFACE` | `full` | `search` lists three tools that find, describe and run the rest |
 | `<PREFIX>_TOOL_TIMEOUT_MS` | none | Give up on any tool after this long |
-| `<PREFIX>_HTTP_PORT` | `8787` | For `--http` |
+| `<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>_DEBUG` | `0` | `1` prints debug lines on stderr |
@@ -556,6 +562,15 @@ Every server reads these, under its own prefix: the app name in capitals, `NOTES
 
 See [CHANGELOG.md](CHANGELOG.md).
 
+## Servers built on Slipway
+
+| Server | Package | Covers |
+| --- | --- | --- |
+| [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 |
+| [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 |
+
+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.
+
 ## 15. FAQ ❓
 
 <details>

package/SKILL.md

@@ -22,7 +22,7 @@ Run `npm ls @thenavidm/slipway` in the repo. If it does not list a version, STOP
 |---|---|---|
 | `src/tools.ts` | The tools, from `toolkit<Context>().defineTool` | One `defineTool` per action |
 | `src/app.ts` | `export const app = slipway({...})` | Describes only. Never calls `main()`, so checks and tests can import it |
-| `src/index.ts` | `await app.main()` | The only file that starts anything. Both binaries point at it |
+| `src/index.ts` | `nodeModule.enableCompileCache?.()`, then `await import("./app.js")` and `app.main()` | The only file that starts anything. Both binaries point at it. The cache goes on before the app loads, so later launches skip compiling it |
 | `src/npx.ts` | `import "./index.js";` | What `npx -y <package>` runs. Its binary is named after the package |
 
 `package.json` declares `"<name>-mcp"` and `"<name>-cli"` on `dist/index.js`, and a third binary named after the package (`"<name>-mcp-cli"`) on `dist/npx.js`. npx only picks a binary by name when they point to different files; otherwise it takes whichever one the registry lists first, which may be the CLI.

package/dist/app.d.ts

@@ -48,6 +48,13 @@ export type ServiceSetting = {
     description: string;
     /** A credential: shown as set or unset, never printed. */
     secret?: boolean;
+    /**
+     * Tuning with a working default, such as a timeout or a retry count, or a
+     * second name for another setting. Listed in help and `agent-context`, but
+     * `install` leaves it out, so a client entry and its instructions hold only
+     * what connects an account.
+     */
+    tuning?: boolean;
 };
 export type CliIO = {
     stdout: (text: string) => void;
@@ -62,6 +69,18 @@ export type CliIO = {
     /** The folder a project-scoped `install` writes into. Defaults to the current one. */
     cwd?: string;
 };
+/** An interactive sign-in. It gets the words after `login` and returns an exit code. */
+export type LoginFlow = (io: CliIO, args: string[]) => number | Promise<number>;
+/** A terminal-only command an app adds beside its tools. */
+export type CliCommand = {
+    /** The word typed after the binary: `logout`. Must not be a tool's command or a built-in. */
+    name: string;
+    /** What it takes, as help shows it: `logout [<handle>]`. Defaults to the name. */
+    usage?: string;
+    /** One line: what it does. */
+    help: string;
+    run: (io: CliIO, args: string[]) => number | Promise<number>;
+};
 export type AppDefinition<Ctx> = {
     /** The service slug: "bluesky". Binaries default to bluesky-mcp and bluesky-cli. */
     name: string;
@@ -83,6 +102,12 @@ export type AppDefinition<Ctx> = {
     };
     /** The npm package that ships the binaries, so `install` can have a client start it with npx. */
     package?: string;
+    /**
+     * The port `--http` listens on when neither `--port` nor `<PREFIX>_HTTP_PORT`
+     * names one. 8787 when unset; a server that already shipped another default
+     * keeps it here.
+     */
+    httpPort?: number;
     /**
      * Builds what handlers need: an API client, config, accounts. Called once,
      * on the first call that needs it, so `--help` works with nothing configured.
@@ -93,12 +118,34 @@ export type AppDefinition<Ctx> = {
     prompts?: readonly PromptDefinition<Ctx>[];
     /** Whether any credentials are set. False makes `doctor` exit 10 and the server warn at startup. */
     configured?: (ctx: Ctx) => boolean | Promise<boolean>;
-    /** Service checks for `doctor`. `network` is true only when the person passed --network. */
+    /** Service checks for `doctor`. `network` is true only when the person passed --network, or `doctorNetwork` is set. */
     doctor?: (ctx: Ctx, options: {
         network: boolean;
     }) => DoctorCheck[] | Promise<DoctorCheck[]>;
-    /** How to sign in: printed instructions, or an interactive flow that returns an exit code. */
-    login?: string | ((io: CliIO) => number | Promise<number>);
+    /**
+     * Call the service on every `doctor`, not only with --network. Off by
+     * default, so doctor stays quick and spends no requests; on for a service
+     * whose most common failure only a request finds, such as a token missing
+     * a scope.
+     */
+    doctorNetwork?: boolean;
+    /**
+     * How to sign in: printed instructions, or an interactive flow that returns an
+     * exit code. A flow gets the words after `login`: `mastodon-cli login mastodon.social`.
+     * A flow given with `usage` and `help` shows them in help, `login --help` and
+     * `agent-context`, so nobody has to guess that it takes an instance.
+     */
+    login?: string | LoginFlow | {
+        usage?: string;
+        help: string;
+        run: LoginFlow;
+    };
+    /**
+     * 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`,
+     * and gets the words after its name.
+     */
+    commands?: readonly CliCommand[];
     /** Values to mask in every result: API keys, tokens. */
     secrets?: (ctx: Ctx) => Array<string | undefined | null>;
     /**

package/dist/check.js

@@ -50,6 +50,15 @@ export async function checkApp(app, options = {}) {
         add("warn", "schema", "ajv is not installed, so schemas were not checked against JSON Schema 2020-12. Add ajv as a dev dependency.");
     let totalBytes = 0;
     let largest;
+    for (const command of app.definition.commands ?? []) {
+        if (BUILTINS.includes(command.name) || app.find(command.name)) {
+            add("error", "names", `The terminal command '${command.name}' has the name of a built-in or a tool. Rename it.`);
+        }
+    }
+    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.`);
+    }
     for (const tool of app.allTools) {
         if (BUILTINS.includes(tool.command)) {
             add("error", "names", `'${tool.command}' is a built-in CLI command. Rename the tool.`, tool.name);
@@ -288,7 +297,7 @@ function checkDocs(app, file, add) {
             // The match may begin on the character before the binary, a newline included.
             const at = segment.offset + (match.index ?? 0) + (match[0].length - match[0].trimStart().length);
             const line = text.slice(0, at).split("\n").length;
-            if (BUILTINS.includes(command))
+            if (BUILTINS.includes(command) || app.definition.commands?.some((custom) => custom.name === command))
                 continue;
             const tool = app.find(command);
             if (!tool) {

package/dist/cli/completion.js

@@ -10,9 +10,9 @@ function globalFlags() {
 function toolFlags(tool) {
     return flagsFor(tool.jsonSchema).map((flag) => flag.flag);
 }
-function bash(bin, tools) {
+function bash(bin, tools, words) {
     const fn = `_${bin.replace(/[^A-Za-z0-9]/g, "_")}`;
-    const commands = [...tools.map((tool) => tool.command), ...BUILTINS].join(" ");
+    const commands = [...tools.map((tool) => tool.command), ...words].join(" ");
     const globals = globalFlags().join(" ");
     const cases = tools
         .map((tool) => `    ${tool.command}) COMPREPLY=( $(compgen -W "${[...toolFlags(tool), ...(tool.paginate ? ["--all", "--max-items"] : [])].join(" ")} ${globals}" -- "$cur") ) ;;`)
@@ -35,16 +35,16 @@ ${cases}
 complete -F ${fn} ${bin}
 `;
 }
-function zsh(bin, tools) {
+function zsh(bin, tools, words) {
     return `#compdef ${bin}
 # ${bin} completion for zsh, through zsh's bash compatibility layer.
 autoload -U +X bashcompinit && bashcompinit
-${bash(bin, tools)}`;
+${bash(bin, tools, words)}`;
 }
 function fishEscape(text) {
     return text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
 }
-function fish(bin, tools) {
+function fish(bin, tools, words) {
     const lines = [`# ${bin} completion for fish`, `complete -c ${bin} -f`];
     for (const tool of tools) {
         lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${tool.command}' -d '${fishEscape(tool.title)}'`);
@@ -52,20 +52,22 @@ function fish(bin, tools) {
             lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${tool.command}' -l '${flag.flag.slice(2)}' -d '${fishEscape(flag.help.slice(0, 80))}'`);
         }
     }
-    for (const builtin of BUILTINS)
-        lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${builtin}'`);
+    for (const word of words)
+        lines.push(`complete -c ${bin} -n '__fish_use_subcommand' -a '${word}'`);
     for (const flag of globalFlags())
         lines.push(`complete -c ${bin} -l '${flag.slice(2)}'`);
     return `${lines.join("\n")}\n`;
 }
 export function completionScript(app, shell, bin, env) {
     const tools = app.tools(env);
+    // The built-ins, then any terminal commands the app adds, such as logout.
+    const words = [...BUILTINS, ...(app.definition.commands ?? []).map((command) => command.name)];
     if (shell === "bash")
-        return bash(bin, tools);
+        return bash(bin, tools, words);
     if (shell === "zsh")
-        return zsh(bin, tools);
+        return zsh(bin, tools, words);
     if (shell === "fish")
-        return fish(bin, tools);
+        return fish(bin, tools, words);
     throw new UsageError(`completion expects bash, zsh or fish${shell ? `, got '${shell}'` : ""}.`, {
         hint: `Add \`source <(${bin} completion bash)\` to your shell's startup file.`,
     });

package/dist/cli/context.d.ts

@@ -24,6 +24,11 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     exit_codes: Record<number, string>;
     hidden_commands?: number | undefined;
     toolsets?: Record<string, string> | undefined;
+    extra_commands?: {
+        command: string;
+        usage: string;
+        description: string;
+    }[] | undefined;
     commands: {
         command: string;
         title: string;
@@ -79,6 +84,11 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     })[];
     toolsets?: Record<string, string> | undefined;
     hidden_commands: number;
+    extra_commands?: {
+        command: string;
+        usage: string;
+        description: string;
+    }[] | undefined;
     commands: {
         command: string;
         tool: string;

package/dist/cli/context.js

@@ -28,6 +28,13 @@ export function agentContext(app, env, bin, options = {}) {
     const names = policyEnvNames(app.envPrefix);
     const tools = app.tools(env);
     const hidden = app.allTools.length - tools.length;
+    // Terminal commands the app adds beside its tools, such as logout, and a sign-in flow that says what it takes.
+    const login = app.definition.login;
+    const extra = [...(typeof login === "object" ? [{ name: "login", ...login }] : []), ...(app.definition.commands ?? [])].map((command) => ({
+        command: command.name,
+        usage: `${bin} ${command.usage ?? command.name}`,
+        description: command.help,
+    }));
     const note = "--agent never confirms a write. A command that requires --confirm runs only when it is passed explicitly.";
     if (options.brief) {
         // Enough to pick a command: what each one is, and which write or need --confirm. The full read adds flags and settings.
@@ -38,6 +45,7 @@ export function agentContext(app, env, bin, options = {}) {
             usage: { run: `${bin} <command> [flags]`, help: `${bin} <command> --help`, note },
             exit_codes: EXIT_MEANINGS,
             ...(hidden ? { hidden_commands: hidden, ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}) } : {}),
+            ...(extra.length ? { extra_commands: extra } : {}),
             commands: tools.map((tool) => ({
                 command: tool.command,
                 title: tool.title,
@@ -76,9 +84,14 @@ export function agentContext(app, env, bin, options = {}) {
             { env: names.auditLog, value: policy.auditLog ?? null, description: "file that records every attempted write" },
             { env: names.toolTimeoutMs, value: policy.toolTimeoutMs ?? null, description: "deadline for any tool" },
             { env: names.confirm, value: policy.confirm, description: "who confirms a confirmed call over MCP: human asks a person where the client can, model accepts confirm: true" },
+            { 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}_DEBUG`, value: /^(1|true|yes)$/i.test(env[`${app.envPrefix}_DEBUG`] ?? ""), description: "print debug lines on stderr" },
         ],
         ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
         hidden_commands: hidden,
+        ...(extra.length ? { extra_commands: extra } : {}),
         commands: tools.map((tool) => ({
             command: tool.command,
             tool: tool.name,

package/dist/cli/data.js

@@ -59,7 +59,7 @@ export async function runData(app, io, tokens, options) {
                 throw new UsageError("data sync expects the command to copy: data sync <command>.");
             const tool = app.find(command);
             if (!tool)
-                throw new UsageError(`Unknown command '${command}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`Unknown command '${command}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             if (!tool.sync) {
                 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"}.` });

package/dist/cli/help.js

@@ -94,7 +94,9 @@ export function renderList(app, tools, bin, env = process.env) {
         for (const tool of members)
             lines.push(`  ${riskMark(tool.risk)} ${tool.command.padEnd(width)}${tool.title}`);
     }
-    lines.push(``, `  * writes    ! public or irreversible`, ``, `  ${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));
+    // 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));
     return lines.join("\n");
 }
 function shellQuote(value) {
@@ -186,16 +188,18 @@ export function renderGeneralHelp(app, bin) {
     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 and Slipway's own settings say only what they do.
     const commands = [
-        [bin, "list the commands"],
+        [app.bins.cli, "list the commands"],
         [`${bin} <command> --help`, "what one takes, with examples"],
         [`${bin} which <words>`, "find the command for a task"],
-        [`${bin} schema <command>`, "its JSON Schema; --output for the result's"],
-        [`${bin} agent-context`, "all of this as JSON; --brief for less"],
-        [`${bin} doctor [--network]`, "check the setup and say what is wrong"],
-        [`${bin} login`, "how to connect an account"],
-        [`${bin} install <client>`, "add the server to claude-code, codex, claude-desktop, cursor, vscode or gemini"],
-        [`${bin} completion <shell>`, "tab completion for bash, zsh or fish"],
+        [`${bin} doctor${app.definition.doctorNetwork ? "" : " [--network]"}`, "check the setup and say what is wrong"],
+        typeof app.definition.login === "object"
+            ? [`${bin} ${app.definition.login.usage ?? "login"}`, app.definition.login.help]
+            : [`${bin} login`, "how to connect an account"],
+        ...(app.definition.commands ?? []).map((command) => [`${bin} ${command.usage ?? command.name}`, command.help]),
+        [`${bin} install <client>`, "add the server to an MCP client; install --help lists them"],
         ...(cache || sync ? [[`${bin} data`, "what is kept on this machine; data clear [<command>] deletes it"]] : []),
         ...(sync
             ? [
@@ -206,17 +210,21 @@ export function renderGeneralHelp(app, bin) {
             : []),
         [app.bins.mcp, "the MCP server over stdio; --http [--port N] for HTTP"],
     ];
+    // Tuning keeps a working default, so it is named on one line; agent-context says what each does.
+    const tuning = (app.definition.settings ?? []).filter((setting) => setting.tuning).map((setting) => setting.env);
     const settings = [
-        ...(app.definition.settings ?? []).map((setting) => [setting.env, setting.description]),
+        ...(app.definition.settings ?? []).filter((setting) => !setting.tuning).map((setting) => [setting.env, setting.description]),
         [`${names.readOnly}=1`, "hide and refuse every write"],
-        [`${names.allowDestructive}=0`, "keep writes, refuse the irreversible ones"],
+        [`${names.allowDestructive}=0`, "refuse the irreversible writes"],
         [`${names.toolsets}=a,b`, "only these toolsets, or all"],
-        [`${names.surface}=search`, "MCP serves three tools that find, describe and run the rest"],
-        [`${names.auditLog}=<file>`, "log every attempted write to this file"],
-        [`${names.toolTimeoutMs}=<ms>`, "give up on any tool after this long"],
-        [`${names.confirm}=model`, "confirm: true alone confirms, for an agent with no person to ask"],
+        [`${names.surface}=search`, "MCP lists three finder tools instead"],
+        [`${names.auditLog}=<file>`, "log every attempted write"],
+        [`${names.toolTimeoutMs}=<ms>`, "deadline for any tool"],
+        [`${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}_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));
@@ -224,16 +232,18 @@ export function renderGeneralHelp(app, bin) {
     const row = ([left, help]) => `  ${left.padEnd(width)}${help}`;
     const lines = [
         ``,
-        `${app.title} ${app.version}${app.description ? `: ${app.description}` : ""}`,
+        `${app.title} ${app.version}`,
         ``,
         ...commands.map(row),
+        `  Also: schema <command>, agent-context [--brief] (all of this as JSON), completion <shell>.`,
         ``,
-        `Flags: ${flags.join(", ")}, and --agent for compact JSON with no prompts, which never confirms a write.`,
+        `Flags: ${flags.join(", ")}, and --agent: compact JSON, no prompts, never confirms a write.`,
         ``,
         `Settings:`,
         ...settings.map(row),
+        ...(tuning.length ? [`  Also: ${tuning.join(", ")}, described in agent-context.`] : []),
         ``,
-        `Exit codes: ${EXIT.ok} ok, ${EXIT.error} unexpected error, ${EXIT.usage} usage or refused write, ${EXIT.notFound} not found, ${EXIT.auth} auth, ${EXIT.api} API, ${EXIT.rateLimited} rate limited, ${EXIT.notConfigured} nothing configured`,
+        `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`,
         ``,
     ];
     if (app.definition.links?.repository)

package/dist/cli/run.js

@@ -140,7 +140,8 @@ export async function runCli(app, argv, partial = {}) {
     const at = findCommand(argv);
     const command = at === -1 ? undefined : argv[at];
     const builtin = command !== undefined && BUILTINS.includes(command);
-    const tool = command !== undefined && !builtin ? app.find(command) : undefined;
+    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) : []);
     let agent = argv.includes("--agent");
     try {
@@ -155,11 +156,16 @@ export async function runCli(app, argv, partial = {}) {
         }
         if (builtin)
             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 await custom.run(io, rest);
+        }
         if (!tool) {
-            const candidates = [...app.tools(io.env).map((t) => t.command), ...BUILTINS];
+            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 \`${io.bin}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
+                hint: `Run \`${app.bins.cli}\` to list commands, or \`${io.bin} which <words>\` to find one.`,
             });
         }
         const seen = visibility(tool, app.policy(io.env));
@@ -196,6 +202,9 @@ async function runBuiltin(app, io, command, rest, globals) {
     // `<built-in> --help` explains the command instead of running it.
     if (globals.help && command === "install")
         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`);
     if (globals.help && command !== "help")
         return print(io, renderGeneralHelp(app, io.bin));
     const target = rest.find((token) => !token.startsWith("-"));
@@ -209,13 +218,13 @@ async function runBuiltin(app, io, command, rest, globals) {
                 return print(io, renderGeneralHelp(app, io.bin));
             const tool = app.find(target);
             if (!tool)
-                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`Unknown command '${target}'.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             return print(io, renderToolHelp(tool, io.bin));
         }
         case "schema": {
             const tool = target ? app.find(target) : undefined;
             if (!tool)
-                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${io.bin}\` to list commands.` });
+                throw new UsageError(`schema expects a command${target ? `; '${target}' is not one` : ""}.`, { hint: `Run \`${app.bins.cli}\` to list commands.` });
             if (rest.includes("--output")) {
                 if (!tool.output)
                     throw new UsageError(`${tool.command} declares no output schema.`);
@@ -234,15 +243,16 @@ async function runBuiltin(app, io, command, rest, globals) {
                 return print(io, json(globals, matches.map(({ tool, score }) => ({ command: tool.command, title: tool.title, risk: tool.risk, score: Number(score.toFixed(2)) }))));
             }
             if (!matches.length)
-                return print(io, `No command matches '${query}'. Run \`${io.bin}\` to see them all.`);
+                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"));
         }
         case "doctor":
             return runDoctor(app, io, { network: rest.includes("--network"), json: globals.format !== "auto" });
         case "login": {
-            const login = app.definition.login;
             if (typeof login === "function")
-                return await login(io);
+                return await login(io, rest);
+            if (typeof login === "object")
+                return await login.run(io, rest);
             if (typeof login === "string")
                 return print(io, login);
             return print(io, `${app.title} reads its credentials from the environment. Run \`${io.bin} doctor\` to see what is missing.`);

package/dist/doctor.js

@@ -68,15 +68,16 @@ export async function runDoctor(app, io, options) {
             ...(configured ? {} : { fix: `Run \`${app.bins.cli} login\` to see how to connect an account.` }),
         });
     }
+    const network = options.network || app.definition.doctorNetwork === true;
     if (ctx !== undefined && app.definition.doctor) {
         try {
-            checks.push(...(await app.definition.doctor(ctx, { network: options.network })));
+            checks.push(...(await app.definition.doctor(ctx, { network })));
         }
         catch (error) {
             checks.push({ name: "Service check", ok: false, detail: app.secrets.redact(error?.message ?? String(error)) });
         }
     }
-    if (!options.network && app.definition.doctor) {
+    if (!network && app.definition.doctor) {
         checks.push({ name: "Network", ok: true, warn: true, detail: "not checked; run with --network to call the service" });
     }
     const failed = checks.filter((check) => !check.ok && !check.warn);

package/dist/errors.js

@@ -149,5 +149,10 @@ export function toSlipwayError(error) {
         return new AuthError(message, { cause: error });
     if (/\b404\b|not found|does not exist/.test(text))
         return new NotFoundError(message, { cause: error });
+    // A request that never got an answer is the service's failure, not a bug here: exit 5, which a script may retry.
+    const codes = [error?.code, error?.cause?.code];
+    const network = codes.some((code) => typeof code === "string" && /^(ECONN(REFUSED|RESET|ABORTED)|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|E(HOST|NET)UNREACH|EPIPE|UND_ERR_\w+)$/.test(code));
+    if (network || /fetch failed|could not reach|network error|socket hang up/.test(text))
+        return new ApiError(message, { cause: error });
     return new SlipwayError(message, "internal", EXIT.error, { cause: error });
 }

package/dist/install.js

@@ -207,7 +207,7 @@ export function planInstall(app, options, context) {
     }
     const launch = launchFor(app, { local: options.local, ...(context.entry ? { entry: context.entry } : {}), ...(context.platform ? { platform: context.platform } : {}) });
     const usesNpx = launch.command === "npx" || launch.args.includes("npx");
-    const settings = app.definition.settings ?? [];
+    const settings = (app.definition.settings ?? []).filter((setting) => !setting.tuning);
     const variables = settings.map((setting) => setting.env);
     const env = { forwarded: [], copied: [], toAdd: [] };
     const notes = [];

package/dist/schema.js

@@ -83,6 +83,25 @@ export const CONTROL_NAMES = ["confirm", "wait_seconds"];
 export const CONFIRM_DESCRIPTION = "Set true only when the user asked for exactly this action.";
 /** The schema already carries the range and the default, so the words only say what the number is for. */
 export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before returning it to check later.";
+/**
+ * Zod 4 gives every whole number the safe-integer bounds, `maximum:
+ * 9007199254740991` and its negative, unless the schema sets its own. They say
+ * nothing a client can use, so they are left out of what it receives.
+ * Validation still runs on the schema itself.
+ */
+function withoutSafeIntegerBounds(node) {
+    if (Array.isArray(node))
+        return node.map(withoutSafeIntegerBounds);
+    if (node === null || typeof node !== "object")
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if ((key === "maximum" && value === Number.MAX_SAFE_INTEGER) || (key === "minimum" && value === Number.MIN_SAFE_INTEGER))
+            continue;
+        out[key] = withoutSafeIntegerBounds(value);
+    }
+    return out;
+}
 /**
  * A schema as clients receive it, without the `$schema` line that names its
  * dialect. A client reads JSON Schema 2020-12 when no dialect is named, so
@@ -91,10 +110,8 @@ export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before re
 export function advertised(schema) {
     const std = schema["~standard"];
     const plain = (json) => {
-        if (!("$schema" in json))
-            return json;
         const { $schema: _dialect, ...rest } = json;
-        return rest;
+        return withoutSafeIntegerBounds(rest);
     };
     return {
         "~standard": {

package/dist/serve.js

@@ -43,7 +43,7 @@ async function warnIfUnconfigured(app, env, warn) {
 export function httpOptions(app, env, argv) {
     const at = argv.findIndex((token) => token === "--port" || token.startsWith("--port="));
     const raw = at === -1 ? env[`${app.envPrefix}_HTTP_PORT`] : argv[at].includes("=") ? argv[at].split("=")[1] : argv[at + 1];
-    const port = Number(raw ?? 8787);
+    const port = Number(raw ?? app.definition.httpPort ?? 8787);
     if (!Number.isInteger(port) || port < 1 || port > 65535)
         throw new UsageError(`--port expects a port number, got '${raw}'.`);
     return {

package/package.json

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