# Gavana Help Center > One public documentation surface for people using Gavana and agents operating its supported interfaces. ## Instructions for agents 1. Start with the page that matches the requested task, then use the linked canonical API contract for exact parameters and schemas. 2. Inspect a canvas before making a decision or write. Use only Gavana handles returned by the service; never invent a handle, model, endpoint, or scope. 3. Ask for explicit current-turn approval before saving an image or starting image, workflow, or video work. Never automatically retry potentially paid work. 4. Keep OAuth and Agent Access credentials out of messages, URLs, logs, screenshots, and repositories. Return durable handles or a review link; share only X-Request-ID with support. ## Canonical machine contracts - [Canvas API OpenAPI 3.1](https://app.gavana.ai/openapi/canvas-agent-v1.json) - [Canvas API compact reference](https://app.gavana.ai/openapi/canvas-agent-v1.md) - [Gavana API and CLI context](https://app.gavana.ai/llms-full.txt) ## Help pages - [How Sync Works in Gavana](https://help.gavana.ai/account-sync/how-sync-works/): Gavana stores canvases locally first, then syncs to your account — what that means for your data. - [Account & Sync](https://help.gavana.ai/account-sync/): How Gavana's local-first storage and account sync work together. - [Reading Your Sync Status in Gavana](https://help.gavana.ai/account-sync/sync-status/): What the sync status indicator on the Gavana Canvas Library means. - [Admin Canvas Viewer: Read-Only Review](https://help.gavana.ai/admin/admin-canvas-viewer/): How admins can open another member's canvas in read-only mode in Gavana. - [All Members: Reviewing Every User's Canvases](https://help.gavana.ai/admin/all-members/): How the Gavana admin All Members view combines profiles, canvases, and image assets — and how to read it. - [Admin](https://help.gavana.ai/admin/): Admin-only Gavana features: reviewing every member's canvases, read-only canvas review, and managing feature requests. - [How to Submit and Manage Feature Requests in Gavana](https://help.gavana.ai/admin/manage-feature-requests/): Submit a feature request from any canvas, and review requests as an admin. - [Canvas API Reference](https://help.gavana.ai/agent-access/api-reference/): Use Gavana's stable V1 Canvas API contract from a CLI, MCP client, or your own integration. - [Gavana CLI Reference](https://help.gavana.ai/agent-access/cli-reference/): Commands, exit codes, and output format for the Gavana CLI. - [Connect Gavana to ChatGPT](https://help.gavana.ai/agent-access/connect-via-chatgpt/): Connect ChatGPT to Gavana's hosted OAuth MCP to inspect canvases and make explicitly approved canvas, workflow, image, or video work. - [Connect Gavana to Claude or Codex via MCP](https://help.gavana.ai/agent-access/connect-via-mcp/): Use Gavana's local stdio MCP for advanced Claude, Codex, and developer automation. - [How to Create an Agent Access Token in Gavana](https://help.gavana.ai/agent-access/create-an-agent-access-token/): Create a scoped Agent Access token so a CLI or AI agent can work with your Gavana canvases. - [Build with Gavana](https://help.gavana.ai/agent-access/): Use Gavana with ChatGPT, Claude, Codex, a terminal, or your own integration—with one clear contract for people and agents. - [How to Install and Log In to the Gavana CLI](https://help.gavana.ai/agent-access/install-the-cli/): Install the Gavana CLI and use the smallest appropriate login for terminal automation. - [Gavana Agent Quickstart](https://help.gavana.ai/agent-access/quickstart/): Connect Gavana safely, inspect a canvas first, and make your first reversible handoff with an agent. - [Reusable Workflows and Video](https://help.gavana.ai/agent-access/workflows-and-video/): Create repeatable Gavana workflows and start image or video work with explicit approval, exact models, and resumable status checks. - [Batch Prompts or Reference Images with a List Node](https://help.gavana.ai/ai-generation/batch-with-lists/): Use a List node in Gavana to generate multiple images from a batch of prompts or reference images at once. - [How to Edit an Image with Reference Images in Gavana](https://help.gavana.ai/ai-generation/edit-an-image-with-reference-images/): Use reference images to edit an existing image node in Gavana instead of generating from scratch. - [How to Generate an Image from a Prompt in Gavana](https://help.gavana.ai/ai-generation/generate-an-image-from-a-prompt/): Generate an image on a Gavana canvas by describing what you want in the Image generation panel. - [AI Image Generation](https://help.gavana.ai/ai-generation/): Generate and edit images on a Gavana canvas: prompting, reference images, retrying failed generations, and batching with lists. - [Retry and Regenerate: Fixing a Failed Image Generation](https://help.gavana.ai/ai-generation/retry-and-regenerate/): What to do when an image generation fails or doesn't look right in Gavana. - [How to Create a Brand Manually in Gavana](https://help.gavana.ai/brand-kit/create-a-brand-manually/): Build a Gavana brand kit by hand instead of importing from a website. - [How to Import a Brand from a Website in Gavana](https://help.gavana.ai/brand-kit/import-a-brand-from-a-website/): Import a brand kit into Gavana directly from a website URL — logo, colors, and fonts are pulled in automatically. - [Brand Kit & Import](https://help.gavana.ai/brand-kit/): Import a brand from its website or build one manually, then reuse its logo, palette, and voice on the canvas. - [Using Your Brand Kit on the Canvas](https://help.gavana.ai/brand-kit/use-your-brand-on-the-canvas/): Reference of what a Gavana brand kit contains and how to pull it into your canvas work. - [How to Add a Text Node or Sticky Note in Gavana](https://help.gavana.ai/canvas-basics/add-a-text-or-sticky-node/): Add text nodes and sticky notes to a Gavana canvas from the toolbar. - [How to Add an Image Node in Gavana](https://help.gavana.ai/canvas-basics/add-an-image-node/): Add an image node to a Gavana canvas — generate one with AI, upload a file, or pull from your assets or brand kit. - [Canvas Navigation Reference](https://help.gavana.ai/canvas-basics/canvas-navigation/): How to pan, zoom, select, and resize on a Gavana canvas. - [How to Connect Nodes in Gavana](https://help.gavana.ai/canvas-basics/connect-nodes/): Draw connections between nodes on a Gavana canvas to link prompts, context, and images. - [Canvas Basics](https://help.gavana.ai/canvas-basics/): The building blocks of a Gavana canvas: text nodes, image nodes, sticky notes, connections, and navigation. - [Canvas Library Overview](https://help.gavana.ai/getting-started/canvas-library-overview/): What you can do from the Gavana Canvas Library: create, import, export, delete, and submit feature requests. - [How to Create Your First Canvas in Gavana](https://help.gavana.ai/getting-started/create-your-first-canvas/): Step-by-step guide to creating a new canvas in Gavana and saving your first nodes to it. - [Getting Started with Gavana](https://help.gavana.ai/getting-started/): New to Gavana? Start here to sign in, understand the Canvas Library, and create your first canvas. - [Gavana Quick Start](https://help.gavana.ai/getting-started/quick-start/): The shortest path from signing in to Gavana to generating your first AI image on a canvas. - [How to Export a Canvas in Gavana](https://help.gavana.ai/import-export/export-a-canvas/): Download one or more Gavana canvases as a JSON file, including referenced images. - [How to Import a Canvas in Gavana](https://help.gavana.ai/import-export/import-a-canvas/): Restore a previously exported Gavana canvas from a JSON file. - [Import & Export](https://help.gavana.ai/import-export/): Export a Gavana canvas to a JSON file with embedded assets, and import it back. - [Gavana Help Center](https://help.gavana.ai/): Welcome to the Gavana help center. Find guides on canvases, AI image generation, brand kits, import/export, and agent access. - [Fix: Images Show Up but the Canvas Is Missing](https://help.gavana.ai/troubleshooting/canvas-shows-assets-but-no-canvases/): What to do when images are visible but the expected canvas is missing from Gavana. - [Common Gavana Issues](https://help.gavana.ai/troubleshooting/common-issues/): Quick fixes for the most common problems in Gavana: sync, imports, and image generation. - [Troubleshooting](https://help.gavana.ai/troubleshooting/): Fixes for common Gavana issues: missing canvases, sync problems, and failed image generation. ## Complete help-center content ### How Sync Works in Gavana Source page: https://help.gavana.ai/account-sync/how-sync-works/ Agent-readable page contract: - Audience: people and agents - Intent: Gavana stores canvases locally first, then syncs to your account — what that means for your data. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How Sync Works Gavana stores canvas state in your browser (local storage), and layers account sync on top once you're signed in. ## The local-first model - The app can hydrate its UI from browser-local state immediately, without waiting on the network. - Sync to your account starts only after local state has hydrated and you have a valid, signed-in session. - If your account sync is temporarily unavailable, the app keeps working from local state. ## What gets synced - Canvas documents (nodes, connections, canvas appearance) - Image assets referenced by your canvases ## What can go out of sync Because storage is split — a canvas document and its image assets are stored separately — it's possible for an image asset to exist without a saved canvas document pointing to it (for example, if a save was interrupted). If you notice images that don't seem to belong to any visible canvas, see [Canvas Shows Assets But No Canvases](/troubleshooting/canvas-shows-assets-but-no-canvases). ## Related Articles - [Reading Your Sync Status](/account-sync/sync-status) - [Canvas Shows Assets But No Canvases](/troubleshooting/canvas-shows-assets-but-no-canvases) ### Account & Sync Source page: https://help.gavana.ai/account-sync/ Agent-readable page contract: - Audience: people and agents - Intent: How Gavana's local-first storage and account sync work together. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Account & Sync Gavana is local-first: your canvases live in your browser first, and sync to your account after. This section explains what that means day-to-day. - [How Sync Works](/account-sync/how-sync-works) - [Reading Your Sync Status](/account-sync/sync-status) ### Reading Your Sync Status in Gavana Source page: https://help.gavana.ai/account-sync/sync-status/ Agent-readable page contract: - Audience: people and agents - Intent: What the sync status indicator on the Gavana Canvas Library means. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Reading Your Sync Status The Canvas Library header shows a sync status indicator next to the **Gavana** title. It reflects whether your local canvas state has finished syncing to your account. ## Where to look Open the Canvas Library — the indicator sits directly beside the page title, at the top of the page. ## What it tells you - Whether your most recent local changes have synced - Whether sync is actively catching up If you're working from a fresh browser session or just signed in, give sync a moment to catch up before assuming a canvas is missing — check [How Sync Works](/account-sync/how-sync-works) for the underlying model. ## Related Articles - [How Sync Works](/account-sync/how-sync-works) - [Canvas Library Overview](/getting-started/canvas-library-overview) ### Admin Canvas Viewer: Read-Only Review Source page: https://help.gavana.ai/admin/admin-canvas-viewer/ Agent-readable page contract: - Audience: people and agents - Intent: How admins can open another member's canvas in read-only mode in Gavana. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Admin Canvas Viewer Admins can open another user's saved canvas in a read-only view — useful for support and review without touching the member's work. ## Steps ### Step 1: Find the canvas From [All Members](/admin/all-members), locate the member and canvas you want to review. ### Step 2: Open it in read-only mode Open the canvas from the admin view. It loads read-only — you can look, but not edit. ## Limits This view can open only saved canvases that remain accessible to the member. If images are visible but a saved canvas is missing, see [Canvas Shows Assets But No Canvases](/troubleshooting/canvas-shows-assets-but-no-canvases) for the recovery path. ## Related Articles - [All Members](/admin/all-members) - [Canvas Shows Assets But No Canvases](/troubleshooting/canvas-shows-assets-but-no-canvases) ### All Members: Reviewing Every User's Canvases Source page: https://help.gavana.ai/admin/all-members/ Agent-readable page contract: - Audience: people and agents - Intent: How the Gavana admin All Members view combines profiles, canvases, and image assets — and how to read it. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # All Members Admins can switch the Canvas Library to the **All Members** view to see each member’s visible canvases, images, and profile information in one place. ## Steps ### Step 1: Open the Canvas Library ### Step 2: Switch to All Members Use the segmented control in the header and choose **All Members**. ## What it combines - Member profile details available to an admin - Saved canvases and their node and connection counts - Images associated with the member’s account ## How to read it - **Canvases** means the member’s saved, accessible canvases. - **Assets** means images associated with the member’s account. - **Nodes** and **Connections** are counts from the saved canvas. ### A member can show image assets but 0 canvases This can happen after a canvas was deleted, after a device did not finish syncing, or with older incomplete work. Do not assume the member’s data was reset. See [Canvas Shows Assets But No Canvases](/troubleshooting/canvas-shows-assets-but-no-canvases) for a support-safe recovery path. ## Related Articles - [Admin Canvas Viewer](/admin/admin-canvas-viewer) - [Canvas Shows Assets But No Canvases](/troubleshooting/canvas-shows-assets-but-no-canvases) ### Admin Source page: https://help.gavana.ai/admin/ Agent-readable page contract: - Audience: people and agents - Intent: Admin-only Gavana features: reviewing every member's canvases, read-only canvas review, and managing feature requests. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Admin Admin accounts see extra views in the Canvas Library: **All Members**, **Feature Requests**, and read-only access to any member's canvas. - [All Members](/admin/all-members) - [Admin Canvas Viewer](/admin/admin-canvas-viewer) - [Manage Feature Requests](/admin/manage-feature-requests) ### How to Submit and Manage Feature Requests in Gavana Source page: https://help.gavana.ai/admin/manage-feature-requests/ Agent-readable page contract: - Audience: people and agents - Intent: Submit a feature request from any canvas, and review requests as an admin. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Manage Feature Requests Any user can submit a feature request from the Canvas Library; admins can review all of them in one place. ## Submitting a request ### Step 1: Click New request In the Canvas Library header, click **New request**. ### Step 2: Fill in the details Provide a title and details. You can optionally include the current canvas as context. ### Step 3: Submit The request is created with status **open**. ## Reviewing requests (admin) ### Step 1: Switch to Feature Requests In the Canvas Library, use the segmented control and choose **Feature Requests**. ### Step 2: Review Admin review reads across all members' requests, not just your own. ## Related Articles - [Canvas Library Overview](/getting-started/canvas-library-overview) - [All Members](/admin/all-members) ### Canvas API Reference Source page: https://help.gavana.ai/agent-access/api-reference/ Agent-readable page contract: - Audience: API builders and agents - Intent: Use the generated Canvas API contract without inventing operations or schemas. - Side effects: depends on endpoint and token scopes - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # Canvas API Reference The Canvas API is the backend contract used by the Gavana CLI and MCP adapter. Most people should use the CLI; use the raw API when you are building your own integration, client library, or automation. ## Machine-readable contract [Open the OpenAPI 3.1 document](https://app.gavana.ai/openapi/canvas-agent-v1.json) The document is the machine-readable contract for every stable V1 path, required input, common output shape, permission scope, error code, and request ID. Tools such as Postman, Bruno, Insomnia, and OpenAPI client generators can For tools that read Markdown or `llms.txt`, use the [compact Markdown reference](https://app.gavana.ai/openapi/canvas-agent-v1.md), [LLM index](https://app.gavana.ai/llms.txt), or [complete LLM context](https://app.gavana.ai/llms-full.txt). Production builds fail when these generated files drift from the OpenAPI contract. The production base URL is: ```text https://app.gavana.ai/api/canvas-agent/v1 ``` ## Authentication Create an [Agent Access Token](/agent-access/create-an-agent-access-token), then send it as a bearer token: ```http Authorization: Bearer cba_... X-Gavana-Agent-Surface: api ``` Never put a token in a URL, screenshot, log, or support message. ## Safe retries Mutations to an existing canvas require both: - `baseRevision` from the latest canvas read - an `idempotencyKey` containing 8–200 characters If somebody changes the canvas first, the API returns `409 conflict`. Read the canvas again, update `baseRevision`, and retry with a key that represents the same intended change. Creating a new canvas is a separate operation; follow its exact OpenAPI schema rather than adding these fields by assumption. ## Errors and support IDs Every response includes `X-Request-ID`. Errors also have a stable code and may identify the exact input fields to fix: ```json { "error": { "code": "input_validation_error", "message": "baseRevision is required.", "fields": [ { "field": "baseRevision", "message": "Read the canvas and pass its current revision." } ] } } ``` Share the request ID—not the token—when asking for support. ## Paginating lists Canvas, Recipe, asset, Action, model, and provider list responses keep their existing named array and also include page metadata: ```json { "canvases": [], "page": { "limit": 25, "hasMore": true, "nextCursor": "opaque-value" } } ``` Pass `limit` to choose the page size. When `hasMore` is true, send `nextCursor` back as the next request's `cursor`. The cursor is opaque and is valid only with the same endpoint and filters. Do not decode it or construct one yourself. Canvas and asset pages are newest first, with stable handles breaking ties. Owned and shared canvases are merged into the same recent-first order while each request stays bounded for large accounts. Canvas pages contain at most 25 summaries because each summary currently reads its complete graph document. ## Recipe Runs and shared Runs Recipe discovery, forking, and execution are separate. `POST /recipes/{recipeId}/fork` creates one private, editable Recipe instance and never executes it. `POST /recipes/{recipeId}/runs` is the explicit operation that binds typed inputs, materializes declared outputs, and starts sequential text or image work: ```json { "canvasId": "canvas:OWNER_UID:CANVAS_ID", "baseRevision": "LATEST_CANVAS_REVISION", "idempotencyKey": "product-direction-001", "inputs": { "product-context": "A matte black travel bottle for a quiet premium campaign" } } ``` Pass `instanceNodeId` to run an already connected private Recipe. Otherwise, Gavana creates a private instance from the requested catalog version. Each value must match a named port returned by `GET /recipes/{recipeId}`. Image ports require a durable image `node:` or `asset:` handle. Written ports accept plain text, a text/sticky `node:` handle, or an image `node:`/`asset:` handle when the Recipe asks for a reference image or written note. Terminal outputs include typed durable `node:` handles plus `asset:` handles for images. The current Recipe start route requires `image:generate` and its dependent scopes for every Recipe, including a text-only Recipe. Every Recipe, image, and Action start returns a shared `run:` handle and `pollUrl`. Use `GET /runs/{runId}` until the status is terminal, or `DELETE` that route to cancel. The older `/jobs/{jobId}` route and `job:` handle remain an image and Action compatibility alias; Recipe Runs never have a `job:` handle. Recipe Run records currently persist without the temporary image-job TTL described below. ## Deterministic Image Actions Image Actions make exact raster changes without invoking an AI model or spending AI-generation credits. `GET /actions` lists the stable catalog and `GET /actions/{actionKey}` returns each Action's ordered image inputs, typed parameters, defaults, bounds, and output contract. The first stable catalog contains: - `action:resize` - `action:crop` - `action:change-aspect-ratio` - `action:side-by-side-composite` - `action:add-text-to-image` - `action:overlay-image` - `action:color-grade` - `action:rotate` Run one with `POST /actions/{actionKey}/runs`: ```json { "canvasId": "canvas:OWNER_UID:CANVAS_ID", "baseRevision": "LATEST_CANVAS_REVISION", "idempotencyKey": "resize-product-card-001", "targetNodeId": "node:OUTPUT_IMAGE_NODE", "inputs": ["node:SOURCE_IMAGE_NODE"], "params": { "width": 1080, "height": 1350, "fit": "cover" } } ``` The raw API requires an existing empty image target; create it with a revision-safe canvas operation first. The CLI and browser do that setup automatically. Action runs require `canvas:read`, `canvas:write`, and `asset:read`, but not `image:generate`. They return the same shared `run:` state, signed webhook option, durable `asset:` result, and durable `node:` result as AI image work. That scope statement applies to the raw Action request, which accepts existing `node:` and `asset:` handles. The CLI can also upload a local file, stdin, or the macOS clipboard before starting the Action; that separate private asset upload currently requires `image:generate`. In the browser, an editor can right-click an existing image, choose **Image Actions…**, select one of the eight transformations, and receive a new result beside the untouched original. ## Discovering image models `GET /models` returns only models Gavana can run through the managed image runtime or your saved provider connections. Each entry names its exact connection, supported operations, typed parameters, allowed values, and an estimated duration: ```json { "handle": "model:opaque-key", "modelId": "gpt-image-1", "provider": "openai", "capabilities": ["image.generate", "image.edit", "image.variations"], "estimatedSeconds": 35, "parameters": [{ "name": "count", "type": "integer", "min": 1, "max": 4 }] } ``` Use the returned opaque `model:` handle with `GET /models/{modelKey}`. Do not decode or construct model keys. Image start requests may pass the same handle as `model`; Gavana resolves both the saved connection and provider model without a second lookup. Duration is an operational estimate, not a billing or delivery guarantee; Gavana does not invent credit costs for bring-your-own provider keys. ## Understanding image and Action job retention Image and Action starts return a shared `run:` handle and a legacy `job:` alias for the same temporary queue record. Both observation handles expire together; neither is permanent history. Read the Run until `status` is `succeeded`, `failed`, `canceled`, or `expired`. Every state includes an `estimatedSeconds` value from the selected model or deterministic Action catalog, plus observed timing: ```json { "id": "job:...", "run": "run:...", "kind": "image", "pollUrl": "/api/canvas-agent/v1/runs/...", "status": "failed", "estimatedSeconds": 35, "durationMs": 42118, "timing": { "queueDurationMs": 812, "executionDurationMs": 41306, "totalDurationMs": 42118 }, "failure": { "code": "provider_rate_limited", "message": "The image provider is rate limiting requests. Wait briefly, then retry.", "retryable": true, "providerStatus": 429 } } ``` A provider failure is a normal terminal job response, not an authentication error from Gavana. Use `failure.retryable` instead of guessing from the message. For potentially paid image, workflow, or video work, ask for explicit approval before retrying. Starting the same intended request with the same idempotency key replays its job; use a new key only when intentionally starting a new attempt. By default, an unacknowledged job result expires after 24 hours. After the first server finalization—either an authenticated Run GET or the worker finalization that precedes a signed callback—its temporary job record expires after 15 minutes. The `expired` tombstone remains for seven days before the handle returns `404`. Operators may override these retention windows. Fetched `asset:` and `node:` outputs remain durable; store those handles rather than treating either the image/Action `run:` or `job:` resource as permanent history. Recipe `run:` records currently do not use this temporary TTL. ## Signed completion webhooks Polling is optional. Signed webhooks require an Agent Access token. Add a caller-owned webhook to a Recipe, image, or Action start request: ```json { "webhook": { "url": "https://automation.example.com/hooks/gavana", "secret": "a-caller-owned-secret-containing-at-least-32-characters" } } ``` Gavana accepts only public HTTPS destinations, encrypts the secret at rest, never returns it, and sends one stable terminal event. Delivery is at least once: Gavana makes at most four total attempts. Retryable network failures, `408`, `425`, `429`, and `5xx` responses back off for 10 seconds, 60 seconds, then 5 minutes. Redirects and other `4xx` responses stop delivery. With `job:manage`, inspect `run.webhook` to see `pending`, `delivering`, `delivered`, or `failed` without exposing the endpoint or secret. A start-only callback token cannot query later delivery state. For a Recipe, Gavana stores a revocable one-Run worker capability and refreshes the original Agent Access delegation, so `--no-wait` execution continues independently of the starting HTTP or CLI process. If that delegation expires or is revoked before completion, the Run fails with `delegation_revoked` and Gavana sends the signed failed callback. Verify the raw request body before parsing it. The signature is the lowercase hex HMAC-SHA256 of: ```text . ``` using your secret. Compare it to the `v1` value in `Gavana-Webhook-Signature` with a constant-time comparison. Use `Gavana-Webhook-Id` plus the event `id` to ignore duplicate deliveries. The event says which Run became terminal. Recipe events include typed output statuses and durable handles. Successful Image and Action callbacks are not sent until Gavana has finalized the provider response into durable canvas, `node:`, and `asset:` results; those successful event payloads include the images, so a callback-only integration does not need an extra GET to make them durable. Actions use the same `image_job.*` event family as generated images; inspect `data.run.operation` and `data.run.actionId` to identify an Action. If a provider succeeds but Gavana cannot durably store its output after internal retries, the callback type is `image_job.finalization_failed`, `data.run.status` is `failed`, and `data.run.failure.code` is `output_finalization_failed` with `retryable: true`. If the caller also has `job:manage`, it can inspect the shared Run; otherwise, start a new intended attempt with a new idempotency key after correcting the storage or access problem. ## Stable and deprecated surfaces Canvas, Recipe, asset, Action, image, video, model, provider, Run, and job-alias endpoints are the supported V1 surface. Campaign endpoints remain in the contract only for compatibility and are marked deprecated. Campaign records remain readable, but campaign mutations return `410 Gone` by default unless a server operator explicitly enables legacy compatibility. New integrations should use explicit Recipe Runs, shared Runs, and revision-safe canvas operations instead. ## Related Articles - [Install the CLI](/agent-access/install-the-cli) - [CLI Reference](/agent-access/cli-reference) - [Connect via MCP](/agent-access/connect-via-mcp) ### Gavana CLI Reference Source page: https://help.gavana.ai/agent-access/cli-reference/ Agent-readable page contract: - Audience: CLI users and agents - Intent: Use the scriptable Gavana CLI with stable JSON output and explicit side effects. - Side effects: depends on command and token scopes - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # CLI Reference ## Running the CLI ```sh # After the current source install, or after the future npm release gavana --help ``` `gavana-canvas` is the descriptive alias. `craftboard` and `craftboard-canvas` remain backward-compatible aliases for existing scripts. See [Install the CLI](/agent-access/install-the-cli) for the current package release status. ## Output format The CLI writes one JSON result to stdout by default: ```json { "ok": true, "result": {} } ``` Errors and progress events go to stderr, so a script or AI client can parse stdout cleanly. Use `--output markdown` for a chat-ready result or `--output jsonl` for one selected array item per line. Use `--jq` to select a property path and `-r` to print strings or numbers without JSON quotes: ```sh gavana canvas list --limit 25 --jq '.canvases[].handle' -r gavana asset list --jq '.assets[]' --output jsonl ``` The built-in selector supports property paths, non-negative array indexes, and `[]` projections, such as `.canvases[0].title` or `.connections[].models[]`. It intentionally does not execute arbitrary jq programs, so it works without a separate jq installation. Errors include a stable code and, when possible, the exact fields to fix: ```json { "ok": false, "error": { "code": "input_validation_error", "message": "baseRevision is required.", "fields": [ { "field": "baseRevision", "message": "Read the canvas and pass its current revision." } ], "requestId": "7f8e0d9d-4bf8-4e6e-96e0-8bcd6a8f315a" } } ``` The `requestId` is safe to share with support. Never share an Agent Access Token. Fix validation and permission errors before retrying. A client may retry safe read requests after a temporary error such as `rate_limited`, `service_unavailable`, or `upstream_timeout`; for an image, workflow, video, or other potentially paid write, ask for explicit approval before starting a new attempt. ## Exit codes | Exit | Meaning | | ---: | ------------------------------------------- | | `0` | Success | | `2` | Usage, configuration, or validation error | | `3` | Authentication or authorization error | | `4` | Revision conflict | | `5` | Not found | | `7` | Network error | | `8` | Wait timeout — the Run can still be resumed | | `9` | Recipe, image, or Action Run ended unsuccessfully | ## Core commands ```text auth login|status|logout config list|use mcp install|config canvas list|create|agent|get|render|apply node get|create|update|move|resize|delete connection list|create|delete asset list|get|upload provider list model list|get recipe search|get|fork|run action list|get|run image generate|edit|variations video generate|download run get|wait|cancel job get|wait|cancel ``` - Destructive commands require `--yes`. - Recipe, image, and Action commands wait for durable persistence by default — pass `--no-wait` to get the shared `run:` handle immediately and resume it later with `run wait`. - Default waiting plus `run get|wait|cancel` requires the token's `job:manage` scope. A start-only token can use `--no-wait` and a signed webhook instead. - `job get|wait|cancel` remains an image and Action compatibility alias; it is never used for Recipe Runs. - Canvas, Recipe, asset, Action, model, and provider list commands accept `--limit` and the opaque `--cursor` returned as `page.nextCursor`. Keep the same filters when requesting the next page. Run results include `estimatedSeconds`, observed queue/execution timing, and a stable `failure.code` plus `failure.retryable` when generation fails. A failed provider request is returned as a terminal Run result, so `run wait` finishes without hiding the reason behind a generic request error. The complete terminal resource remains on stdout for automation, while `recipe run`, `image ...`, `action run`, and `run wait` return exit code `9` when the terminal state is `failed`, `canceled`, or `expired`. Image and Action `run:` handles and their legacy `job:` aliases address the same temporary record and expire together. By default, unacknowledged results expire after 24 hours; a successfully finalized result expires 15 minutes after its first server finalization (from a Run GET or signed callback), and the expired tombstone is deleted after seven days. Operators may override these windows. Recipe Run records currently do not use this temporary TTL. Persist the returned `asset:` and `node:` handles, which remain durable after the observation handles expire. To receive one signed callback instead of polling, keep the secret out of shell history: ```sh read -rs 'GAVANA_WEBHOOK_SECRET?Webhook signing secret: '; printf '\n' export GAVANA_WEBHOOK_SECRET gavana image generate \ --destination agent-canvas \ --prompt "A studio product photograph" \ --webhook-url "https://automation.example.com/hooks/gavana" \ --no-wait unset GAVANA_WEBHOOK_SECRET ``` Use `--webhook-secret-env MY_SECRET_VARIABLE` to read a different environment variable. The CLI sends the secret only in the authenticated Run-start body; Gavana encrypts it and Run output reports only delivery state. Recipe and Image Action starts accept the same webhook options. The always-on worker keeps an authenticated Recipe moving after the original CLI process exits. Successful Image and Action callbacks are sent only after their durable canvas, node, and asset results are stored. Failed, canceled, or expired callbacks describe the terminal state without requiring images. ## Stable handles Use handles returned by Gavana: ```text canvas:: node: connection: asset: asset:: (shared asset) recipe: action: model: run: job: ``` Use the owner-qualified handle returned by `asset list` for a shared asset. This lets Gavana read that exact asset directly without searching another user's library. Recipe and Action handles come from their catalogs. Model, Run, and job IDs are opaque results: copy their complete returned handles and do not decode, guess, or construct them. ## Recipe Runs Forking and running are deliberately separate. `recipe fork` adds a private, editable Recipe card and never executes it. `recipe run` is the explicit action that binds typed inputs, creates declared output nodes, and starts text or image work: ```sh gavana recipe run recipe:product-visual-direction \ --input product-context="A matte black travel bottle for a quiet premium campaign" \ --destination canvas:OWNER_UID:CANVAS_ID ``` Use each exact input key returned by `recipe get`. Written ports accept inline text, `@path`, a text/sticky `node:`, or an image reference when the Recipe asks for “an image or written note.” For that flexible written port, upload a local visual first and pass the returned `asset:` handle; `@path` reads the file as text. Image ports accept `node:` or `asset:` handles, local raster paths, stdin, or the macOS clipboard. All Recipe starts currently require `image:generate` and its dependent scopes, including text-only Recipes. The terminal Run returns typed outputs with durable `node:` and, for images, `asset:` handles. Use `gavana model list --capability image.edit` before choosing a model. The result tells you which saved connection can run it, the exact valid parameters, and its estimated duration. Then inspect one entry with `gavana model get model:` and pass the same handle to an image command with `--model model:`. ## Deterministic Image Actions Image Actions make precise raster changes without asking an AI model and without spending AI credits. The first stable set is resize, crop, change aspect ratio, side-by-side composite, add text, overlay image, color grade, and rotate. Inspect the catalog before running an Action: ```sh gavana action list gavana action get action:resize gavana action run action:resize \ --input ./product.png \ --destination agent-canvas \ --width 1080 \ --height 1350 ``` For two-input Actions, repeat `--input` in the order shown by `action get`: ```sh gavana action run action:side-by-side-composite \ --input node:FIRST_IMAGE \ --input asset:SECOND_IMAGE \ --destination canvas:OWNER_UID:CANVAS_ID \ --direction horizontal \ --gap 24 ``` Inputs may be `node:` or `asset:` handles, a local PNG/JPEG/WebP/GIF path, stdin (`-`), or `clipboard` on macOS. The CLI privately uploads local inputs, creates one output node when `--target` is omitted, waits for durable asset and node handles by default, and returns exit code `9` for a failed terminal Run. Use repeatable `--param NAME=VALUE` for schema fields that do not have a dedicated flag. Existing handles need only the Action scopes; local, stdin, and clipboard inputs additionally require `image:generate` for the private upload. ## Video generation Video generation is an explicit potentially paid action. Discover the exact connected model and capability before starting; do not guess a `model:` handle or retry a failed paid request automatically. ```sh gavana model list --capability video.generate gavana model get model:OPAQUE_MODEL_KEY gavana video generate \ --model model:OPAQUE_MODEL_KEY \ --prompt "A slow product turntable" \ --duration 15 \ --aspect-ratio 9:16 \ --download ./turntable.mp4 ``` For image-to-video, use `--first-frame` with a durable `node:`/`asset:` handle, public HTTPS URL, local image, stdin, or the macOS clipboard. A last frame requires a first frame. Add `--no-wait` to return the `job:` handle immediately, then use `job get`, `job wait`, `job cancel`, or `video download job:JOB_ID --file ./result.mp4`. Generation requires `canvas:read`, `asset:read`, and `video:generate`; waiting, downloading, and cancellation also need `job:manage`. ## Concurrency An operation that changes an existing canvas takes its latest `baseRevision` (from a prior read) and an `idempotencyKey`, so retries are safe and concurrent browser and agent edits do not clobber each other. Creating a new canvas or resolving the persistent Agent Canvas is a separate operation; use the exact contract for that command. ## Related Articles - [Install the CLI](/agent-access/install-the-cli) - [Create an Agent Access Token](/agent-access/create-an-agent-access-token) - [Canvas API Reference](/agent-access/api-reference) ### Connect Gavana to ChatGPT Source page: https://help.gavana.ai/agent-access/connect-via-chatgpt/ Agent-readable page contract: - Audience: ChatGPT users and agents - Intent: Use the hosted OAuth MCP; begin read-only when inspection is enough. - Side effects: the normal endpoint can write canvas state and start provider-backed work - Source of truth: https://app.gavana.ai/mcp - Last verified: 2026-08-03 # Connect Gavana to ChatGPT Gavana provides a hosted MCP endpoint with browser OAuth. It keeps the normal visual workflow visible: an agent can inspect a canvas, hand you a verified review link, and return durable Gavana handles after you approve a change. Start with the strict read-only endpoint when you want an agent to review rather than create: ```text https://app.gavana.ai/mcp/readonly ``` Use the normal endpoint when you intend to save work or explicitly run generation: ```text https://app.gavana.ai/mcp ``` ## Connect 1. In an MCP-capable ChatGPT workspace, open the custom connector setup. Your workspace may require an administrator to allow custom connectors. 2. Add one Gavana endpoint: ```text https://app.gavana.ai/mcp/readonly ``` 3. Choose **Connect**. Gavana opens a sign-in and consent screen. 4. Review the requested permissions, then approve the connection. The read-only endpoint asks only for canvas inspection. The normal endpoint requests broad canvas, asset, image, video, and job permissions by default, so use it only when you intend to create work. ChatGPT returns to the plugin after the OAuth authorization-code flow completes. You never paste an Agent Access token into ChatGPT. OAuth uses PKCE and an exact callback binding. ## Available tools | Tool | What it does | Side effect | | --- | --- | --- | | `canvas_list`, `canvas_get`, `get_canvas_image`, `open_canvas` | Find, inspect, preview, or open an accessible canvas | Read only | | `save_image_to_canvas` | Save a ChatGPT or public HTTPS image as a durable image node | Writes canvas state | | `create_canvas_workflow` | Save a private reusable workflow card | Writes canvas state; never generates | | `run_canvas_workflow`, `get_canvas_workflow_run` | Explicitly run or check a workflow | A run may incur provider cost | | `generate_image_in_canvas` | Generate an image into a canvas | May incur provider cost | | `find_video_models`, `generate_video`, `get_video_job` | Discover a model, explicitly start video, or check it | Video may incur provider cost | The read-only endpoint exposes only the first row. The normal endpoint exposes the complete hosted catalog above. The persistent **Agent Canvas** is the default destination when no specific canvas is selected. Every save or generation call uses a caller-stable idempotency key, so retrying the exact same intended request does not create duplicate work. A workflow is deliberately two steps: `create_canvas_workflow` saves it; `run_canvas_workflow` is the separate explicit execution step. ## What to ask ```text List my Gavana canvases, inspect the most relevant one for this brief, and open it for review. Do not change anything. ``` ```text Save this image to my Agent Canvas, then create a reusable workflow with the saved image as a fixed default. Do not run it yet. ``` ```text I approve one video generation. Find a connected model with image-to-video support, use this saved Gavana image as the first frame, and return the job status and review link. ``` The agent should inspect first, use exact returned handles, ask before a provider-backed run, and never automatically retry a failed paid request. ## Disconnect Disconnect the connector in ChatGPT to stop new use from that client. You can also revoke the Gavana OAuth delegation for that client from Gavana’s Agent Access settings. Revocation takes effect on the next request. ## Security notes - The hosted endpoint accepts OAuth bearer tokens only; do not use Agent Access tokens here. - The normal endpoint is `https://app.gavana.ai/mcp`; the safer inspection endpoint is `https://app.gavana.ai/mcp/readonly`. - Image imports accept public HTTPS URLs and reject private or local network destinations. - Image, workflow, and video runs can consume credits or incur charges with the provider you connected to Gavana. They require explicit approval in the current conversation. ## Related articles - [Connect Claude or Codex via local MCP](/agent-access/connect-via-mcp) - [Create an Agent Access token](/agent-access/create-an-agent-access-token) - [Reusable workflows and video](/agent-access/workflows-and-video) ### Connect Gavana to Claude or Codex via MCP Source page: https://help.gavana.ai/agent-access/connect-via-mcp/ Agent-readable page contract: - Audience: local MCP users and agents - Intent: Connect a local MCP client with the smallest necessary tool surface. - Side effects: depends on token scopes and registered local tools - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # Connect via MCP Gavana’s local stdio MCP lets MCP-capable clients such as Claude, Codex, or Hermes use the broader Canvas API contract directly from a conversation. It is intended for advanced automation; for ChatGPT or a remote OAuth-capable client, start with the smaller [hosted MCP](/agent-access/connect-via-chatgpt) instead. ## Prerequisites - An [Agent Access token](/agent-access/create-an-agent-access-token) with the scopes needed by the tools you will enable, or an existing local [CLI login](/agent-access/install-the-cli). - Node.js 20 or newer ## Steps ### Step 1: Configure the Agent Access token ```text GAVANA_BASE_URL=https://app.gavana.ai GAVANA_AGENT_TOKEN= ``` Store the token in the MCP client's private environment or secret store. Never put a literal token in a shared configuration, repository, or chat message. Existing `CRAFTBOARD_BASE_URL` and `CRAFTBOARD_AGENT_TOKEN` variables continue to work as compatibility aliases. ### Step 2: Register the MCP server with your client Register this local stdio command using the client’s MCP configuration: ```sh npx -y @gavana/mcp@0.1.0 ``` The repository contains the package release candidate, but this help center does not treat npm publication as verified. If `npx` cannot resolve it, use the checked-out source command only when you have repository access: ```sh bun run canvas:mcp ``` Use `gavana mcp install codex --read-only` when you want the CLI to register the hosted strict read-only endpoint for Codex instead of configuring a local server. ### Step 3: Work with your canvas from the conversation Once connected, the agent can list canvases, read and change nodes, discover and explicitly run Recipes, run deterministic Image Actions, queue image or video work, and return durable results—subject to its token scopes and local tool configuration. `recipe_fork` only adds a private editable workflow; `recipe_run` is the separate tool that executes it. Use `run_get`, `run_wait`, and `run_cancel` for Recipe, image, or Action work. The older `job_*` tools remain image and Action compatibility aliases; they are never used for Recipe Runs. Action runs do not spend AI credits. The `run_get`, `run_wait`, and `run_cancel` tools require `job:manage`; include that scope on the Agent Access token for the normal wait-for-result flow. ## Reference The token's name (set when you [created it](/agent-access/create-an-agent-access-token)) is written into node and activity provenance, so canvas review can tell apart callers like `Codex · CLI`, `Claude · MCP`, and `Hermes · MCP` without trusting a caller-supplied label. ## Notes - ChatGPT uses Gavana’s separate hosted OAuth MCP endpoint. See [Connect Gavana to ChatGPT](/agent-access/connect-via-chatgpt). - The package and preferred environment variables already use Gavana. The API domain, saved CLI configuration path, and `cba_` token prefix remain stable until the full application cutover. - The canvas UI remains available for visual review at any time; using MCP doesn't require opening it. - Recipe, image, and Action webhooks are intentionally API/CLI-only. Webhook signing secrets are omitted from MCP tool arguments so they cannot enter model-visible conversation or tool logs. Use the CLI's `--webhook-secret-env` option or call the API from a trusted backend when you need callbacks. ## Related Articles - [Install the CLI](/agent-access/install-the-cli) - [CLI Reference](/agent-access/cli-reference) - [Gavana Agent Quickstart](/agent-access/quickstart) ### How to Create an Agent Access Token in Gavana Source page: https://help.gavana.ai/agent-access/create-an-agent-access-token/ Agent-readable page contract: - Audience: automation owners and agents - Intent: Create a least-privilege, revocable token for local CLI, MCP, or API use. - Side effects: creates a credential - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # How to Create an Agent Access Token An Agent Access token lets a client authenticate to Gavana without your browser session. Tokens are scoped, named, and revocable. ## Steps ### Step 1: Sign in to Gavana ### Step 2: Open Agent Access Open the account menu and choose **Agent Access**. ### Step 3: Create a token Give the token a descriptive name (for example, `Codex · CLI` or `Claude · MCP`) — this name shows up in node and activity provenance so you can tell which client made a given change. ### Step 4: Choose scopes Select only the permissions the client needs: | Scope | Grants | |---|---| | `canvas:read` | Read canvas graphs | | `canvas:write` | Change canvases (requires `canvas:read`) | | `asset:read` | Read asset references | | `image:generate` | Generate/edit images, upload local raster inputs, and start any Recipe, including text-only Recipes (requires `canvas:read`, `canvas:write`, `asset:read`) | | `video:generate` | Discover connected video models and start video work (requires `canvas:read` and `asset:read`) | | `job:manage` | Observe, resume, wait for, and cancel shared Runs; required for default CLI/MCP waiting | The token form selects dependent scopes automatically — for example, choosing `image:generate` also enables the three scopes it depends on. For normal CLI or MCP execution, also select `job:manage`; without it the client can start work with `--no-wait` but cannot poll, wait for, or cancel the returned Run. A trusted API or CLI backend may instead provide a signed webhook; Gavana's worker then keeps the Recipe moving independently while the original Agent Access token remains revocable. If that token expires or is revoked before completion, Gavana stops the Recipe with `delegation_revoked` and sends its signed failed callback. MCP intentionally omits webhook secrets from model-visible tool arguments. ### Step 5: Set an expiry Tokens expire after 1–90 days. Choose the shortest expiry that's practical. ### Step 6: Copy the token Copy the token immediately — Gavana never shows it again after this screen. ## Tips - Use a separate, descriptively named token per client rather than sharing one token across tools. - You can revoke a token at any time from the Agent Access screen. ## Related Articles - [Install the CLI](/agent-access/install-the-cli) - [Connect via MCP](/agent-access/connect-via-mcp) ### Build with Gavana Source page: https://help.gavana.ai/agent-access/ Agent-readable page contract: - Audience: people, agents, and integration builders - Intent: Choose a safe Gavana connection and understand the side effects before acting. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # Build with Gavana Gavana works as a visual workspace for people and as a precise canvas contract for agents. Use the path that matches what you want to do; every path returns real canvas handles and review links, so you can always check the result on the board. ## Choose a path | You want to… | Best path | Authentication | What it can do | | --- | --- | --- | --- | | Work with Gavana from ChatGPT or a remote MCP client | [Hosted MCP](/agent-access/connect-via-chatgpt) | Browser OAuth | Inspect, save images, create/run workflows, generate image or video work after explicit approval | | Let Codex or Claude work locally | [Local MCP](/agent-access/connect-via-mcp) | Agent Access token or local CLI profile | Broad canvas, asset, Recipe, Image Action, image, video, and Run tools | | Automate from a terminal | [CLI](/agent-access/install-the-cli) | Browser OAuth or Agent Access token | Scriptable JSON output and the same stable Canvas API operations | | Build your own service | [Canvas API](/agent-access/api-reference) | Agent Access token | Stable OpenAPI contract, revision-safe writes, callbacks, and durable handles | For inspection only, use the hosted read-only endpoint: `https://app.gavana.ai/mcp/readonly`. It exposes only read operations and cannot save, generate, cancel, or alter a canvas. ## A safe operating contract This is the same guidance for a person using an agent and for an agent reading this page: 1. **Inspect before deciding.** List canvases, read the exact canvas, then use returned `canvas:`, `node:`, and `asset:` handles—never guessed IDs. 2. **Ask before side effects.** Saving an image writes a durable node. Workflow, image, and video generation can use a connected provider and incur cost. Never start or automatically retry paid work without explicit current-turn approval. 3. **Keep writes safe.** Reuse a caller-stable 8–200 character idempotency key for the same intended request. For raw canvas writes, read the latest `baseRevision` first. 4. **Finish the handoff.** Poll the matching Run or video status tool while work is queued or running, then return the durable node, asset, job/run handle, or review link. 5. **Protect credentials.** Keep OAuth and Agent Access tokens out of chat, URLs, screenshots, repositories, and logs. Share `X-Request-ID` with support instead. ## Start here - [60-second safe quickstart](/agent-access/quickstart) - [Create an Agent Access Token](/agent-access/create-an-agent-access-token) - [Install the CLI](/agent-access/install-the-cli) - [CLI Reference](/agent-access/cli-reference) - [Canvas API Reference](/agent-access/api-reference) - [Connect via MCP](/agent-access/connect-via-mcp) - [Connect Gavana to ChatGPT](/agent-access/connect-via-chatgpt) - [Reusable workflows and video](/agent-access/workflows-and-video) ## Machine-readable references This help center publishes an [LLM index](/llms.txt) and [complete help-center context](/llms-full.txt) alongside its normal pages. For exact API operations and schemas, use Gavana’s generated [OpenAPI 3.1 document](https://app.gavana.ai/openapi/canvas-agent-v1.json) rather than inferring an endpoint or parameter. ### How to Install and Log In to the Gavana CLI Source page: https://help.gavana.ai/agent-access/install-the-cli/ Agent-readable page contract: - Audience: CLI users and agents - Intent: Authenticate a local CLI without exposing credentials. - Side effects: creates a private local CLI profile - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # How to Install and Log In to the Gavana CLI ## Prerequisites - Node.js 20 or newer For interactive use, the CLI can use browser OAuth. For unattended automation, create a least-privilege [Agent Access token](/agent-access/create-an-agent-access-token). ## Steps ### Step 1: Install the CLI The repository contains the CLI package, but this help center does not treat npm publication as verified. If the public package is unavailable, use the source install only when you have repository access: ```sh git clone https://gitlab.com/avada/gavana.ai.git cd gavana.ai npm install npm run canvas:cli:install command -v gavana gavana --help ``` The older `craftboard` and `craftboard-canvas` commands remain available as compatibility aliases. When `@gavana/cli` is publicly available, the install is: ```sh npm install --global @gavana/cli ``` ### Step 2: Choose a login For the smallest interactive browser-authorized profile, use the CLI’s OAuth login and choose read-only when you only need inspection: ```sh gavana auth login --read-only ``` For a non-interactive integration, use a scoped Agent Access token without putting it in shell history or process arguments: ### Step 3: Log in with an Agent Access token Use the command for your shell. Each version prompts without storing the token in shell history or exposing it in the process arguments. #### zsh (the default shell on current macOS) ```sh read -rs 'GAVANA_AGENT_TOKEN?Paste Agent Access token: '; printf '\n'; printf '%s' "$GAVANA_AGENT_TOKEN" | gavana auth login --base-url 'https://app.gavana.ai' --token-stdin; unset GAVANA_AGENT_TOKEN ``` #### Bash ```bash read -rsp 'Paste Agent Access token: ' GAVANA_AGENT_TOKEN; printf '\n'; printf '%s' "$GAVANA_AGENT_TOKEN" | gavana auth login --base-url 'https://app.gavana.ai' --token-stdin; unset GAVANA_AGENT_TOKEN ``` #### PowerShell ```powershell $secureToken = Read-Host 'Paste Agent Access token' -AsSecureString $token = [System.Net.NetworkCredential]::new('', $secureToken).Password $token | gavana auth login --base-url 'https://app.gavana.ai' --token-stdin Remove-Variable token, secureToken ``` Paste the token when prompted, then press Return. For local development, use `--base-url http://localhost:3000` instead. ### Step 4: Verify ```sh gavana auth status ``` ## Reference - The CLI keeps its local profile private; do not copy it into a repository, chat, or support request. - Environment variables override saved config: `GAVANA_BASE_URL`, `GAVANA_AGENT_TOKEN`. - Existing `~/.config/craftboard/agent.json`, `CRAFTBOARD_*` variables, and `craftboard` commands remain supported during the transition. - HTTPS is required for remote origins. Plain HTTP is only accepted for `localhost`, `127.0.0.1`, or `::1`. ## Tips - Never paste a literal `cba_…` token directly into a shell command — use the stdin prompt above so it never lands in your shell history. - Use a distinct token per machine or client so you can revoke access individually. - Installing the CLI does not install the local MCP adapter. Follow the separate [MCP setup guide](/agent-access/connect-via-mcp) when you need it. - Use `gavana doctor` when the local profile, connectivity, or installed capabilities need a diagnosis. ## Related Articles - [Create an Agent Access Token](/agent-access/create-an-agent-access-token) - [CLI Reference](/agent-access/cli-reference) ### Gavana Agent Quickstart Source page: https://help.gavana.ai/agent-access/quickstart/ Agent-readable page contract: - Audience: people and agents - Intent: Inspect an accessible canvas without creating, generating, or paying for work. - Side effects: read only - Source of truth: https://app.gavana.ai/mcp/readonly - Last verified: 2026-08-03 # Gavana Agent Quickstart Use this path when you want an agent to understand a Gavana canvas before either of you changes it. It is deliberately read-only: the agent can list, read, preview, and open canvases, but cannot write, generate, cancel, or spend provider credits. ## 1. Connect the read-only MCP Use this endpoint in an OAuth-capable remote MCP client: ```text https://app.gavana.ai/mcp/readonly ``` Complete the browser sign-in and consent screen. You do not paste an Agent Access token into this connection. For a local Codex profile, the CLI can install the same safe endpoint: ```sh gavana mcp install codex --read-only ``` ## 2. Give the agent a bounded task Paste a request like this—replace the bracketed text with your goal: ```text Connect to Gavana in read-only mode. List my canvases, inspect the one most relevant to [goal], and summarize its nodes, connections, current revision, and the safest next step. Do not make changes or start generation. ``` The expected operation order is: ```text canvas_list → canvas_get → optionally get_canvas_image or open_canvas ``` The agent should use the exact handles returned by Gavana, not titles or reconstructed IDs. `open_canvas` gives you a verified link for visual review. ## 3. Decide whether to continue If you only need a review, you are done. To create durable work, reconnect with the normal hosted endpoint, a local MCP, the CLI, or the raw API. Say what may happen next—for example, “save this image to my Agent Canvas” or “run this workflow once.” > **Agent rule:** Read before a write. Ask for approval before any provider-backed image, workflow, or video generation. Do not retry a failed paid request automatically. ## What comes back Read operations return structured canvas data and stable handles such as `canvas:`, `node:`, and `asset:`. These are safe references to use in the next Gavana operation. Temporary image previews are for review; the durable asset or node handle is the record to keep. ## Next steps - [Connect Gavana to ChatGPT](/agent-access/connect-via-chatgpt) - [Connect via local MCP](/agent-access/connect-via-mcp) - [Reusable workflows and video](/agent-access/workflows-and-video) ### Reusable Workflows and Video Source page: https://help.gavana.ai/agent-access/workflows-and-video/ Agent-readable page contract: - Audience: people and agents - Intent: Create reusable canvas workflows or approved image/video work without ambiguous side effects. - Side effects: workflow creation writes; image, workflow, and video runs may incur provider cost - Source of truth: https://app.gavana.ai/openapi/canvas-agent-v1.json - Last verified: 2026-08-03 # Reusable Workflows and Video Gavana separates saving a reusable workflow from running it. That makes a workflow safe to review and reuse before it asks a connected provider to generate anything. ## Reusable canvas workflows ### Create is not run `create_canvas_workflow` saves a private workflow card on a selected canvas. It can declare typed text, sticky-note, or image inputs; its outputs describe text or image work. Creating it changes the canvas but **never starts generation**. For a fixed visual reference, first use `save_image_to_canvas`, then use its returned image node as an input default. Later runs can supply only the inputs that change. ```text save_image_to_canvas (fixed reference) → create_canvas_workflow (inputs + outputs + optional fixed default) → review the workflow card on the canvas ``` ### Run only with approval `run_canvas_workflow` explicitly starts a saved workflow. It may use your connected image provider and can incur cost. Supply the exact returned `workflowNodeId`, a caller-stable `idempotencyKey`, and only the inputs you want to replace. Use `get_canvas_workflow_run` while its `run:` handle is queued or running. ```text run_canvas_workflow (exact workflowNodeId, changed inputs, idempotencyKey) → get_canvas_workflow_run (runId) until terminal → return the durable node/asset handles and review link ``` ## Image generation `generate_image_in_canvas` creates a destination node and briefly waits for the connected image provider. It writes durable canvas work and may incur provider cost. Ask first; do not retry a failed paid request unless the user explicitly requests another attempt. For precise non-AI transformations in the local MCP or CLI, use the deterministic Image Actions instead. Resize, crop, aspect-ratio change, composite, text overlay, overlay image, color grade, and rotate do not spend AI-generation credits. See the [CLI reference](/agent-access/cli-reference) and [Canvas API reference](/agent-access/api-reference) for their exact schemas. ## Video generation Video is always an explicit, potentially paid action. Before generating, discover the exact connected model and capability; never make up a `model:` handle. ```text find_video_models (requested model/provider + required capability) → generate_video (exact returned model handle + prompt + idempotencyKey) → get_video_job (jobId) until terminal ``` To use a ChatGPT-made image as the first frame, save it to Gavana first and pass the returned `node:` handle as `firstFrame`. Use `video.generate.fromImage` when you need that capability. A last frame requires a first frame; references must be unique. ## Agent checklist - Inspect the destination canvas first and retain the returned handles. - State whether the next action writes only, generates through a provider, or is a deterministic Image Action. - Ask for current-turn confirmation before an image, workflow, or video run. - Reuse an idempotency key only for the identical intended request. - Poll only the matching run or job tool, then hand back durable output handles and a review link. - Never expose OAuth tokens, Agent Access tokens, provider configuration, or scoped preview URLs. ## Related articles - [Gavana Agent Quickstart](/agent-access/quickstart) - [Connect Gavana to ChatGPT](/agent-access/connect-via-chatgpt) - [Canvas API Reference](/agent-access/api-reference) ### Batch Prompts or Reference Images with a List Node Source page: https://help.gavana.ai/ai-generation/batch-with-lists/ Agent-readable page contract: - Audience: people and agents - Intent: Use a List node in Gavana to generate multiple images from a batch of prompts or reference images at once. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Batch with Lists A **List** node lets you queue multiple prompts, or multiple reference images, and generate them as a batch instead of one image node at a time. ## When to use it - You have several prompt variations you want to generate at once - You have several reference images you want to run the same edit against ## Steps ### Step 1: Add a List node Open the add menu and choose **List** — described as "Batch prompts or reference images." ### Step 2: Add items Add prompt options or reference images to the list, depending on the list type. ### Step 3: Select and generate Select the items you want to run. A generated batch shows its results as **Generated results**. ### Step 4: Retry failures If some items in the batch fail, select them and use **Retry selected** rather than rerunning the whole batch. ## Tips - Lists are useful for exploring several directions from one base prompt before committing to one. - You can create a focused batch from just the selected prompt options or reference images in a list. ## Related Articles - [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt) - [Retry and Regenerate](/ai-generation/retry-and-regenerate) ### How to Edit an Image with Reference Images in Gavana Source page: https://help.gavana.ai/ai-generation/edit-an-image-with-reference-images/ Agent-readable page contract: - Audience: people and agents - Intent: Use reference images to edit an existing image node in Gavana instead of generating from scratch. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Edit an Image with Reference Images Instead of generating a brand-new image, you can edit an existing one — Gavana uses the current image plus any reference images as input. ## Prerequisites - An image node that already has an image on it ## Steps ### Step 1: Select the image node Click the image node you want to edit. Its panel switches to editing mode for a populated node. ### Step 2: Describe the edit Type into the edit prompt field. The placeholder reads **"Describe how you want to edit this image"**. ### Step 3: Add reference images (optional) Attach one or more reference images to guide the edit — for example, a style reference or a product shot. These appear as **Reference images** (or **Shared reference images** when reused across a batch). ### Step 4: Generate the edit Click **Generate** to run the edit. The current image and any reference images are used as input. ## Tips - Reference images are separate from the node's own output — you can swap them out without losing your generated result. - Use **Assets** from the add menu to reuse an image already on the canvas as a reference. ## Related Articles - [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt) - [Batch with Lists](/ai-generation/batch-with-lists) ### How to Generate an Image from a Prompt in Gavana Source page: https://help.gavana.ai/ai-generation/generate-an-image-from-a-prompt/ Agent-readable page contract: - Audience: people and agents - Intent: Generate an image on a Gavana canvas by describing what you want in the Image generation panel. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Generate an Image from a Prompt Every image node has an **Image generation** panel for describing what you want and running the generation. ## Prerequisites - An open canvas with an image node added (see [Add an Image Node](/canvas-basics/add-an-image-node)) ## Steps ### Step 1: Open the Image generation panel Select or add an image node. Its **Image generation** panel opens with a prompt field. ### Step 2: Describe what you want Type your prompt into the field. Empty image nodes show the placeholder **"Describe what you want to create..."**. ### Step 3: Click Generate Click **Generate**. The button becomes **Stop** while generation is running, in case you want to cancel. ### Step 4: Review the result When generation finishes, the image appears on the node. If you want a different result, use **Regenerate** to run the same prompt again. ## Tips - Under **Prompt options**, you can adjust generation settings before running. - Connect a text node to an image node to feed extra context into the prompt. - If generation fails, the node stays in place — retry it instead of starting over (see [Retry and Regenerate](/ai-generation/retry-and-regenerate)). ## Related Articles - [Edit an Image with Reference Images](/ai-generation/edit-an-image-with-reference-images) - [Retry and Regenerate](/ai-generation/retry-and-regenerate) - [Add an Image Node](/canvas-basics/add-an-image-node) ### AI Image Generation Source page: https://help.gavana.ai/ai-generation/ Agent-readable page contract: - Audience: people and agents - Intent: Generate and edit images on a Gavana canvas: prompting, reference images, retrying failed generations, and batching with lists. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # AI Image Generation Image nodes are where Gavana generates and edits images with AI, right on the canvas. - [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt) - [Edit an Image with Reference Images](/ai-generation/edit-an-image-with-reference-images) - [Retry and Regenerate](/ai-generation/retry-and-regenerate) - [Batch with Lists](/ai-generation/batch-with-lists) ### Retry and Regenerate: Fixing a Failed Image Generation Source page: https://help.gavana.ai/ai-generation/retry-and-regenerate/ Agent-readable page contract: - Audience: people and agents - Intent: What to do when an image generation fails or doesn't look right in Gavana. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Retry and Regenerate Image generation can fail — a bad connection, a provider error, or a prompt that needs adjusting. Gavana keeps the node in place so you can retry without losing your setup. ## Symptom An image node shows a failed or errored state instead of a result, or the result isn't what you wanted. ## Fixes ### If generation failed Use the node's retry control to run the same generation again. In a batch (a **List** node), you can select specific failed items and use **Retry selected** to retry only those. ### If the result isn't right Use **Regenerate** to run the same prompt again, or edit the prompt first and generate again. Adding a reference image can also steer the result closer to what you want — see [Edit an Image with Reference Images](/ai-generation/edit-an-image-with-reference-images). ### If generation is stuck Click **Stop** on a running generation to cancel it, then retry. ## Tips - A failed node doesn't lose your prompt or reference images — they're still there when you retry. - If retries keep failing, check your connection and try again in a moment before assuming it's a prompt issue. ## Related Articles - [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt) - [Batch with Lists](/ai-generation/batch-with-lists) ### How to Create a Brand Manually in Gavana Source page: https://help.gavana.ai/brand-kit/create-a-brand-manually/ Agent-readable page contract: - Audience: people and agents - Intent: Build a Gavana brand kit by hand instead of importing from a website. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Create a Brand Manually If you don't have a website to import from, you can start a brand kit from scratch. ## Steps ### Step 1: Open the Brand panel From the canvas add menu, choose **Brand**. ### Step 2: Choose Create a brand manually Enter a **Brand name** (for example, "SaltySocks") to start a new, empty brand kit. ### Step 3: Fill in the sections Fill in as much or as little as you want across **Logo**, **Typography**, **Identity**, **Palette**, **Voice**, **Brand direction**, and **Product heroes**. For **Voice**, describe tone in a sentence or two — the placeholder example is "Playful, beachy and direct. Use short sentences...". ## Tips - You don't need to complete every section before using the brand kit — partially filled kits show as **"Ready to shape."** - You can add a **Website** later even after creating a brand manually. ## Related Articles - [Import a Brand from a Website](/brand-kit/import-a-brand-from-a-website) - [Use Your Brand on the Canvas](/brand-kit/use-your-brand-on-the-canvas) ### How to Import a Brand from a Website in Gavana Source page: https://help.gavana.ai/brand-kit/import-a-brand-from-a-website/ Agent-readable page contract: - Audience: people and agents - Intent: Import a brand kit into Gavana directly from a website URL — logo, colors, and fonts are pulled in automatically. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Import a Brand from a Website Gavana can build a brand kit for you by reading a website — no manual setup required for the basics. ## Steps ### Step 1: Open the Brand panel From the canvas add menu, choose **Brand** — "Your brand's source of truth." ### Step 2: Choose Import a brand from its website Select the import option and enter the **Website URL** (for example, `https://yourbrand.com`). ### Step 3: Run the import Submit the form. Gavana fetches the site and populates a draft brand kit — logo, palette, typography, and identity — from what it finds. ### Step 4: Review and adjust Review each section — **Logo**, **Typography**, **Identity**, **Palette**, **Voice**, **Brand direction**, **Product heroes** — and edit anything that needs correcting. A brand kit still being filled in shows as **"Ready to shape."** ## Tips - If the import fails, you'll see an **"Import failed"** message — try the URL again or fall back to [creating the brand manually](/brand-kit/create-a-brand-manually). - A brand created only in your browser (not yet synced) is marked **Local only**. ## Related Articles - [Create a Brand Manually](/brand-kit/create-a-brand-manually) - [Use Your Brand on the Canvas](/brand-kit/use-your-brand-on-the-canvas) ### Brand Kit & Import Source page: https://help.gavana.ai/brand-kit/ Agent-readable page contract: - Audience: people and agents - Intent: Import a brand from its website or build one manually, then reuse its logo, palette, and voice on the canvas. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Brand Kit & Import A brand kit is your brand's source of truth inside Gavana — logo, typography, identity, palette, voice, brand direction, and product heroes — that you can pull from while building on the canvas. - [Import a Brand from a Website](/brand-kit/import-a-brand-from-a-website) - [Create a Brand Manually](/brand-kit/create-a-brand-manually) - [Use Your Brand on the Canvas](/brand-kit/use-your-brand-on-the-canvas) ### Using Your Brand Kit on the Canvas Source page: https://help.gavana.ai/brand-kit/use-your-brand-on-the-canvas/ Agent-readable page contract: - Audience: people and agents - Intent: Reference of what a Gavana brand kit contains and how to pull it into your canvas work. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Use Your Brand on the Canvas Once a brand kit exists, it becomes reusable material for anything you build on the canvas. ## What a brand kit contains | Section | What it holds | |---|---| | **Logo** | Your brand's logo asset(s) | | **Typography** | Fonts used by the brand (e.g. "Inter, DM Serif Display") | | **Identity** | Brand name and source website | | **Palette** | Brand colors | | **Voice** | A short description of tone (e.g. "Playful, beachy and direct.") | | **Brand direction** | Style keywords and category (e.g. "playful, beachy, colorful") | | **Product heroes** | Key product images associated with the brand | ## Using it on a canvas Open the add menu on any canvas and choose **Brand** to pull an asset — like a logo or product hero — directly onto the board as an image node. ## Related Articles - [Import a Brand from a Website](/brand-kit/import-a-brand-from-a-website) - [Create a Brand Manually](/brand-kit/create-a-brand-manually) - [Add an Image Node](/canvas-basics/add-an-image-node) ### How to Add a Text Node or Sticky Note in Gavana Source page: https://help.gavana.ai/canvas-basics/add-a-text-or-sticky-node/ Agent-readable page contract: - Audience: people and agents - Intent: Add text nodes and sticky notes to a Gavana canvas from the toolbar. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Add a Text Node or Sticky Note Text nodes and sticky notes hold writing on your canvas — prompts, notes, or context for the nodes around them. ## Steps ### Step 1: Open a canvas Open any canvas from the Canvas Library, or [create a new one](/getting-started/create-your-first-canvas). ### Step 2: Open the toolbar The toolbar sits at the bottom of the canvas. ### Step 3: Click Text or Sticky Note Click **Text** to add a plain text node, or **Sticky Note** to add a colored note. Both appear on the canvas ready to edit. ### Step 4: Edit the content Click into the node and type. Click outside the node to finish editing. ## Tips - Use **Section** from the same toolbar to group related nodes inside a labeled frame. - Text nodes can be referenced by nearby image nodes as prompt context. ## Related Articles - [Add an Image Node](/canvas-basics/add-an-image-node) - [Connect Nodes](/canvas-basics/connect-nodes) ### How to Add an Image Node in Gavana Source page: https://help.gavana.ai/canvas-basics/add-an-image-node/ Agent-readable page contract: - Audience: people and agents - Intent: Add an image node to a Gavana canvas — generate one with AI, upload a file, or pull from your assets or brand kit. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Add an Image Node Image nodes are where Gavana's AI generation lives. You can generate a new image from a prompt, upload your own, reuse an existing asset, or pull from your brand kit. ## Prerequisites - An open canvas ## Steps ### Step 1: Open the add menu On the canvas, open the add menu — it offers five options: **Generate image**, **Upload image**, **Assets**, **Brand**, and **List**. ### Step 2: Choose how to add the image - **Generate image** — create from a prompt (see [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt)) - **Upload image** — add a file from your computer - **Assets** — browse images already used on this canvas - **Brand** — pull an asset from your brand's source of truth (see [Use Your Brand on the Canvas](/brand-kit/use-your-brand-on-the-canvas)) - **List** — batch multiple prompts or reference images at once ### Step 3: Position the node Drag the new image node into place, or connect it to a text node for prompt context. ## Tips - Image nodes that fail to generate can be retried without starting over — see [Retry and Regenerate](/ai-generation/retry-and-regenerate). - Uploaded and generated images are both stored as canvas assets, so they show up under **Assets** for reuse. ## Related Articles - [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt) - [Edit an Image with Reference Images](/ai-generation/edit-an-image-with-reference-images) - [Add a Text Node or Sticky Note](/canvas-basics/add-a-text-or-sticky-node) ### Canvas Navigation Reference Source page: https://help.gavana.ai/canvas-basics/canvas-navigation/ Agent-readable page contract: - Audience: people and agents - Intent: How to pan, zoom, select, and resize on a Gavana canvas. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Canvas Navigation The canvas is an infinite, zoomable board. This page covers the core navigation actions. | Action | What it does | |---|---| | Pan | Move around the canvas | | Zoom | Zoom in or out using the on-canvas zoom controls or your trackpad/mouse wheel | | Select | Click a node to select it; drag a selection box to select multiple | | Resize | Drag a selected node's edge or corner to resize it | | Mini-map | Shows your current viewport relative to the whole canvas, useful on large boards | ## Tips - Use the mini-map to jump to a distant part of a large canvas without zooming all the way out. - Multi-select before deleting to remove several nodes at once. ## Related Articles - [Connect Nodes](/canvas-basics/connect-nodes) - [Add an Image Node](/canvas-basics/add-an-image-node) ### How to Connect Nodes in Gavana Source page: https://help.gavana.ai/canvas-basics/connect-nodes/ Agent-readable page contract: - Audience: people and agents - Intent: Draw connections between nodes on a Gavana canvas to link prompts, context, and images. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Connect Nodes Connections are the curved lines linking nodes on your canvas. They show relationships — for example, a text node feeding context into an image node. ## Steps ### Step 1: Select the source node Click the node you want to connect from. ### Step 2: Drag from its edge Drag from the edge of the node to the node you want to connect to. A curved connection line is drawn between them. ### Step 3: Release to confirm Release over the target node to complete the connection. ## Tips - Connections are saved as part of the canvas — they persist across sessions and syncs. - Removing a node also removes any connections attached to it. ## Related Articles - [Add a Text Node or Sticky Note](/canvas-basics/add-a-text-or-sticky-node) - [Add an Image Node](/canvas-basics/add-an-image-node) ### Canvas Basics Source page: https://help.gavana.ai/canvas-basics/ Agent-readable page contract: - Audience: people and agents - Intent: The building blocks of a Gavana canvas: text nodes, image nodes, sticky notes, connections, and navigation. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Canvas Basics A canvas is made of nodes — text, image, and sticky note — that you arrange and connect. This section covers the core building blocks. - [Add a Text or Sticky Note](/canvas-basics/add-a-text-or-sticky-node) - [Add an Image Node](/canvas-basics/add-an-image-node) - [Connect Nodes](/canvas-basics/connect-nodes) - [Canvas Navigation](/canvas-basics/canvas-navigation) ### Canvas Library Overview Source page: https://help.gavana.ai/getting-started/canvas-library-overview/ Agent-readable page contract: - Audience: people and agents - Intent: What you can do from the Gavana Canvas Library: create, import, export, delete, and submit feature requests. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Canvas Library Overview The Canvas Library is the Gavana home page. It lists every canvas you've saved and gives you the following actions in the header: | Action | What it does | |---|---| | **New canvas** | Creates a new canvas and opens it immediately | | **Import canvas** | Restores a canvas from a previously exported JSON file | | **New request** | Opens a dialog to submit a feature request | | Select one or more canvases | Reveals **Export selected** and **Delete selected** | ## Selecting canvases Selecting one or more canvas cards in the library reveals two additional actions: - **Export selected** — downloads the selected canvases as a JSON file, including referenced images - **Delete selected** — removes the selected canvases ## Sync status Next to the **Gavana** title is a sync status indicator. It reflects whether your local changes have finished syncing to your account. See [How Sync Works](/account-sync/how-sync-works) for details on local-first storage and Firebase sync. ## Admin view If your account has admin access, the library header also shows a segmented control with three views: - **My Canvases** — your own canvases (the default view) - **All Members** — every member's canvases, images, and sync status (see [All Members](/admin/all-members)) - **Feature Requests** — review requests submitted by users (see [Manage Feature Requests](/admin/manage-feature-requests)) ## Related Articles - [Create Your First Canvas](/getting-started/create-your-first-canvas) - [Export a Canvas](/import-export/export-a-canvas) - [Import a Canvas](/import-export/import-a-canvas) ### How to Create Your First Canvas in Gavana Source page: https://help.gavana.ai/getting-started/create-your-first-canvas/ Agent-readable page contract: - Audience: people and agents - Intent: Step-by-step guide to creating a new canvas in Gavana and saving your first nodes to it. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Create Your First Canvas A canvas is where you build with Gavana — an infinite board that holds text nodes, image nodes, sticky notes, and the connections between them. This guide walks through creating one from scratch. ## Prerequisites - You're signed in to Gavana ## Steps ### Step 1: Open the Canvas Library Sign in and land on the **Canvas Library** — the page that lists every canvas you've saved. ### Step 2: Click New Canvas Click **New canvas** in the top-right of the header. A new canvas is created and opens immediately — there's no naming step required to get started. ### Step 3: Add a node Use the toolbar to add your first node — **Text**, **Section**, or **Sticky Note** — or open the add menu for **Generate image**, **Upload image**, **Assets**, **Brand**, or **List**. ### Step 4: Arrange the board Drag nodes to position them, and drag from one node's edge to another to draw a connection between them. ### Step 5: Let it save Your canvas saves to local browser storage as you work. Once you're signed in and sync is ready, it also syncs to your account — watch the sync status indicator next to the **Gavana** title on the library page. ## Tips - You don't need to click a separate "save" button — Gavana saves automatically. - If you're not signed in or sync hasn't caught up yet, your canvas still exists locally and will sync once it can. - You can always get back to the library from the canvas by navigating to the Gavana home. ## Related Articles - [Quick Start](/getting-started/quick-start) - [Canvas Basics](/canvas-basics) - [Account & Sync](/account-sync) ### Getting Started with Gavana Source page: https://help.gavana.ai/getting-started/ Agent-readable page contract: - Audience: people and agents - Intent: New to Gavana? Start here to sign in, understand the Canvas Library, and create your first canvas. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Getting Started Gavana is a local-first AI canvas: an infinite board where you drop text notes, images, and sticky notes, connect them, and generate or edit images with AI directly on the board. This section gets you from sign-in to your first canvas. - [Quick Start](/getting-started/quick-start) — the shortest path from sign-in to a working canvas - [Create Your First Canvas](/getting-started/create-your-first-canvas) — step-by-step walkthrough - [Canvas Library Overview](/getting-started/canvas-library-overview) — what the library page can do ### Gavana Quick Start Source page: https://help.gavana.ai/getting-started/quick-start/ Agent-readable page contract: - Audience: people and agents - Intent: The shortest path from signing in to Gavana to generating your first AI image on a canvas. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Quick Start Gavana stores your work locally first, then syncs it to your account once you're signed in — so the app stays usable even if sync hasn't caught up yet. ## 1. Sign in Open Gavana and sign in. Your canvases hydrate from local browser storage immediately; sync with your account starts right after. ## 2. Open the Canvas Library The Canvas Library is the home screen — it lists every canvas you've saved, and shows a sync status indicator next to the **Gavana** title. ## 3. Create a canvas Click **New canvas** in the top-right of the Canvas Library. This creates a new canvas and opens it immediately. ## 4. Add something to the board Use the toolbar at the bottom of the canvas to add a **Text**, **Section**, or **Sticky Note** node, or open the add menu to **Generate image** from a prompt. ## 5. Generate an image Add an image node, type a prompt describing what you want, and click **Generate**. See [Generate an Image from a Prompt](/ai-generation/generate-an-image-from-a-prompt) for the full walkthrough. ## What's next - [Create Your First Canvas](/getting-started/create-your-first-canvas) — a slower, more detailed walkthrough - [Canvas Basics](/canvas-basics) — nodes, connections, and navigation - [AI Image Generation](/ai-generation) — prompting, editing, and reference images ### How to Export a Canvas in Gavana Source page: https://help.gavana.ai/import-export/export-a-canvas/ Agent-readable page contract: - Audience: people and agents - Intent: Download one or more Gavana canvases as a JSON file, including referenced images. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Export a Canvas Exporting saves your canvas — nodes, connections, and referenced images — as a single JSON file you can keep or move elsewhere. ## Steps ### Step 1: Go to the Canvas Library Open the Canvas Library, where all your saved canvases are listed. ### Step 2: Select the canvas or canvases Select one or more canvas cards. Selecting reveals **Export selected** and **Delete selected** in the header. ### Step 3: Click Export selected Click **Export selected**. The file downloads as `gavana-{n}-boards.json`, where images are embedded as data URLs where possible. ## Tips - Exporting multiple canvases at once bundles them into a single file. - Keep exports as backups before making large changes to a canvas. ## Related Articles - [Import a Canvas](/import-export/import-a-canvas) - [Canvas Library Overview](/getting-started/canvas-library-overview) ### How to Import a Canvas in Gavana Source page: https://help.gavana.ai/import-export/import-a-canvas/ Agent-readable page contract: - Audience: people and agents - Intent: Restore a previously exported Gavana canvas from a JSON file. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # How to Import a Canvas Importing restores a canvas — and its embedded images — from a JSON file exported earlier. ## Prerequisites - A canvas JSON file exported from Gavana (see [Export a Canvas](/import-export/export-a-canvas)) ## Steps ### Step 1: Go to the Canvas Library Open the Canvas Library. ### Step 2: Click Import canvas Click **Import canvas** in the header and choose your exported `.json` file. ### Step 3: Confirm the import Gavana restores the canvas (or canvases, if the file contains more than one) and shows a success message like **"Imported 1 canvas."** Embedded images are restored through local image storage, then synced normally. ## Tips - If the import fails, you'll see **"Import failed. Please choose a valid canvas file."** — make sure the file is an unmodified Gavana export. - Imported canvases appear as new entries in your library; they don't overwrite existing ones with the same name. ## Related Articles - [Export a Canvas](/import-export/export-a-canvas) - [Canvas Library Overview](/getting-started/canvas-library-overview) ### Import & Export Source page: https://help.gavana.ai/import-export/ Agent-readable page contract: - Audience: people and agents - Intent: Export a Gavana canvas to a JSON file with embedded assets, and import it back. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Import & Export Canvases export to a self-contained JSON file, including their referenced images, so you can back them up or move them between accounts. - [Export a Canvas](/import-export/export-a-canvas) - [Import a Canvas](/import-export/import-a-canvas) ### Gavana Help Center Source page: https://help.gavana.ai/ Agent-readable page contract: - Audience: people and agents - Intent: Welcome to the Gavana help center. Find guides on canvases, AI image generation, brand kits, import/export, and agent access. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Welcome to Gavana Gavana is a visual AI canvas for people and agents. Create text, image, and sticky-note ideas; connect them; then review or make work on the board. Browse the guides below or use search to find an answer quickly. ## Find the right guide ### Fix: Images Show Up but the Canvas Is Missing Source page: https://help.gavana.ai/troubleshooting/canvas-shows-assets-but-no-canvases/ Agent-readable page contract: - Audience: people and agents - Intent: What to do when images are visible but the expected canvas is missing from Gavana. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Fix: Images Show Up but the Canvas Is Missing ## Symptom In the [All Members](/admin/all-members) admin view, a member may show images but `0` canvases—or a canvas you expect to see is not listed. ## Why this happens Images and canvases can have different save histories. For example, a canvas may have been deleted, its original device may not have finished syncing, or older work may have left images without a recoverable canvas record. This symptom does not by itself prove that data was reset. ## Causes to check, in order 1. **The canvas was deleted** — images can remain available after a canvas is removed. 2. **Sync was interrupted** — the original device may still have an unsynced version. 3. **Older work is incomplete** — some older images may not have a recoverable canvas record. ## How to recover - Ask the owner to open Gavana on the device where the canvas was last edited and check its sync status. - Check for an export of the canvas (see [Export a Canvas](/import-export/export-a-canvas)) taken before the issue occurred. - Check the visible canvas history when it is available. - If the canvas cannot be recovered, rebuild it from the surviving images in a new canvas. ## What not to assume Do not conclude that an account was reset based on this symptom alone. Record the affected account, approximate canvas title, date, and any export or screenshot, then contact support with that information. ## Related Articles - [All Members](/admin/all-members) - [How Sync Works](/account-sync/how-sync-works) - [Export a Canvas](/import-export/export-a-canvas) ### Common Gavana Issues Source page: https://help.gavana.ai/troubleshooting/common-issues/ Agent-readable page contract: - Audience: people and agents - Intent: Quick fixes for the most common problems in Gavana: sync, imports, and image generation. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Common Issues ## My canvas isn't showing up Give sync a moment — Gavana hydrates from local browser storage first and syncs to your account after. See [How Sync Works](/account-sync/how-sync-works). If it still doesn't appear, check whether you're signed in to the right account, and see [Assets Without a Saved Canvas](/troubleshooting/canvas-shows-assets-but-no-canvases) if you can see related images but not the canvas itself. ## Import failed You'll see **"Import failed. Please choose a valid canvas file."** if the selected file isn't an unmodified Gavana export. Re-export the canvas and try again — see [Export a Canvas](/import-export/export-a-canvas). ## Image generation failed or is stuck Use the node's retry control, or **Stop** a stuck generation and try again. See [Retry and Regenerate](/ai-generation/retry-and-regenerate) for the full walkthrough. ## Brand import failed You'll see an **"Import failed"** message if Gavana couldn't read the website. Try the URL again, or fall back to [creating the brand manually](/brand-kit/create-a-brand-manually). ## Related Articles - [How Sync Works](/account-sync/how-sync-works) - [Retry and Regenerate](/ai-generation/retry-and-regenerate) - [Assets Without a Saved Canvas](/troubleshooting/canvas-shows-assets-but-no-canvases) ### Troubleshooting Source page: https://help.gavana.ai/troubleshooting/ Agent-readable page contract: - Audience: people and agents - Intent: Fixes for common Gavana issues: missing canvases, sync problems, and failed image generation. - Side effects: Follow the user-facing guide. Do not infer permissions, API parameters, or provider cost. - Source of truth: This user-facing help article; use the canonical Canvas API contract before an integration action. - Last verified: Not declared; verify current Gavana behavior before acting. # Troubleshooting - [Assets Without a Saved Canvas](/troubleshooting/canvas-shows-assets-but-no-canvases) - [Common Issues](/troubleshooting/common-issues) For AI generation failures specifically, see [Retry and Regenerate](/ai-generation/retry-and-regenerate).