@gavana.ai/cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog — @gavana.ai/cli
 
+## 0.2.1
+
+### Fixed
+
+- macOS Keychain-backed profiles now distinguish a credential that is genuinely
+  absent from one that the current process cannot access. Restricted processes
+  report `keychain_inaccessible` with an actionable explanation instead of
+  sending users through login again.
+
 ## 0.2.0
 
 First release published to npm. Version 0.1.0 existed in this repository but was

package/README.md

@@ -103,6 +103,9 @@ retried automatically.
 gavana canvas list
 gavana canvas list --limit 25 --jq '.canvases[].handle' -r
 gavana asset get asset:OWNER_UID:ASSET_ID
+gavana element list
+gavana element get element:ELEMENT_ID@v3
+gavana element create --name "Soft window light" --type lighting --guidelines "Keep diffuse, cool window light."
 gavana recipe search "product visual"
 gavana recipe run recipe:product-visual-direction --input product-context="A matte black travel bottle" --destination agent-canvas
 gavana model list --capability image.generate
@@ -217,6 +220,37 @@ commands for canvases, recipes, assets, Actions, models, and providers accept `-
 `--jq` selector supports property paths, array indexes, and `[]` projections
 without requiring a separate jq installation.
 
+## Elements
+
+Elements are reusable visual references, not copied image files. Use
+`element list`, `element get element:<id>@v<n>`, and `element history` to
+inspect current or immutable historical revisions. Create or update with one
+or more `--source-asset asset:<id>` references, `--guidelines`, or both.
+`element archive` asks for interactive confirmation; in scripts and other
+non-interactive environments it requires `--yes`. An archived Element remains
+restorable with `element restore`. `element collection-delete` follows the same
+confirmation rule and never deletes the Elements it organized.
+
+Apply an exact immutable revision during image work with repeatable
+`--element element:<id>@v<n>` flags. JSON callers may also pass
+`{ "handle": "element:<id>@v<n>", "role": "style", "influence": 0.8 }`.
+An image job accepts up to eight Elements; their source images share the
+existing 16-reference limit.
+
+## Chat-first work
+
+Use `work_prepare` or `gavana work prepare` for a broad campaign request. It
+returns exactly three directions and a recommendation without paid generation.
+Use `work_continue` or `gavana work continue` to answer a factual question,
+select one direction, adjust the brief, or acknowledge a changed Canvas with
+`--rebase`. `work_execute` and `gavana work execute work:<id> --confirm
+--idempotency-key KEY` send `confirm: true`, start only the selected direction,
+and return durable progress immediately; they never wait or automatically
+retry paid work. `work_get` is read-only and never polls providers or writes
+state; use `gavana work refresh work:<id>` to reconcile provider progress.
+The snapshot returns the latest brief, choice, outputs, and Canvas
+synchronization state.
+
 ## JavaScript client
 
 The same dependency-free client is exported for Node.js applications:

package/guides/creative-canvas.md

@@ -0,0 +1,52 @@
+---
+id: creative-canvas
+title: Creative Canvas
+description: Keep creative work on the Canvas without lifecycle states.
+keywords: ["creative", "ideas", "directions", "brainstorm", "refine", "compose", "campaign"]
+order: 11
+---
+
+## The Canvas is the memory
+
+Every 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.
+
+Reference 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.
+
+## Spatial structure, not stages
+
+Use 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.
+
+## Campaign assistance
+
+When a person supplies only a product and a broad ask, do not jump straight to a
+generic photoshoot, poster, or banner. First make a visible reference-led
+concept cluster with three roles:
+
+- **Product identity:** the exact supplied product, logo, garment, or other
+  identity reference when one exists.
+- **Brand-world:** the lighting, material, setting, and cultural visual world.
+- **Typography/layout:** the editorial hierarchy, copy placement, crop, and
+  composition reference.
+
+Connect each source to the work it informs. If inspiration is missing and the
+current request explicitly authorizes generation, autonomously create small,
+clearly labelled concept-reference images or boards for every missing role: a
+product-identity concept study, brand-world, and typography/layout. A
+product-identity study is provisional when no exact product source exists; none
+of these generated concept references may be claimed as product evidence,
+official assets, or real campaigns. If the request authorizes preparation only,
+create editable prompt and Text references without starting a paid image job.
+
+Infer a concise brief and create at least three materially different directions.
+Vary the central idea, composition, setting, copy hierarchy, typography/layout
+concept, or audience — not merely the pose or crop. Give every direction a
+short rationale Text node and preserve all attempts on the Canvas. Add one
+**Recommended next move** Text node that explains the strongest direction; this
+is editorial advice, not approval.
+
+Do not create a default Section set. If a person asks for a structured campaign
+area, use only the ordinary Sections they request. Ask one short question only
+when a missing product-versus-style distinction would materially change the
+work. Otherwise make a useful first pass and let the person point to, combine,
+or refine any result. Exporting or publishing is an explicit action from any
+selected node or Section, not a status transition.

package/guides/generated-assets.md

@@ -10,11 +10,16 @@ order: 6
 
 - Read the destination canvas and relevant source nodes.
 - Use exact source `node:` or `asset:` handles.
+- 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.
 - For a standalone image request, pass every visual source in `references`.
   Use `{ "handle": "node:...", "role": "identity" }` when its
   responsibility is known; valid roles are `identity`, `construction`,
   `texture`, `fit`, and `style`. Do not flatten multi-reference work
   into prompt prose or omit a source during fallback.
+- Reuse existing Canvas `node:` or `asset:` handles directly. Do not download
+  and re-upload a generated Canvas image merely to use it as the next
+  generation's reference. State whether a style reference establishes the
+  brand-world or typography/layout direction in the prompt.
 - Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.
 - Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.
 
@@ -26,4 +31,4 @@ Generation is allowed only after explicit current-turn user intent. Start one ru
 
 Do 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.
 
-Keep 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.
+Keep 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.

package/guides/sections-layout.md

@@ -10,10 +10,10 @@ order: 3
 
 - Treat the current canvas as user-owned. Preserve existing coordinates unless reorganization was explicitly requested.
 - 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.
-- Use 48 units of inner Section padding, 32 units between sibling nodes, and at least 80 units between major stages.
-- Keep workflow direction consistent, normally left to right. Keep inputs before transformations and outputs after them.
+- Use 48 units of inner Section padding, 32 units between sibling nodes, and at least 80 units between major clusters.
+- 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.
 - Use compact rows or columns. Avoid extremely long, thin canvases that become unreadable at Fit Canvas.
-- 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.
+- 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.
 - Size Sections after their contents. Do not use Section overlap as a substitute for node placement.
 - Run `canvas_validate` before and after a multi-node layout change.
 

package/guides/validation-recovery.md

@@ -12,7 +12,14 @@ Call it with only `canvasId` to audit the current graph. Pass the proposed `oper
 
 Warning- 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.
 
-`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.
+`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.
+
+For a campaign, poster, banner, or multi-direction composition, structural
+validation is necessary but not visual proof. Render the completed Canvas and
+check the actual composition, distinctness of directions, visible product and
+layout, and separation of 4:5 feed work from 16:9 ads. Report an unavailable
+render or incomplete visual check as a limitation rather than claiming it was
+verified.
 
 ## Blocked writes
 
@@ -30,4 +37,4 @@ When a batch is rejected with error-severity findings:
 - Use a new idempotency key if the corrected payload represents a changed intent.
 - Read and validate again after a successful write.
 
-Common 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.
+Common 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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gavana.ai/cli",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "description": "JSON-first command-line client for the Gavana Canvas API",
     "type": "module",
     "bin": {

package/src/canvas-agent-guide.mjs

@@ -1,13 +1,13 @@
 // Guide metadata, lookup, and search. The prose itself lives in ../guides/*.md
 // and is loaded through ./guide-sources.mjs, so editing a guide is a content
 // change rather than a code change. Graph validation moved to
-// ./canvas-agent-validation.mjs in guide version 1.2.0.
+// ./canvas-agent-validation.mjs in guide version 1.5.0.
 import { GAVANA_CANVAS_GUIDE_SOURCES } from "./guide-sources.mjs";
 
-export const GAVANA_CANVAS_GUIDE_VERSION = "1.2.0";
+export const GAVANA_CANVAS_GUIDE_VERSION = "1.5.0";
 export const GAVANA_CANVAS_GUIDE_INDEX_URI = `gavana://guides/canvas/v${GAVANA_CANVAS_GUIDE_VERSION.split(".")[0]}/index`;
 export const GAVANA_CANVAS_GUIDE_WORKFLOW_INSTRUCTION =
-    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, blocking findings remain, or product-fidelity review is needed. Treat legacy warnings as review items, not permission to rewrite unrelated work.";
+    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. Campaign work must read creative-canvas and use a reference-led concept before image output. Before image or video generation, call model_list for the required capability and use 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 the connection instead of asking the user to add a key again. When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, delivery is pending, failed, or non-durable, or blocking findings remain. Render campaign compositions for visual inspection. Treat legacy warnings as review items, not permission to rewrite unrelated work.";
 export const GAVANA_CANVAS_GUIDE_READ_ONLY_INSTRUCTION =
     "For the first canvas task in a session, and before any unfamiliar canvas review, inspect the relevant guide through MCP resources or call guide_search then guide_get. Call canvas_get before reasoning about an existing canvas, and use canvas_validate to audit its current graph. Treat validation warnings as review items and never claim to mutate the canvas.";
 

package/src/canvas-agent-validation.mjs

@@ -1,6 +1,6 @@
 // Deterministic canvas graph validation and destructive-impact reporting.
 //
-// Split out of canvas-agent-guide.mjs in guide version 1.2.0: guide prose is now
+// Split out of canvas-agent-guide.mjs in guide version 1.5.0: guide prose is now
 // editable markdown under ../guides/, and validation is code. The two no longer
 // share a file. Validation still cites guide topics, so it imports the guide URI
 // helpers — the dependency runs one way only (validation -> guide).
@@ -333,8 +333,9 @@ function agentOwnsNode(node) {
 function buildCompletionReview(canvas, findings) {
     const generatedOutputs = canvas.nodes.filter(isGeneratedOutput);
     const durableOutputs = generatedOutputs.filter(hasDurableOutput);
-    const pendingOutputs = generatedOutputs.filter((node) => node.metadata?.aiJobStatus === "queued" || node.metadata?.aiJobStatus === "running" || node.metadata?.outputValidationStatus === "checking");
+    const pendingOutputs = generatedOutputs.filter((node) => node.metadata?.aiJobStatus === "queued" || node.metadata?.aiJobStatus === "running");
     const failedOutputs = generatedOutputs.filter((node) => node.metadata?.status === "error" || node.metadata?.aiJobStatus === "failed" || node.metadata?.aiJobStatus === "canceled");
+    const nonDurableOutputs = generatedOutputs.filter((node) => !hasDurableOutput(node) && !pendingOutputs.includes(node) && !failedOutputs.includes(node));
     const overlap = reviewArea(findings, "node_overlap");
     const containment = reviewArea(findings, "section_content_overflow", "unsectioned_node");
     const referenceLineage = reviewArea(findings, "broken_generated_lineage", "unconnected_generated_output", "orphan_media_placeholder");
@@ -342,12 +343,13 @@ function buildCompletionReview(canvas, findings) {
     const blockingFindings = findings.filter((finding) => finding.blocksWrite === true || finding.blocksCompletion === true);
     const blockingFindingCodes = uniqueSorted(blockingFindings.map((finding) => finding.code));
     const advisoryFindingCodes = uniqueSorted(findings.filter((finding) => !blockingFindings.includes(finding)).map((finding) => finding.code));
-    const doneClaimAllowed = blockingFindings.length === 0 && productFidelity.status !== "needs-review";
+    const delivery = deliveryReview(pendingOutputs, failedOutputs, nonDurableOutputs);
+    const doneClaimAllowed = blockingFindings.length === 0 && delivery.status === "clear";
 
     return {
-        status: doneClaimAllowed ? "ready" : blockingFindings.length ? "blocked" : "needs-review",
+        status: doneClaimAllowed ? "ready" : "blocked",
         doneClaimAllowed,
-        instruction: "Do not claim Done while blocking findings remain or product-fidelity review is needed.",
+        instruction: "Do not claim Done while blocking findings remain or generated output delivery is pending, failed, or non-durable.",
         outputs: {
             count: generatedOutputs.length,
             durableCount: durableOutputs.length,
@@ -359,11 +361,27 @@ function buildCompletionReview(canvas, findings) {
         containment,
         referenceLineage,
         productFidelity,
+        delivery,
         blockingFindingCodes,
         advisoryFindingCodes,
     };
 }
 
+function deliveryReview(pendingOutputs, failedOutputs, nonDurableOutputs) {
+    const statuses = [
+        pendingOutputs.length ? "pending" : "",
+        failedOutputs.length ? "failed" : "",
+        nonDurableOutputs.length ? "non-durable" : "",
+    ].filter(Boolean);
+    return {
+        status: statuses.length ? "blocked" : "clear",
+        ...(statuses.length ? { reasons: statuses } : {}),
+        pendingOutputHandles: pendingOutputs.map((node) => nodeHandle(node.id)).sort(),
+        failedOutputHandles: failedOutputs.map((node) => nodeHandle(node.id)).sort(),
+        nonDurableOutputHandles: nonDurableOutputs.map((node) => nodeHandle(node.id)).sort(),
+    };
+}
+
 function reviewArea(findings, ...codes) {
     const matched = findings.filter((finding) => codes.includes(finding.code));
     const blocking = matched.some((finding) => finding.blocksWrite === true || finding.blocksCompletion === true);
@@ -385,17 +403,14 @@ function productFidelityReview(canvas, generatedOutputs) {
             evidenceMissingOutputHandles: [],
         };
     }
-    const needsReview = referenceTargets.filter((node) => node.metadata?.outputValidationStatus === "needs-review" || node.metadata?.outputValidationStatus === "checking");
-    const evidenceMissing = referenceTargets.filter((node) => !node.metadata?.outputValidationStatus || node.metadata?.outputValidationStatus === "skipped");
     return {
-        status: needsReview.length || evidenceMissing.length ? "needs-review" : "passed",
-        reviewedOutputCount: referenceTargets.length - needsReview.length - evidenceMissing.length,
-        needsReviewOutputHandles: needsReview.map((node) => nodeHandle(node.id)).sort(),
-        evidenceMissingOutputHandles: evidenceMissing.map((node) => nodeHandle(node.id)).sort(),
-        reasons: referenceTargets
-            .filter((node) => typeof node.metadata?.outputValidationReason === "string" && node.metadata.outputValidationReason)
-            .map((node) => ({ nodeHandle: nodeHandle(node.id), reason: node.metadata.outputValidationReason }))
-            .sort((left, right) => left.nodeHandle.localeCompare(right.nodeHandle)),
+        // References preserve origin and intent. They never turn a retained
+        // creative output into a completion gate.
+        status: "passed",
+        reviewedOutputCount: referenceTargets.length,
+        needsReviewOutputHandles: [],
+        evidenceMissingOutputHandles: [],
+        reasons: [],
     };
 }
 

package/src/capabilities.mjs

@@ -4,7 +4,7 @@
 import { GAVANA_CLI_VERSION } from "./version.mjs";
 
 export { GAVANA_CLI_VERSION };
-export const GAVANA_MCP_TOOLSETS = Object.freeze(["canvas", "recipes", "assets", "models", "actions", "images", "videos", "runs", "campaigns"]);
+export const GAVANA_MCP_TOOLSETS = Object.freeze(["canvas", "recipes", "assets", "elements", "models", "actions", "images", "videos", "runs", "campaigns"]);
 
 import { GAVANA_TOOL_REGISTRY } from "./tools/registry.mjs";
 
@@ -37,6 +37,7 @@ const TOOLSET_FOR_PREFIX = Object.freeze([
     ["node_", "canvas"],
     ["connection_", "canvas"],
     ["asset_", "assets"],
+    ["element_", "elements"],
     ["provider_", "models"],
     ["model_", "models"],
     ["action_", "actions"],
@@ -44,6 +45,7 @@ const TOOLSET_FOR_PREFIX = Object.freeze([
     ["video_", "videos"],
     ["job_", "runs"],
     ["run_", "runs"],
+    ["work_", "canvas"],
 ]);
 
 export function gavanaToolsetForName(name) {

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;