@gavana.ai/cli 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog — @gavana.ai/cli
 
+## 0.2.2
+
+### Changed
+
+- Image commands and MCP tools now return immediately after the durable Canvas
+  targets and Run are queued. Use `--wait` in the CLI or `wait: true` in an MCP
+  call when the completed image is required in the same interaction.
+- Distinct local image references upload concurrently while their original
+  reference order and duplicate-upload reuse remain stable.
+
+## 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
@@ -111,6 +114,7 @@ gavana action list
 gavana action get action:resize
 gavana action run action:resize --input ./product.png --destination agent-canvas --width 1080 --height 1350
 gavana image generate --destination agent-canvas --model model:OPAQUE_MODEL_KEY --prompt "A studio product photograph"
+gavana image generate --destination agent-canvas --prompt "A studio product photograph" --wait
 gavana model list --capability video.generate
 gavana video generate --model model:OPAQUE_MODEL_KEY --prompt "A slow product turntable" --duration 15 --aspect-ratio 9:16 --download ./turntable.mp4
 gavana video generate --model model:OPAQUE_MODEL_KEY --prompt "Animate the fabric naturally" --first-frame ./product.png --no-wait
@@ -176,8 +180,13 @@ text-only Recipes.
 
 Recipe, image, and Action work returns a shared `run:` handle with typed outputs,
 duration estimates, observed queue/execution timing, and stable retry guidance.
-Default waiting and `run get|wait|cancel` require `job:manage`; a start-only
-token can use `--no-wait` with a signed webhook.
+Image commands return as soon as Gavana has created the durable Canvas targets
+and queued the Run, so the caller can continue while generation proceeds. Add
+`--wait` only when the completed image is needed in the same command. `--no-wait`
+remains accepted for existing image scripts. Recipe and Action commands retain
+their existing wait-by-default behavior. Waiting and `run get|wait|cancel`
+require `job:manage`; a start-only token can queue image work directly or use
+`--no-wait` with a signed webhook.
 The legacy `job:` handle remains an image and Action compatibility alias; it is
 never used for Recipes. Image and Action `run:` and `job:` handles point to the
 same temporary record and expire together:
@@ -217,6 +226,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,20 +10,25 @@ 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.
 
 ## Paid execution
 
-Generation 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.
+Generation 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.
 
 ## Completion
 
 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/paid-action-safety.md

@@ -15,7 +15,7 @@ Start paid work only when the current user message explicitly asks to run or gen
 ## Retry boundary
 
 - Use one stable idempotency key for one intended paid operation.
-- Poll the returned handle with status tools.
+- 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.
 - Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.
 - Ask for new user intent before any new paid attempt.
 

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.2",
     "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.1";
 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. Image tools return durable queued progress by default; report it immediately and call run_wait only when the current user explicitly needs the completed asset in the same interaction. A later run_get or Canvas read can observe progress. 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) {