@thenavidm/slipway 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.14, 2026-10-05: what Buffer needed
+
+- **`which` and the search surface read what a tool takes.** Argument names count for a little less than the title and more than the description, and camelCase is split, so `channelId` reads as "channel" and `createPost` as "create post". Buffer's "schedule a post to a channel" never listed `create-post`, whose description says neither word but whose `channelId` and `schedulingType` say both; a Codex run that asked `which` then read the whole command list as well.
+
+## 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.

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,6 +576,7 @@ 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 |

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

@@ -12,6 +12,8 @@ const STOP_WORDS = new Set([
 ]);
 function words(text) {
     return text
+        // camelCase splits, so `channelId` reads as "channel id" and `createPost` as "create post".
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
         .toLowerCase()
         .split(/[^a-z0-9]+/)
         .filter((word) => word.length > 1)
@@ -91,11 +93,13 @@ export function searchTools(tools, query, limit = 10, synonyms = {}) {
         const title = words(tool.title);
         const tags = tool.tags.flatMap(words);
         const description = words(tool.description);
+        // What a tool takes says what it is for: `channelId` and `schedulingType` find the post tool for "schedule a post to a channel".
+        const args = Object.keys(tool.jsonSchema.properties ?? {}).filter((key) => key !== "confirm").flatMap(words);
         let score = 0;
         let matched = 0;
         for (const term of terms) {
             // A term that is the tool's name is not a hint, it is the answer.
-            const got = (named(tool, term) ? 20 : 0) + hits(term, name, extra) * 5 + hits(term, title, extra) * 4 + hits(term, tags, extra) * 3 + hits(term, description, extra);
+            const got = (named(tool, term) ? 20 : 0) + hits(term, name, extra) * 5 + hits(term, title, extra) * 4 + hits(term, tags, extra) * 3 + hits(term, args, extra) * 2 + hits(term, description, extra);
             if (got > 0)
                 matched++;
             score += got;

package/package.json

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