@gavana.ai/cli 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog — @gavana.ai/cli
+
+## 0.2.0
+
+First release published to npm. Version 0.1.0 existed in this repository but was
+never published, so there is no upgrade path to describe — everything below is
+what shipped between the two internal versions, kept here because the package
+exports (`@gavana.ai/cli/client`, `@gavana.ai/cli/capabilities`) are consumed
+inside the repository and by the MCP server.
+
+### Added
+
+- **One command table.** `src/commands.mjs` declares every `gavana` command
+  once. Root help, per-group help, and the zsh/bash/fish completion scripts are
+  all generated from it, and dispatch is gated on it. Before, those four things
+  were four hand-maintained copies of the same list, and they had drifted.
+- **Shell completions complete sub-commands.** `gavana completion zsh|bash|fish`
+  previously offered only the top-level groups; it now offers each group's
+  actions too. Deprecated and alias commands stay dispatchable and stay out of
+  completions.
+- **Tool registry export.** `src/tools/registry.mjs` carries every tool
+  definition shared by the stdio MCP server and the hosted endpoint, with each
+  tool's schema in `src/tools/schemas.mjs`.
+- **Progress helper.** `src/tools/progress.mjs` turns the client's existing
+  `onProgress` polling callback into MCP `notifications/progress` messages.
+- **Guides as markdown.** The Canvas Agent Guide is now
+  `packages/cli/guides/*.md` rather than string literals, and ships in the
+  package.
+
+### Fixed
+
+- An unknown command is now rejected wherever it appears. `gavana version bogus`
+  and `gavana capabilities bogus` used to print a result and exit 0, because
+  both commands answered before anything checked whether the command existed.
+  They now exit 2 with `Unknown command`. `gavana --version` still answers, as
+  it carries no command at all.
+
+### Deprecated
+
+Still callable; nothing is removed in 0.2.0.
+
+- **`gavana campaign *`** — `plan`, `start`, `get`, `review`, `cancel`. Hidden
+  from help and completions, and rejected unless
+  `GAVANA_ENABLE_LEGACY_CAMPAIGN_COMMANDS=true`. Existing `gavana recipe *`
+  commands remain API compatibility operations; this does not expose the
+  production Recipe UI.
+- **`gavana ai-connection list`** — a compatibility alias for
+  `gavana provider list`. Dispatches identically, no longer advertised.
+
+### Compatibility
+
+- The `craftboard` and `craftboard-canvas` binaries, and the
+  `CRAFTBOARD_*` environment variables, continue to work as aliases. They are
+  not deprecated.

package/LICENSE.md

@@ -0,0 +1,7 @@
+# Gavana Customer Package License
+
+Copyright 2026 Gavana. All rights reserved.
+
+This package is proprietary software. Permission to install and use it is
+governed by the current [Gavana Terms of Service](https://app.gavana.ai/terms).
+No rights are granted beyond those terms.

package/README.md

@@ -0,0 +1,237 @@
+# Gavana CLI
+
+The Gavana CLI is a JSON-first command-line client for the Gavana
+Canvas API. It can read and change canvases, work with assets, explicitly run
+Recipes, run deterministic Image Actions, and observe every execution through
+shared Run and Job interfaces without opening the browser. It also queues
+model-aware video generation with local or durable frame references.
+
+## Install from npm
+
+```sh
+npm install --global @gavana.ai/cli
+gavana --help
+```
+
+The npm command works after the package owner publishes this release. For local
+package verification from the Gavana repository, run
+`npm run test:canvas-cli-package`.
+
+Use of the published CLI is subject to the current
+[Gavana Terms of Service](https://app.gavana.ai/terms). Its customer package
+license incorporates those terms by reference.
+
+Node.js 20 or newer is required. `craftboard` and `craftboard-canvas` remain
+available as compatibility aliases.
+
+## Sign in
+
+Browser OAuth is the default:
+
+```sh
+gavana auth login
+gavana auth status
+```
+
+The CLI opens Gavana, asks the user to approve exact scopes, and returns through
+a loopback callback. On macOS the resulting revocable token is stored in
+Keychain; custom config paths and other platforms use the mode-`0600` config
+file. Use `--read-only` for a browse-only profile.
+
+Named profiles keep accounts and environments separate:
+
+```sh
+gavana auth login --profile work
+gavana auth login --profile staging --base-url https://staging.example.com
+gavana config list
+gavana config use work
+gavana canvas list --profile staging
+```
+
+Manual Agent Access tokens remain supported for automation and compatibility.
+
+Create an Agent Access token in Gavana, then save it without putting the
+secret in shell history. On 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
+gavana auth status
+```
+
+On 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
+```
+
+On 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
+```
+
+The saved configuration lives at
+`~/.config/gavana/agent.json` with file mode `0600`. Environment variables
+`GAVANA_BASE_URL` and `GAVANA_AGENT_TOKEN` override saved values. Existing
+`~/.config/craftboard/agent.json` and `CRAFTBOARD_*` aliases remain readable.
+
+## Discover and diagnose
+
+```sh
+gavana doctor
+gavana version
+gavana completion zsh
+gavana canvas --help
+gavana api GET /canvases --field limit=10
+gavana mcp install codex
+gavana mcp install codex --read-only
+gavana mcp config cursor
+```
+
+JSON remains the stable scripting default. Use `--output human` for a compact
+terminal view, or `jsonl`, `markdown`, `raw`, and `--jq` for composition.
+Transient network errors and `429/502/503/504` responses are retried only for
+safe GET requests, respecting `Retry-After`; paid generation writes are never
+retried automatically.
+
+## Examples
+
+```sh
+gavana canvas list
+gavana canvas list --limit 25 --jq '.canvases[].handle' -r
+gavana asset get asset:OWNER_UID:ASSET_ID
+gavana recipe search "product visual"
+gavana recipe run recipe:product-visual-direction --input product-context="A matte black travel bottle" --destination agent-canvas
+gavana model list --capability image.generate
+gavana model get model:OPAQUE_MODEL_KEY
+gavana action list
+gavana action get action:resize
+gavana action run action:resize --input ./product.png --destination agent-canvas --width 1080 --height 1350
+gavana image generate --destination agent-canvas --model model:OPAQUE_MODEL_KEY --prompt "A studio product photograph"
+gavana model list --capability video.generate
+gavana video generate --model model:OPAQUE_MODEL_KEY --prompt "A slow product turntable" --duration 15 --aspect-ratio 9:16 --download ./turntable.mp4
+gavana video generate --model model:OPAQUE_MODEL_KEY --prompt "Animate the fabric naturally" --first-frame ./product.png --no-wait
+gavana video download job:JOB_ID --file ./result.mp4
+gavana run wait run:RUN_ID --output markdown
+```
+
+`video generate` validates duration, aspect ratio, resolution, audio, and frame
+capabilities against the selected model before starting paid work. Use
+`gavana model get model:OPAQUE_MODEL_KEY` to inspect its exact values.
+First frame, last frame, and repeatable `--reference` inputs accept image
+`node:` or `asset:` handles, public HTTPS URLs, local image paths, stdin (`-`),
+or the macOS clipboard. Local images upload privately first. Pass
+`--canvas canvas:<id>` when any input is a `node:` handle. A last frame requires
+a first frame.
+
+Video generation returns a `job:` handle. By default the CLI waits up to 30
+minutes and returns the completed job with its authenticated video download
+path. Add `--download ./output.mp4` to stream the successful result directly to
+disk, or use `video download job:<id> --file ./output.mp4` later. Existing files
+are preserved unless `--yes` is supplied. Use `--no-wait` to return after
+queueing, then use `job get`, `job wait`, or `job cancel`. Waiting, downloading,
+and cancellation require `job:manage`; generation requires `canvas:read`,
+`asset:read`, and `video:generate`.
+
+Image Actions resize, crop, reframe, composite, add text, overlay, color grade,
+or rotate existing images. They are deterministic and do not spend AI credits.
+Use `action get` to inspect the exact input order, valid fields, defaults, and
+limits. `action run` accepts `node:` and `asset:` handles, local image paths,
+stdin (`-`), or the macOS clipboard.
+Local, stdin, and clipboard inputs are privately uploaded first and therefore
+also require the token's `image:generate` scope; existing handles do not.
+
+For reference-aware image generation, repeat `--reference` for every durable
+visual and repeat `--reference-role` in the same order when the role is known:
+`identity`, `construction`, `texture`, `fit`, or `style`. Gavana records the
+exact handles and roles in the job result and target-node provenance, and sends
+the request through the reference/edit backend rather than dropping inputs into
+a prompt-only fallback.
+
+`recipe run` takes repeatable named inputs such as
+`--input product-context="A matte black travel bottle"` and
+`--input offer-brief=@brief.md`. Use the exact keys returned by `recipe get`.
+For distinct product variants, use a Prompt List: connect the product image
+once to the List, make one explicit direction per row, and connect the List to
+an image generator. Each row inherits the same reference; agents should state
+that the exact product must be preserved and never substituted. For a style
+that belongs to only one row, use that row's `referenceBindings` with the
+durable image handle (`{ "nodeId": "node:<id>", "role": "style" }`), rather
+than inserting a copied image name into prompt text. Gavana preserves the
+shared Product -> Prompt List -> output path and draws the row Style -> output
+edge separately.
+Written ports accept text, text/sticky `node:` handles, and image handles when
+the Recipe asks for “an image or written note.” Image ports may also use local
+raster paths, stdin, or the clipboard and are uploaded privately first. Upload
+a local visual first and pass its `asset:` handle when using it on a written
+reference port; `@path` on that port reads the file as text. Starting a Recipe
+creates a private instance when needed, materializes its declared outputs on
+the destination canvas, and returns their durable `node:` and `asset:` handles.
+`recipe fork` remains setup-only and never starts a Run. All Recipe starts
+currently require `image:generate` and its dependent scopes, including
+text-only Recipes.
+
+Recipe, image, and Action work returns a shared `run:` handle with typed outputs,
+duration estimates, observed queue/execution timing, and stable retry guidance.
+Default waiting and `run get|wait|cancel` require `job:manage`; a start-only
+token can use `--no-wait` with a signed webhook.
+The legacy `job:` handle remains an image and Action compatibility alias; it is
+never used for Recipes. Image and Action `run:` and `job:` handles point to the
+same temporary record and expire together:
+the default retention is 24 hours while unacknowledged, 15 minutes after the
+first successful server finalization (from a Run GET or callback), and seven
+days for the expired tombstone. Recipe Run records currently persist without
+that temporary TTL. Persist the returned durable asset and node handles.
+For a signed terminal
+callback, provide the endpoint and read the secret from an environment
+variable:
+
+```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 NAME` to select a different variable. The CLI never
+prints the secret. Successful Image and Action callbacks are sent only after
+Gavana has stored the durable canvas, node, and asset results. Failed,
+canceled, or expired callbacks describe the terminal state without requiring
+images; Recipe callbacks contain their typed terminal outputs. A start-only token remains revocable while
+Gavana's worker resumes the Run independently of the original CLI process.
+If the token expires or is revoked first, the Recipe stops with
+`delegation_revoked` and sends its signed failed callback.
+
+Commands emit one JSON result to stdout by default. Progress and errors go to
+stderr, making the CLI safe to compose in scripts and agent workflows. List
+commands for canvases, recipes, assets, Actions, models, and providers accept `--limit` and
+`--cursor`; responses return the continuation at `page.nextCursor`. Use
+`--output jsonl` for line-oriented output. The built-in
+`--jq` selector supports property paths, array indexes, and `[]` projections
+without requiring a separate jq installation.
+
+## JavaScript client
+
+The same dependency-free client is exported for Node.js applications:
+
+```js
+import { createCanvasAgentClient } from "@gavana.ai/cli";
+
+const client = createCanvasAgentClient({
+    baseUrl: process.env.GAVANA_BASE_URL,
+    token: process.env.GAVANA_AGENT_TOKEN,
+    surface: "api",
+});
+
+const result = await client.listCanvases();
+```
+
+Remote servers must use HTTPS. Plain HTTP is accepted only for local loopback
+development.

package/bin/craftboard.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCraftboardAgentCli } from "../src/runner.mjs";
+
+process.exitCode = await runCraftboardAgentCli();

package/bin/gavana.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runGavanaCli } from "../src/runner.mjs";
+
+process.exitCode = await runGavanaCli();

package/guides/connections.md

@@ -0,0 +1,35 @@
+---
+id: connections
+title: Connections
+description: Create directed, persistent relationships with valid endpoint semantics.
+keywords: ["connection","connect","edge","direction","input","output","reference","list","first-frame","last-frame","prompt"]
+order: 4
+---
+
+## Direction
+
+A connection goes from source to target. Use source input or instruction -> transformation or generator -> output. Never connect a node to itself, and never connect a Section as if it were a workflow step.
+
+## Modes
+
+- Omit `mode` for a normal dependency or transformation flow.
+- `prompt`: a text or sticky note whose content is the generation prompt for the target image node. One prompt connection per target; image generation reads the prompt from this node when the request omits a prompt.
+- `reference`: an image reference that guides another node.
+- `list`: a Prompt List or Image List flow.
+- `first-frame`: an image used as the first frame of a video node.
+- `last-frame`: an image used as the last frame of a video node.
+
+Use exact `node:` handles or batch-local `client:` references. Connections remain attached when nodes move. Avoid duplicate edges with the same source, target, and mode.
+
+## Batch-local example
+
+```json
+{
+  "type": "connection.create",
+  "clientId": "brief-to-generator",
+  "from": "client:brief",
+  "to": "client:generator"
+}
+```
+
+Do not rely on spatial proximity to imply a relationship. If a relationship matters to execution or later understanding, connect it.

package/guides/examples-common-mistakes.md

@@ -0,0 +1,29 @@
+---
+id: examples-common-mistakes
+title: Examples and Common Mistakes
+description: Compact patterns to copy and anti-patterns agents must avoid.
+keywords: ["example","examples","mistake","mistakes","anti-pattern","section","note","text","generated","connection"]
+order: 10
+---
+
+## Good patterns
+
+- Research cluster: one Section, several Sticky observations, one Text synthesis, and directed observation -> synthesis connections.
+- Creative workflow: source image -> Prompt List -> empty generator -> generated outputs.
+- Video workflow: first image -[first-frame]-> video target and optional last image -[last-frame]-> video target.
+- Existing-canvas addition: new contained Section outside the current bounds, with no existing-node mutations.
+
+## Common mistakes
+
+- Using long Text or Sticky nodes as fake headers instead of Sections.
+- Creating every node at `{ "x": 0, "y": 0 }` or stacking nodes on top of one another.
+- Leaving generated outputs disconnected from their prompt, List, source, or stage.
+- Connecting a Section to workflow nodes.
+- Treating nearby objects as implicit inputs without explicit handles or connections.
+- Copying a style image name into prompt text instead of using a row-level reference binding.
+- Writing generated media content directly into node metadata.
+- Reorganizing or deleting existing work when the user asked only to add something.
+- Starting generation when the user asked only to prepare a workflow.
+- Retrying a failed paid operation automatically.
+- Reporting a temporary Job or Run handle as a durable Canvas output.
+- Passing `force: true` to push a batch past error-severity findings instead of fixing the operations. Force is for explicit, user-approved exceptions only.

package/guides/existing-canvases.md

@@ -0,0 +1,19 @@
+---
+id: existing-canvases
+title: Editing Existing Canvases Safely
+description: Preserve user structure, concurrent edits, and unrelated content while making scoped changes.
+keywords: ["existing","preserve","concurrent","revision","conflict","409","idempotency","unrelated","delete","scope"]
+order: 7
+---
+
+## Preservation contract
+
+- Call `canvas_get` and retain the exact revision before planning a write.
+- Make the smallest requested delta. Do not move, resize, retitle, reconnect, delete, or rewrite an existing node outside the requested scope.
+- Prefer one atomic batch for related nodes and connections so a malformed operation leaves no partial graph.
+- Pass the read revision as `baseRevision`.
+- On `409`, read again and rebase the intended additions around the newer graph. Preserve the concurrent user change.
+- Reuse an idempotency key only for an identical intended payload. If the intended payload changes, use a new key.
+- Pass proposed delete operations to `canvas_validate` and report their node and connection impact before applying them.
+
+An agent-authored addition should be removable without damaging surrounding user work. Exact returned handles are the audit trail.

package/guides/generated-assets.md

@@ -0,0 +1,29 @@
+---
+id: generated-assets
+title: Generated Images, Videos, and Durable Outputs
+description: Prepare media nodes, start only explicit generation, and preserve output lineage.
+keywords: ["generated","generation","image","video","output","asset","durable","lineage","placeholder","job"]
+order: 6
+---
+
+## Before generation
+
+- Read the destination canvas and relevant source nodes.
+- Use exact source `node:` or `asset:` handles.
+- For a standalone image request, pass every visual source in `references`.
+  Use `{ "handle": "node:...", "role": "identity" }` when its
+  responsibility is known; valid roles are `identity`, `construction`,
+  `texture`, `fit`, and `style`. Do not flatten multi-reference work
+  into prompt prose or omit a source during fallback.
+- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.
+- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.
+
+## Paid execution
+
+Generation is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. Poll the returned Run or Job; do not start another run while waiting. A terminal failure must be reported without automatic retry.
+
+## Completion
+
+Do not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.
+
+Keep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, durable output count, and product-fidelity review state. Do not claim Done while it says `doneClaimAllowed: false`. Product-fidelity uncertainty requires human review; never create another paid provider call automatically.

package/guides/getting-started.md

@@ -0,0 +1,26 @@
+---
+id: getting-started
+title: Canvas Agent Workflow
+description: The required inspect, guide, validate, edit, and review sequence for every canvas task.
+keywords: ["start","workflow","inspect","read","validate","edit","review","revision","idempotency"]
+order: 1
+---
+
+## Required sequence
+
+1. Identify one exact canvas handle. Never guess between candidates.
+2. Call `canvas_get` before reasoning about or changing an existing canvas.
+3. Read the guide topics relevant to the requested operation.
+4. Plan the smallest graph change that satisfies the request. Preserve unrelated nodes, connections, positions, metadata, and the user's current structure.
+5. Call `canvas_validate` with the proposed operations before a large, spatial, or destructive batch.
+6. Apply related changes atomically with `canvas_apply_batch`, the current `baseRevision`, and one caller-stable idempotency key.
+7. If a write returns revision conflict `409`, read the canvas again, preserve the newer user change, and retry the same intent. Reuse the same idempotency key only for the same payload.
+8. Call `canvas_validate` after editing. Report exact changed handles and unresolved warnings.
+
+## Non-negotiable safety
+
+- Building or preparing a workflow does not mean running it.
+- Never start image, video, Action, or Recipe generation unless the user explicitly requested that paid action in the current conversation.
+- Never automatically retry a failed paid action.
+- Never delete, disconnect, overwrite, or reorganize existing work unless the user explicitly requested that scope.
+- Generated media content is server-owned. Use generation or import tools; do not place bytes or arbitrary media URLs into node metadata.

package/guides/notes-text-sections.md

@@ -0,0 +1,44 @@
+---
+id: notes-text-sections
+title: Notes, Text, and Sections
+description: Choose the correct native canvas object for observations, durable copy, headings, and spatial groups.
+keywords: ["note","notes","sticky","text","heading","header","section","frame","content","annotation"]
+order: 2
+---
+
+## Object grammar
+
+- Sticky note: one short observation, idea, decision, question, or human annotation. Create a `sticky` node and put the readable value in `metadata.content`.
+- Text: a paragraph, prompt, brief, instruction, caption, or durable written output. Create a `text` node and put the body in `metadata.content`.
+- Section: a labeled spatial container and navigation landmark. Create a `text` node with `metadata.isSection: true`. Put the section title in `title`; keep `metadata.content` empty unless the user asked for a section description.
+- Heading: use the title of a real Section. Do not stretch an ordinary Text or Sticky node across the canvas to imitate a section header.
+
+## Section example
+
+```json
+{
+  "type": "node.create",
+  "clientId": "research-section",
+  "node": {
+    "type": "text",
+    "title": "Customer objections",
+    "position": { "x": 1200, "y": 200 },
+    "width": 1040,
+    "height": 720,
+    "metadata": { "isSection": true }
+  }
+}
+```
+
+Place each child's complete frame inside the Section bounds; a centered but
+overflowing frame is not contained. A Section may overlap its children by
+design; ordinary nodes should not overlap one another. A child whose frame
+crosses its Section boundary receives a `section_content_overflow` finding.
+
+## Stored membership
+
+Membership is stored: the server keeps `metadata.sectionId` on every node
+whose complete frame fits inside a Section, recomputing it after each batch on
+create, move, resize, and delete. When Sections nest or overlap, the smallest
+containing Section wins. Do not set `sectionId` yourself — geometry is the
+source of truth and caller-supplied values are corrected.

package/guides/paid-action-safety.md

@@ -0,0 +1,22 @@
+---
+id: paid-action-safety
+title: Paid Action Safety
+description: Separate preparation from execution and prevent accidental or repeated provider charges.
+keywords: ["paid","credits","cost","generate","run","retry","failure","prepare","setup","explicit"]
+order: 8
+---
+
+## Intent boundary
+
+"Build", "prepare", "set up", "connect", "draft", and "make ready" authorize graph edits only. They do not authorize Recipe, image, video, or Action execution.
+
+Start paid work only when the current user message explicitly asks to run or generate it. Do not infer authorization from an older message, a node label, an unfinished placeholder, or nearby content.
+
+## Retry boundary
+
+- Use one stable idempotency key for one intended paid operation.
+- Poll the returned handle with status tools.
+- Never automatically retry a terminal failure, timeout, disconnect, or ambiguous provider response with a new key.
+- Ask for new user intent before any new paid attempt.
+
+Deterministic Actions may be described as credit-free only when `action_get` confirms that contract. Inspect an Action before running it.

package/guides/prompt-lists.md

@@ -0,0 +1,20 @@
+---
+id: prompt-lists
+title: Prompt Lists and Repeated Directions
+description: Represent several editable creative directions as one native Prompt List with shared and row-specific references.
+keywords: ["prompt","list","directions","rows","referenceBindings","product","style","batch","generator"]
+order: 5
+---
+
+## Prompt List shape
+
+Use one `text` node with:
+
+- `metadata.isList: true`
+- `metadata.listType: "prompt"`
+- `metadata.listExecutionMode: "batch"` for separate outputs
+- one checked `metadata.listItems` entry per direction
+
+Connect a shared product image to the List once. Connect the List to one empty image generator. For a row-specific style, store the exact style image in that row's `referenceBindings` as `{ "nodeId": "node:<id>", "role": "style" }`. Do not copy a filename into prompt prose as a substitute for a binding.
+
+Every product-variant row should explicitly say to preserve the exact connected product and not substitute it. Building the List and generator prepares the workflow only; it must not start generation.

package/guides/sections-layout.md

@@ -0,0 +1,43 @@
+---
+id: sections-layout
+title: Sections and Layout
+description: Place native objects in readable groups without hiding or rearranging existing work.
+keywords: ["section","layout","position","overlap","spacing","grid","right","below","contain","navigation"]
+order: 3
+---
+
+## Layout rules
+
+- Treat the current canvas as user-owned. Preserve existing coordinates unless reorganization was explicitly requested.
+- For additions to an existing canvas, compute its visible bounding box and place the new Section to the right with at least 160 canvas units of outer spacing. If right-side placement would make the canvas excessively wide, place it below with the same spacing.
+- Use 48 units of inner Section padding, 32 units between sibling nodes, and at least 80 units between major stages.
+- Keep workflow direction consistent, normally left to right. Keep inputs before transformations and outputs after them.
+- Use compact rows or columns. Avoid extremely long, thin canvases that become unreadable at Fit Canvas.
+- For 2-8 generated image outputs, reserve each requested final aspect frame before work begins and pack the complete result cluster as a grid. The usual four-image photoshoot is a 2x2 grid; do not stack it as a tall output column that can overlap when images finalize.
+- Size Sections after their contents. Do not use Section overlap as a substitute for node placement.
+- Run `canvas_validate` before and after a multi-node layout change.
+
+## One task = one Section
+
+Group each task's output in a titled Section sized to its contents plus 48
+units of padding. Workflow creation and multi-output image generation wrap
+their clusters in a Section automatically (multi-output wrapping applies to
+automatic placement; passing explicit target coordinates opts out and leaves
+placement fully caller-controlled); do the same for hand-built
+clusters. Agent-created nodes left outside every Section raise an info-level
+`unsectioned_node` finding. Membership is stored server-side as
+`metadata.sectionId`, recomputed from complete-frame geometry after every
+batch. Agent-created Sections receive an owned auto-fit contract; after a
+generated child changes size, Gavana refits only that still-owned Section to
+the full child bounds plus 48 units. Do not use this as permission to move or
+resize a user-controlled Section.
+
+For a newly proposed agent cluster, ordinary-node overlap and full-frame
+Section overflow are write-blocking errors. On an existing Canvas, historical
+user-created overlap or overflow remains advisory so an unrelated scoped edit
+can still proceed. Agent-owned task findings still block completion review
+until they are corrected.
+
+## Existing canvas rule
+
+When the user says "add", do not interpret it as "reorganize". New work should be distinguishable, spatially contained, and reversible without moving unrelated content.

package/guides/validation-recovery.md

@@ -0,0 +1,33 @@
+---
+id: validation-recovery
+title: Validation and Recovery
+description: Interpret structural findings, correct invalid batches, and finish with an evidence-based review.
+keywords: ["validate","lint","overlap","orphan","header","connection","destructive","recovery","error","atomic","blocked","force"]
+order: 9
+---
+
+## Use `canvas_validate`
+
+Call it with only `canvasId` to audit the current graph. Pass the proposed `operations` to inspect the planned post-batch graph and destructive impact before writing.
+
+Warning- and info-level findings are advisory. Error-severity findings caused by the proposed agent write have teeth: `canvas_apply_batch` rejects that batch and writes nothing. Historical findings remain visible for review but do not turn an unrelated scoped write into a forced cleanup. Validation never mutates the canvas or consumes an idempotency key.
+
+`summary.passed` means there is no structural error. `summary.reviewRequired` is true when errors, warnings, or truncated findings still require agent or human review. `completionReview` is the finalization-ready structured view: it names overlap, containment, reference lineage, output count, and product-fidelity state. Never claim Done unless `completionReview.doneClaimAllowed` is true.
+
+## Blocked writes
+
+When a batch is rejected with error-severity findings:
+
+- Nothing was written and the idempotency key was not consumed — the same key retries the corrected batch of the same intent.
+- The rejection lists the blocking findings. Fix the listed operations, then confirm with `canvas_validate` using the same `operations` before applying again.
+- `force: true` applies the batch despite error findings. Use it only after validating, and only when the user explicitly accepts the listed findings — never as a routine retry shortcut.
+
+## Recovery
+
+- If an operation is rejected, the atomic batch makes no partial change.
+- Read the finding's exact handles and linked guide topic.
+- Correct unsupported object types, metadata, endpoint modes, positions, or references instead of guessing repeatedly.
+- Use a new idempotency key if the corrected payload represents a changed intent.
+- Read and validate again after a successful write.
+
+Common findings include ordinary-node overlap, Section content overflow, generated output without an incoming relationship, text imitating a Section header, broken lineage handles, unclear media connections, and proposed deletions. Product-fidelity uncertainty is a review state, not authorization to regenerate.