@gavana.ai/cli 0.2.2 → 0.3.0

package/src/tools/element_create.mjs

@@ -3,7 +3,7 @@ import { elementInput } from "./schemas.mjs";
 export function defineElementCreate(client) {
     return {
         title: "Create a Gavana Element",
-        description: "Create a reusable visual Element from 1-8 existing image assets, guidelines, or both.",
+        description: "Create a reusable visual Element. creative Elements inspire, identity Elements guide recognizable subjects, and exact Elements require one PNG source for deterministic composition.",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
         inputSchema: elementInput,
         handler: (input) => client.createElement(input),

package/src/tools/element_update.mjs

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { elementType, mutableElementReference, assetReference } from "./schemas.mjs";
+import { elementApplicationMode, elementType, mutableElementReference, assetReference } from "./schemas.mjs";
 
 export function defineElementUpdate(client) {
     return {
@@ -13,6 +13,7 @@ export function defineElementUpdate(client) {
                 type: elementType,
                 sourceAssetIds: z.array(assetReference).max(8).default([]),
                 guidelines: z.string().max(2_000).optional(),
+                applicationMode: elementApplicationMode.optional(),
             })
             .strict()
             .refine((value) => value.sourceAssetIds.length > 0 || Boolean(value.guidelines?.trim()), "Add at least one source asset or guideline."),

package/src/tools/guide_get.mjs

@@ -11,6 +11,6 @@ export function defineGuideGet(client) {
        description: `Read one canonical Gavana Canvas Agent Guide topic. Start at ${GAVANA_CANVAS_GUIDE_INDEX_URI} or use guide_search to find an exact topic ID.`,
        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
        inputSchema: z.object({ guideId: z.string().min(1).max(600).describe("Guide topic ID or exact gavana:// guide URI returned by guide_search or resources/list.") }),
-       handler: ({ guideId }) => getCanvasGuide(guideId),
+       handler: ({ guideId }) => getCanvasGuide(guideId, "local"),
     };
 }

package/src/tools/guide_search.mjs

@@ -11,6 +11,6 @@ export function defineGuideSearch(client) {
        description: `Search the canonical Gavana Canvas Agent Guide v${GAVANA_CANVAS_GUIDE_VERSION}. Use this before the first canvas mutation in a session or whenever an operation is unfamiliar.`,
        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
        inputSchema: z.object({ query: z.string().max(240).default(""), limit: z.number().int().min(1).max(10).default(10) }),
-       handler: ({ query, limit }) => searchCanvasGuides(query, limit),
+       handler: ({ query, limit }) => searchCanvasGuides(query, limit, "local"),
     };
 }

package/src/tools/image_tool.mjs

@@ -11,16 +11,21 @@ export function imageToolDefinition(operation, client) {
             title: `${operation === "generate" ? "Generate" : operation === "edit" ? "Edit" : "Vary"} canvas images`,
             description:
                 operation === "generate"
-                    ? "Queue image generation into existing target image nodes. Campaign work needs a visible reference-led concept before output; reuse existing Canvas node:/asset: handles for product identity, brand-world, and typography/layout references. For an exact product, logo, face, garment, or other visual identity, do not rely on prompt-only generation: use a user-provided local image (or an existing node:/asset: handle), then call image_edit with references."
+                    ? "Queue image generation into existing target image nodes. Campaign work needs a visible reference-led concept before output; reuse existing Canvas node:/asset: handles for product identity, brand-world, and typography/layout references. identity Elements guide preservation but do not guarantee identical pixels. exact Elements require normalized placements and are deterministically composited from original source pixels. Set preflight true to inspect the compiled reference plan before paid generation. For several images set count (1-4): Gavana writes one image node per output. Never describe multiple panels, frames, or a collage in one prompt, and when you pass targetNodeIds pass exactly one target node per output."
                     : operation === "edit"
-                      ? "Queue an image edit using stable node: or asset: references. Reuse a Canvas image by its existing handle rather than re-uploading it. Use this for exact product or visual identity work; call asset_upload first only when the user supplied a local image."
-                      : "Queue variations using an existing node: or asset: source.",
+                      ? "Queue an image edit using stable node: or asset: references. Reuse a Canvas image by its existing handle rather than re-uploading it. For a local image the user explicitly supplied, call asset_upload first. identity guidance is not pixel-exact; use an exact Element with placements for deterministic logo or wordmark composition. Set preflight true to inspect the compiled reference plan before paid generation. For several images set count (1-4): Gavana writes one image node per output. Never describe multiple panels, frames, or a collage in one prompt, and when you pass targetNodeIds pass exactly one target node per output."
+                      : "Queue variations using an existing node: or asset: source. For several images set count (1-4): Gavana writes one image node per output. Never describe multiple panels, frames, or a collage in one prompt, and when you pass targetNodeIds pass exactly one target node per output.",
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
             inputSchema: imageSchema(),
             markdown: true,
             handler: async (input, extra) => {
                 validateImageInput(operation, input);
                 const destination = input.destination || input.canvasId;
+                if (input.preflight === true) {
+                    const { destination: _destination, canvasId: _canvasId, canvasTitle: _canvasTitle, preflight: _preflight, wait: _wait, timeoutSeconds: _timeoutSeconds, ...preflightInput } = input;
+                    const plan = await client.preflightImage(operation, { ...preflightInput, canvasId: destination });
+                    return { ...plan, destination: { requested: destination, canvasId: destination, targetNodeIds: input.targetNodeIds } };
+                }
                 const prepared = await client.prepareImageDestination({
                     ...input,
                     operation,
@@ -36,6 +41,7 @@ export function imageToolDefinition(operation, client) {
                     targetY: _targetY,
                     targetWidth: _targetWidth,
                     targetHeight: _targetHeight,
+                    preflight: _preflight,
                     wait: _wait,
                     timeoutSeconds: _timeoutSeconds,
                     ...jobInput

package/src/tools/registry.mjs

@@ -144,7 +144,11 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
     {
         name: "canvas_create",
         toolset: "canvas",
-        surfaces: ["local"],
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write"],
+        hostedOrder: 6,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
         localOrder: 15,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
     },
@@ -260,6 +264,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         scopes: ["canvas:read","job:manage"],
         hostedOrder: 12,
         hostedReadOnly: false,
+        hostedCategory: "read",
         hostedToolset: "runs",
         embedImage: true,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
@@ -284,7 +289,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 17,
+        hostedOrder: 18,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 48,
@@ -296,7 +301,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 18,
+        hostedOrder: 19,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 50,
@@ -307,7 +312,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 19,
+        hostedOrder: 20,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 53,
@@ -320,7 +325,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 20,
+        hostedOrder: 21,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 49,
@@ -331,7 +336,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 21,
+        hostedOrder: 22,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 52,
@@ -342,7 +347,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 22,
+        hostedOrder: 23,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 45,
@@ -354,7 +359,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 23,
+        hostedOrder: 24,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 43,
@@ -366,7 +371,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 24,
+        hostedOrder: 25,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 44,
@@ -378,7 +383,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["element:read"],
         readOnlySurface: true,
-        hostedOrder: 25,
+        hostedOrder: 26,
         hostedReadOnly: true,
         hostedToolset: "elements",
         localOrder: 42,
@@ -389,7 +394,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 26,
+        hostedOrder: 27,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 47,
@@ -400,7 +405,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 27,
+        hostedOrder: 28,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 46,
@@ -411,7 +416,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "elements",
         surfaces: ["hosted","local"],
         scopes: ["element:read","element:write"],
-        hostedOrder: 28,
+        hostedOrder: 29,
         hostedReadOnly: false,
         hostedToolset: "elements",
         localOrder: 51,
@@ -455,7 +460,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         hostedAlias: "generate_image_in_canvas",
         scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
         conditionalScopes: { elements: ["element:read"] },
-        hostedOrder: 13,
+        hostedOrder: 14,
         paid: true,
         hostedReadOnly: false,
         hostedToolset: "images",
@@ -551,6 +556,18 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         localOrder: 20,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
+    {
+        name: "product_photoshoot_generate",
+        toolset: "images",
+        surfaces: ["hosted"],
+        hostedAlias: "generate_product_photoshoot_in_canvas",
+        scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
+        hostedOrder: 13,
+        paid: true,
+        hostedReadOnly: false,
+        hostedToolset: "images",
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
     {
         name: "product_reference_pack_import",
         toolset: "assets",
@@ -611,10 +628,30 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
     {
         name: "run_get",
         toolset: "runs",
-        surfaces: ["local"],
+        surfaces: ["hosted","local"],
+        hostedAlias: "get_image_run",
+        scopes: ["job:manage"],
+        embedImage: true,
+        hostedOrder: 35,
+        hostedReadOnly: false,
+        hostedCategory: "read",
+        hostedToolset: "runs",
         localOrder: 42,
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
+    {
+        name: "run_list",
+        toolset: "jobs",
+        surfaces: ["hosted","local"],
+        scopes: ["job:manage"],
+        hostedAlias: "list_image_runs",
+        hostedOrder: 36,
+        hostedReadOnly: false,
+        hostedToolset: "jobs",
+        localOrder: 41,
+        readOnlySurface: true,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
     {
         name: "run_wait",
         toolset: "runs",
@@ -627,8 +664,8 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "videos",
         surfaces: ["hosted","local"],
         hostedAlias: "generate_video",
-        scopes: ["canvas:read","asset:read","video:generate","job:manage"],
-        hostedOrder: 15,
+        scopes: ["canvas:read","canvas:write","asset:read","video:generate","job:manage"],
+        hostedOrder: 16,
         paid: true,
         hostedReadOnly: false,
         hostedToolset: "videos",
@@ -641,8 +678,9 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted"],
         hostedAlias: "get_video_job",
         scopes: ["job:manage"],
-        hostedOrder: 16,
+        hostedOrder: 17,
         hostedReadOnly: false,
+        hostedCategory: "read",
         hostedToolset: "runs",
         annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
@@ -652,8 +690,8 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted"],
         hostedAlias: "find_video_models",
         scopes: ["video:generate"],
-        hostedOrder: 14,
-        hostedReadOnly: true,
+        hostedOrder: 15,
+        hostedReadOnly: false,
         hostedToolset: "models",
         annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
@@ -662,7 +700,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write"],
-        hostedOrder: 31,
+        hostedOrder: 32,
         hostedReadOnly: false,
         hostedToolset: "canvas",
         localOrder: 56,
@@ -674,7 +712,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write","asset:read","image:generate"],
-        hostedOrder: 32,
+        hostedOrder: 33,
         paid: true,
         hostedReadOnly: false,
         hostedToolset: "canvas",
@@ -688,7 +726,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         scopes: ["canvas:read"],
         readOnlySurface: true,
-        hostedOrder: 30,
+        hostedOrder: 31,
         hostedReadOnly: true,
         hostedToolset: "canvas",
         localOrder: 55,
@@ -700,7 +738,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write","asset:read"],
-        hostedOrder: 29,
+        hostedOrder: 30,
         hostedReadOnly: false,
         hostedToolset: "canvas",
         localOrder: 54,
@@ -712,7 +750,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         toolset: "canvas",
         surfaces: ["hosted","local"],
         scopes: ["canvas:read","canvas:write","image:generate"],
-        hostedOrder: 33,
+        hostedOrder: 34,
         hostedReadOnly: false,
         hostedToolset: "canvas",
         localOrder: 58,
@@ -744,8 +782,16 @@ export function gavanaToolsForSurface(surface, { includeLegacyCampaign = false,
     // each surface keeps the order it shipped with rather than falling out of the
     // registry's alphabetical layout.
     const key = surface === "hosted" ? "hostedOrder" : "localOrder";
+    // The two read-only flags are not the same question, and `run_list` is the
+    // first tool where they part. Local read-only serves whatever declares
+    // `readOnlyHint`, so a tool that only reads belongs there. Hosted read-only
+    // additionally has to grant the tool's OAuth scopes out of a read-only set
+    // that does not contain `job:manage`, so the same tool cannot be served
+    // there at all. Filtering both surfaces through the local flag advertised a
+    // hosted tool the hosted server would never serve.
+    const readOnlyKey = surface === "hosted" ? "hostedReadOnly" : "readOnlySurface";
     return GAVANA_TOOL_REGISTRY.filter(
-        (tool) => tool.surfaces.includes(surface) && (includeLegacyCampaign || !tool.legacyCampaign) && (!readOnly || tool.readOnlySurface),
+        (tool) => tool.surfaces.includes(surface) && (includeLegacyCampaign || !tool.legacyCampaign) && (!readOnly || tool[readOnlyKey]),
     )
         .slice()
         .sort((left, right) => (left[key] ?? 0) - (right[key] ?? 0));

package/src/tools/run_list.mjs

@@ -0,0 +1,20 @@
+// Tool definition: run_list
+//
+// Registered through ./definitions.mjs. ./registry.mjs is the catalog that says
+// this tool exists and on which surfaces; this file is what it does.
+import { z } from "zod";
+
+export function defineRunList(client) {
+    return {
+        title: "List Gavana image runs",
+        description:
+            "List image and Action runs this account has started, newest first, with their status and canvas. Use this to answer questions about work already in flight, to recover a run handle you no longer have, and to see which runs are holding the concurrent-job limit.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({
+            status: z.enum(["active", "all"]).default("active").describe("active returns only runs still queued or running; all includes finished and failed runs."),
+            canvasId: z.string().min(1).max(240).optional().describe("Restrict to runs targeting one canvas."),
+            limit: z.number().int().min(1).max(50).default(20),
+        }),
+        handler: (input) => client.listRuns(input),
+    };
+}

package/src/tools/schemas.mjs

@@ -26,13 +26,17 @@ const elementCollectionReference = z
     .string()
     .regex(/^element-collection:[A-Za-z0-9_-]{1,180}$/)
     .describe("Stable Element collection handle element-collection:<id>.");
-const elementType = z.enum(["character", "product/object", "environment", "style", "material/texture", "lighting"]);
+const elementType = z.enum(["character", "product/object", "environment", "style", "material/texture", "lighting", "brand/mark"]);
+const elementApplicationMode = z
+    .enum(["creative", "identity", "exact"])
+    .describe("creative permits visual reinterpretation; identity guides preservation but is not pixel-exact; exact composites original Element pixels after generation.");
 const elementInput = z
     .object({
         name: z.string().min(1).max(160),
         type: elementType,
         sourceAssetIds: z.array(assetReference).max(8).default([]),
         guidelines: z.string().max(2_000).optional(),
+        applicationMode: elementApplicationMode.optional().describe("creative uses an Element as inspiration; identity guides recognizable subjects; exact preserves an original PNG through deterministic composition."),
         collectionIds: z.array(elementCollectionReference).max(24).optional(),
     })
     .strict()
@@ -119,6 +123,15 @@ const approvedOutputReferences = z
 const campaignIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same campaign action.");
 const recipeForkIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same Recipe fork.");
 const campaignAspectRatio = z.enum(["1:1", "4:5", "3:4", "16:9", "9:16"]);
+const exactElementPlacement = z
+    .object({
+        x: z.number().min(0).max(1).describe("Normalized left coordinate in the output, from 0 through 1."),
+        y: z.number().min(0).max(1).describe("Normalized top coordinate in the output, from 0 through 1."),
+        width: z.number().gt(0).max(1).describe("Normalized width in the output, greater than 0 through 1."),
+        height: z.number().gt(0).max(1).describe("Normalized height in the output, greater than 0 through 1."),
+    })
+    .strict()
+    .refine((placement) => placement.x + placement.width <= 1 && placement.y + placement.height <= 1, "Exact Element placement must remain inside the normalized output bounds.");
 const elementGenerationInput = z
     .union([
         pinnedElementReference,
@@ -127,10 +140,16 @@ const elementGenerationInput = z
                 handle: pinnedElementReference,
                 role: z.enum(["identity", "construction", "texture", "fit", "style"]).optional(),
                 influence: z.number().min(0).max(1).optional(),
+                applicationMode: elementApplicationMode.optional(),
+                currentTurnUserModeOverride: z
+                    .literal(true)
+                    .optional()
+                    .describe("Required only when the current user explicitly asks to override this Element version's stored application mode."),
+                placements: z.array(exactElementPlacement).min(1).max(16).optional().describe("Required for exact Elements. Repeat placements to composite unchanged source pixels more than once."),
             })
             .strict(),
     ])
-    .describe("A version-pinned Element, optionally with the visual role and influence to apply.");
+    .describe("A version-pinned Element. identity is guided preservation, not pixel-exact. exact requires placements and returns exact-composed only when original Element pixels are deterministically composited.");
 const MAX_LOCAL_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
 const revisionFields = {
     baseRevision: z.string().min(1).optional().describe("Revision returned by canvas_get. Omit to read the latest revision immediately before the write."),
@@ -165,7 +184,16 @@ function imageSchema() {
         model: z.union([modelReference, rawModelId]).optional(),
         size: z.string().max(80).optional(),
         quality: z.string().max(80).optional(),
-        count: z.number().int().min(1).max(4).optional(),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(4)
+            .optional()
+            .describe(
+                "Number of separate images to generate, 1-4. Gavana creates one image node per output, and this is the only way to produce more than one image. Never ask for several panels, frames, or a collage inside one prompt. When you pass targetNodeIds, count must equal the number of targetNodeIds; when you omit count, Gavana uses the number of targets.",
+            ),
+        preflight: z.boolean().optional().describe("Compile and validate the final reference plan without creating targets, starting a provider request, or consuming generation credits. Requires an existing canvas and explicit targetNodeIds."),
         wait: z.boolean().default(false).describe("Return after queueing by default. Set true to wait for the completed Run."),
         timeoutSeconds: z.number().min(1).max(3_600).default(900),
     });
@@ -182,6 +210,11 @@ function validateImageInput(operation, value) {
     // the job, and the blank node would be left behind as an orphan.
     if (operation !== "variations" && !value.prompt && !value.promptNodeId && !value.targetNodeIds?.length) issues.push("Provide prompt or promptNodeId, or pass targetNodeIds whose nodes have a prompt connection.");
     if (operation !== "generate" && !value.source && !value.references?.length) issues.push(`${operation} requires source or references.`);
+    if (value.preflight) {
+        const destination = value.destination || value.canvasId;
+        if (destination === "agent-canvas" || destination === "new-canvas") issues.push("preflight requires an existing canvas handle, not agent-canvas or new-canvas.");
+        if (!value.targetNodeIds?.length) issues.push("preflight requires explicit targetNodeIds; it never creates target nodes.");
+    }
     if (!issues.length) return;
     const error = new Error(`Input validation error: ${issues.join(" ")}`);
     error.code = "invalid_image_input";
@@ -195,6 +228,7 @@ export {
     assetReference,
     elementCollectionReference,
     elementGenerationInput,
+    elementApplicationMode,
     elementInput,
     elementType,
     campaignAspectRatio,

package/src/tools/surface-names.mjs

@@ -0,0 +1,120 @@
+// Tool vocabulary per surface.
+//
+// The hosted and local servers advertise different catalogs under different
+// naming conventions (see ./registry.mjs). The Canvas Agent Guide is shared
+// prose, so a sentence written in one surface's vocabulary reaches agents on
+// the other surface naming a tool they cannot call. That is not a hypothetical:
+// the guide told every agent to "call `model_list` before image or video
+// generation", and `model_list` is local-only, so hosted agents either guessed
+// a substitute or gave up on a mandatory pre-flight step.
+//
+// This module is the one place that answers "what is this tool called here, and
+// does it exist here at all". scripts/canvas-agent-guide.test.mjs asserts that
+// no served guide text names a tool the reading surface cannot call, so the
+// drift fails the build instead of reaching an agent.
+
+import { GAVANA_TOOL_REGISTRY } from "./registry.mjs";
+
+export const GAVANA_TOOL_SURFACES = Object.freeze(["hosted", "local"]);
+
+/** Name a surface advertises for one registry entry, or undefined when it does not advertise it. */
+function advertisedNameFor(tool, surface) {
+    if (!tool.surfaces.includes(surface)) return undefined;
+    return surface === "hosted" ? (tool.hostedAlias ?? tool.name) : tool.name;
+}
+
+/**
+ * Every spelling of every tool, mapped to what `surface` calls it.
+ *
+ * `rename` covers both directions: a canonical name written in the guide maps to
+ * the hosted alias when hosted advertises it, and a hosted alias maps back to the
+ * canonical name for the local surface. `absent` holds tools no spelling of which
+ * the surface can call.
+ */
+export function surfaceToolVocabulary(surface) {
+    if (!GAVANA_TOOL_SURFACES.includes(surface)) {
+        throw new Error(`Unknown tool surface: ${surface}. Expected one of ${GAVANA_TOOL_SURFACES.join(", ")}.`);
+    }
+    const advertised = new Set();
+    const rename = new Map();
+    const absent = new Set();
+
+    for (const tool of GAVANA_TOOL_REGISTRY) {
+        const spellings = [tool.name, tool.hostedAlias].filter(Boolean);
+        const here = advertisedNameFor(tool, surface);
+        if (!here) {
+            for (const spelling of spellings) absent.add(spelling);
+            continue;
+        }
+        advertised.add(here);
+        for (const spelling of spellings) {
+            if (spelling !== here) rename.set(spelling, here);
+        }
+    }
+
+    // A spelling this surface advertises is never "absent", even when another
+    // registry entry shares the word. Advertised always wins.
+    for (const name of advertised) absent.delete(name);
+    for (const spelling of rename.keys()) absent.delete(spelling);
+
+    return { surface, advertised, rename, absent };
+}
+
+const VOCABULARIES = new Map(GAVANA_TOOL_SURFACES.map((surface) => [surface, surfaceToolVocabulary(surface)]));
+
+/** Cached vocabulary. Callers must not mutate the returned sets. */
+export function toolVocabulary(surface) {
+    const vocabulary = VOCABULARIES.get(surface);
+    if (!vocabulary) throw new Error(`Unknown tool surface: ${surface}. Expected one of ${GAVANA_TOOL_SURFACES.join(", ")}.`);
+    return vocabulary;
+}
+
+// Word boundary that keeps `run_get` from matching inside `canvas_workflow_run_get`.
+const identifier = (name) => new RegExp(`(?<![A-Za-z0-9_])${name}(?![A-Za-z0-9_])`, "g");
+
+const CONDITIONAL = /\{\{#(hosted|local)\}\}([\s\S]*?)\{\{\/\1\}\}/g;
+
+/**
+ * Resolve `{{#hosted}}…{{/hosted}}` / `{{#local}}…{{/local}}` spans for one surface.
+ *
+ * Guide prose uses these where the two surfaces genuinely differ in capability
+ * rather than only in spelling — an instruction that cannot be satisfied at all
+ * on one surface must not merely be renamed there.
+ */
+export function resolveSurfaceConditionals(text, surface) {
+    return String(text ?? "").replace(CONDITIONAL, (_match, branch, body) => (branch === surface ? body : ""));
+}
+
+/** Rewrite every tool name in `text` to the spelling `surface` advertises. */
+export function renameToolsForSurface(text, surface) {
+    const { rename } = toolVocabulary(surface);
+    let output = String(text ?? "");
+    for (const [from, to] of rename) output = output.replace(identifier(from), to);
+    return output;
+}
+
+/**
+ * Guide prose as one surface should read it: conditionals resolved, then names
+ * translated. Order matters — a conditional branch may name a tool that only
+ * exists on its own surface, so the other branch must be dropped before renaming.
+ */
+export function renderForSurface(text, surface) {
+    return renameToolsForSurface(resolveSurfaceConditionals(text, surface), surface);
+}
+
+/**
+ * Tool names `text` mentions that `surface` cannot call. Empty is the contract.
+ *
+ * Only registry-known spellings count, so ordinary prose is never flagged. Call
+ * this on already-rendered text: an unresolved conditional would report its
+ * other branch as a violation.
+ */
+export function unavailableToolMentions(text, surface) {
+    const { absent } = toolVocabulary(surface);
+    const value = String(text ?? "");
+    const found = new Set();
+    for (const name of absent) {
+        if (identifier(name).test(value)) found.add(name);
+    }
+    return Array.from(found).sort();
+}

package/src/version.mjs

@@ -7,4 +7,4 @@
 //
 // scripts/gavana-mcp-tool-contract.test.mjs asserts this equals
 // packages/cli/package.json, so the two cannot drift.
-export const GAVANA_CLI_VERSION = "0.2.2";
+export const GAVANA_CLI_VERSION = "0.3.0";