@thenavidm/slipway 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed in Slipway, newest first.
 
+## 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.
+- **`slipway check` compiles every schema.** A schema that cannot compile, such as one with a broken `$ref`, used to stop the server at startup. It now fails the check, before release, and names the tool.
+- **`--version` prints the bare version.** It printed `notes 1.0.0 (slipway 0.1.3)`, where every server built before Slipway prints `1.0.0`, so a script comparing versions broke on migration. `agent-context` still names the framework and its version.
+- **`structuredContent` only for a tool with an output schema.** An object result went out as JSON text and again as `structuredContent`. Codex hands a model the structured copy in place of the text, as one escaped string, so on a measured Teachable call it read 211 more tokens than for the same JSON as text, and the copy also hid a `render` text or an image. An untyped result is now text alone; a typed one still carries its validated copy. `resultData()` in `@thenavidm/slipway/testing` reads either.
+- **A built-in command explains itself with `--help`.** `install --help` failed asking for a client; it now lists the clients and flags. Every other built-in prints the general help instead of running.
+- **Shorter CLI screens, measured in tokens.** An agent pays for every line it reads. On Teachable's 26 commands, counted with OpenAI's tokenizer: the command list went from 413 tokens to 335, a command's `--help` from 368 to 230, the general help from 802 to 639, and `agent-context --brief` from 2,200 to 912. A command's help now shows only the output flags that command can use, and the command list names the setting that turns hidden commands on.
+
 ## 0.1.3, 2026-10-04: npx picks the server by name
 
 - **`slipway check` matches npm's real rule.** npx picks a binary named after the package only when the binaries point to different files. When they share one file it starts whichever one the registry lists first, and the registry does not keep the published order: 23 published servers listed their MCP binary first and still started the CLI. 0.1.2's order check could not catch that. The check now requires a binary named after the package on a file of its own, and the README shows the one-line `src/npx.ts` it runs.

package/README.md

@@ -83,7 +83,7 @@ They are the same program reading the same tool definitions, so anything one can
 - **Local data.** Reads can opt in to a cache, kept per account and cleared by any write. `data sync`, `data search` and `data sql` keep an offline, searchable copy of any list, in one private SQLite file with nothing to install.
 - **OpenAPI to tools.** `fromOpenAPI()` turns every operation in a document into a tool, with the risk its method implies, its tags as toolsets, and a hash pin that refuses a changed document. It turns 611 of the 612 operations in Stripe's API into tools, and 1,230 of GitHub's 1,232; the rest are file uploads or raw text.
 - **One command to install.** `<cli> install codex`, or `claude-code`, `claude-desktop`, `cursor`, `vscode` or `gemini`, adds the server to that client's own configuration and passes credentials on instead of writing them down.
-- **Typed results.** Declare an output schema and results go out as validated `structuredContent`. Object results are structured even without one.
+- **Typed results.** Declare an output schema and results also go out as validated `structuredContent`. Without one, a result is compact text alone: Codex reads a structured copy in place of the text, and on a measured call that cost 211 more tokens.
 - **Contract tools.** A tool built from a pinned JSON contract joins the same list as a hand-written Zod tool, with `jsonSchema({...})`.
 - **Toolsets and a search surface** for large catalogs, so a client loads only what a person turns on.
 - **Typed errors and exit codes.** Every error carries its exit code and a hint: JSON on stderr in a terminal, a readable error result over MCP.
@@ -196,7 +196,7 @@ npx picks a binary named after the package only when the binaries point to diffe
 
 `notes-mcp` with no arguments serves MCP over stdio and stays silent on stdout. `notes-cli` with no arguments lists the commands. Any argument on either binary is a command, so a typo is reported instead of starting a server that waits on stdin.
 
-The context is built on the first call that needs it, never at startup. `--help` works with nothing configured, and the server answers a client at once and explains what is missing instead of exiting.
+The context is built on the first call that needs it, never at startup, and so is each tool's JSON Schema validator: Stripe's 611 generated tools are ready in about 70 ms. `--help` works with nothing configured, and the server answers a client at once and explains what is missing instead of exiting.
 
 ## 3. Tools
 
@@ -224,7 +224,7 @@ The context is built on the first call that needs it, never at startup. `--help`
 | `render` | Text for the result when JSON is not the best way to read it |
 | `handler` | `(args, ctx) => result`. `ctx` is your context plus `signal`, `surface`, `env`, `progress`, `log` and `secrets` |
 
-A handler returns plain data. An object goes out as compact JSON text and as typed `structuredContent`. Return `content([...], data)` with `image()`, `audio()`, `file()` or `resourceLink()` for anything that is not text.
+A handler returns plain data. An object goes out as compact JSON text, and as typed `structuredContent` too when the tool declares `output`. Return `content([...], data)` with `image()`, `audio()`, `file()` or `resourceLink()` for anything that is not text.
 
 Throw one of the error classes and the caller gets its exit code. `httpError(status, message)` maps an HTTP status in one line, and `UsageError`, `NotFoundError`, `AuthError`, `RateLimitError`, `ApiError` and `NotConfiguredError` cover the rest.
 
@@ -383,7 +383,7 @@ Override any operation's name or risk with `names` and `risk`, keep a subset wit
 | `<cli> <command> --help` | Its flags, choices, defaults, examples and risk |
 | `<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 names only |
+| `<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> install <client>` | Add the MCP server to a client. See [Add it to a client](#10-add-it-to-a-client) |
@@ -492,10 +492,10 @@ Parity runs on both protocol revisions a client may open with. `slipway docs dis
 ## 13. Testing
 
 ```ts
-import { checkApp, cli, connect } from "@thenavidm/slipway/testing";
+import { checkApp, cli, connect, resultData } from "@thenavidm/slipway/testing";
 
 const mcp = await connect(app, { env: { NOTES_API_KEY: "test" } });
-const result = await mcp.callTool("get_note", { id: 7 });
+const note = resultData(await mcp.callTool("get_note", { id: 7 }));
 await mcp.close();
 
 const { code } = await cli(app, ["delete-note", "7"], { env: {} });
@@ -504,7 +504,7 @@ const { code } = await cli(app, ["delete-note", "7"], { env: {} });
 const report = await checkApp(app, { env: {} });
 ```
 
-`connect` talks to the real server over an in-memory transport, through the same stdio entry the binary runs. `cli` runs the real CLI with captured output. To stub the network, build the app with a context that returns a fake client.
+`connect` talks to the real server over an in-memory transport, through the same stdio entry the binary runs. `resultData` reads what a call returned, typed or not. `cli` runs the real CLI with captured output. To stub the network, build the app with a context that returns a fake client.
 
 To test approval by a person, give `connect` an `elicit` answer, and pass `era: "modern"` for the 2026-07-28 revision or `clientInfo` to be a particular client:
 
@@ -673,7 +673,7 @@ Return `content([image(bytes, "image/png")], data)`. `audio()`, `file()` and `re
 <details>
 <summary><b>Do I need an output schema?</b></summary>
 
-No. An object result already goes out as `structuredContent`. Declare `output` when you want the result validated before it leaves the server and its shape advertised to clients, which lets a client use the data without parsing text.
+No. Without one, an object result goes out as compact JSON text, which every client reads. Declare `output` when you want the result validated before it leaves the server, its shape advertised, and a typed `structuredContent` copy sent for clients that use data without parsing text. Codex reads that copy in place of the text, so a schema is worth declaring when something uses the shape.
 
 </details>
 

package/SKILL.md

@@ -59,7 +59,7 @@ For a tool generated from an API contract, pass the operation's JSON Schema thro
 
 ## Results and errors
 
-- Return plain data. An object goes out as compact JSON text and as `structuredContent`.
+- Return plain data. An object goes out as compact JSON text; with `output` declared, also as validated `structuredContent`.
 - Add `output` when the shape is stable, so results are validated and typed for clients.
 - Return `content([image(bytes, "image/png")], data)` for images, audio, files and links.
 - Throw `httpError(status, message)` for upstream failures, or `UsageError`, `NotFoundError`, `AuthError`, `RateLimitError`, `ApiError`, `NotConfiguredError`. Each carries its exit code.

package/dist/check.js

@@ -81,6 +81,15 @@ export async function checkApp(app, options = {}) {
         const problem = meta?.(schema);
         if (problem)
             add("error", "schema", `Not valid JSON Schema 2020-12: ${problem}`, tool.name);
+        // A JSON Schema validator compiles on the tool's first call, so compile each one here instead.
+        for (const [which, candidate] of [["input", tool.schema], ["output", tool.output]]) {
+            try {
+                await candidate?.["~standard"].validate({});
+            }
+            catch (error) {
+                add("error", "schema", `The ${which} schema does not compile: ${error.message}`, tool.name);
+            }
+        }
         const bytes = schemaBytes(schema);
         totalBytes += bytes;
         if (!largest || bytes > largest.bytes)

package/dist/cli/context.d.ts

@@ -11,6 +11,26 @@ export declare const EXIT_MEANINGS: Record<number, string>;
 export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: string, options?: {
     brief?: boolean;
 }): {
+    name: string;
+    version: string;
+    description?: string | undefined;
+    usage: {
+        run: string;
+        help: string;
+        note: string;
+        agent_mode?: undefined;
+        confirm_flag?: undefined;
+    };
+    exit_codes: Record<number, string>;
+    hidden_commands?: number | undefined;
+    toolsets?: Record<string, string> | undefined;
+    commands: {
+        command: string;
+        title: string;
+        risk?: "destructive" | "write" | undefined;
+        requires_confirm?: boolean | undefined;
+    }[];
+} | {
     name: string;
     title: string;
     version: string;
@@ -59,12 +79,7 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
     })[];
     toolsets?: Record<string, string> | undefined;
     hidden_commands: number;
-    commands: ({
-        command: string;
-        title: string;
-        risk: import("../tool.js").Risk;
-        requires_confirm: boolean;
-    } | {
+    commands: {
         command: string;
         tool: string;
         title: string;
@@ -93,5 +108,5 @@ export declare function agentContext(app: App, env: NodeJS.ProcessEnv, bin: stri
             description: string;
             command: string;
         }[] | undefined;
-    })[];
+    }[];
 };

package/dist/cli/context.js

@@ -27,6 +27,25 @@ export function agentContext(app, env, bin, options = {}) {
     const policy = app.policy(env);
     const names = policyEnvNames(app.envPrefix);
     const tools = app.tools(env);
+    const hidden = app.allTools.length - tools.length;
+    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.
+        return {
+            name: app.name,
+            version: app.version,
+            ...(app.description ? { description: app.description } : {}),
+            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 } : {}) } : {}),
+            commands: tools.map((tool) => ({
+                command: tool.command,
+                title: tool.title,
+                ...(tool.risk !== "read" ? { risk: tool.risk } : {}),
+                ...(tool.requireConfirm ? { requires_confirm: true } : {}),
+            })),
+        };
+    }
     return {
         name: app.name,
         title: app.title,
@@ -39,7 +58,7 @@ export function agentContext(app, env, bin, options = {}) {
             help: `${bin} <command> --help`,
             agent_mode: "--agent",
             confirm_flag: "--confirm",
-            note: "--agent never confirms a write. A command that requires --confirm runs only when it is passed explicitly.",
+            note,
         },
         exit_codes: EXIT_MEANINGS,
         global_flags: GLOBAL_FLAGS.map(([flag, description]) => ({ flag, description })),
@@ -59,36 +78,34 @@ export function agentContext(app, env, bin, options = {}) {
             { 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" },
         ],
         ...(app.definition.toolsets ? { toolsets: app.definition.toolsets } : {}),
-        hidden_commands: app.allTools.length - tools.length,
-        commands: tools.map((tool) => options.brief
-            ? { command: tool.command, title: tool.title, risk: tool.risk, requires_confirm: tool.requireConfirm }
-            : {
-                command: tool.command,
-                tool: tool.name,
-                title: tool.title,
-                description: tool.description,
-                risk: tool.risk,
-                requires_confirm: tool.requireConfirm,
-                ...(tool.tags.length ? { toolsets: tool.tags } : {}),
-                ...(tool.positional.length ? { positional: tool.positional } : {}),
-                flags: flagsFor(tool.jsonSchema)
-                    .filter((flag) => flag.key !== "confirm")
-                    .map((flag) => ({
-                    flag: flag.flag,
-                    type: flag.kind,
-                    required: flag.required,
-                    ...(flag.repeatable ? { repeatable: true } : {}),
-                    ...(flag.choices ? { choices: flag.choices } : {}),
-                    ...(flag.default !== undefined ? { default: flag.default } : {}),
-                    ...(flag.help ? { description: flag.help } : {}),
-                })),
-                ...(tool.output ? { output_schema: outputJsonSchema(tool.output) } : {}),
-                ...(tool.paginate ? { paginates: true } : {}),
-                ...(tool.job && !tool.statusOf ? { job: { status_command: `${tool.command}-status`, background: "background" in tool.job } } : {}),
-                ...(tool.statusOf ? { checks_jobs_of: tool.statusOf.replace(/_/g, "-") } : {}),
-                ...(tool.examples.length
-                    ? { examples: tool.examples.map((example) => ({ description: example.description, command: exampleCommand(bin, tool, example.args) })) }
-                    : {}),
-            }),
+        hidden_commands: hidden,
+        commands: tools.map((tool) => ({
+            command: tool.command,
+            tool: tool.name,
+            title: tool.title,
+            description: tool.description,
+            risk: tool.risk,
+            requires_confirm: tool.requireConfirm,
+            ...(tool.tags.length ? { toolsets: tool.tags } : {}),
+            ...(tool.positional.length ? { positional: tool.positional } : {}),
+            flags: flagsFor(tool.jsonSchema)
+                .filter((flag) => flag.key !== "confirm")
+                .map((flag) => ({
+                flag: flag.flag,
+                type: flag.kind,
+                required: flag.required,
+                ...(flag.repeatable ? { repeatable: true } : {}),
+                ...(flag.choices ? { choices: flag.choices } : {}),
+                ...(flag.default !== undefined ? { default: flag.default } : {}),
+                ...(flag.help ? { description: flag.help } : {}),
+            })),
+            ...(tool.output ? { output_schema: outputJsonSchema(tool.output) } : {}),
+            ...(tool.paginate ? { paginates: true } : {}),
+            ...(tool.job && !tool.statusOf ? { job: { status_command: `${tool.command}-status`, background: "background" in tool.job } } : {}),
+            ...(tool.statusOf ? { checks_jobs_of: tool.statusOf.replace(/_/g, "-") } : {}),
+            ...(tool.examples.length
+                ? { examples: tool.examples.map((example) => ({ description: example.description, command: exampleCommand(bin, tool, example.args) })) }
+                : {}),
+        })),
     };
 }

package/dist/cli/help.d.ts

@@ -1,12 +1,15 @@
 /**
  * What a person sees before they know what to type.
+ *
+ * An agent reads this too, and pays for every token of it, so each screen
+ * shows what applies and points to the rest instead of repeating it.
  */
 import type { App } from "../app.js";
 import type { Tool } from "../tool.js";
 /** The words the CLI owns, which no tool command may take. */
 export declare const BUILTINS: readonly ["help", "tools", "schema", "agent-context", "which", "doctor", "login", "completion", "version", "data", "install"];
 export declare const GLOBAL_FLAGS: Array<[string, string]>;
-export declare function renderList(app: App, tools: readonly Tool[], bin: 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;

package/dist/cli/help.js

@@ -1,8 +1,11 @@
 /**
  * What a person sees before they know what to type.
+ *
+ * An agent reads this too, and pays for every token of it, so each screen
+ * shows what applies and points to the rest instead of repeating it.
  */
 import { EXIT } from "../errors.js";
-import { policyEnvNames, riskMark } from "../policy.js";
+import { policyEnvNames, riskMark, visibility } from "../policy.js";
 import { firstSentence } from "../search.js";
 import { flagsFor } from "./flags.js";
 const COLUMN = 30;
@@ -29,12 +32,52 @@ function line(left, help) {
     return left.length < COLUMN ? [`${left.padEnd(COLUMN)}${help}`] : [left, `${" ".repeat(COLUMN)}${help}`];
 }
 function riskWords(tool) {
-    const base = tool.risk === "read" ? "read only" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
-    return tool.requireConfirm ? `${base}, runs only with --confirm` : base;
+    return tool.risk === "read" ? "read only" : tool.risk === "write" ? "writes, reversible" : "public or irreversible";
 }
-export function renderList(app, tools, bin) {
+/** The output flags a command can use: the four every command takes, and those its kind adds. */
+function outputFlagsFor(tool) {
+    const wanted = new Set(["--json", "--compact", "--select <a,b.c>", "--agent"]);
+    if (tool.risk !== "read")
+        wanted.add("--dry-run");
+    if (tool.cache)
+        wanted.add("--refresh");
+    if (tool.paginate || tool.sync)
+        for (const flag of ["--jsonl", "--csv / --tsv", "--quiet"])
+            wanted.add(flag);
+    return GLOBAL_FLAGS.filter(([flag]) => wanted.has(flag));
+}
+/** Why some commands are not listed, and the setting that lists them. */
+function hiddenNote(app, env) {
+    const policy = app.policy(env);
+    const names = policyEnvNames(app.envPrefix);
+    const off = new Set();
+    let byToolset = 0;
+    let byReadOnly = 0;
+    for (const tool of app.allTools) {
+        const seen = visibility(tool, policy);
+        if (seen.visible)
+            continue;
+        if (seen.reason === "read-only")
+            byReadOnly += 1;
+        else {
+            byToolset += 1;
+            for (const tag of tool.tags)
+                if (policy.toolsets === "all" || !policy.toolsets.has(tag))
+                    off.add(tag);
+        }
+    }
+    const lines = [];
+    if (byToolset) {
+        const sets = [...off].sort();
+        lines.push(`  ${byToolset} more ${byToolset === 1 ? "command is" : "commands are"} in ${sets.join(", ")}, off: ${names.toolsets}=${sets.join(",")} turns ${byToolset === 1 ? "it" : "them"} on.`);
+    }
+    if (byReadOnly)
+        lines.push(`  ${byReadOnly} ${byReadOnly === 1 ? "write is" : "writes are"} hidden by ${names.readOnly}=1.`);
+    return lines.length ? [...lines, ``] : [];
+}
+export function renderList(app, tools, bin, env = process.env) {
     const width = Math.max(10, ...tools.map((tool) => tool.command.length)) + 2;
-    const lines = [``, `${app.title} ${app.version}${app.description ? `: ${app.description}` : ""}`, ``];
+    const lines = [``, `${bin} ${app.version}: ${tools.length} ${tools.length === 1 ? "command" : "commands"}`];
     const toolsets = app.definition.toolsets ?? {};
     const groups = new Map();
     for (const tool of tools) {
@@ -43,19 +86,15 @@ export function renderList(app, tools, bin) {
     }
     const ordered = [...groups.entries()].sort(([a], [b]) => (a === "" ? -1 : b === "" ? 1 : a.localeCompare(b)));
     const grouped = ordered.length > 1 || (ordered[0]?.[0] ?? "") !== "";
-    lines.push(`Commands (${tools.length})`);
+    if (!grouped)
+        lines.push(``);
     for (const [group, members] of ordered) {
         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(``, `  * writes    ! public or irreversible`, ``, `  ${bin} <command> --help       what a command takes, with examples`, `  ${bin} which <words>          find the command for a task`, `  ${bin} schema <command>       the JSON Schema an MCP client sees`, `  ${bin} agent-context          everything above, as JSON for an agent`, `  ${bin} doctor                 check the setup`, `  ${bin} install <client>       add it to an MCP client: codex, claude-code, cursor…`, ``);
-    const hidden = app.allTools.length - tools.length;
-    if (hidden > 0) {
-        const names = policyEnvNames(app.envPrefix);
-        lines.push(`  ${hidden} more ${hidden === 1 ? "command is" : "commands are"} off: see ${names.readOnly} and ${names.toolsets} in \`${bin} help\`.`, ``);
-    }
+    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));
     return lines.join("\n");
 }
 function shellQuote(value) {
@@ -108,9 +147,10 @@ export function renderToolHelp(tool, bin) {
     ]
         .filter(Boolean)
         .join(" ");
-    const lines = [``, `${tool.title}`, ``, tool.description, ``, `Usage:`, `  ${usage}`, ``];
-    const describe = (list, heading) => {
-        if (!list.length)
+    // The title is already on the command list; the description says more.
+    const lines = [``, tool.description, ``, `Usage:`, `  ${usage}`, ``];
+    const describe = (list, heading, after = []) => {
+        if (!list.length && !after.length)
             return;
         lines.push(`${heading}:`);
         for (const flag of list) {
@@ -119,13 +159,10 @@ export function renderToolHelp(tool, bin) {
                 .join(" ");
             lines.push(...line(`  ${flag.flag}${placeholder(flag)}`, [flag.help, extra].filter(Boolean).join(" ")));
         }
-        lines.push(``);
+        lines.push(...after, ``);
     };
-    describe(required, "Required");
+    describe(required, "Required", tool.requireConfirm ? line("  --confirm", "it runs only with this; --agent never adds it") : []);
     describe(optional, "Options");
-    if (tool.requireConfirm) {
-        lines.push(`Safety:`, ...line("  --confirm", "required: this runs only when you mean it"), ``);
-    }
     if (tool.paginate) {
         lines.push(`Pages:`, ...line("  --all", "follow every page and print all items"), ...line("  --max-items <n>", "stop after this many items"), ``);
     }
@@ -139,68 +176,64 @@ export function renderToolHelp(tool, bin) {
             lines.push(`  # ${example.description}`, `  ${exampleCommand(bin, tool, example.args)}`, ``);
     }
     lines.push(`Output:`);
-    for (const [flag, help] of GLOBAL_FLAGS)
+    for (const [flag, help] of outputFlagsFor(tool))
         lines.push(...line(`  ${flag}`, help));
     lines.push(``, `Risk: ${riskWords(tool)}`, ``);
     return lines.join("\n");
 }
 export function renderGeneralHelp(app, bin) {
     const names = policyEnvNames(app.envPrefix);
+    const cache = app.allTools.some((tool) => tool.cache);
+    const sync = app.allTools.some((tool) => tool.sync);
+    const jobs = app.allTools.some((tool) => tool.job);
+    const commands = [
+        [bin, "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"],
+        ...(cache || sync ? [[`${bin} data`, "what is kept on this machine; data clear [<command>] deletes it"]] : []),
+        ...(sync
+            ? [
+                [`${bin} data sync <command>`, "copy every page of a list to this machine"],
+                [`${bin} data search <words>`, "search synced records offline (--in <command>)"],
+                [`${bin} data sql "<select>"`, "query local data with read-only SQL"],
+            ]
+            : []),
+        [app.bins.mcp, "the MCP server over stdio; --http [--port N] for HTTP"],
+    ];
+    const settings = [
+        ...(app.definition.settings ?? []).map((setting) => [setting.env, setting.description]),
+        [`${names.readOnly}=1`, "hide and refuse every write"],
+        [`${names.allowDestructive}=0`, "keep writes, refuse the irreversible ones"],
+        [`${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"],
+        ...(cache ? [[`${names.cache}=0`, "never answer from the local cache"]] : []),
+        ...(cache || sync ? [[`${names.dataDir}=<dir>`, "keep local data in this folder"]] : []),
+    ];
+    // 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 lines = [
         ``,
         `${app.title} ${app.version}${app.description ? `: ${app.description}` : ""}`,
         ``,
-        `Usage:`,
-        `  ${app.bins.mcp}                      run the MCP server over stdio (what an MCP client launches)`,
-        `  ${app.bins.mcp} --http [--port N]    run it over HTTP`,
-        `  ${bin}                      list every command`,
-        `  ${bin} <command> [flags]    run one`,
+        ...commands.map(row),
         ``,
-        `Commands:`,
-        ...line("  <command> --help", "what a command takes, with examples"),
-        ...line("  which <words>", "find the command for a task"),
-        ...line("  schema <command>", "the JSON Schema an MCP client sees (--output for the result's)"),
-        ...line("  agent-context", "commands, flags, risk, exit codes and settings as JSON"),
-        ...line("  doctor [--network]", "check the setup and say what is wrong"),
-        ...line("  login", "how to connect an account"),
-        ...line("  install <client>", "add this server to claude-code, codex, claude-desktop, cursor, vscode or gemini"),
-        ...line("  completion <shell>", "tab completion for bash, zsh or fish"),
-        ...line("  version", "print the version"),
+        `Flags: ${flags.join(", ")}, and --agent for compact JSON with no prompts, which never confirms a write.`,
         ``,
-        ...(app.allTools.some((tool) => tool.cache || tool.sync)
-            ? [
-                `Local data:`,
-                ...line("  data", "what is kept on this machine, and where"),
-                ...(app.allTools.some((tool) => tool.sync)
-                    ? [
-                        ...line("  data sync <command>", "copy every page of a list to this machine"),
-                        ...line("  data search <words>", "search synced records offline (--in <command>)"),
-                        ...line('  data sql "<select>"', "query local data with read-only SQL"),
-                    ]
-                    : []),
-                ...line("  data clear [<command>]", "delete this account's local data (--cache for cached results only)"),
-                ``,
-            ]
-            : []),
-        `Output flags, on any command:`,
-        ...GLOBAL_FLAGS.flatMap(([flag, help]) => line(`  ${flag}`, help)),
-        ``,
-        ...(app.definition.settings?.length
-            ? [`${app.title} settings:`, ...app.definition.settings.flatMap((setting) => line(`  ${setting.env}`, setting.description)), ``]
-            : []),
         `Settings:`,
-        ...line(`  ${names.readOnly}=1`, "hide and refuse every write"),
-        ...line(`  ${names.allowDestructive}=0`, "keep writes, refuse the irreversible ones"),
-        ...line(`  ${names.toolsets}=a,b`, "only these toolsets (or all)"),
-        ...line(`  ${names.surface}=search`, "MCP lists three tools that find, describe and run the rest"),
-        ...line(`  ${names.auditLog}=<file>`, "append every attempted write to this file"),
-        ...line(`  ${names.toolTimeoutMs}=<ms>`, "give up on any tool after this long"),
-        ...line(`  ${names.confirm}=model`, "let confirm: true alone confirm, for an agent with no person to ask"),
-        ...(app.allTools.some((tool) => tool.cache) ? line(`  ${names.cache}=0`, "never answer from the local cache") : []),
-        ...(app.allTools.some((tool) => tool.cache || tool.sync) ? line(`  ${names.dataDir}=<dir>`, "keep local data in this folder") : []),
+        ...settings.map(row),
         ``,
-        `Exit codes:`,
-        `  ${EXIT.ok} ok   ${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 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`,
         ``,
     ];
     if (app.definition.links?.repository)

package/dist/cli/install.d.ts

@@ -3,6 +3,8 @@
  */
 import type { App, CliIO } from "../app.js";
 import type { Format } from "./output.js";
+/** What `install --help` prints. */
+export declare function installHelp(app: App, bin: string): string;
 export declare function runInstall(app: App, io: CliIO, tokens: string[], options: {
     agent: boolean;
     dryRun: boolean;

package/dist/cli/install.js

@@ -21,6 +21,25 @@ function describe(plan) {
         lines.push(...(typeof plan.entry === "string" ? plan.entry : JSON.stringify({ [plan.name]: plan.entry }, null, 2)).split("\n").map((line) => `  ${line}`));
     return lines.join("\n");
 }
+/** What `install --help` prints. */
+export function installHelp(app, bin) {
+    return [
+        ``,
+        `Usage: ${bin} install <client> [flags]`,
+        ``,
+        `Adds ${app.title} to an MCP client in that client's own format, and keeps a backup of any file it changes.`,
+        ``,
+        `Clients: ${Object.keys(CLIENTS).join(", ")}`,
+        ``,
+        `Flags:`,
+        `  --scope user|project   where the client keeps it, for a client that has both`,
+        `  --name <name>          the server's name in the client (default: ${app.name})`,
+        `  --copy-env             copy credentials into the client's file, for a client that sees no environment`,
+        `  --local                start this copy on disk instead of the published package`,
+        `  --dry-run              show the change without making it`,
+        ``,
+    ].join("\n");
+}
 export async function runInstall(app, io, tokens, options) {
     const client = tokens.find((token) => !token.startsWith("--") && !["--scope", "--name"].includes(tokens[tokens.indexOf(token) - 1] ?? ""));
     const ids = Object.keys(CLIENTS);

package/dist/cli/run.js

@@ -14,7 +14,7 @@ import { visibility, policyEnvNames } from "../policy.js";
 import { outputJsonSchema } from "../schema.js";
 import { didYouMean, searchTools } from "../search.js";
 import { completionScript } from "./completion.js";
-import { agentContext, SLIPWAY_VERSION } from "./context.js";
+import { agentContext } from "./context.js";
 import { flagsFor, missingRequired, parseJsonValue, parseToolArgs } from "./flags.js";
 import { BUILTINS, renderGeneralHelp, renderList, renderToolHelp, toolLine } from "./help.js";
 import { formatOutput } from "./output.js";
@@ -151,7 +151,7 @@ export async function runCli(app, argv, partial = {}) {
                 return printVersion(app, io);
             if (globals.help)
                 return print(io, renderGeneralHelp(app, io.bin));
-            return print(io, renderList(app, app.tools(io.env), io.bin));
+            return print(io, renderList(app, app.tools(io.env), io.bin, io.env));
         }
         if (builtin)
             return await runBuiltin(app, io, command, rest, globals);
@@ -185,17 +185,23 @@ function print(io, text) {
     io.stdout(text.endsWith("\n") ? text : `${text}\n`);
     return EXIT.ok;
 }
+/** The bare version, which scripts compare. `agent-context` names the framework and its version. */
 function printVersion(app, io) {
-    return print(io, `${app.name} ${app.version} (slipway ${SLIPWAY_VERSION})`);
+    return print(io, app.version);
 }
 function json(globals, value) {
     return globals.format === "compact" ? JSON.stringify(value) : JSON.stringify(value, null, 2);
 }
 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));
+    if (globals.help && command !== "help")
+        return print(io, renderGeneralHelp(app, io.bin));
     const target = rest.find((token) => !token.startsWith("-"));
     switch (command) {
         case "tools":
-            return print(io, renderList(app, app.tools(io.env), io.bin));
+            return print(io, renderList(app, app.tools(io.env), io.bin, io.env));
         case "version":
             return printVersion(app, io);
         case "help": {

package/dist/result.d.ts

@@ -1,10 +1,15 @@
 /**
  * Turning what a handler returns into what a client receives.
  *
- * A handler returns plain data. An object goes out twice: as compact JSON text,
- * which every client can show a model, and as `structuredContent`, which a
- * client can use without parsing text. Compact, because the reader of that text
- * is usually a model paying for every character, not a person.
+ * A handler returns plain data. An object goes out as compact JSON text, which
+ * every client can show a model. Compact, because the reader of that text is
+ * usually a model paying for every character, not a person.
+ *
+ * Only a tool that declares an output schema also sends `structuredContent`.
+ * Codex hands a model the structured copy in place of the text, as one escaped
+ * string: on a 700-character result that cost 211 more tokens than the text,
+ * and it hides a `render` text or an image the same way. With a schema the
+ * copy is typed and validated data a client can use; without one it only costs.
  */
 import type { CallToolResult, ContentBlock } from "@modelcontextprotocol/server";
 import type { SlipwayError } from "./errors.js";

package/dist/result.js

@@ -1,10 +1,15 @@
 /**
  * Turning what a handler returns into what a client receives.
  *
- * A handler returns plain data. An object goes out twice: as compact JSON text,
- * which every client can show a model, and as `structuredContent`, which a
- * client can use without parsing text. Compact, because the reader of that text
- * is usually a model paying for every character, not a person.
+ * A handler returns plain data. An object goes out as compact JSON text, which
+ * every client can show a model. Compact, because the reader of that text is
+ * usually a model paying for every character, not a person.
+ *
+ * Only a tool that declares an output schema also sends `structuredContent`.
+ * Codex hands a model the structured copy in place of the text, as one escaped
+ * string: on a 700-character result that cost 211 more tokens than the text,
+ * and it hides a `render` text or an image the same way. With a schema the
+ * copy is typed and validated data a client can use; without one it only costs.
  */
 const CONTENT = Symbol.for("slipway.content");
 export function content(parts, data) {
@@ -48,7 +53,8 @@ export function toCallToolResult(tool, value, secrets) {
     if (isContentResult(value)) {
         const parts = value.parts.map((part) => part.type === "text" ? { ...part, text: secrets.redact(part.text) } : part);
         const data = secrets.redactDeep(value.data);
-        const structured = data !== undefined && (isPlainObject(data) || tool.output !== undefined);
+        // Without a schema the parts are the result, and the data is for a terminal.
+        const structured = data !== undefined && tool.output !== undefined;
         return structured ? { content: parts, structuredContent: data } : { content: parts };
     }
     const data = secrets.redactDeep(value);
@@ -62,12 +68,9 @@ export function toCallToolResult(tool, value, secrets) {
             : { content: [text(rendered ?? data)] };
     }
     const body = rendered ?? (typeof data === "object" ? JSON.stringify(data) : String(data));
-    // An object is always typed data. Anything else only is when the tool declares
-    // an output schema, because the protocol needs a schema to describe it.
-    if (isPlainObject(data) || tool.output !== undefined) {
-        return { content: [text(body)], structuredContent: data };
-    }
-    return { content: [text(body)] };
+    return tool.output !== undefined
+        ? { content: [text(body)], structuredContent: data }
+        : { content: [text(body)] };
 }
 export function errorResult(error, secrets) {
     return { isError: true, content: [text(secrets.redact(JSON.stringify(secrets.redactDeep(error.toJSON()))))] };

package/dist/schema.d.ts

@@ -33,6 +33,11 @@ export type Issue = {
  *
  * This is how a tool generated from an OpenAPI document or a pinned contract
  * joins the same tool list as hand-written ones.
+ *
+ * The validator compiles on the tool's first call, not when the server starts.
+ * Compiling all 123 schemas of one server up front held its first answer back
+ * by 118 ms, for tools most sessions never call. `slipway check` compiles every
+ * one, so a schema that cannot compile still fails before release.
  */
 export declare function jsonSchema<T = Record<string, unknown>>(schema: JsonSchema): Schema<T, T>;
 /** The input of a tool that takes nothing. */

package/dist/schema.js

@@ -14,9 +14,22 @@ const TARGET = { target: "draft-2020-12" };
  *
  * This is how a tool generated from an OpenAPI document or a pinned contract
  * joins the same tool list as hand-written ones.
+ *
+ * The validator compiles on the tool's first call, not when the server starts.
+ * Compiling all 123 schemas of one server up front held its first answer back
+ * by 118 ms, for tools most sessions never call. `slipway check` compiles every
+ * one, so a schema that cannot compile still fails before release.
  */
 export function jsonSchema(schema) {
-    return fromJsonSchema(schema);
+    let compiled;
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "mcp",
+            jsonSchema: { input: () => schema, output: () => schema },
+            validate: (value) => (compiled ??= fromJsonSchema(schema))["~standard"].validate(value),
+        },
+    };
 }
 /** The input of a tool that takes nothing. */
 export function emptyInput() {

package/dist/server.js

@@ -151,7 +151,7 @@ function registerSearchSurface(server, app, env, policy) {
             summary: firstSentence(tool.description),
         }));
         const data = { query, count: matches.length, tools: matches };
-        return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
     });
     register("describe_tool", {
         title: "Describe a tool",
@@ -172,7 +172,7 @@ function registerSearchSurface(server, app, env, policy) {
             ...(tool.output ? { output_schema: outputJsonSchema(tool.output) } : {}),
             ...(tool.examples.length ? { examples: tool.examples } : {}),
         };
-        return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+        return { content: [{ type: "text", text: JSON.stringify(data) }] };
     });
     register("call_tool", {
         title: "Run a tool",

package/dist/testing.d.ts

@@ -1,10 +1,10 @@
 /**
  * Helpers for testing an app the way its users reach it.
  *
- *     import { connect, cli } from "@thenavidm/slipway/testing";
+ *     import { connect, cli, resultData } from "@thenavidm/slipway/testing";
  *
  *     const mcp = await connect(app, { env });
- *     const result = await mcp.callTool("get_profile", { actor: "alice" });
+ *     const profile = resultData(await mcp.callTool("get_profile", { actor: "alice" }));
  *
  *     const { code, stdout } = await cli(app, ["get-profile", "alice", "--json"], { env });
  */
@@ -21,6 +21,17 @@ export type { ConnectOptions, ElicitAnswer, ElicitRequest, ListedTool, RpcClient
 export declare function connect(app: App, options?: ConnectOptions & {
     env?: NodeJS.ProcessEnv;
 }): Promise<RpcClient>;
+/**
+ * The data a tool call returned: its `structuredContent` when the tool declares
+ * an output schema, otherwise the JSON in its first text block.
+ */
+export declare function resultData<T = any>(result: {
+    content?: ReadonlyArray<{
+        type: string;
+        text?: string;
+    }>;
+    structuredContent?: unknown;
+}): T;
 export type CliRun = {
     code: number;
     stdout: string;

package/dist/testing.js

@@ -1,10 +1,10 @@
 /**
  * Helpers for testing an app the way its users reach it.
  *
- *     import { connect, cli } from "@thenavidm/slipway/testing";
+ *     import { connect, cli, resultData } from "@thenavidm/slipway/testing";
  *
  *     const mcp = await connect(app, { env });
- *     const result = await mcp.callTool("get_profile", { actor: "alice" });
+ *     const profile = resultData(await mcp.callTool("get_profile", { actor: "alice" }));
  *
  *     const { code, stdout } = await cli(app, ["get-profile", "alice", "--json"], { env });
  */
@@ -20,6 +20,18 @@ export function connect(app, options = {}) {
     const { env, ...rest } = options;
     return connectInMemory(app, env ?? {}, rest);
 }
+/**
+ * The data a tool call returned: its `structuredContent` when the tool declares
+ * an output schema, otherwise the JSON in its first text block.
+ */
+export function resultData(result) {
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    const first = result.content?.find((part) => part.type === "text");
+    if (first?.text === undefined)
+        throw new Error("The result has no structured content and no text.");
+    return JSON.parse(first.text);
+}
 /** Run the CLI with captured output. Nothing reaches the real terminal. */
 export async function cli(app, argv, options = {}) {
     let stdout = "";

package/dist/tool.d.ts

@@ -131,7 +131,7 @@ export type ToolDefinition<Ctx, I extends Schema, O extends Schema | undefined>
     cache?: CacheOptions;
     /** This read lists records worth keeping locally: `data sync` copies every page, `data search` finds them. */
     sync?: SyncOptions;
-    /** Text for the result, when JSON is not the best way to read it. Typed data still goes out as `structuredContent`. */
+    /** Text for the result, when JSON is not the best way to read it. With `output` declared, the data also goes out as `structuredContent`. */
     render?: (result: Returns<O>) => string;
     handler: (args: InferOutput<I>, ctx: ToolContext<Ctx>) => Returns<O> | Promise<Returns<O>>;
 };

package/package.json

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