@thenavidm/slipway 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.13, 2026-10-05: what Beehiiv needed
+
+- **`jsonSchema(schema, { shareRepeats: true })` writes each repeated part of a contract schema once.** A schema generated from an API contract often spells one definition out everywhere it is used. Beehiiv's post body repeats its block styling in each of 33 block types and carries the body twice, as its own fields and as `payload`, so its create-post tool advertised 387 KB. With each repeated part under `$defs` and referred to with `$ref`, it is 40 KB, and Beehiiv's 117 tools together go from 1,684 KB to 308 KB. Nothing is lost: each part reads the same once the references are followed, Claude Code and Codex both read fields that appear only under `$defs`, and validation accepts and refuses the same arguments. Definitions take the name of the property or block type they came from, such as `paragraph` or `visual_settings`, and parts under 200 bytes stay inline. The work is linear in the schema's size and happens when the tool is first listed. `shareRepeats()` is exported for a schema built some other way.
+- **`slipway check` names that fix wherever it would help.** A schema over the size budget whose shared form is at least a fifth smaller says how big it would be.
+- **CLI flags read through `$ref`.** An array whose items were a reference became a repeatable text flag, so a list of objects could not be passed; it is a JSON flag again, and a property that is only a reference takes its type, choices and description from the definition. `slipway check` no longer warns that such a property has no description.
+- **`doctor` tells a server that only reads apart.** "Writes: on" read as if it could change something; it now says every tool only reads. A setting doctor cannot read points at `login` for what to set, where it told the person to run the doctor they were running, and the verdict says a setting needs fixing rather than that nothing is configured.
+
+## 0.1.12, 2026-10-05: what the Meta Ad Library needed
+
+- **The write switches appear only where they act.** `<PREFIX>_READ_ONLY` and `<PREFIX>_AUDIT_LOG` are listed in the general help, `agent-context` and the generated settings table only when a tool writes, and `<PREFIX>_ALLOW_DESTRUCTIVE` and `<PREFIX>_CONFIRM` only when a tool can be irreversible, spends money or needs confirming. The Meta Ad Library server only reads, and its help offered to "refuse the irreversible writes"; it is now 40 tokens shorter, 399 against 439. The switches still work if set.
+
 ## 0.1.11, 2026-10-05: what WordPress needed
 
 - **Records no longer advertise `propertyNames`.** Zod 4 gives every `z.record` `propertyNames: { type: "string" }`, which every JSON object key already is, and the Zod 3 converters never wrote it. Slipway leaves it out of what clients receive, as it does the safe-integer bounds, and validation still runs on the schema itself. Each one cost 8 tokens; WordPress has nine. An argument that happens to be named `propertyNames` is a name, so it stays.

package/README.md

@@ -255,6 +255,8 @@ export const renameCourse = defineTool({
 });
 ```
 
+A contract schema often spells one definition out everywhere it is used. `jsonSchema(schema, { shareRepeats: true })` advertises it with each repeated part written once under `$defs` and referred to with `$ref`. Beehiiv's create-post tool went from 387 KB to 40 KB this way, and nothing is lost: Claude Code and Codex both read fields that appear only under `$defs`, validation accepts and refuses the same arguments, and the CLI's flags read through the references. `slipway check` says when it would help, and by how much.
+
 ## 4. Safety
 
 Shipping no writes is not safety: it hands the work back to a person. Shipping them unguarded is worse. So every write works, and the irreversible ones need a confirmation the caller gives on purpose.
@@ -574,15 +576,18 @@ See [CHANGELOG.md](CHANGELOG.md).
 | --- | --- | --- |
 | [Apple Podcasts](https://github.com/thenavidm/apple-podcasts-mcp-cli) | [`@thenavidm/apple-podcasts-mcp-cli`](https://www.npmjs.com/package/@thenavidm/apple-podcasts-mcp-cli) 2.0.0 | The catalog, charts per country, reviews and feeds, your library on this Mac with its transcript excerpts, and analytics for a show you own |
 | [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 |
+| [Meta Ad Library](https://github.com/thenavidm/facebook-ad-library-mcp-cli) | [`@thenavidm/facebook-ad-library-mcp-cli`](https://www.npmjs.com/package/@thenavidm/facebook-ad-library-mcp-cli) 0.6.0 | Every ad running on Facebook, Instagram and Threads for any advertiser: copy, creatives, how long each has run, what changed, and EU spend and reach |
 | [Google Photos](https://github.com/thenavidm/google-photos-mcp-cli) | [`@thenavidm/google-photos-mcp-cli`](https://www.npmjs.com/package/@thenavidm/google-photos-mcp-cli) 2.0.0 | The photo picker, uploads, albums and their captions, places and maps, and media this server uploaded, across several Google accounts |
 | [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 |
+| [Podcast Index](https://github.com/thenavidm/podcastindex-mcp-cli) | [`@thenavidm/podcastindex-mcp-cli`](https://www.npmjs.com/package/@thenavidm/podcastindex-mcp-cli) 2.0.0 | The open podcast directory, with the transcripts and chapters it links to fetched and read, guest histories, feed health and value-for-value |
 | [Substack](https://github.com/thenavidm/substack-mcp-cli) | [`@thenavidm/substack-mcp-cli`](https://www.npmjs.com/package/@thenavidm/substack-mcp-cli) 3.0.0 | Drafts, publishing and scheduling, Notes, subscribers, analytics, tags, comments and researching other publications |
 | [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 |
 | [TikTok](https://github.com/thenavidm/tiktok-mcp-cli) | [`@thenavidm/tiktok-mcp-cli`](https://www.npmjs.com/package/@thenavidm/tiktok-mcp-cli) 2.0.0 | Your own account's profile and videos, ranked by any metric, posting and drafts, through TikTok's official API |
 | [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 |
-| [YouTube](https://github.com/thenavidm/youtube-mcp-cli) | [`@thenavidm/youtube-mcp-cli`](https://www.npmjs.com/package/@thenavidm/youtube-mcp-cli) 3.0.0 | Transcripts of any public video, channel research against each channel's own median, and your own channels' videos, comments and analytics |
+| [WordPress](https://github.com/thenavidm/wordpress-mcp-cli) | [`@thenavidm/wordpress-mcp-cli`](https://www.npmjs.com/package/@thenavidm/wordpress-mcp-cli) 2.0.0 | Posts, pages, custom post types, media, terms, users and comments across several sites, plus Elementor, Rank Math, redirects and bulk edits through a helper plugin |
+| [YouTube](https://github.com/thenavidm/youtube-mcp-cli) | [`@thenavidm/youtube-mcp-cli`](https://www.npmjs.com/package/@thenavidm/youtube-mcp-cli) 3.0.1 | Transcripts of any public video, channel research against each channel's own median, and your own channels' videos, comments and analytics |
 
 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/check.js

@@ -15,7 +15,7 @@ import { agentContext } from "./cli/context.js";
 import { flagsFor } from "./cli/flags.js";
 import { BUILTINS, GLOBAL_FLAGS, renderToolHelp } from "./cli/help.js";
 import { connectInMemory } from "./rpc.js";
-import { repeatedDefinitions, schemaBytes, validate, formatIssues } from "./schema.js";
+import { repeatedDefinitions, resolveLocalRef, schemaBytes, shareRepeats, validate, formatIssues } from "./schema.js";
 import { REQUIRES_USER_INTERACTION } from "./server.js";
 const PROPERTY = /^[A-Za-z0-9_.-]{1,64}$/;
 const DEFAULT_BUDGET = { warnBytes: 16 * 1024, errorBytes: 128 * 1024 };
@@ -98,7 +98,7 @@ export async function checkApp(app, options = {}) {
             if (!PROPERTY.test(name))
                 add("error", "schema", `Property '${name}' must be 1-64 letters, digits, '_', '.' or '-'.`, tool.name);
         }
-        const undocumented = Object.entries(properties).filter(([name, prop]) => name !== "confirm" && !prop.description).map(([name]) => name);
+        const undocumented = Object.entries(properties).filter(([name, prop]) => name !== "confirm" && !resolveLocalRef(schema, prop).description).map(([name]) => name);
         if (undocumented.length)
             add("warn", "descriptions", `No description for: ${undocumented.join(", ")}.`, tool.name);
         const problem = meta?.(schema);
@@ -117,10 +117,13 @@ export async function checkApp(app, options = {}) {
         totalBytes += bytes;
         if (!largest || bytes > largest.bytes)
             largest = { name: tool.name, bytes };
+        // Sharing the repeated parts is the fix that loses nothing, so it is named first wherever it would help.
+        const shared = bytes > budget.warnBytes ? schemaBytes(shareRepeats(schema)) : bytes;
+        const share = shared < bytes * 0.8 ? ` jsonSchema(schema, { shareRepeats: true }) writes each repeated part once and brings it to ${Math.round(shared / 1024)} KB, with nothing lost.` : "";
         if (bytes > budget.errorBytes)
-            add("error", "size", `The schema is ${Math.round(bytes / 1024)} KB. Advertise a short schema and validate the full one in the handler.`, tool.name);
+            add("error", "size", `The schema is ${Math.round(bytes / 1024)} KB.${share} ${share ? "Or advertise" : "Advertise"} a short schema and validate the full one in the handler.`, tool.name);
         else if (bytes > budget.warnBytes)
-            add("warn", "size", `The schema is ${Math.round(bytes / 1024)} KB, which a model pays for every time it loads this tool.`, tool.name);
+            add("warn", "size", `The schema is ${Math.round(bytes / 1024)} KB, which a model pays for every time it loads this tool.${share}`, tool.name);
         const repeated = repeatedDefinitions(schema);
         if (repeated.length)
             add("warn", "size", `Definitions appear more than once: ${repeated.slice(0, 5).join(", ")}${repeated.length > 5 ? "…" : ""}.`, tool.name);

package/dist/cli/context.js

@@ -7,7 +7,7 @@
  */
 import { createRequire } from "node:module";
 import { EXIT } from "../errors.js";
-import { policyEnvNames } from "../policy.js";
+import { policyEnvNames, switchesThatApply } from "../policy.js";
 import { outputJsonSchema } from "../schema.js";
 import { exampleCommand, GLOBAL_FLAGS } from "./help.js";
 import { flagsFor } from "./flags.js";
@@ -26,6 +26,7 @@ export const EXIT_MEANINGS = {
 export function agentContext(app, env, bin, options = {}) {
     const policy = app.policy(env);
     const names = policyEnvNames(app.envPrefix);
+    const applies = switchesThatApply(app.allTools);
     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.
@@ -78,15 +79,19 @@ export function agentContext(app, env, bin, options = {}) {
                 ...(setting.secret ? { secret: true } : {}),
                 description: setting.description,
             })),
-            { env: names.readOnly, value: policy.readOnly, description: "hide and refuse every write" },
-            { 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" },
+            ...(applies.readOnly ? [{ env: names.readOnly, value: policy.readOnly, description: "hide and refuse every write" }] : []),
+            ...(applies.allowDestructive
+                ? [{ 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" }]
                 : []),
             { env: names.surface, value: policy.surface, description: "full tool list, or search for very large catalogs" },
-            { env: names.auditLog, value: policy.auditLog ?? null, description: "file that records every attempted write" },
+            ...(applies.auditLog ? [{ 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" },
+            ...(applies.confirm
+                ? [{ 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" },

package/dist/cli/flags.d.ts

@@ -5,7 +5,7 @@
  * one surface and not the other, and its help text is the description the
  * model reads.
  */
-import type { JsonSchema } from "../schema.js";
+import { type JsonSchema } from "../schema.js";
 export type FlagKind = "string" | "number" | "integer" | "boolean" | "enum" | "json";
 export type Flag = {
     /** The property name: `reply_to`. */

package/dist/cli/flags.js

@@ -7,28 +7,30 @@
  */
 import { readFileSync } from "node:fs";
 import { UsageError } from "../errors.js";
+import { resolveLocalRef } from "../schema.js";
 import { didYouMean } from "../search.js";
-/** The first concrete type, looking through nullable unions and type lists. */
-function concrete(node) {
+/** The first concrete type, looking through references, nullable unions and type lists. */
+function concrete(raw, root) {
+    const node = resolveLocalRef(root, raw);
     const union = node.anyOf ?? node.oneOf;
     if (union) {
-        const options = union.filter((option) => option.type !== "null");
+        const options = union.map((option) => resolveLocalRef(root, option)).filter((option) => option.type !== "null");
         // A union of plain literals is an enum in disguise, which a person types as a word.
         if (options.length > 1 && options.every((option) => option.const !== undefined)) {
             return { ...node, enum: options.map((option) => option.const) };
         }
-        return concrete({ ...(options[0] ?? {}), description: node.description ?? options[0]?.description });
+        return concrete({ ...(options[0] ?? {}), description: node.description ?? options[0]?.description }, root);
     }
     if (Array.isArray(node.type))
         return { ...node, type: node.type.find((type) => type !== "null") ?? "string" };
     return node;
 }
-function kindOf(node) {
-    const n = concrete(node);
+function kindOf(node, root) {
+    const n = concrete(node, root);
     if (n.enum)
         return { kind: "enum", repeatable: false, choices: n.enum.map(String) };
     if (n.type === "array") {
-        const item = concrete(n.items ?? {});
+        const item = concrete(n.items ?? {}, root);
         if (item.enum)
             return { kind: "enum", repeatable: true, choices: item.enum.map(String) };
         if (item.type === "object" || item.type === "array")
@@ -50,11 +52,11 @@ export function flagsFor(schema) {
     const properties = schema.properties ?? {};
     const required = new Set(schema.required ?? []);
     return Object.entries(properties).map(([key, node]) => {
-        const n = concrete(node);
+        const n = concrete(node, schema);
         return {
             key,
             flag: flagName(key),
-            ...kindOf(node),
+            ...kindOf(node, schema),
             required: required.has(key),
             help: (node.description ?? n.description ?? "").trim(),
             ...(node.default !== undefined ? { default: node.default } : n.default !== undefined ? { default: n.default } : {}),

package/dist/cli/help.js

@@ -5,7 +5,7 @@
  * shows what applies and points to the rest instead of repeating it.
  */
 import { EXIT } from "../errors.js";
-import { policyEnvNames, riskMark, visibility } from "../policy.js";
+import { policyEnvNames, riskMark, switchesThatApply, visibility } from "../policy.js";
 import { firstSentence } from "../search.js";
 import { flagsFor } from "./flags.js";
 const COLUMN = 30;
@@ -205,6 +205,7 @@ function table(rows) {
 }
 export function renderGeneralHelp(app, bin) {
     const names = policyEnvNames(app.envPrefix);
+    const applies = switchesThatApply(app.allTools);
     const cache = app.allTools.some((tool) => tool.cache);
     const sync = app.allTools.some((tool) => tool.sync);
     const jobs = app.allTools.some((tool) => tool.job);
@@ -236,20 +237,24 @@ export function renderGeneralHelp(app, bin) {
     const tuning = [
         ...(app.definition.settings ?? []).filter((setting) => setting.tuning).map((setting) => setting.env),
         names.surface,
-        names.auditLog,
+        ...(applies.auditLog ? [names.auditLog] : []),
         names.toolTimeoutMs,
-        names.confirm,
+        ...(applies.confirm ? [names.confirm] : []),
         ...(cache ? [names.cache] : []),
         ...(cache || sync ? [names.dataDir] : []),
         `${app.envPrefix}_DEBUG`,
     ];
     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`,
-            `${app.definition.defaults?.destructiveOff === "hide" ? "hide and refuse" : "refuse"} the irreversible writes${app.allTools.some((tool) => tool.spends) ? " and paid calls" : ""}`,
-        ],
+        ...(applies.readOnly ? [[`${names.readOnly}=1`, "hide and refuse every write"]] : []),
+        ...(applies.allowDestructive
+            ? [
+                [
+                    `${names.allowDestructive}=0`,
+                    `${app.definition.defaults?.destructiveOff === "hide" ? "hide and refuse" : "refuse"} the irreversible writes${app.allTools.some((tool) => tool.spends) ? " and paid calls" : ""}`,
+                ],
+            ]
+            : []),
         // 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"]] : []),
         [`${app.envPrefix}_HTTP_PORT / _HOST / _TOKEN / _ALLOWED_ORIGINS`, "for --http"],

package/dist/docs.js

@@ -7,7 +7,7 @@
  */
 import { flagsFor } from "./cli/flags.js";
 import { exampleCommand } from "./cli/help.js";
-import { policyEnvNames } from "./policy.js";
+import { policyEnvNames, switchesThatApply } from "./policy.js";
 function cell(text) {
     return text.replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ").trim() || "None";
 }
@@ -47,17 +47,22 @@ export function toolReference(app, tools, heading = "###") {
 }
 export function settingsTable(app) {
     const names = policyEnvNames(app.envPrefix);
+    const applies = switchesThatApply(app.allTools);
     return [
         "| Variable | What it does |",
         "|---|---|",
         ...(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${app.allTools.some((tool) => tool.spends) ? " and paid calls" : ""} |`,
+        ...(applies.readOnly ? [`| \`${names.readOnly}=1\` | Hide and refuse every write |`] : []),
+        ...(applies.allowDestructive
+            ? [`| \`${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 |`,
+        ...(applies.auditLog ? [`| \`${names.auditLog}\` | File that records every attempted write |`] : []),
         `| \`${names.toolTimeoutMs}\` | Give up on any tool after this many milliseconds |`,
-        `| \`${names.confirm}=model\` | Let \`confirm: true\` alone confirm a call, for an agent with no person to ask. The default, \`human\`, asks a person wherever the client can |`,
+        ...(applies.confirm
+            ? [`| \`${names.confirm}=model\` | Let \`confirm: true\` alone confirm a call, for an agent with no person to ask. The default, \`human\`, asks a person wherever the client can |`]
+            : []),
     ].join("\n");
 }
 export function renderDocs(app, env = process.env) {

package/dist/doctor.js

@@ -17,7 +17,13 @@ export async function runDoctor(app, io, options) {
     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 paid = app.allTools.some((tool) => tool.spends) ? " and paid" : "";
-    const writes = policy.readOnly ? "off (read-only)" : policy.allowDestructive ? "on" : `on, irreversible${paid} ones refused`;
+    const writes = !app.allTools.some((tool) => tool.risk !== "read")
+        ? "none: every tool only reads"
+        : 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",
@@ -51,14 +57,18 @@ export async function runDoctor(app, io, options) {
         });
     }
     let configured = true;
+    let unreadable = false;
     let ctx;
     try {
         ctx = await app.context(io.env);
     }
     catch (error) {
         configured = false;
+        unreadable = true;
         const e = error instanceof SlipwayError ? error : new NotConfiguredError(String(error?.message ?? error));
-        checks.push({ name: "Setup", ok: false, detail: e.message, fix: e.hint ?? `Run \`${app.bins.cli} login\`.` });
+        // Outside doctor, a setting that cannot be read points here; in here, it points at how to set it.
+        const fix = e.hint && !e.hint.includes(`${app.bins.cli} doctor`) ? e.hint : `Run \`${app.bins.cli} login\` for what to set.`;
+        checks.push({ name: "Setup", ok: false, detail: e.message, fix });
     }
     if (ctx !== undefined && app.definition.configured) {
         configured = await app.definition.configured(ctx);
@@ -95,7 +105,8 @@ export async function runDoctor(app, io, options) {
             if (!check.ok && check.fix)
                 lines.push(`    ${" ".repeat(width)}${check.fix}`);
         }
-        lines.push(``, code === EXIT.ok ? "  Ready." : code === EXIT.notConfigured ? "  Nothing is configured yet." : "  Something needs fixing.", ``);
+        const verdict = code === EXIT.ok ? "Ready." : unreadable ? "A setting needs fixing." : code === EXIT.notConfigured ? "Nothing is configured yet." : "Something needs fixing.";
+        lines.push(``, `  ${verdict}`, ``);
         io.stdout(lines.join("\n"));
     }
     return code;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { slipway, stderrLogger } from "./app.js";
 export type { App, AppDefinition, CliIO, DoctorCheck, DryRun, InvokeOptions, PromptDefinition, ResourceDefinition, ServiceSetting, } from "./app.js";
 export { defineTool, isTool, toolkit } from "./tool.js";
 export type { CacheOptions, Logger, Paginate, Risk, RunContext, Surface, SyncOptions, Tool, ToolContext, ToolDefinition, ToolExample } from "./tool.js";
-export { emptyInput, inputJsonSchema, jsonSchema, outputJsonSchema, validate, CONFIRM_DESCRIPTION } from "./schema.js";
+export { emptyInput, inputJsonSchema, jsonSchema, outputJsonSchema, shareRepeats, validate, CONFIRM_DESCRIPTION } from "./schema.js";
 export type { InferInput, InferOutput, JsonSchema, Schema } from "./schema.js";
 export { ApiError, AuthError, CanceledError, EXIT, NotConfiguredError, NotFoundError, RateLimitError, RefusedError, SlipwayError, TimeoutError, UsageError, httpError, toSlipwayError, } from "./errors.js";
 export type { ErrorCode, ErrorPayload } from "./errors.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  */
 export { slipway, stderrLogger } from "./app.js";
 export { defineTool, isTool, toolkit } from "./tool.js";
-export { emptyInput, inputJsonSchema, jsonSchema, outputJsonSchema, validate, CONFIRM_DESCRIPTION } from "./schema.js";
+export { emptyInput, inputJsonSchema, jsonSchema, outputJsonSchema, shareRepeats, validate, CONFIRM_DESCRIPTION } from "./schema.js";
 export { ApiError, AuthError, CanceledError, EXIT, NotConfiguredError, NotFoundError, RateLimitError, RefusedError, SlipwayError, TimeoutError, UsageError, httpError, toSlipwayError, } from "./errors.js";
 export { audio, content, file, image, resourceLink, text } from "./result.js";
 export { readPolicy, policyEnvNames } from "./policy.js";

package/dist/policy.d.ts

@@ -62,6 +62,19 @@ export type PolicyEnv = {
     cache: string;
     dataDir: string;
 };
+/**
+ * Which of the write switches can change anything for these tools. A server
+ * whose tools all read has nothing for read-only mode to hide or the audit log
+ * to record, and one with no irreversible, paid or confirmed call has nothing
+ * for the destructive and confirm switches to act on, so help, agent-context
+ * and the generated docs leave those out. They still work if set.
+ */
+export declare function switchesThatApply(tools: readonly Tool[]): {
+    readOnly: boolean;
+    allowDestructive: boolean;
+    auditLog: boolean;
+    confirm: boolean;
+};
 export declare function policyEnvNames(prefix: string): PolicyEnv;
 export declare function readPolicy(env: NodeJS.ProcessEnv, prefix: string, defaults?: PolicyDefaults): Policy;
 export type Visibility = {

package/dist/policy.js

@@ -6,6 +6,22 @@
  * block the irreversible ones, keep a log, load fewer tools. They live under
  * the server's own prefix, so two servers in one client never share a switch.
  */
+/**
+ * Which of the write switches can change anything for these tools. A server
+ * whose tools all read has nothing for read-only mode to hide or the audit log
+ * to record, and one with no irreversible, paid or confirmed call has nothing
+ * for the destructive and confirm switches to act on, so help, agent-context
+ * and the generated docs leave those out. They still work if set.
+ */
+export function switchesThatApply(tools) {
+    const writes = tools.some((tool) => tool.risk !== "read");
+    return {
+        readOnly: writes,
+        allowDestructive: tools.some((tool) => tool.risk === "destructive" || tool.spends),
+        auditLog: writes,
+        confirm: tools.some((tool) => tool.requireConfirm),
+    };
+}
 export function policyEnvNames(prefix) {
     return {
         readOnly: `${prefix}_READ_ONLY`,

package/dist/schema.d.ts

@@ -38,8 +38,13 @@ export type Issue = {
  * 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.
+ *
+ * `shareRepeats: true` advertises the schema with each repeated part written
+ * once, as `shareRepeats()` describes.
  */
-export declare function jsonSchema<T = Record<string, unknown>>(schema: JsonSchema): Schema<T, T>;
+export declare function jsonSchema<T = Record<string, unknown>>(schema: JsonSchema, options?: {
+    shareRepeats?: boolean;
+}): Schema<T, T>;
 /** The input of a tool that takes nothing. */
 export declare function emptyInput(): Schema<Record<string, never>>;
 export declare function isSchema(value: unknown): value is Schema;
@@ -101,4 +106,28 @@ export declare function schemaBytes(schema: JsonSchema): number;
  * often half repetition.
  */
 export declare function repeatedDefinitions(schema: JsonSchema): string[];
+/**
+ * The same schema with each part that repeats written once, under `$defs`, and
+ * referred to with `$ref` everywhere it appeared.
+ *
+ * A schema generated from an API contract often spells one definition out
+ * everywhere it is used: one newsletter API's post body repeats the same
+ * styling block 33 times, and its create-post tool came to 378 KB, where
+ * sharing the repeats leaves 37 KB. Nothing is lost: each part reads the
+ * same, and Claude Code and Codex both read fields that appear only under
+ * `$defs`. Parts under 200 bytes stay inline, so the schema still reads top
+ * to bottom.
+ *
+ * A schema with a `$ref` to anything but its own definitions is returned as
+ * it is, since moving a part could break that reference. The work is linear in
+ * the schema's size: each distinct part is serialized once.
+ */
+export declare function shareRepeats(schema: JsonSchema, options?: {
+    minBytes?: number;
+}): JsonSchema;
+/**
+ * A property that is only a reference into the schema's own definitions, read
+ * as the definition it points to, with its own words first.
+ */
+export declare function resolveLocalRef<T extends Record<string, unknown>>(root: JsonSchema, node: T): T;
 export {};

package/dist/schema.js

@@ -19,15 +19,21 @@ const TARGET = { target: "draft-2020-12" };
  * 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.
+ *
+ * `shareRepeats: true` advertises the schema with each repeated part written
+ * once, as `shareRepeats()` describes.
  */
-export function jsonSchema(schema) {
+export function jsonSchema(schema, options = {}) {
     let compiled;
+    let shared;
+    // Shared on first use, like the validator, so a command that never lists this tool never pays for it.
+    const advertisedSchema = () => (options.shareRepeats ? (shared ??= shareRepeats(schema)) : schema);
     return {
         "~standard": {
             version: 1,
             vendor: "mcp",
-            jsonSchema: { input: () => schema, output: () => schema },
-            validate: (value) => (compiled ??= fromJsonSchema(schema))["~standard"].validate(value),
+            jsonSchema: { input: advertisedSchema, output: advertisedSchema },
+            validate: (value) => (compiled ??= fromJsonSchema(advertisedSchema()))["~standard"].validate(value),
         },
     };
 }
@@ -231,3 +237,204 @@ export function repeatedDefinitions(schema) {
     visit(schema);
     return [...seen.entries()].filter(([, count]) => count > 1).map(([fingerprint]) => fingerprint.split(":")[0]);
 }
+/** Keywords whose value is one subschema. */
+const ONE_SCHEMA = new Set(["items", "additionalItems", "additionalProperties", "contains", "not", "if", "then", "else", "propertyNames", "unevaluatedItems", "unevaluatedProperties", "contentSchema"]);
+/** Keywords whose value is a list of subschemas. */
+const SCHEMA_LIST = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+/** Keywords whose value maps names to subschemas. */
+const SCHEMA_MAP = new Set(["properties", "patternProperties", "dependentSchemas", "$defs", "definitions"]);
+/** A part that carries one of these stays where it is: something may point into it, or it changes how references inside it resolve. */
+const ANCHORED = ["$id", "$anchor", "$dynamicAnchor", "$defs", "definitions"];
+/** Smaller parts stay inline, so the schema still reads top to bottom. */
+const SHARE_MIN_BYTES = 200;
+const CHILD = Symbol("child");
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Every `$ref` in the schema points into its own definitions, so moving any other part breaks none of them. */
+function refsOnlyInto(node, prefix) {
+    if (Array.isArray(node))
+        return node.every((item) => refsOnlyInto(item, prefix));
+    if (!isRecord(node))
+        return true;
+    if (node.$ref !== undefined && !(typeof node.$ref === "string" && node.$ref.startsWith(prefix)))
+        return false;
+    return Object.values(node).every((value) => refsOnlyInto(value, prefix));
+}
+/** A definition name a JSON pointer carries as is: letters, digits, `_`, `.` and `-`. */
+function definitionName(label) {
+    return label.replace(/[^A-Za-z0-9_.-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64) || "shared";
+}
+/** What to call one of several options: its title, or the value its `type` property is fixed to, such as `paragraph`. */
+function optionLabel(option, parent) {
+    if (!isRecord(option))
+        return `${parent}_option`;
+    if (typeof option.title === "string")
+        return option.title;
+    const discriminator = isRecord(option.properties) && isRecord(option.properties.type) ? option.properties.type : undefined;
+    const fixed = discriminator?.const ?? (Array.isArray(discriminator?.enum) && discriminator.enum.length === 1 ? discriminator.enum[0] : undefined);
+    return typeof fixed === "string" ? fixed : `${parent}_option`;
+}
+/**
+ * The same schema with each part that repeats written once, under `$defs`, and
+ * referred to with `$ref` everywhere it appeared.
+ *
+ * A schema generated from an API contract often spells one definition out
+ * everywhere it is used: one newsletter API's post body repeats the same
+ * styling block 33 times, and its create-post tool came to 378 KB, where
+ * sharing the repeats leaves 37 KB. Nothing is lost: each part reads the
+ * same, and Claude Code and Codex both read fields that appear only under
+ * `$defs`. Parts under 200 bytes stay inline, so the schema still reads top
+ * to bottom.
+ *
+ * A schema with a `$ref` to anything but its own definitions is returned as
+ * it is, since moving a part could break that reference. The work is linear in
+ * the schema's size: each distinct part is serialized once.
+ */
+export function shareRepeats(schema, options = {}) {
+    const minBytes = options.minBytes ?? SHARE_MIN_BYTES;
+    const key = !("$defs" in schema) && "definitions" in schema ? "definitions" : "$defs";
+    if ("$defs" in schema && "definitions" in schema)
+        return schema;
+    if (!refsOnlyInto(schema, `#/${key}/`))
+        return schema;
+    // Each distinct part once, by a signature built from its children's ids, so serializing is linear.
+    const parts = [];
+    const ids = new Map();
+    const build = (node, label) => {
+        if (!isRecord(node)) {
+            const json = JSON.stringify(node);
+            const known = ids.get(json);
+            if (known !== undefined)
+                return known;
+            parts.push({ template: node, bytes: Buffer.byteLength(json), label, movable: false, parents: new Map() });
+            ids.set(json, parts.length - 1);
+            return parts.length - 1;
+        }
+        const own = typeof node.title === "string" ? node.title : label;
+        const template = {};
+        const signature = [];
+        const children = [];
+        let bytes = 2 + Math.max(0, Object.keys(node).length - 1);
+        const child = (value, childLabel) => {
+            const id = build(value, childLabel);
+            children.push(id);
+            return { mark: { [CHILD]: id }, sig: `#${id}`, bytes: parts[id].bytes };
+        };
+        for (const [name, value] of Object.entries(node)) {
+            let entry;
+            if (ONE_SCHEMA.has(name) && (isRecord(value) || typeof value === "boolean")) {
+                entry = child(value, name === "items" ? `${own}_item` : own);
+            }
+            else if ((SCHEMA_LIST.has(name) || name === "items") && Array.isArray(value)) {
+                const list = value.map((item) => child(item, optionLabel(item, own)));
+                entry = { mark: list.map((item) => item.mark), sig: `[${list.map((item) => item.sig).join(",")}]`, bytes: 2 + Math.max(0, list.length - 1) + list.reduce((sum, item) => sum + item.bytes, 0) };
+            }
+            else if (SCHEMA_MAP.has(name) && isRecord(value)) {
+                const map = Object.entries(value).map(([field, sub]) => [JSON.stringify(field), child(sub, field)]);
+                entry = {
+                    mark: Object.fromEntries(map.map(([field, item]) => [JSON.parse(field), item.mark])),
+                    sig: `{${map.map(([field, item]) => `${field}:${item.sig}`).join(",")}}`,
+                    bytes: 2 + Math.max(0, map.length - 1) + map.reduce((sum, [field, item]) => sum + Buffer.byteLength(field) + 1 + item.bytes, 0),
+                };
+            }
+            else {
+                const json = JSON.stringify(value);
+                entry = { mark: value, sig: json, bytes: Buffer.byteLength(json) };
+            }
+            template[name] = entry.mark;
+            signature.push(`${JSON.stringify(name)}:${entry.sig}`);
+            bytes += Buffer.byteLength(JSON.stringify(name)) + 1 + entry.bytes;
+        }
+        const sig = `{${signature.join(",")}}`;
+        const known = ids.get(sig);
+        if (known !== undefined)
+            return known;
+        const id = parts.length;
+        parts.push({ template, bytes, label: own, movable: !ANCHORED.some((anchor) => anchor in node), parents: new Map() });
+        ids.set(sig, id);
+        for (const c of children)
+            parts[c].parents.set(id, (parts[c].parents.get(id) ?? 0) + 1);
+        return id;
+    };
+    const { [key]: existingDefs, ...rest } = schema;
+    const root = build(rest, "");
+    const names = new Map();
+    const taken = new Set();
+    const defsOrder = [];
+    // Two definitions with the same body keep both names: references in the schema use either.
+    const aliases = [];
+    for (const [name, body] of Object.entries(isRecord(existingDefs) ? existingDefs : {})) {
+        const id = build(body, name);
+        if (names.has(id))
+            aliases.push([name, id]);
+        else {
+            names.set(id, name);
+            defsOrder.push(id);
+        }
+        taken.add(name);
+    }
+    // How many times each part would be written out, deciding the larger ones first: a part is always larger than
+    // anything inside it, so every part that could contain this one is already decided.
+    const appear = new Array(parts.length).fill(0);
+    appear[root] = 1;
+    for (const id of defsOrder)
+        appear[id] = Math.max(appear[id], 1);
+    const order = parts.map((_, id) => id).sort((a, b) => parts[b].bytes - parts[a].bytes);
+    for (const id of order) {
+        const part = parts[id];
+        for (const [parent, times] of part.parents)
+            appear[id] += times * (names.has(parent) ? 1 : appear[parent]);
+        if (id === root || names.has(id) || !part.movable || part.bytes < minBytes || appear[id] < 2)
+            continue;
+        let name = definitionName(part.label);
+        for (let n = 2; taken.has(name); n++)
+            name = `${definitionName(part.label)}_${n}`;
+        const ref = Buffer.byteLength(JSON.stringify({ $ref: `#/${key}/${name}` }));
+        if ((appear[id] - 1) * part.bytes - appear[id] * ref - name.length - 4 <= 0)
+            continue;
+        names.set(id, name);
+        taken.add(name);
+        defsOrder.push(id);
+    }
+    if (!names.size)
+        return schema;
+    const fill = (template) => {
+        if (Array.isArray(template))
+            return template.map(fill);
+        if (!isRecord(template))
+            return template;
+        const marked = template[CHILD];
+        if (marked !== undefined)
+            return emit(marked, false);
+        return Object.fromEntries(Object.entries(template).map(([name, value]) => [name, fill(value)]));
+    };
+    const emit = (id, asDefinition) => {
+        const name = names.get(id);
+        return name !== undefined && !asDefinition ? { $ref: `#/${key}/${name}` } : fill(parts[id].template);
+    };
+    const out = fill(parts[root].template);
+    out[key] = Object.fromEntries([
+        ...defsOrder.map((id) => [names.get(id), emit(id, true)]),
+        ...aliases.map(([name, id]) => [name, { $ref: `#/${key}/${names.get(id)}` }]),
+    ]);
+    // Nothing repeated, or only a definition that every use already refers to: the schema stays the object it was.
+    return schemaBytes(out) < schemaBytes(schema) ? out : schema;
+}
+/**
+ * A property that is only a reference into the schema's own definitions, read
+ * as the definition it points to, with its own words first.
+ */
+export function resolveLocalRef(root, node) {
+    let current = node;
+    for (let hop = 0; hop < 8 && typeof current.$ref === "string"; hop++) {
+        const match = /^#\/(\$defs|definitions)\/([^/]+)$/.exec(current.$ref);
+        const defs = match ? root[match[1]] : undefined;
+        const target = match && isRecord(defs) ? defs[match[2].replace(/~1/g, "/").replace(/~0/g, "~")] : undefined;
+        if (!isRecord(target))
+            break;
+        const { $ref: _ref, ...own } = current;
+        current = { ...target, ...own };
+    }
+    return current;
+}

package/package.json

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