@gavana.ai/cli 0.2.0 → 0.2.2

package/src/client.mjs

@@ -519,6 +519,36 @@ export function createCanvasAgentClient(options = {}) {
                 signal: requestOptions.signal,
             });
         },
+        prepareWork: (input, requestOptions = {}) =>
+            request("/works", {
+                method: "POST",
+                body: normalizeWorkPrepareInput(input),
+                signal: requestOptions.signal,
+            }),
+        getWork: (workReference, requestOptions = {}) => {
+            const work = parseRequiredStableHandle(workReference, "work");
+            return request(`/works/${encodeURIComponent(work.id)}`, { signal: requestOptions.signal });
+        },
+        refreshWork: (workReference, requestOptions = {}) => {
+            const work = parseRequiredStableHandle(workReference, "work");
+            return request(`/works/${encodeURIComponent(work.id)}/refresh`, { method: "POST", signal: requestOptions.signal });
+        },
+        continueWork: (workReference, input, requestOptions = {}) => {
+            const work = parseRequiredStableHandle(workReference, "work");
+            return request(`/works/${encodeURIComponent(work.id)}/continue`, {
+                method: "POST",
+                body: normalizeWorkContinueInput(input),
+                signal: requestOptions.signal,
+            });
+        },
+        executeWork: (workReference, input, requestOptions = {}) => {
+            const work = parseRequiredStableHandle(workReference, "work");
+            return request(`/works/${encodeURIComponent(work.id)}/execute`, {
+                method: "POST",
+                body: normalizeWorkExecuteInput(input),
+                signal: requestOptions.signal,
+            });
+        },
         cancelCampaign: (runReference, requestOptions = {}) => {
             const run = parseRequiredStableHandle(runReference, "run");
             return request(`/campaigns/${encodeURIComponent(run.id)}`, {
@@ -558,6 +588,94 @@ export function createCanvasAgentClient(options = {}) {
                 signal: requestOptions.signal,
             });
         },
+        listElements: (filters = {}, requestOptions = {}) =>
+            request("/elements", {
+                query: {
+                    search: cleanOptionalText(filters.query, "Element search query", 240),
+                    state: filters.state === "archived" ? "archived" : filters.state === "active" ? "active" : undefined,
+                    ...paginationQuery(requestOptions, 100),
+                },
+                signal: requestOptions.signal,
+            }).then(decorateElementListResponse),
+        getElement: (elementReference, requestOptions = {}) => {
+            const element = parseElementHandle(elementReference);
+            return request(`/elements/${encodeURIComponent(element.id)}`, {
+                query: element.version ? { version: element.version } : undefined,
+                signal: requestOptions.signal,
+            }).then((result) => decorateElementGetResponse(result, element));
+        },
+        listElementHistory: (elementReference, requestOptions = {}) => {
+            const element = parseMutableElementHandle(elementReference);
+            return request(`/elements/${encodeURIComponent(element.id)}/versions`, {
+                query: paginationQuery(requestOptions, 100),
+                signal: requestOptions.signal,
+            }).then(decorateElementHistoryResponse);
+        },
+        createElement: (input, requestOptions = {}) =>
+            request("/elements", {
+                method: "POST",
+                body: normalizeElementInput(input, { includeCollections: true }),
+                signal: requestOptions.signal,
+            }),
+        updateElement: (elementReference, input, requestOptions = {}) => {
+            const element = parseMutableElementHandle(elementReference);
+            return request(`/elements/${encodeURIComponent(element.id)}`, {
+                method: "PATCH",
+                body: { operation: "update", element: normalizeElementInput(input) },
+                signal: requestOptions.signal,
+            });
+        },
+        updateElementCollections: (elementReference, collectionIds, requestOptions = {}) => {
+            const element = parseMutableElementHandle(elementReference);
+            return request(`/elements/${encodeURIComponent(element.id)}`, {
+                method: "PATCH",
+                body: { operation: "collections", collectionIds: normalizeElementCollectionIds(collectionIds) },
+                signal: requestOptions.signal,
+            });
+        },
+        archiveElement: (elementReference, requestOptions = {}) => {
+            const element = parseMutableElementHandle(elementReference);
+            return request(`/elements/${encodeURIComponent(element.id)}`, {
+                method: "PATCH",
+                body: { operation: "archive", confirm: true },
+                signal: requestOptions.signal,
+            });
+        },
+        restoreElement: (elementReference, requestOptions = {}) => {
+            const element = parseMutableElementHandle(elementReference);
+            return request(`/elements/${encodeURIComponent(element.id)}`, {
+                method: "PATCH",
+                body: { operation: "restore" },
+                signal: requestOptions.signal,
+            });
+        },
+        listElementCollections: (requestOptions = {}) =>
+            request("/element-collections", {
+                query: paginationQuery(requestOptions, 100),
+                signal: requestOptions.signal,
+            }).then(decorateElementCollectionsResponse),
+        createElementCollection: (input, requestOptions = {}) =>
+            request("/element-collections", {
+                method: "POST",
+                body: normalizeElementCollectionInput(input),
+                signal: requestOptions.signal,
+            }),
+        updateElementCollection: (collectionReference, input, requestOptions = {}) => {
+            const collection = parseElementCollectionHandle(collectionReference);
+            return request(`/element-collections/${encodeURIComponent(collection.id)}`, {
+                method: "PATCH",
+                body: normalizeElementCollectionInput(input),
+                signal: requestOptions.signal,
+            });
+        },
+        deleteElementCollection: (collectionReference, requestOptions = {}) => {
+            const collection = parseElementCollectionHandle(collectionReference);
+            return request(`/element-collections/${encodeURIComponent(collection.id)}`, {
+                method: "DELETE",
+                body: { confirm: true },
+                signal: requestOptions.signal,
+            });
+        },
         uploadAsset: (input, requestOptions = {}) => {
             if (!input || !input.bytes) throw new CanvasAgentApiError("Image bytes are required.", { code: "usage" });
             const canvas = input.canvasReference ? parseStableHandle(input.canvasReference, "canvas") : undefined;
@@ -752,6 +870,92 @@ export function parseStableHandle(value, expectedKind) {
     return { kind: expectedKind, id: validateId(parts[1], capitalize(expectedKind)) };
 }
 
+export function parseElementHandle(value) {
+    const raw = String(value || "").trim();
+    const match = /^element:([A-Za-z0-9_-]{1,180})(?:@v([1-9][0-9]*))?$/.exec(raw);
+    if (!match) throw new CanvasAgentApiError("Element reference must be element:<id> or element:<id>@v<n>.", { code: "usage" });
+    return { kind: "element", id: match[1], ...(match[2] ? { version: Number(match[2]) } : {}) };
+}
+
+export function parseMutableElementHandle(value) {
+    const element = parseElementHandle(value);
+    if (element.version) throw new CanvasAgentApiError("Element mutations require the current element:<id> handle, not a pinned version.", { code: "usage" });
+    return element;
+}
+
+export function parseElementCollectionHandle(value) {
+    const raw = String(value || "").trim();
+    const match = /^element-collection:([A-Za-z0-9_-]{1,180})$/.exec(raw);
+    if (!match) throw new CanvasAgentApiError("Element collection reference must be element-collection:<id>.", { code: "usage" });
+    return { kind: "element-collection", id: match[1] };
+}
+
+function normalizeElementInput(input, { includeCollections = false } = {}) {
+    const value = requireRecord(input, "Element");
+    const sourceAssetIds = Array.isArray(value.sourceAssetIds) ? value.sourceAssetIds.map((asset) => parseStableHandle(asset, "asset").id) : [];
+    if (!includeCollections && value.collectionIds !== undefined) throw new CanvasAgentApiError("Use the Element collections operation to change collection membership.", { code: "usage" });
+    const collectionIds = includeCollections && value.collectionIds !== undefined ? normalizeElementCollectionIds(value.collectionIds) : undefined;
+    return {
+        name: cleanRequiredText(value.name, "Element name", 160),
+        type: cleanRequiredText(value.type, "Element type", 80),
+        sourceAssetIds,
+        ...(cleanOptionalText(value.guidelines, "Element guidelines", 2_000) ? { guidelines: cleanOptionalText(value.guidelines, "Element guidelines", 2_000) } : {}),
+        ...(collectionIds !== undefined ? { collectionIds } : {}),
+    };
+}
+
+function cleanRequiredText(value, label, maximum) {
+    const cleaned = cleanOptionalText(value, label, maximum);
+    if (!cleaned) throw new CanvasAgentApiError(`${label} is required.`, { code: "usage" });
+    return cleaned;
+}
+
+function normalizeElementCollectionIds(value) {
+    if (!Array.isArray(value) || value.length > 24) throw new CanvasAgentApiError("Choose up to 24 element collections.", { code: "usage" });
+    const ids = value.map((collection) => parseElementCollectionHandle(collection).id);
+    if (new Set(ids).size !== ids.length) throw new CanvasAgentApiError("Element collections must be unique.", { code: "usage" });
+    return ids;
+}
+
+function normalizeElementCollectionInput(input) {
+    const value = requireRecord(input, "Element collection");
+    return { name: cleanRequiredText(value.name, "Element collection name", 120) };
+}
+
+function decorateElementListResponse(result) {
+    if (!isRecord(result) || !Array.isArray(result.elements)) return result;
+    return { ...result, elements: result.elements.map(decorateElement) };
+}
+
+function decorateElementGetResponse(result, reference) {
+    if (!isRecord(result)) return result;
+    if (reference.version && isRecord(result.version)) return { ...result, version: decorateElementVersion(result.version, reference.id) };
+    if (isRecord(result.element)) return { ...result, element: decorateElement(result.element) };
+    return result;
+}
+
+function decorateElementHistoryResponse(result) {
+    if (!isRecord(result) || !Array.isArray(result.versions)) return result;
+    return { ...result, versions: result.versions.map(decorateElementVersion) };
+}
+
+function decorateElementCollectionsResponse(result) {
+    if (!isRecord(result) || !Array.isArray(result.collections)) return result;
+    return { ...result, collections: result.collections.map((collection) => (isRecord(collection) && typeof collection.id === "string" ? { ...collection, handle: `element-collection:${collection.id}` } : collection)) };
+}
+
+function decorateElement(element) {
+    if (!isRecord(element) || typeof element.id !== "string" || !Number.isInteger(element.version) || element.version < 1) return element;
+    return { ...element, handle: `element:${element.id}`, versionHandle: `element:${element.id}@v${element.version}` };
+}
+
+function decorateElementVersion(version, fallbackElementId) {
+    if (!isRecord(version)) return version;
+    const elementId = typeof version.elementId === "string" ? version.elementId : fallbackElementId;
+    if (!elementId || !Number.isInteger(version.version) || version.version < 1) return version;
+    return { ...version, handle: `element:${elementId}@v${version.version}` };
+}
+
 export function parseRequiredStableHandle(value, expectedKind) {
     const raw = String(value || "").trim();
     if (!raw.startsWith(`${expectedKind}:`)) throw invalidHandle(expectedKind);
@@ -842,6 +1046,54 @@ function normalizeCampaignReviewInput(input) {
     };
 }
 
+function normalizeWorkPrepareInput(input) {
+    const source = requireRecord(input, "work prepare");
+    const references = source.references === undefined ? undefined : normalizeWorkReferences(source.references);
+    const canvas = source.canvasId === undefined ? undefined : stableHandle(parseRequiredStableHandle(source.canvasId, "canvas"));
+    return {
+        request: cleanRequiredText(source.request, "Work request", 8_000),
+        ...(references ? { references } : {}),
+        ...(canvas ? { canvasId: canvas } : {}),
+        idempotencyKey: requiredIdempotencyKey(source.idempotencyKey),
+    };
+}
+
+function normalizeWorkContinueInput(input) {
+    const source = requireRecord(input, "work continuation");
+    const idempotencyKey = requiredIdempotencyKey(source.idempotencyKey);
+    const action = source.action === undefined ? "" : cleanRequiredText(source.action, "Work continuation action", 80);
+    const rebase = source.rebase === true;
+    if (rebase || action === "acknowledge_canvas") {
+        if (action && action !== "acknowledge_canvas") throw new CanvasAgentApiError("rebase may only be used with acknowledge_canvas.", { code: "usage" });
+        if (source.answer !== undefined || source.directionId !== undefined || source.adjustment !== undefined) throw new CanvasAgentApiError("Canvas acknowledgement cannot include an answer, selection, or adjustment.", { code: "usage" });
+        return { ...(action ? { action } : {}), ...(rebase ? { rebase: true } : {}), idempotencyKey };
+    }
+    if (action === "answer") return { action, answer: cleanRequiredText(source.answer, "Work answer", 2_000), idempotencyKey };
+    if (action === "select_direction") return { action, directionId: cleanRequiredText(source.directionId, "Work direction", 400), idempotencyKey };
+    if (action === "adjust") return { action, adjustment: cleanRequiredText(source.adjustment, "Work adjustment", 2_000), idempotencyKey };
+    throw new CanvasAgentApiError("Work continuation action must be answer, select_direction, adjust, or acknowledge_canvas.", { code: "usage" });
+}
+
+function normalizeWorkExecuteInput(input) {
+    const source = requireRecord(input, "work execute");
+    if (source.confirm !== true) throw new CanvasAgentApiError("Work execution requires confirm: true.", { code: "usage" });
+    return { confirm: true, idempotencyKey: requiredIdempotencyKey(source.idempotencyKey) };
+}
+
+function normalizeWorkReferences(value) {
+    if (!Array.isArray(value) || value.length > 12) throw new CanvasAgentApiError("Work references must contain at most 12 node: or asset: handles.", { code: "usage" });
+    return value.map((reference) => {
+        const source = isRecord(reference) ? reference : { handle: reference };
+        const raw = String(source.handle || "").trim();
+        const kind = raw.startsWith("node:") ? "node" : raw.startsWith("asset:") ? "asset" : "";
+        if (!kind) throw new CanvasAgentApiError("Work references must be node: or asset: handles.", { code: "usage" });
+        const role = source.role;
+        if (role !== undefined && role !== "identity" && role !== "style" && role !== "product") throw new CanvasAgentApiError("Work reference role must be identity, style, or product.", { code: "usage" });
+        const handle = stableHandle(parseRequiredStableHandle(raw, kind));
+        return role ? { handle, role } : handle;
+    });
+}
+
 function normalizeCampaignProductReference(value) {
     if (value === undefined || value === null) return undefined;
     const reference = isRecord(value) ? (value.handle ?? value.nodeId ?? value.assetId) : value;

package/src/commands.mjs

@@ -84,6 +84,16 @@ export const GAVANA_CLI_COMMANDS = Object.freeze([
             "gavana recipe run recipe:social-creative-angles --input offer-brief=@brief.md --destination agent-canvas",
         ],
     },
+    {
+        group: "work",
+        action: "prepare",
+        usage: ["gavana work prepare --request \"Create a social campaign\" --reference asset:<id> [--canvas canvas:<id>] --idempotency-key KEY"],
+        notesBefore: ["Work commands are chat-first: prepare returns exactly three directions without paid generation; execute requires a selected direction and --confirm."],
+    },
+    { group: "work", action: "get", usage: ["gavana work get work:<id>"] },
+    { group: "work", action: "refresh", usage: ["gavana work refresh work:<id>"] },
+    { group: "work", action: "continue", usage: ["gavana work continue work:<id> --action answer|select_direction|adjust|acknowledge_canvas --idempotency-key KEY", "gavana work continue work:<id> --rebase --idempotency-key KEY"] },
+    { group: "work", action: "execute", usage: ["gavana work execute work:<id> --confirm --idempotency-key KEY"] },
     { group: "canvas", action: "list", usage: ["gavana canvas list [--limit N] [--cursor CURSOR]"] },
     { group: "canvas", action: "agent", usage: ["gavana canvas agent"] },
     { group: "canvas", action: "create", usage: ["gavana canvas create --title \"New canvas\""] },
@@ -107,6 +117,18 @@ export const GAVANA_CLI_COMMANDS = Object.freeze([
     { group: "asset", action: "list", usage: ["gavana asset list [--canvas canvas:<id>] [--limit N] [--cursor CURSOR]"] },
     { group: "asset", action: "get", usage: ["gavana asset get asset:<id>|asset:<ownerUid>:<id>"] },
     { group: "asset", action: "upload", usage: ["gavana asset upload path/to/image.png"] },
+    { group: "element", action: "list", usage: ["gavana element list [query] [--state active|archived] [--limit N] [--cursor CURSOR]"] },
+    { group: "element", action: "get", usage: ["gavana element get element:<id>@v<n>"] },
+    { group: "element", action: "history", usage: ["gavana element history element:<id> [--limit N] [--cursor CURSOR]"] },
+    { group: "element", action: "create", usage: ["gavana element create --name \"Soft window light\" --type lighting [--source-asset asset:<id>] [--guidelines \"...\"]"] },
+    { group: "element", action: "update", usage: ["gavana element update element:<id> --name \"...\" --type lighting [--source-asset asset:<id>] [--guidelines \"...\"]"] },
+    { group: "element", action: "collections", usage: ["gavana element collections element:<id> [--collection element-collection:<id>]"] },
+    { group: "element", action: "archive", usage: ["gavana element archive element:<id> [--yes]"] },
+    { group: "element", action: "restore", usage: ["gavana element restore element:<id>"] },
+    { group: "element", action: "collection-list", usage: ["gavana element collection-list [--limit N] [--cursor CURSOR]"] },
+    { group: "element", action: "collection-create", usage: ["gavana element collection-create --name \"Campaign assets\""] },
+    { group: "element", action: "collection-rename", usage: ["gavana element collection-rename element-collection:<id> --name \"...\""] },
+    { group: "element", action: "collection-delete", usage: ["gavana element collection-delete element-collection:<id> [--yes]"] },
     { group: "provider", action: "list", usage: ["gavana provider list [--limit N] [--cursor CURSOR]"] },
     { group: "model", action: "list", usage: ["gavana model list [query] [--provider PROVIDER] [--capability image.generate]"] },
     { group: "model", action: "get", usage: ["gavana model get model:<id>"] },
@@ -122,9 +144,9 @@ export const GAVANA_CLI_COMMANDS = Object.freeze([
             "gavana action run action:side-by-side-composite --input node:<id> --input asset:<id> --destination canvas:<id>",
         ],
     },
-    { group: "image", action: "generate", usage: ["gavana image generate --destination agent-canvas --prompt \"...\""] },
-    { group: "image", action: "edit", usage: ["gavana image edit --destination canvas:<id> --reference path/to/image.png --prompt \"...\""] },
-    { group: "image", action: "variations", usage: ["gavana image variations --destination new-canvas --canvas-title \"Variations\" --reference path/to/source.png --prompt \"...\""] },
+    { group: "image", action: "generate", usage: ["gavana image generate --destination agent-canvas --prompt \"...\" [--element element:<id>@v<n>] [--wait]"] },
+    { group: "image", action: "edit", usage: ["gavana image edit --destination canvas:<id> --reference path/to/image.png --prompt \"...\" [--wait]"] },
+    { group: "image", action: "variations", usage: ["gavana image variations --destination new-canvas --canvas-title \"Variations\" --reference path/to/source.png --prompt \"...\" [--wait]"] },
     { group: "video", action: "generate", usage: ["gavana video generate --model model:<id> --prompt \"...\" --duration 15", "gavana video generate --model model:<id> --prompt \"...\" --first-frame path/to/start.png --no-wait", "gavana video generate --model model:<id> --prompt \"...\" --download output.mp4"] },
     { group: "video", action: "download", usage: ["gavana video download job:<id> --file output.mp4 [--yes]"] },
     { group: "job", action: "get", usage: ["gavana job get job:<id>"] },

package/src/config.mjs

@@ -7,13 +7,18 @@ import { promisify } from "node:util";
 const execFile = promisify(execFileCallback);
 const KEYCHAIN_SERVICE = "ai.gavana.cli";
 
-export async function readAgentConfig(env = process.env) {
+export async function readAgentConfig(env = process.env, dependencies = {}) {
     const store = await readAgentConfigStore(env);
     const profile = selectedProfileName(store, env);
     const selected = store.profiles?.[profile] || {};
     let token = selected.token || "";
-    if (!token && selected.credentialStore === "macos-keychain") token = await readMacKeychainCredential(profile);
-    return { ...store, ...selected, ...(token ? { token } : {}), profile };
+    let credentialState = token ? "available" : "missing";
+    if (!token && selected.credentialStore === "macos-keychain") {
+        const credential = await keychainCredentialReader(dependencies)(profile);
+        token = credential.token;
+        credentialState = credential.state;
+    }
+    return { ...store, ...selected, ...(token ? { token } : {}), credentialState, profile };
 }
 
 export async function readAgentConfigMetadata(env = process.env) {
@@ -115,18 +120,30 @@ export async function setActiveAgentProfile(profile, env = process.env) {
     return { profile: name, configPath: agentConfigFilePath(env) };
 }
 
-export async function listAgentProfiles(env = process.env) {
+export async function listAgentProfiles(env = process.env, dependencies = {}) {
     const store = await readAgentConfigStore(env);
+    const readKeychainCredential = keychainCredentialReader(dependencies);
     return {
         activeProfile: selectedProfileName(store, env),
-        profiles: Object.entries(store.profiles || {})
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([name, value]) => ({
-                name,
-                baseUrl: value?.baseUrl || "",
-                active: name === selectedProfileName(store, env),
-                configured: Boolean(value?.baseUrl && (value?.token || value?.credentialStore === "macos-keychain")),
-            })),
+        profiles: await Promise.all(
+            Object.entries(store.profiles || {})
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(async ([name, value]) => {
+                    const credential = value?.token
+                        ? { token: value.token, state: "available" }
+                        : value?.credentialStore === "macos-keychain"
+                          ? await readKeychainCredential(name)
+                          : { token: "", state: "missing" };
+                    return {
+                        name,
+                        baseUrl: value?.baseUrl || "",
+                        active: name === selectedProfileName(store, env),
+                        configured: Boolean(value?.baseUrl && credential.state === "available"),
+                        credentialStore: value?.credentialStore || "",
+                        credentialState: credential.state,
+                    };
+                }),
+        ),
         configPath: agentConfigFilePath(env),
     };
 }
@@ -179,15 +196,31 @@ async function writeMacKeychainCredential(profile, token) {
     await execFile("security", ["add-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE, "-w", token, "-U"]);
 }
 
-async function readMacKeychainCredential(profile) {
+function keychainCredentialReader(dependencies) {
+    if (dependencies.readKeychainCredential) return dependencies.readKeychainCredential;
+    return (profile) => readMacKeychainCredential(profile, dependencies.execFile || execFile);
+}
+
+async function readMacKeychainCredential(profile, execute = execFile) {
     try {
-        const { stdout } = await execFile("security", ["find-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE, "-w"]);
-        return stdout.trim();
-    } catch {
-        return "";
+        const { stdout } = await execute("security", ["find-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE, "-w"]);
+        const token = stdout.trim();
+        return { token, state: token ? "available" : "missing" };
+    } catch (error) {
+        if (!isMissingMacKeychainCredential(error)) return { token: "", state: "inaccessible" };
+        try {
+            await execute("security", ["show-keychain-info"]);
+            return { token: "", state: "missing" };
+        } catch {
+            return { token: "", state: "inaccessible" };
+        }
     }
 }
 
+function isMissingMacKeychainCredential(error) {
+    return Number(error?.code) === 44 || /could not be found|item not found/i.test(String(error?.stderr || ""));
+}
+
 async function removeMacKeychainCredential(profile) {
     try {
         await execFile("security", ["delete-generic-password", "-a", profile, "-s", KEYCHAIN_SERVICE]);

package/src/guide-sources.mjs

@@ -25,7 +25,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Place native objects in readable groups without hiding or rearranging existing work.",
         keywords: Object.freeze(["section","layout","position","overlap","spacing","grid","right","below","contain","navigation"]),
         order: 3,
-        markdown: "\n## Layout rules\n\n- Treat the current canvas as user-owned. Preserve existing coordinates unless reorganization was explicitly requested.\n- For additions to an existing canvas, compute its visible bounding box and place the new Section to the right with at least 160 canvas units of outer spacing. If right-side placement would make the canvas excessively wide, place it below with the same spacing.\n- Use 48 units of inner Section padding, 32 units between sibling nodes, and at least 80 units between major stages.\n- Keep workflow direction consistent, normally left to right. Keep inputs before transformations and outputs after them.\n- Use compact rows or columns. Avoid extremely long, thin canvases that become unreadable at Fit Canvas.\n- For 2-8 generated image outputs, reserve each requested final aspect frame before work begins and pack the complete result cluster as a grid. The usual four-image photoshoot is a 2x2 grid; do not stack it as a tall output column that can overlap when images finalize.\n- Size Sections after their contents. Do not use Section overlap as a substitute for node placement.\n- Run `canvas_validate` before and after a multi-node layout change.\n\n## One task = one Section\n\nGroup each task's output in a titled Section sized to its contents plus 48\nunits of padding. Workflow creation and multi-output image generation wrap\ntheir clusters in a Section automatically (multi-output wrapping applies to\nautomatic placement; passing explicit target coordinates opts out and leaves\nplacement fully caller-controlled); do the same for hand-built\nclusters. Agent-created nodes left outside every Section raise an info-level\n`unsectioned_node` finding. Membership is stored server-side as\n`metadata.sectionId`, recomputed from complete-frame geometry after every\nbatch. Agent-created Sections receive an owned auto-fit contract; after a\ngenerated child changes size, Gavana refits only that still-owned Section to\nthe full child bounds plus 48 units. Do not use this as permission to move or\nresize a user-controlled Section.\n\nFor a newly proposed agent cluster, ordinary-node overlap and full-frame\nSection overflow are write-blocking errors. On an existing Canvas, historical\nuser-created overlap or overflow remains advisory so an unrelated scoped edit\ncan still proceed. Agent-owned task findings still block completion review\nuntil they are corrected.\n\n## Existing canvas rule\n\nWhen the user says \"add\", do not interpret it as \"reorganize\". New work should be distinguishable, spatially contained, and reversible without moving unrelated content.\n",
+        markdown: "\n## Layout rules\n\n- Treat the current canvas as user-owned. Preserve existing coordinates unless reorganization was explicitly requested.\n- For additions to an existing canvas, compute its visible bounding box and place the new Section to the right with at least 160 canvas units of outer spacing. If right-side placement would make the canvas excessively wide, place it below with the same spacing.\n- Use 48 units of inner Section padding, 32 units between sibling nodes, and at least 80 units between major clusters.\n- Keep a left-to-right direction only when the user asks for a linear workflow. For creative exploration, use Sections as optional spatial places rather than a required sequence.\n- Use compact rows or columns. Avoid extremely long, thin canvases that become unreadable at Fit Canvas.\n- For 2-8 generated image outputs, reserve each requested final aspect frame before work begins and pack the complete result cluster as a grid. A normal feed photoshoot uses 4:5 portrait frames in its own 2x2 Section. Put horizontal 16:9 campaign ads in a separate Section with their own targets; do not mix formats unless the user explicitly asks for a mixed-format deliverable.\n- Size Sections after their contents. Do not use Section overlap as a substitute for node placement.\n- Run `canvas_validate` before and after a multi-node layout change.\n\n## One task = one Section\n\nGroup each task's output in a titled Section sized to its contents plus 48\nunits of padding. Workflow creation and multi-output image generation wrap\ntheir clusters in a Section automatically (multi-output wrapping applies to\nautomatic placement; passing explicit target coordinates opts out and leaves\nplacement fully caller-controlled); do the same for hand-built\nclusters. Agent-created nodes left outside every Section raise an info-level\n`unsectioned_node` finding. Membership is stored server-side as\n`metadata.sectionId`, recomputed from complete-frame geometry after every\nbatch. Agent-created Sections receive an owned auto-fit contract; after a\ngenerated child changes size, Gavana refits only that still-owned Section to\nthe full child bounds plus 48 units. Do not use this as permission to move or\nresize a user-controlled Section.\n\nFor a newly proposed agent cluster, ordinary-node overlap and full-frame\nSection overflow are write-blocking errors. On an existing Canvas, historical\nuser-created overlap or overflow remains advisory so an unrelated scoped edit\ncan still proceed. Agent-owned task findings still block completion review\nuntil they are corrected.\n\n## Existing canvas rule\n\nWhen the user says \"add\", do not interpret it as \"reorganize\". New work should be distinguishable, spatially contained, and reversible without moving unrelated content.\n",
     }),
     Object.freeze({
         id: "connections",
@@ -49,7 +49,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Prepare media nodes, start only explicit generation, and preserve output lineage.",
         keywords: Object.freeze(["generated","generation","image","video","output","asset","durable","lineage","placeholder","job"]),
         order: 6,
-        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Poll the returned Run or Job; do not start another run while waiting. A terminal failure must be reported without automatic retry.\n\n## Completion\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, durable output count, and product-fidelity review state. Do not claim Done while it says `doneClaimAllowed: false`. Product-fidelity uncertainty requires human review; never create another paid provider call automatically.\n",
+        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n- Before image or video generation, call `model_list` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Reuse existing Canvas `node:` or `asset:` handles directly. Do not download\n  and re-upload a generated Canvas image merely to use it as the next\n  generation's reference. State whether a style reference establishes the\n  brand-world or typography/layout direction in the prompt.\n- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Image tools return durable queued progress by default; report that progress immediately and do not automatically call `run_wait`. Call `run_wait` only when the current user explicitly needs the completed asset in this same interaction. Otherwise, a later `run_get` or Canvas read can observe progress and the durable output. Do not start another run while one is pending. A terminal failure must be reported without automatic retry.\n\n## Completion\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, and delivery state. Do not claim Done while it says `doneClaimAllowed: false`, including when delivery is pending, failed, or non-durable. Render the Canvas for visual inspection when the request includes a campaign, poster, banner, or multi-direction composition. Reference provenance is not a user workflow state and never requires a Keep action. Never create another paid provider call automatically.\n",
     }),
     Object.freeze({
         id: "existing-canvases",
@@ -65,7 +65,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Separate preparation from execution and prevent accidental or repeated provider charges.",
         keywords: Object.freeze(["paid","credits","cost","generate","run","retry","failure","prepare","setup","explicit"]),
         order: 8,
-        markdown: "\n## Intent boundary\n\n\"Build\", \"prepare\", \"set up\", \"connect\", \"draft\", and \"make ready\" authorize graph edits only. They do not authorize Recipe, image, video, or Action execution.\n\nStart paid work only when the current user message explicitly asks to run or generate it. Do not infer authorization from an older message, a node label, an unfinished placeholder, or nearby content.\n\n## Retry boundary\n\n- Use one stable idempotency key for one intended paid operation.\n- Poll the returned handle with status tools.\n- Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.\n- Ask for new user intent before any new paid attempt.\n\nDeterministic Actions may be described as credit-free only when `action_get` confirms that contract. Inspect an Action before running it.\n",
+        markdown: "\n## Intent boundary\n\n\"Build\", \"prepare\", \"set up\", \"connect\", \"draft\", and \"make ready\" authorize graph edits only. They do not authorize Recipe, image, video, or Action execution.\n\nStart paid work only when the current user message explicitly asks to run or generate it. Do not infer authorization from an older message, a node label, an unfinished placeholder, or nearby content.\n\n## Retry boundary\n\n- Use one stable idempotency key for one intended paid operation.\n- Return an image Run's durable queued progress immediately. Do not call `run_wait` unless the current user explicitly needs the completed asset in this same interaction; otherwise observe it later with `run_get` or a Canvas read.\n- Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.\n- Ask for new user intent before any new paid attempt.\n\nDeterministic Actions may be described as credit-free only when `action_get` confirms that contract. Inspect an Action before running it.\n",
     }),
     Object.freeze({
         id: "validation-recovery",
@@ -73,7 +73,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Interpret structural findings, correct invalid batches, and finish with an evidence-based review.",
         keywords: Object.freeze(["validate","lint","overlap","orphan","header","connection","destructive","recovery","error","atomic","blocked","force"]),
         order: 9,
-        markdown: "\n## Use `canvas_validate`\n\nCall it with only `canvasId` to audit the current graph. Pass the proposed `operations` to inspect the planned post-batch graph and destructive impact before writing.\n\nWarning- and info-level findings are advisory. Error-severity findings caused by the proposed agent write have teeth: `canvas_apply_batch` rejects that batch and writes nothing. Historical findings remain visible for review but do not turn an unrelated scoped write into a forced cleanup. Validation never mutates the canvas or consumes an idempotency key.\n\n`summary.passed` means there is no structural error. `summary.reviewRequired` is true when errors, warnings, or truncated findings still require agent or human review. `completionReview` is the finalization-ready structured view: it names overlap, containment, reference lineage, output count, and product-fidelity state. Never claim Done unless `completionReview.doneClaimAllowed` is true.\n\n## Blocked writes\n\nWhen a batch is rejected with error-severity findings:\n\n- Nothing was written and the idempotency key was not consumed — the same key retries the corrected batch of the same intent.\n- The rejection lists the blocking findings. Fix the listed operations, then confirm with `canvas_validate` using the same `operations` before applying again.\n- `force: true` applies the batch despite error findings. Use it only after validating, and only when the user explicitly accepts the listed findings — never as a routine retry shortcut.\n\n## Recovery\n\n- If an operation is rejected, the atomic batch makes no partial change.\n- Read the finding's exact handles and linked guide topic.\n- Correct unsupported object types, metadata, endpoint modes, positions, or references instead of guessing repeatedly.\n- Use a new idempotency key if the corrected payload represents a changed intent.\n- Read and validate again after a successful write.\n\nCommon findings include ordinary-node overlap, Section content overflow, generated output without an incoming relationship, text imitating a Section header, broken lineage handles, unclear media connections, and proposed deletions. Product-fidelity uncertainty is a review state, not authorization to regenerate.\n",
+        markdown: "\n## Use `canvas_validate`\n\nCall it with only `canvasId` to audit the current graph. Pass the proposed `operations` to inspect the planned post-batch graph and destructive impact before writing.\n\nWarning- and info-level findings are advisory. Error-severity findings caused by the proposed agent write have teeth: `canvas_apply_batch` rejects that batch and writes nothing. Historical findings remain visible for review but do not turn an unrelated scoped write into a forced cleanup. Validation never mutates the canvas or consumes an idempotency key.\n\n`summary.passed` means there is no structural error. `summary.reviewRequired` is true when errors, warnings, or truncated findings still require agent or human review. `completionReview` is the finalization-ready structured view: it names overlap, containment, reference lineage, and delivery state. Never claim Done unless `completionReview.doneClaimAllowed` is true; pending, failed, or non-durable generated outputs block that claim even when the geometry is clean.\n\nFor a campaign, poster, banner, or multi-direction composition, structural\nvalidation is necessary but not visual proof. Render the completed Canvas and\ncheck the actual composition, distinctness of directions, visible product and\nlayout, and separation of 4:5 feed work from 16:9 ads. Report an unavailable\nrender or incomplete visual check as a limitation rather than claiming it was\nverified.\n\n## Blocked writes\n\nWhen a batch is rejected with error-severity findings:\n\n- Nothing was written and the idempotency key was not consumed — the same key retries the corrected batch of the same intent.\n- The rejection lists the blocking findings. Fix the listed operations, then confirm with `canvas_validate` using the same `operations` before applying again.\n- `force: true` applies the batch despite error findings. Use it only after validating, and only when the user explicitly accepts the listed findings — never as a routine retry shortcut.\n\n## Recovery\n\n- If an operation is rejected, the atomic batch makes no partial change.\n- Read the finding's exact handles and linked guide topic.\n- Correct unsupported object types, metadata, endpoint modes, positions, or references instead of guessing repeatedly.\n- Use a new idempotency key if the corrected payload represents a changed intent.\n- Read and validate again after a successful write.\n\nCommon findings include ordinary-node overlap, Section content overflow, generated output without an incoming relationship, text imitating a Section header, broken lineage handles, unclear media connections, and proposed deletions. Reference provenance is not authorization to regenerate.\n",
     }),
     Object.freeze({
         id: "examples-common-mistakes",
@@ -83,4 +83,12 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         order: 10,
         markdown: "\n## Good patterns\n\n- Research cluster: one Section, several Sticky observations, one Text synthesis, and directed observation -> synthesis connections.\n- Creative workflow: source image -> Prompt List -> empty generator -> generated outputs.\n- Video workflow: first image -[first-frame]-> video target and optional last image -[last-frame]-> video target.\n- Existing-canvas addition: new contained Section outside the current bounds, with no existing-node mutations.\n\n## Common mistakes\n\n- Using long Text or Sticky nodes as fake headers instead of Sections.\n- Creating every node at `{ \"x\": 0, \"y\": 0 }` or stacking nodes on top of one another.\n- Leaving generated outputs disconnected from their prompt, List, source, or stage.\n- Connecting a Section to workflow nodes.\n- Treating nearby objects as implicit inputs without explicit handles or connections.\n- Copying a style image name into prompt text instead of using a row-level reference binding.\n- Writing generated media content directly into node metadata.\n- Reorganizing or deleting existing work when the user asked only to add something.\n- Starting generation when the user asked only to prepare a workflow.\n- Retrying a failed paid operation automatically.\n- Reporting a temporary Job or Run handle as a durable Canvas output.\n- Passing `force: true` to push a batch past error-severity findings instead of fixing the operations. Force is for explicit, user-approved exceptions only.\n",
     }),
+    Object.freeze({
+        id: "creative-canvas",
+        title: "Creative Canvas",
+        description: "Keep creative work on the Canvas without lifecycle states.",
+        keywords: Object.freeze(["creative","ideas","directions","brainstorm","refine","compose","campaign"]),
+        order: 11,
+        markdown: "\n## The Canvas is the memory\n\nEvery generated image, written thought, reference, and experiment remains on the Canvas until a person deletes it. Do not assign creative output a draft, rejected, accepted, approved, or final lifecycle state. A retained node has value even when it is not currently selected.\n\nReference handles and connections are durable provenance. They explain where a creative result came from; they do not require a user to click Keep or clear a review gate.\n\n## Spatial structure, not stages\n\nUse an ordinary Section only when the person explicitly asks to organize work. Name it for their brief; it is never a required left-to-right workflow. Any node may move between Sections, appear in more than one discussion, become a reference for later work, or remain untouched. Do not move, rename, or create Sections unless the user requests structure.\n\n## Campaign assistance\n\nWhen a person supplies only a product and a broad ask, do not jump straight to a\ngeneric photoshoot, poster, or banner. First make a visible reference-led\nconcept cluster with three roles:\n\n- **Product identity:** the exact supplied product, logo, garment, or other\n  identity reference when one exists.\n- **Brand-world:** the lighting, material, setting, and cultural visual world.\n- **Typography/layout:** the editorial hierarchy, copy placement, crop, and\n  composition reference.\n\nConnect each source to the work it informs. If inspiration is missing and the\ncurrent request explicitly authorizes generation, autonomously create small,\nclearly labelled concept-reference images or boards for every missing role: a\nproduct-identity concept study, brand-world, and typography/layout. A\nproduct-identity study is provisional when no exact product source exists; none\nof these generated concept references may be claimed as product evidence,\nofficial assets, or real campaigns. If the request authorizes preparation only,\ncreate editable prompt and Text references without starting a paid image job.\n\nInfer a concise brief and create at least three materially different directions.\nVary the central idea, composition, setting, copy hierarchy, typography/layout\nconcept, or audience — not merely the pose or crop. Give every direction a\nshort rationale Text node and preserve all attempts on the Canvas. Add one\n**Recommended next move** Text node that explains the strongest direction; this\nis editorial advice, not approval.\n\nDo not create a default Section set. If a person asks for a structured campaign\narea, use only the ordinary Sections they request. Ask one short question only\nwhen a missing product-versus-style distinction would materially change the\nwork. Otherwise make a useful first pass and let the person point to, combine,\nor refine any result. Exporting or publishing is an explicit action from any\nselected node or Section, not a status transition.\n",
+    }),
 ]);

package/src/mcp-targets.mjs

@@ -0,0 +1,72 @@
+/**
+ * MCP server naming and per-client config for the CLI.
+ *
+ * This mirrors `src/lib/canvas-agent/connect-targets.ts`, which is the same
+ * contract the web hub emits. The CLI ships as its own package and cannot
+ * import the app's TypeScript, so the two are pinned against each other by
+ * `scripts/connect-targets-cli-drift.test.ts` — change both together.
+ *
+ * Before this existed the CLI hardcoded the name `gavana` for every
+ * environment and both scopes, so `gavana mcp install claude` from a local
+ * checkout silently replaced the user's production entry, and `--read-only`
+ * silently replaced their full-access one.
+ */
+
+export function gavanaMcpEndpoint(baseUrl, readOnly = false) {
+    return `${normalizeOrigin(baseUrl)}/mcp${readOnly ? "/readonly" : ""}`;
+}
+
+export function gavanaMcpServerName(baseUrl, readOnly = false) {
+    return `${environmentServerName(baseUrl)}${readOnly ? "-readonly" : ""}`;
+}
+
+export function gavanaMcpEnvironment(baseUrl) {
+    let hostname;
+    try {
+        hostname = new URL(normalizeOrigin(baseUrl)).hostname.toLowerCase();
+    } catch {
+        return "production";
+    }
+    if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1" || hostname.endsWith(".localhost")) return "development";
+    if (hostname.includes("staging")) return "staging";
+    return "production";
+}
+
+export function gavanaMcpClientDefinition(clientName, baseUrl, readOnly = false) {
+    const endpoint = gavanaMcpEndpoint(baseUrl, readOnly);
+    const serverName = gavanaMcpServerName(baseUrl, readOnly);
+
+    if (clientName === "codex") return { client: "codex", transport: "streamable-http", endpoint, serverName, command: "codex", args: ["mcp", "add", serverName, "--url", endpoint] };
+    if (clientName === "claude") return { client: "claude", transport: "streamable-http", endpoint, serverName, command: "claude", args: ["mcp", "add", "--transport", "http", "--scope", "user", serverName, endpoint] };
+    if (clientName === "cursor") return { client: "cursor", transport: "streamable-http", endpoint, serverName, config: { mcpServers: { [serverName]: { url: endpoint } } } };
+    if (clientName === "vscode") return { client: "vscode", transport: "streamable-http", endpoint, serverName, config: { servers: { [serverName]: { type: "http", url: endpoint } } } };
+    if (clientName === "chatgpt") {
+        return { client: "chatgpt", transport: "streamable-http", endpoint, serverName, instructions: "Add the endpoint as a custom MCP connector, then complete Gavana OAuth in the browser. ChatGPT requires an https endpoint." };
+    }
+    if (clientName === "stdio" || clientName === "local") {
+        return {
+            client: "local",
+            transport: "stdio",
+            serverName,
+            command: "npx",
+            args: ["-y", "@gavana.ai/mcp@0.2.1"],
+            env: readOnly ? { GAVANA_MCP_READ_ONLY: "true" } : {},
+            credentialSource: "Reads the active Gavana CLI profile or inherited GAVANA_BASE_URL and GAVANA_AGENT_TOKEN environment variables.",
+        };
+    }
+    return null;
+}
+
+function environmentServerName(baseUrl) {
+    const environment = gavanaMcpEnvironment(baseUrl);
+    return environment === "development" ? "gavana-dev" : environment === "staging" ? "gavana-staging" : "gavana";
+}
+
+function normalizeOrigin(baseUrl) {
+    const trimmed = String(baseUrl || "").trim();
+    try {
+        return new URL(trimmed).origin;
+    } catch {
+        return trimmed.replace(/\/+$/, "");
+    }
+}