@spendgraph/tools 0.5.0 → 0.7.0

package/docs/selecting.mdx

@@ -0,0 +1,79 @@
+export const meta = {
+  title: "Selecting tools — spendgraph docs",
+  description:
+    "Fifty tools is 7.5k tokens before the user has said anything. `limit` is an accuracy budget, not a token one, and selection is keyword and usage on purpose.",
+};
+
+# Selecting
+
+```ts
+const bus = toolbus([lookup, currentTime()], { limit: 6 });
+
+bus.select(query)          // the working set for one request
+bus.anthropic(decls?)      // declarations, per provider
+bus.openai(decls?)
+bus.markdown(decls?)       // for a model with no tools API
+await bus.invoke(name, args)
+bus.missing(["refund"])    // names something expects that this bus lacks
+bus.usage()
+```
+
+Holding tools in one place is what makes selection possible. Fifty tools at roughly 150 tokens of declaration each is **7.5k tokens on every call** before the user has said anything, so past a point you stop sending all of them.
+
+## `limit` is an accuracy budget
+
+More tools in front of a model makes it worse at picking the right one **regardless of context length**. Measured shortlists cluster around five to eight. Pinned tools count against it — what is in front of the model is what costs accuracy, whoever put it there.
+
+A limit that is `NaN` is refused rather than clamped: `Math.max(1, NaN)` is `NaN`, and every length compares false against it, so the model would be offered **nothing** — the one outcome selection exists to avoid.
+
+## Keyword and usage, deliberately
+
+No embedding provider, no extra call, no latency. It is also the baseline that says what embeddings would buy.
+
+Relevance comes before usage: at a shortlist of six, three previously-used tools take half the slots and push out the tool the query needs. Usage earns its place as the tiebreaker among equal matches, and as the fallback when nothing matches — the case where an agent would otherwise be handed nothing.
+
+Words are found in **any script**. A query with no ASCII letters used to produce no terms at all, so every request fell through to "the first six declared" — the same six for a Japanese question as for a Russian one.
+
+## How a tool scores
+
+Whole words, never substrings. A term matching inside a longer word is noise, not signal: `me` sits inside `statement`, and at a few hundred tools that alone puts half the catalogue in every shortlist.
+
+Where the word appears decides its weight — **name beats alias beats description**. A tool named `refund` is a stronger answer to a question about refunds than one that merely mentions the word in a paragraph.
+
+Then each term is weighted by how **rare** it is across the bus. A word one tool in two thousand uses says far more than one four hundred of them share, and without that every term counts the same and common vocabulary decides the shortlist.
+
+## Aliases reach words a description never used
+
+Lexical ranking cannot cross a synonym. A question about money back scores **zero** against a tool called `refund`, whatever its description says. Declare the wording callers actually type:
+
+```ts
+tool({
+  name: "issue_refund",
+  aliases: ["money back", "chargeback", "reimburse"],
+  description: "Reverses a completed order and returns the payment.",
+  args,
+  run,
+});
+```
+
+They are matched, never sent — every provider shape drops them, exactly as it drops `effect`. Unlike an embedding, a bad match is fixed by editing one line.
+
+<Callout tone="trap" title="Pinned tools spend the budget too">
+  `limit` counts pinned tools, so a shortlist of 5 with `finish` and `escalate` pinned leaves three slots for the query. A tool that needs a partner is dropped rather than offered alone — an agent told to prefer `recall` and handed only `deep_recall` will reach for the one it does not have.
+</Callout>
+
+## Past a few hundred tools
+
+Ranking, not speed, is what gives out first: selection stays near a millisecond at two thousand tools, but a coincidental match in an unrelated domain starts taking slots. [`busgroup`](/docs/tools/bus) gives each domain its own bus and routes between them.
+
+## `missing` catches a silent failure
+
+A prompt edited to expect a `refund` tool, deployed against a bus without one, does not error. The agent is never offered it and answers anyway.
+
+```ts
+bus.missing(["refund", "escalate"]);   // the names this bus does not have
+```
+
+## Two tools that describe themselves the same way
+
+Two near-identical descriptions are worse than one tool: the model cannot tell them apart and picks wrong more often, with nothing failing. The bus says so at construction, once, however many pairs there are — a line each buries whatever else the process said at startup and teaches people to switch the check off.

package/docs/stored.mdx

@@ -0,0 +1,83 @@
+export const meta = {
+  title: "A stored tool — spendgraph docs",
+  description:
+    "The dashboard owns the description, your code owns the arguments and the handler, and bindTool checks the two against each other before the model ever sees it.",
+};
+
+# A stored tool
+
+The description is the biggest lever on whether a model calls a tool correctly, and the part you will want to change most often. `bindTool` puts that half in the dashboard and leaves the rest in code.
+
+```ts
+import { bindTool } from "@spendgraph/tools";
+import { Spendgraph } from "@spendgraph/sdk";
+
+const lookup = await bindTool(sg, {
+  name: "lookup_contract",
+  args: [{ name: "ref", type: "string", required: true }] as const,
+  run: ({ ref }) => search(ref),
+});
+```
+
+No `description` in that call. That is the point — one source for the string the model reads, and it is the one you can edit without a release.
+
+## Who owns what
+
+```
+  DASHBOARD                        YOUR CODE
+  ─────────                        ─────────
+  description   ◀── iterate on     args      ──▶ run() is typed from them
+  effect            these without  run()     ──▶ the thing that actually happens
+  pinned            a deploy
+```
+
+Arguments stay in code because the handler's parameter types are inferred from them. Pull those from the server and every `run` is handed a `Record<string, unknown>`, which gives up the one guarantee [declaring a tool](/docs/tools/declaring) exists to provide.
+
+Write `as const` here exactly as you would for `tool()`. Without it inference falls back to nothing, and the drift check below becomes the only thing still catching a rename.
+
+## Drift fails at bind, not mid-loop
+
+The stored arguments and the declared ones are compared on the way through, by **name, type and requiredness** — the three a handler is written against.
+
+```ts
+import { ToolDriftError, ToolNotStoredError } from "@spendgraph/tools";
+
+try {
+  await bindTool(sg, spec);
+} catch (err) {
+  if (err instanceof ToolDriftError) err.differences;  // every disagreement, in words
+  if (err instanceof ToolNotStoredError) err.toolName; // nothing stored under that name
+}
+```
+
+`differences` reads like a review comment rather than a diff:
+
+```
+"ref" is string here and number stored
+"limit" is declared here but not stored
+"mode" is stored but not declared here
+```
+
+A description or a bound that differs is **not** drift — that is the dashboard being edited, which is the whole feature. A renamed argument is a handler about to be passed `undefined` halfway through an agent loop, so it throws.
+
+<Callout tone="warn" title="Bind at startup, not per request">
+  Every `bindTool` is a round trip to the API. Bind once when the process starts and hold the result, the same as you would a database connection — a bind inside a request handler puts a network hop in front of every model call.
+</Callout>
+
+<Callout tone="trap" title="A rename in the dashboard is a handler passed `undefined`">
+  The wording is editable without a deploy; the argument names are not. `bindTool` compares them at bind time and refuses — a deploy that fails is recoverable, and the same rename noticed mid-loop is a handler halfway through somebody's refund reading an argument that is not there.
+</Callout>
+
+## When nothing is stored yet
+
+`ToolNotStoredError` is the ordinary case of "you have not written this one in the dashboard yet", not an exotic failure. It exists so a 404 from three layers down arrives as a sentence naming the tool.
+
+Create the row first — `sg.tools.create` on the [client](/docs/sdk/client), or the Tools page in the dashboard — then bind to it.
+
+## It is an ordinary tool afterwards
+
+What comes back is what `tool()` returns. Register it on a bus, select it, invoke it, record it; nothing downstream knows or cares where the wording came from.
+
+```ts
+const bus = toolbus([lookup, calculate()]);
+```

package/docs/turns.mdx

@@ -0,0 +1,57 @@
+export const meta = {
+  title: "A turn — spendgraph docs",
+  description:
+    "A turn is selected once and remembers what it offered. Without that a record cannot tell 'chose not to' from 'was never offered', which are opposite bugs.",
+};
+
+# A turn
+
+```ts
+const turn = bus.trace(query);
+
+const reply = await llm.call(messages, { tools: turn });
+await turn.invoke(call.name, call.args);
+
+turn.record();   // { offeredTools, steps }
+```
+
+A turn is **selected once** and remembers what it offered. A trace cannot disagree with itself about what the model saw.
+
+## Offered is recorded, not just called
+
+Which tools were offered is recorded as well as which were called. Without it a record cannot tell **"chose not to"** from **"was never offered"** — which are opposite bugs, and look identical in a log that only lists calls.
+
+## What a turn answers
+
+| | |
+| --- | --- |
+| `turn.offered` | the shortlist this turn was given |
+| `turn.anthropic()` · `openai()` · `markdown()` | the same list, per provider |
+| `turn.effectOf(name)` | what that tool said it does, or `undefined` |
+| `turn.invoke(name, args)` | runs one and records the step. Never throws |
+| `turn.steps()` | the steps so far, in call order |
+| `turn.record()` | the pair, in the shape `report` takes |
+
+## Never throwing is the point
+
+A tool that fails is an **outcome the agent can react to** and a step worth recording, not an exception that ends the run — the same argument `status` and `error` exist on a rollout for.
+
+A tool the bus does not have is a failure that says what was offered, since the usual cause is a hallucinated name.
+
+<Callout tone="trap" title="`undefined` means two different things">
+  A tool that was offered and stayed quiet, and a tool this turn never offered, both answer `undefined`. `offeredTools` is what tells them apart — which is the difference between a model that declined to look something up and a model that could not.
+</Callout>
+
+## Usage drives the tiebreaker
+
+`bus.usage()` counts what has actually been called, which is what selection falls back on when a query singles out nothing. A call that never reached the tool — a name that does not exist, arguments that did not validate — is not counted, because it was not a use.
+
+## With a prompt
+
+```ts
+await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: turn }), {
+  tools: bus,
+});
+```
+
+The prompt hands the turn to your callback and puts `record()` on the rollout. The three packages compose without any of them importing another.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@spendgraph/tools",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Declare a tool once, offer the right few, and record what was called.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fnLog0/spendgraph.git",
@@ -28,10 +28,23 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./docs/*": "./docs/*",
+    "./bogus": {
+      "types": "./dist/bogus/index.d.ts",
+      "import": "./dist/bogus/index.js"
+    },
     "./wire": {
       "types": "./dist/wire/index.d.ts",
       "import": "./dist/wire/index.js"
     },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
     "./internals": {
       "types": "./dist/internals.d.ts",
       "import": "./dist/internals.js"
@@ -40,19 +53,18 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
-    "test": "vitest run",
-    "examples": "npm run build && node examples/02-select/01-shortlist.mjs"
-  },
   "dependencies": {
-    "@locusgraph/client": "^0.8.1",
-    "@spendgraph/sdk": "^0.5.0"
+    "@spendgraph/sdk": "^0.7.0",
+    "jszip": "^3.10.2",
+    "unpdf": "^1.8.1"
   },
   "devDependencies": {
-    "@spendgraph/prompt": "^0.5.0",
+    "@locusgraph/client": "^0.8.1",
+    "@spendgraph/prompt": "^0.7.0",
+    "pdf-lib": "^1.17.1",
     "typescript": "^5"
   },
   "engines": {
@@ -60,5 +72,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "test": "vitest run",
+    "examples": "pnpm run build && node examples/02-select/01-shortlist.mjs"
   }
-}
+}

package/dist/builtin/deep-recall/deep-recall.d.ts

@@ -1,27 +0,0 @@
-import type { LocusGraphClient } from "@locusgraph/client";
-export interface DeepRecallOptions {
-    /** A `LocusGraphClient`, or anything carrying its `deepRecall`. */
-    client: Pick<LocusGraphClient, "deepRecall">;
-    /** Graph the walk runs over. Unset, the client's own default is used. */
-    graphId?: string;
-    /** Longest evidence list handed back. Default 20. */
-    maxFacts?: number;
-}
-/**
- * Your own knowledge base, answered with cited evidence.
- *
- * Cost comes back as micro-USD because deep recall runs model calls of its own,
- * and that spend is invisible to whatever loop called this.
- */
-export declare function deepRecall(opts: DeepRecallOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
-    readonly name: "question";
-    readonly type: "string";
-    readonly required: true;
-    readonly maxLength: 1000;
-    readonly description: "One focused question, not a conversation and not several at once.";
-}, {
-    readonly name: "context_ids";
-    readonly type: "list";
-    readonly required: false;
-    readonly description: string;
-}]>>;

package/dist/builtin/deep-recall/deep-recall.js

@@ -1,45 +0,0 @@
-import { tool } from "../../tool/index.js";
-const DEFAULT_MAX_FACTS = 20;
-export function deepRecall(opts) {
-    const maxFacts = opts.maxFacts ?? DEFAULT_MAX_FACTS;
-    return tool({
-        name: "deep_recall",
-        description: "Searches your own knowledge base and returns an answer with the evidence it rests " +
-            "on. A walker follows linked contexts, so it answers questions spread across several " +
-            "notes — what do we know about X, what was decided and why. Ask one focused thing. " +
-            "Prefer it over a web search whenever the answer could already be in your records.",
-        effect: "readonly",
-        args: [
-            {
-                name: "question",
-                type: "string",
-                required: true,
-                maxLength: 1000,
-                description: "One focused question, not a conversation and not several at once.",
-            },
-            {
-                name: "context_ids",
-                type: "list",
-                required: false,
-                description: "Contexts to start the walk from, as type:name — take them from the contexts of " +
-                    "an earlier result. A hint, not a filter; the walk may go elsewhere.",
-            },
-        ],
-        run: async ({ question, context_ids }) => {
-            const result = await opts.client.deepRecall({
-                question,
-                ...(opts.graphId ? { graphId: opts.graphId } : {}),
-                ...(context_ids?.length ? { contextIds: context_ids } : {}),
-            });
-            return {
-                summary: result.summary,
-                facts: result.facts.slice(0, maxFacts),
-                truncated: result.facts.length > maxFacts,
-                contextsWalked: result.contexts_walked,
-                coverage: result.coverage,
-                fallback: result.fallback,
-                costMicroUsd: Math.round(result.usage.cost_usd * 1_000_000),
-            };
-        },
-    });
-}

package/dist/builtin/deep-recall/index.d.ts

@@ -1 +0,0 @@
-export { type DeepRecallOptions, deepRecall } from "./deep-recall.js";

package/dist/builtin/deep-recall/index.js

@@ -1 +0,0 @@
-export { deepRecall } from "./deep-recall.js";

package/dist/builtin/web-search/reply.js

@@ -1,27 +0,0 @@
-function sources(raw) {
-    const listed = raw.search_results ?? [];
-    if (listed.length) {
-        return listed.flatMap((r) => (r.url ? [{ url: r.url, title: r.title, date: r.date }] : []));
-    }
-    return (raw.citations ?? []).map((url) => ({ url }));
-}
-export function readReply(body, fallbackModel, maxChars, maxResults) {
-    const raw = body;
-    const answer = raw.choices?.[0]?.message?.content ?? "";
-    const found = sources(raw);
-    const results = found.slice(0, maxResults);
-    const usage = raw.usage ?? {};
-    return {
-        answer: answer.slice(0, maxChars),
-        results,
-        model: raw.model ?? fallbackModel,
-        truncated: answer.length > maxChars || found.length > results.length,
-        usage: {
-            inputTokens: usage.prompt_tokens ?? 0,
-            outputTokens: usage.completion_tokens ?? 0,
-            citationTokens: usage.citation_tokens ?? 0,
-            reasoningTokens: usage.reasoning_tokens ?? 0,
-            searchQueries: usage.num_search_queries ?? 0,
-        },
-    };
-}

package/dist/builtin/write-document/commission.js

@@ -1,152 +0,0 @@
-import { createRequest, MoaApiError } from "./http.js";
-const TASK_STATUS = {
-    queued: "pending",
-    running: "running",
-    succeeded: "done",
-    failed: "failed",
-    canceled: "failed",
-};
-const ARTIFACT_FORMATS = ["md", "pdf", "docx", "pptx"];
-const formatOf = (name) => {
-    const ext = name?.split(".").pop()?.toLowerCase();
-    return ext && ARTIFACT_FORMATS.includes(ext) ? ext : undefined;
-};
-function toArtifacts(raw) {
-    if (!raw?.length)
-        return undefined;
-    const artifacts = raw.flatMap((a) => {
-        const format = formatOf(a.name);
-        if (!format || !(a.url || a.data))
-            return [];
-        return [
-            {
-                name: a.name ?? `document.${format}`,
-                format,
-                url: a.url,
-                data: a.data,
-                mime: a.contentType,
-                sizeBytes: a.sizeBytes,
-            },
-        ];
-    });
-    return artifacts.length ? artifacts : undefined;
-}
-function deliverablesBlock(formats) {
-    return (`\n\n<deliverables>\nBesides the text answer, save the finished deliverable ` +
-        `into the artifacts/ directory of your working dir as: ` +
-        `${formats.map((f) => `one .${f} file`).join(", ")}.\n</deliverables>`);
-}
-function taskText(input) {
-    let task = input.task;
-    if (input.context)
-        task += `\n\n<context>\n${input.context}\n</context>`;
-    if (input.design)
-        task += `\n\n<design>\n${input.design}\n</design>`;
-    if (input.artifacts?.length)
-        task += deliverablesBlock(input.artifacts);
-    return task;
-}
-export function createCommissionClient(config = {}) {
-    const request = createRequest(config);
-    return {
-        async create(input) {
-            const created = await request("/tasks", {
-                method: "POST",
-                body: {
-                    task: taskText(input),
-                    mode: "striker",
-                    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
-                    ...(input.newSessionId ? { newSessionId: input.newSessionId } : {}),
-                },
-            });
-            if (!created.id)
-                throw new MoaApiError("Moa did not return a task id", 502);
-            return created.id;
-        },
-        async get(id, opts) {
-            const qs = opts?.waitMs && opts.waitMs > 0 ? `?waitMs=${Math.floor(opts.waitMs)}` : "";
-            const t = await request(`/tasks/${encodeURIComponent(id)}${qs}`, {
-                signal: opts?.signal,
-            });
-            const status = t.status ? TASK_STATUS[t.status] : undefined;
-            return {
-                id: t.id ?? id,
-                status: status ?? "running",
-                output: t.result,
-                error: t.error,
-                costUsd: t.costUsd,
-                numTurns: t.numTurns,
-                sessionId: t.sessionId,
-                artifacts: toArtifacts(t.artifacts),
-            };
-        },
-        async cancel(id) {
-            await request(`/tasks/${encodeURIComponent(id)}`, { method: "DELETE" });
-        },
-    };
-}
-export const INTERACTIVE_TIMEOUT_MS = 30_000;
-const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const SETTLE_ATTEMPTS = 3;
-const LONGPOLL_WINDOW_MS = 25_000;
-export class CommissionAbortedError extends Error {
-    commissionId;
-    constructor(commissionId) {
-        super(`Commission ${commissionId} was cancelled by the caller.`);
-        this.name = "CommissionAbortedError";
-        this.commissionId = commissionId;
-    }
-}
-export class CommissionTimeoutError extends Error {
-    commissionId;
-    timeoutMs;
-    constructor(commissionId, timeoutMs) {
-        super(`Commission ${commissionId} did not complete within ${timeoutMs / 1000}s. ` +
-            `The task may still be running in the background.`);
-        this.name = "CommissionTimeoutError";
-        this.commissionId = commissionId;
-        this.timeoutMs = timeoutMs;
-    }
-}
-const sleep = (ms, signal) => new Promise((resolve) => {
-    const onAbort = () => resolve();
-    signal?.addEventListener("abort", onAbort, { once: true });
-    setTimeout(() => {
-        signal?.removeEventListener("abort", onAbort);
-        resolve();
-    }, ms);
-});
-export async function pollUntilDone(client, id, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? INTERACTIVE_TIMEOUT_MS;
-    const pollIntervalMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-    const settleMs = opts.settleMs ?? 0;
-    const signal = opts.signal;
-    const deadline = Date.now() + timeoutMs;
-    while (true) {
-        if (signal?.aborted)
-            throw new CommissionAbortedError(id);
-        const remaining = deadline - Date.now();
-        if (remaining <= 0)
-            throw new CommissionTimeoutError(id, timeoutMs);
-        let result;
-        try {
-            result = await client.get(id, { waitMs: Math.min(remaining, LONGPOLL_WINDOW_MS), signal });
-        }
-        catch (err) {
-            if (signal?.aborted)
-                throw new CommissionAbortedError(id);
-            throw err;
-        }
-        if (result.status === "failed")
-            return result;
-        if (result.status === "done") {
-            const unsettled = (r) => !r.output?.trim() || (opts.expectArtifacts === true && !r.artifacts?.length);
-            for (let i = 0; settleMs > 0 && i < SETTLE_ATTEMPTS && unsettled(result); i++) {
-                await sleep(settleMs);
-                result = await client.get(id);
-            }
-            return result;
-        }
-        await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())), signal);
-    }
-}

package/dist/builtin/write-document/design.js

@@ -1,86 +0,0 @@
-export const DEFAULT_DESIGN = {
-    name: "Spendgraph house style",
-    fonts: { heading: "Inter", body: "Inter", mono: "JetBrains Mono" },
-    palette: {
-        primary: "#0F172A",
-        accent: "#2563EB",
-        text: "#111827",
-        muted: "#64748B",
-        surface: "#FFFFFF",
-    },
-    layout: "A4 portrait, 20mm margins, a single text column at 60-75 characters, a 4pt spacing scale, " +
-        "and one heading scale used consistently (28/20/16/12). Whitespace is the design.",
-    charts: "One message per figure, stated in its caption. Label series directly where there are three " +
-        "or fewer. No 3D, no gradients, no gridline heavier than the data, no pie chart past three " +
-        "slices, and axes that start at zero unless the caption says why not.",
-    tone: "Plain and specific. Lead with the finding, then the evidence. No filler adjectives, no " +
-        "throat-clearing, no sentence that survives being deleted.",
-    rules: [
-        "A cover carrying the title, date and author, and no other ornament.",
-        "Every number traceable to something in the source material; invent nothing.",
-        "Tables for anything being compared; prose for anything being argued.",
-        "No stock imagery, no clip art, no placeholder text in the finished file.",
-        "Page numbers on every page after the cover.",
-    ],
-};
-const FORMAT_CRAFT = {
-    pdf: "Cover, then contents if it runs past four pages, then the body. Figures captioned and " +
-        "referenced from the text. Nothing straddles a page break: no orphan heading, no split table row.",
-    pptx: "16:9. One idea per slide, and the title is that idea as a sentence — a claim, not a label. " +
-        "At most six lines of body per slide, one figure per slide at most, and everything you cut " +
-        "goes into the speaker notes. Close on decisions and next steps, not on 'thank you'.",
-    docx: "Real Word styles for headings rather than manual bold, a table-of-contents field rather " +
-        "than a typed list, a header row on every table, and captions on figures.",
-    md: "A title heading, ATX headings throughout, tables for comparisons, fenced code with a language tag, and no HTML.",
-};
-function mergeGroup(base, over) {
-    if (!base)
-        return over;
-    if (!over)
-        return base;
-    return { ...base, ...over };
-}
-export function mergeDesign(base, over) {
-    if (!over)
-        return base;
-    return {
-        ...base,
-        ...over,
-        fonts: mergeGroup(base.fonts, over.fonts),
-        palette: mergeGroup(base.palette, over.palette),
-        rules: [...(base.rules ?? []), ...(over.rules ?? [])],
-    };
-}
-const line = (label, value) => (value ? [`${label}: ${value}`] : []);
-export function renderDesign(guide, format, notes) {
-    const { fonts, palette } = guide;
-    const parts = [
-        ...line("Style", guide.name),
-        ...line("Typefaces", [
-            fonts?.heading && `headings ${fonts.heading}`,
-            fonts?.body && `body ${fonts.body}`,
-            fonts?.mono && `code ${fonts.mono}`,
-        ]
-            .filter(Boolean)
-            .join(", ") || undefined),
-        ...line("Palette", [
-            palette?.primary && `primary ${palette.primary}`,
-            palette?.accent && `accent ${palette.accent}`,
-            palette?.text && `text ${palette.text}`,
-            palette?.muted && `muted ${palette.muted}`,
-            palette?.surface && `surface ${palette.surface}`,
-        ]
-            .filter(Boolean)
-            .join(", ") || undefined),
-        ...line("Layout", guide.layout),
-        ...line("Figures", guide.charts),
-        ...line("Voice", guide.tone),
-        ...line("Logo", guide.logoUrl),
-        `Format craft (.${format}): ${FORMAT_CRAFT[format]}`,
-        ...(guide.rules?.length ? [`Rules:\n${guide.rules.map((r) => `- ${r}`).join("\n")}`] : []),
-        ...(notes?.trim()
-            ? [`Overrides for this document, which win over everything above:\n${notes.trim()}`]
-            : []),
-    ];
-    return parts.join("\n");
-}