# Avocado Studio

- [Hand the change to an agent. The design system holds.](https://docs.avocadostudio.dev/index.md): Avocado Studio is the agentic operations layer for a website that already exists. An agent plans your change and applies it as typed content operations — from chat, from a click on the live page, from a Jira ticket, or from any MCP client — and never as a code change. Your components are the blocks,…
- [Try the demo](https://docs.avocadostudio.dev/first-run.md): One command, a nine-page site to click through, what turning chat on actually costs, and which of the surprises are deliberate.
- [Add Avocado to your site](https://docs.avocadostudio.dev/quickstart.md): Wire Avocado Studio into a Next.js project you already have — hand one prompt to your coding agent, start two processes, make the first edit.
- [How do I…?](https://docs.avocadostudio.dev/recipes.md): Task-oriented index of common workflows — what you want to do, mapped to the right doc.
- [Compare](https://docs.avocadostudio.dev/compare.md): The category sorts by one question: what is the tool permitted to change? Avocado Studio next to code-writing agents, hosted platforms, headless CMSes, visual page builders, and general AI assistants.
- [Core concepts](https://docs.avocadostudio.dev/concepts.md): The mental model behind Avocado Studio — your components as blocks, the 19-operation vocabulary that is the safety boundary, and how drafts, approval and publishing fit together.
- [How it works](https://docs.avocadostudio.dev/how-it-works.md): One sentence, followed all the way through — intent, plan, validation, streamed apply, the approval gate, undo, and publishing back to wherever your content lives.
- [Architecture](https://docs.avocadostudio.dev/architecture.md): How the three services, packages, and data flow fit together.
- [AI providers and model routing](https://docs.avocadostudio.dev/ai-providers.md): Run the planner on Anthropic, OpenAI, or Google Gemini with your own keys, and choose which model tier plans each edit.
- [A tour of the editor](https://docs.avocadostudio.dev/editing/index.md): What is on screen when you open Avocado Studio, what each control does, and the one button that makes the page clickable.
- [Writing prompts that work](https://docs.avocadostudio.dev/editing/prompts.md): What to ask for, how to scope it, which requests the editor cannot do at all, and the one kind of request that costs real money.
- [Pages and drafts](https://docs.avocadostudio.dev/editing/pages-and-drafts.md): Where your unpublished work lives, why the live site looks unchanged until you publish, and how to move between pages and languages.
- [Review, undo and versions](https://docs.avocadostudio.dev/editing/review-and-undo.md): Every way back — undo, the History drawer, restoring an earlier version of a page, and restoring a published snapshot — and when each one is the right tool.
- [Publishing your changes](https://docs.avocadostudio.dev/editing/publish.md): The review dialog, publishing only some of your pages, and how to confirm the live site actually changed.
- [Asset Manager & AI Images](https://docs.avocadostudio.dev/features/asset-picker.md): Image sources, AI generation with OpenAI and Gemini (nano-banana), multi-turn image chat, and how the editor and chat pipeline resolve images.
- [Variants (block alternatives)](https://docs.avocadostudio.dev/features/variants.md): Generate multiple AI-authored alternatives for a single block — different tones, copy directions, and images — then pick one to apply. Two entry paths: the REST variation pipeline and the agent's generate_variations tool.
- [Chat attachments](https://docs.avocadostudio.dev/features/chat-attachments.md): Attach images and PDFs in the chat composer and have the AI planner read them as native multimodal context — the way Claude and ChatGPT ingest files.
- [Site health (checks and findings)](https://docs.avocadostudio.dev/features/site-health.md): A checker that reads the draft and reports what is wrong with it — missing alt text, dead internal links, duplicate titles, translations that fell behind — as findings you can dismiss or snooze. Runs on publish, on demand, or on every edit.
- [The editorial brief](https://docs.avocadostudio.dev/editing/brief.md): Tell the site what it is about, how it should sound, and what it must never say — once, instead of in every prompt.
- [Internationalization](https://docs.avocadostudio.dev/i18n.md): The editor UI and AI responses both support multiple languages. English and German ship today; adding a locale is a few-line change.
- [Puck mode](https://docs.avocadostudio.dev/integration/puck-mode.md): Enable a visual drag-and-drop editing experience alongside AI chat using the Puck editor.
- [Immersive mode](https://docs.avocadostudio.dev/features/immersive-mode.md): An experimental widget that puts editing directly on the site page. What it offers, how a developer mounts it, and why the editor no longer links to it.
- [Bring your site in](https://docs.avocadostudio.dev/sites/index.md): Three ways to get an existing website into Avocado Studio — hand it to your own coding agent, use the built-in onboarding agent, or read the contract and write it yourself.
- [Hand it to your own coding agent](https://docs.avocadostudio.dev/sites/coding-agent.md): The recommended way to bring an existing site into Avocado Studio: give the integration to the coding agent that already knows your codebase, working in your repo through your normal review flow.
- [Onboarding agent](https://docs.avocadostudio.dev/sites/site-agent.md): The AI agent built into the editor that brings sites into Avocado Studio. How to use it, what you need before you start, and how it runs under the hood.
- [The integration contract](https://docs.avocadostudio.dev/sites/manual.md): Every seam an Avocado Studio integration has to satisfy — the editor API, the page factory, block registration, markers, the CMS adapter, and the coverage check that says it is finished. Whether a human or an agent writes the code, this is what it has to meet.
- [Next.js Integration](https://docs.avocadostudio.dev/integration/nextjs-integration.md): Canonical onboarding path for any Next.js 15 or 16 site — two SDK helpers, one catch-all editor route, edit through Draft Mode without a /preview route.
- [Manual setup](https://docs.avocadostudio.dev/integration/manual-setup.md): The same wiring the agent prompt does, written out — as one shell block, or as seven steps with the reasoning for each.
- [Astro Integration](https://docs.avocadostudio.dev/integration/astro-integration.md): Add Avocado to an Astro site with one integration in astro.config.ts. The site keeps rendering its own .astro components — no React islands, no rewrite.
- [Non-Next.js Integration](https://docs.avocadostudio.dev/integration/non-nextjs.md): How to implement the editor API contract on Remix, SvelteKit, Hono, or any framework that exposes web-standard Request/Response handlers — using the SDK's framework-agnostic /core primitives. Astro has its own integration.
- [Make the Page Directly Editable](https://docs.avocadostudio.dev/integration/inline-editing.md): Optional second step. Mark the element that draws each field and the preview gains inline text editing, hover pills and image buttons — on top of an integration that already works without it.
- [Coverage checks](https://docs.avocadostudio.dev/integration/coverage.md): Two checks that decide whether an integration is finished: does the rendered page offer every field the manifest declares, and is the property panel intelligible to a person.
- [QA gate: avocado qa](https://docs.avocadostudio.dev/integration/qa.md): One command, run last, that checks an integration the way the editor will use it — in a browser, in a frame on the editor's origin, with edited content — and exits non-zero until it is right.
- [The SDK surface](https://docs.avocadostudio.dev/integration/sdk-surface.md): The map of what the SDK publishes: what you declare, which subpath covers each part, and how to prove it worked. Next.js 15 and 16 on the App Router is the supported path.
- [Block System Architecture](https://docs.avocadostudio.dev/integration/block-system.md): How block schemas and renderers are organized, connected, and used across the stack — from definition to AI planning to rendering.
- [Custom Blocks](https://docs.avocadostudio.dev/integration/custom-blocks.md): Register your own block types with custom schemas, renderers, and props — the AI planner picks them up automatically.
- [Built-in Blocks](https://docs.avocadostudio.dev/integration/built-in-blocks.md): Catalogue of the block types Avocado Studio ships out of the box — schemas, renderers, and field metadata included.
- [File-backed sites (no CMS)](https://docs.avocadostudio.dev/integration/file-backed-sites.md): Make a template with its copy written into the markup editable: move the copy into one JSON file per page, keep the markup and the styles, and publish as a clean git diff.
- [CMS Adapters](https://docs.avocadostudio.dev/integration/cms-adapters.md): Plug any content source — JSON file, Contentful, Sanity, Strapi, custom REST — into Avocado Studio via the CmsAdapter interface.
- [The field table](https://docs.avocadostudio.dev/integration/field-table.md): One declaration of what a CMS-backed site lets Avocado edit, and the four things derived from it.
- [Contentful](https://docs.avocadostudio.dev/integration/contentful.md): The Contentful lens pack: every locale in one document, images and references that publish as real Links, and a publish that refuses to take somebody's draft live.
- [Multilingual content](https://docs.avocadostudio.dev/integration/multilingual.md): Avocado has no locale dimension. A CMS with per-language fields maps onto it as one editable page per (document x language) — how to project it, and the four rules that stop the round trip corrupting content.
- [Publishing](https://docs.avocadostudio.dev/integration/publishing.md): Promote draft content to production. Built-in targets cover Git snapshots, Vercel deploy hooks, and the site-contract POST — which is authenticated, and which refuses a publish that would empty the site.
- [Native Tools](https://docs.avocadostudio.dev/integration/tools-mvp.md): Tool contract and onboarding flow for connecting external services (PIM, DAM, search, AI image generation) to the AI planner.
- [MCP server](https://docs.avocadostudio.dev/integration/mcp-server.md): Drive Avocado Studio from any Model Context Protocol host — 49 tools over stdio or streamable HTTP.
- [Jira Integration](https://docs.avocadostudio.dev/integration/jira.md): Let Avocado Studio act on Jira tickets: review, apply edits, and publish via webhook or polling.
- [API Reference](https://docs.avocadostudio.dev/api-reference/index.md): OpenAPI 3.0.3 reference for the orchestrator's HTTP API. The spec began as the Fastify route table and is now hand-maintained; it trails the running server, and several routes still carry placeholder bodies.
- [This OpenAPI document, as the running server generates it](https://docs.avocadostudio.dev/api-reference/this-openapi-document-as-the-running-server-generates-it.md): Served by `@fastify/swagger`. The copy in the docs site is hand-maintained on top of it.
- [The orchestrator's favicon](https://docs.avocadostudio.dev/api-reference/the-orchestrators-favicon.md): An inline SVG, so a browser opening the API directly does not log a 404.
- [Block types this orchestrator process can render](https://docs.avocadostudio.dev/api-reference/draft/block-types-this-orchestrator-process-can-render.md)
- [Fetch a single draft page by slug](https://docs.avocadostudio.dev/api-reference/draft/fetch-a-single-draft-page-by-slug.md)
- [List draft page slugs with metadata](https://docs.avocadostudio.dev/api-reference/draft/list-draft-page-slugs-with-metadata.md)
- [Seed a session's draft with pages](https://docs.avocadostudio.dev/api-reference/draft/seed-a-sessions-draft-with-pages.md): Fills an empty session from the pages in the body, or from the orchestrator's published pages when the body carries none. Skipped with `status: "skipped"` when the draft is already populated and `overwrite` is not set, and also right after a snapshot restore, so a page refresh cannot overwrite what…
- [Fetch the draft site configuration](https://docs.avocadostudio.dev/api-reference/draft/fetch-the-draft-site-configuration.md)
- [Replace the draft site configuration](https://docs.avocadostudio.dev/api-reference/draft/replace-the-draft-site-configuration.md)
- [The draft content snapshot a publish would write](https://docs.avocadostudio.dev/api-reference/publish/the-draft-content-snapshot-a-publish-would-write.md): What a pull-style publish target fetches: every draft page for the scoped session, plus the site config and a generation timestamp.
- [Field-level diff of the draft against the published site](https://docs.avocadostudio.dev/api-reference/publish/field-level-diff-of-the-draft-against-the-published-site.md): Per page: added, removed, modified or unchanged, with the changed fields named. This is what the publish dialog lists before you choose what to ship.
- [Publish the draft to the live site target](https://docs.avocadostudio.dev/api-reference/publish/publish-the-draft-to-the-live-site-target.md): Computes the diff against the currently-published state first, then hands the selected pages to the registered publish target and records a publish-log row either way. Requires the publish token when one is configured; a `siteOrigin` that is not an allowed URL is refused with 400.
- [Poll publish/deployment status for a session](https://docs.avocadostudio.dev/api-reference/publish/poll-publishdeployment-status-for-a-session.md)
- [Recent publish attempts for a session](https://docs.avocadostudio.dev/api-reference/publish/recent-publish-attempts-for-a-session.md): Rows are written on every publish, successful or not, and matured from `triggered` to `success` or `failed` by a later `GET /publish/status`.
- [Fetch one published page by slug](https://docs.avocadostudio.dev/api-reference/publish/fetch-one-published-page-by-slug.md): The published tier, not the draft: what the site serves when draft mode is off.
- [Plan and apply an edit from a natural-language message](https://docs.avocadostudio.dev/api-reference/chat/plan-and-apply-an-edit-from-a-natural-language-message.md)
- [Generate alternative wordings for a block or field](https://docs.avocadostudio.dev/api-reference/chat/generate-alternative-wordings-for-a-block-or-field.md): Returns every variation in one response. Use `/chat/variations/stream` when the block takes images, so the text arrives before the images finish.
- [Generate variations, streaming images as they resolve](https://docs.avocadostudio.dev/api-reference/chat/generate-variations-streaming-images-as-they-resolve.md): Same body as `/chat/variations`. Responds with `text/event-stream` over the POST body: the text variations arrive immediately with `imagesPending: true`, then one `image_resolved` frame per variant as each image finishes.
- [Guess how a half-typed message will be handled](https://docs.avocadostudio.dev/api-reference/chat/guess-how-a-half-typed-message-will-be-handled.md): Called by the editor as the user types, debounced, so it can say "this edit will be instant" before the request is sent. Costs no tokens — it runs the deterministic-intent check only.
- [Allocate a resumable stream for a chat edit](https://docs.avocadostudio.dev/api-reference/chat/allocate-a-resumable-stream-for-a-chat-edit.md)
- [Cancel a running chat stream](https://docs.avocadostudio.dev/api-reference/chat/cancel-a-running-chat-stream.md)
- [Server-sent events for a chat edit](https://docs.avocadostudio.dev/api-reference/chat/server-sent-events-for-a-chat-edit.md): Three modes. With `streamId` and no `afterSeq` it drives the pipeline allocated by `POST /chat/start`. With both it reconnects: buffered events after `afterSeq` are replayed, then live ones follow. With neither it falls back to a legacy direct stream driven from the query string, which has no resume…
- [Apply a batch of atomic block/page operations](https://docs.avocadostudio.dev/api-reference/operations/apply-a-batch-of-atomic-blockpage-operations.md): Applies every operation or none. The orchestrator validates props against its built-in block registry only; a site's own block types are validated against the manifest the request brings. The editor always sends one — a request written by hand must too: set `componentsManifest` to the site's `GET /a…
- [Describe an uploaded image so the planner can use it](https://docs.avocadostudio.dev/api-reference/media/describe-an-uploaded-image-so-the-planner-can-use-it.md)
- [Search Unsplash for the editor's image picker](https://docs.avocadostudio.dev/api-reference/media/search-unsplash-for-the-editors-image-picker.md): A thin proxy so the access key stays on the server. Returns an empty list rather than an error when Unsplash itself fails.
- [Generate one image from a prompt](https://docs.avocadostudio.dev/api-reference/media/generate-one-image-from-a-prompt.md): Runs on your own key. The provider comes from the body, then `IMAGE_GEN_PROVIDER`, then OpenAI. Asking for Gemini without a Google key falls through to OpenAI rather than failing, because the editor sends a provider hint it inferred from the user's wording. Model overrides on this route: `GOOGLE_GEN…
- [Multi-turn image generation session](https://docs.avocadostudio.dev/api-reference/media/multi-turn-image-generation-session.md): Gemini only — needs `GOOGLE_GENAI_API_KEY`. Keeps a conversation so follow-up prompts refine the last image. `chatId` addresses an existing conversation and is meaningless outside the process that minted it. With `stream: true` the response is `text/event-stream` carrying `chatId`, `text` and `image…
- [Upload an image into the orchestrator's image store](https://docs.avocadostudio.dev/api-reference/media/upload-an-image-into-the-orchestrators-image-store.md)
- [Upload a chat attachment (image or PDF)](https://docs.avocadostudio.dev/api-reference/media/upload-a-chat-attachment-image-or-pdf.md): Stored alongside generated images and served from the same origin. The planner reads the bytes back as native multimodal content blocks, which is why only formats the models accept natively are allowed.
- [Serve a generated or uploaded image](https://docs.avocadostudio.dev/api-reference/media/serve-a-generated-or-uploaded-image.md): Where `/image/generate`, `/image/upload` and `/attachment/upload` put their bytes. Immutable, cached for a year. The filename must match `^[a-zA-Z0-9_-]+\.(png|jpg|jpeg|webp|gif)$`.
- [List images from a Google Drive folder](https://docs.avocadostudio.dev/api-reference/media/list-images-from-a-google-drive-folder.md): The Drive tab of the editor's image picker. Needs `GOOGLE_DRIVE_FOLDER_ID` or Google credentials; otherwise 404, and the editor hides the tab.
- [Download, optimise and serve one Drive image](https://docs.avocadostudio.dev/api-reference/media/download-optimise-and-serve-one-drive-image.md): Converted to WebP and cached immutably, so the picker and the page can reference one stable URL instead of a Drive link.
- [Transcribe a voice recording](https://docs.avocadostudio.dev/api-reference/media/transcribe-a-voice-recording.md): Voice input for the chat composer. Tries OpenAI (`OPENAI_TRANSCRIBE_MODEL`, default `gpt-4o-mini-transcribe`) first, then falls back to Gemini (`GOOGLE_GENAI_TRANSCRIBE_MODEL`, default `gemini-2.5-flash`) when OpenAI fails or is over quota. Either key enables it; with neither, `/status/planner` repo…
- [List media from the site's CMS](https://docs.avocadostudio.dev/api-reference/media/list-media-from-the-sites-cms.md): The CMS tab of the editor's image picker. POST rather than GET because the body carries a token: the standalone server wires no CMS adapter of its own, so the connection details come from the caller — the editor holds one `cmsMedia` block per site it knows about. Contentful, Sanity and Strapi are re…
- [Whether undo and redo are available for a page](https://docs.avocadostudio.dev/api-reference/history/whether-undo-and-redo-are-available-for-a-page.md)
- [The version log for a session](https://docs.avocadostudio.dev/api-reference/history/the-version-log-for-a-session.md): Snapshots are stripped from the rows — they are large and the list view never reads them. The log is capped at 100 entries per session.
- [Step one entry back on a page's undo stack](https://docs.avocadostudio.dev/api-reference/history/step-one-entry-back-on-a-pages-undo-stack.md): Undo and redo stacks are capped at 50 entries per page and direction. A `null` entry means the page did not exist at that point, so undoing onto it removes the page.
- [Step one entry forward on a page's redo stack](https://docs.avocadostudio.dev/api-reference/history/step-one-entry-forward-on-a-pages-redo-stack.md)
- [Restore the page state recorded at one version-log entry](https://docs.avocadostudio.dev/api-reference/history/restore-the-page-state-recorded-at-one-version-log-entry.md)
- [Throw away selected changes from the version log](https://docs.avocadostudio.dev/api-reference/history/throw-away-selected-changes-from-the-version-log.md): Rolls each affected page back to the state it held immediately before the earliest version selected on it. The version log is a per-page timeline, not a stack of independent patches, so "undo this one change and keep the later ones" is not a question the stored data can answer — which is why the res…
- [Whether a password is needed, and whether requests will be accepted at all](https://docs.avocadostudio.dev/api-reference/auth/whether-a-password-is-needed-and-whether-requests-will-be-accepted-at-all.md): Public, because a client has to be able to ask before it holds a credential. The two fields are two questions, and they come apart in exactly one state: a `closed` mount has no password gate, so `gateEnabled` is false, and a client that reads that as "open" renders itself around a site whose every o…
- [Exchange the access password for a bearer token](https://docs.avocadostudio.dev/api-reference/auth/exchange-the-access-password-for-a-bearer-token.md): This route is the password exchange and nothing else. Post `{ password }`; the editor stores the token that comes back and attaches it as `x-access-token` (and as `?accessToken=` on `EventSource`, which cannot send headers). Where the deployment is open by choice, or gated by something other than a…
- [Start the onboarding agent and get a stream id](https://docs.avocadostudio.dev/api-reference/sites-agent/start-the-onboarding-agent-and-get-a-stream-id.md): Creates, migrates or integrates a site. **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) is configured, and answe…
- [Interrupt a running onboarding agent](https://docs.avocadostudio.dev/api-reference/sites-agent/interrupt-a-running-onboarding-agent.md): **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) is configured, and answers 404 when unmounted. In development it…
- [Answer a question the onboarding agent asked](https://docs.avocadostudio.dev/api-reference/sites-agent/answer-a-question-the-onboarding-agent-asked.md): **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) is configured, and answers 404 when unmounted. In development it…
- [Server-sent events for the onboarding agent](https://docs.avocadostudio.dev/api-reference/sites-agent/server-sent-events-for-the-onboarding-agent.md): Buffered events after `afterSeq` are replayed on reconnect. **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) is c…
- [Register or update a site configuration](https://docs.avocadostudio.dev/api-reference/sites/register-or-update-a-site-configuration.md)
- [List sites registered for a session](https://docs.avocadostudio.dev/api-reference/sites/list-sites-registered-for-a-session.md)
- [Remove site configurations](https://docs.avocadostudio.dev/api-reference/sites/remove-site-configurations.md): Admin. Matches by substring, so it can remove more than one; `DELETE /sessions` deliberately requires an exact key instead.
- [The session this caller is bound to, and what it holds](https://docs.avocadostudio.dev/api-reference/sessions/the-session-this-caller-is-bound-to-and-what-it-holds.md): Read-only. An MCP install bound to an embedded site asks this before every destructive edit.
- [Every session this orchestrator has state for](https://docs.avocadostudio.dev/api-reference/sessions/every-session-this-orchestrator-has-state-for.md): `demoPublishedPageCount` counts the bundled demo pages and nothing else. Blocked entirely under `DEMO_MODE`.
- [Forget one session](https://docs.avocadostudio.dev/api-reference/sessions/forget-one-session.md): Admin, and by exact key — a session holds drafts, undo stacks and chat history, so a key matching more than the caller meant is not recoverable.
- [Capture a full-page screenshot of a page](https://docs.avocadostudio.dev/api-reference/preview/capture-a-full-page-screenshot-of-a-page.md): Draft mode targets the site's draft-preview route; `published: true` uses `meta.path` rather than the slug.
- [Liveness, build version and editor protocol version](https://docs.avocadostudio.dev/api-reference/health/liveness-build-version-and-editor-protocol-version.md)
- [Which planner, which providers, and which features are available](https://docs.avocadostudio.dev/api-reference/health/which-planner-which-providers-and-which-features-are-available.md): What the editor reads on load to decide what to show. `availableProviders` reflects the keys this deployment actually has — Avocado runs on your own Anthropic, OpenAI and Google keys. `features.audioTranscription` gates the mic button, `features.imageGenerate` the generate tab, `features.agentMode`…
- [Scan the draft and reconcile its findings](https://docs.avocadostudio.dev/api-reference/checks/scan-the-draft-and-reconcile-its-findings.md): Site-health rules read the pages and report metadata, structure, link and image problems. A run also reconciles existing findings: one that the rules no longer see becomes `fixed`. Runs automatically in the background after a successful publish.
- [What is currently wrong with the site](https://docs.avocadostudio.dev/api-reference/checks/what-is-currently-wrong-with-the-site.md): Newest and most severe first. Snoozed findings past their wake time are reopened before the list is built.
- [Dismiss, snooze or reopen one finding](https://docs.avocadostudio.dev/api-reference/checks/dismiss-snooze-or-reopen-one-finding.md): `fixed` is not accepted: that is reconciliation's word, meaning a run looked and the problem was gone. Letting a client assert it would put a finding into a state the next run immediately contradicts.
- [The check-run ledger, including what each run cost](https://docs.avocadostudio.dev/api-reference/checks/the-check-run-ledger-including-what-each-run-cost.md)
- [List publish snapshots that can be restored](https://docs.avocadostudio.dev/api-reference/restore/list-publish-snapshots-that-can-be-restored.md): Snapshots are git commits written by a publish, addressed by hash. A deployment that is not a checkout has no history, and answers with an empty list rather than an error.
- [Replace the draft with the pages published in one commit](https://docs.avocadostudio.dev/api-reference/restore/replace-the-draft-with-the-pages-published-in-one-commit.md): The draft is cleared and refilled rather than merged, so the restore reproduces that commit exactly instead of resurrecting pages the snapshot does not contain. The session is marked recently-restored, which is what stops the next bootstrap seeding from overwriting it.
- [Drop a snapshot by reverting the commit that published it](https://docs.avocadostudio.dev/api-reference/restore/drop-a-snapshot-by-reverting-the-commit-that-published-it.md)
- [Recent chat pipeline traces](https://docs.avocadostudio.dev/api-reference/telemetry/recent-chat-pipeline-traces.md): One row per chat turn: the phases it went through, what it cost, and how it ended.
- [Chat traces arranged for review](https://docs.avocadostudio.dev/api-reference/telemetry/chat-traces-arranged-for-review.md): The same records as `/telemetry/chat`, grouped for reading a session back rather than for filtering.
- [Thumbs up/down left on chat turns](https://docs.avocadostudio.dev/api-reference/telemetry/thumbs-updown-left-on-chat-turns.md)
- [Record a thumbs up or down on one chat turn](https://docs.avocadostudio.dev/api-reference/telemetry/record-a-thumbs-up-or-down-on-one-chat-turn.md)
- [Start an agent run and get a stream id](https://docs.avocadostudio.dev/api-reference/agent/start-an-agent-run-and-get-a-stream-id.md): An open-ended agent loop over the session's content tools, as an alternative to the planner. Needs `AGENT_API_KEY` (Anthropic or OpenAI). **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all w…
- [Abort a running agent loop](https://docs.avocadostudio.dev/api-reference/agent/abort-a-running-agent-loop.md): **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) is configured, and answers 404 when unmounted. In development it…
- [Server-sent events for an agent run](https://docs.avocadostudio.dev/api-reference/agent/server-sent-events-for-an-agent-run.md): The first connection starts the loop; a reconnect replays buffered events after `afterSeq`. **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `…
- [Run an agent loop to completion in one request](https://docs.avocadostudio.dev/api-reference/agent/run-an-agent-loop-to-completion-in-one-request.md): The blocking, non-SSE variant, for tests and scripts. **Not mounted in production unless `AGENT_SURFACE=on`.** The agent routes run open-ended loops with file and shell tools, so the surface refuses to mount at all when no credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) is configu…
- [Receive a Jira issue event](https://docs.avocadostudio.dev/api-reference/jira/receive-a-jira-issue-event.md): The second input channel: move a ticket into the configured review status and Avocado plans the change, applies it to the draft, and posts a preview link back on the issue. Requires `JIRA_BASE_URL` and `JIRA_API_TOKEN`, and the shared secret in the `x-jira-webhook-secret` header or a `secret` query…
- [Process one Jira ticket now](https://docs.avocadostudio.dev/api-reference/jira/process-one-jira-ticket-now.md): The manual trigger, for re-runs and testing. Unlike the webhook this waits for the work to finish.
- [Jira integration configuration and poller state](https://docs.avocadostudio.dev/api-reference/jira/jira-integration-configuration-and-poller-state.md)
- [Docker deployment](https://docs.avocadostudio.dev/operations/docker-deployment.md): Deploy the orchestrator as a self-contained Docker image. Avocado Studio is Apache 2.0 licensed and self-hostable — Docker is the supported path for running it on your own infrastructure.
- [Vercel deployment](https://docs.avocadostudio.dev/operations/vercel-deployment.md): What of Avocado Studio can run on Vercel, what cannot keep its state there, and the variables each project needs.
- [Deploy to Netlify](https://docs.avocadostudio.dev/operations/netlify-deployment.md): Deploy a site that uses Avocado Studio, and the editor, to Netlify, with the orchestrator on a host that keeps its state.
- [Demo mode](https://docs.avocadostudio.dev/operations/demo-mode.md): Run a locked-down public playground on a shared API key. Server-enforced allow-list, per-IP isolation, rate limiting, no image gen.
- [Security and access](https://docs.avocadostudio.dev/reference/security.md): What is open, what is closed by default, the two credentials, the production gate, and the agent surface that stays off unless you turn it on.
- [Environment reference](https://docs.avocadostudio.dev/reference/environment.md): Every environment variable Avocado Studio reads, grouped by what it configures, with which process reads it, its default, and what happens when it is unset.
- [State and backups](https://docs.avocadostudio.dev/operations/state-and-backups.md): Where the orchestrator keeps draft pages, history and sessions, what is not persisted, how snapshots work, and what a clean shutdown does.
- [Chat troubleshooting](https://docs.avocadostudio.dev/observability/chat-troubleshooting.md): Playbook for investigating prompt failures, wrong operations, and regressions in the chat assistant.
- [Chat telemetry events](https://docs.avocadostudio.dev/observability/chat-telemetry-events.md): Reference for all telemetry events emitted by the orchestrator chat pipeline.
- [Token usage tracking](https://docs.avocadostudio.dev/observability/token-usage-tracking.md): How the orchestrator tracks LLM token usage and estimated cost across debug panel, logs, and telemetry.
- [CLI and packages](https://docs.avocadostudio.dev/reference/cli.md): The commands Avocado Studio ships, every flag each one takes, and what each of the twelve published packages is for.
- [Glossary](https://docs.avocadostudio.dev/reference/glossary.md): The words these docs use for Avocado-specific things, in one place — for the meeting where a marketer and a developer are describing the same thing differently.
- [Block Schema Contracts](https://docs.avocadostudio.dev/specs/block-schema-contracts.md): How block schemas are described to the LLM planner, how contracts are assembled, and why we use prop-list contracts instead of JSON Schema.
- [Changelog](https://docs.avocadostudio.dev/changelog.md): What changed in each release of the @avocadostudio-ai packages, what you have to change when you upgrade, and why all twelve packages share one version.

## OpenAPI Specs

- [orchestrator.openapi](/api-reference/orchestrator.openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.