diff --git a/apps/docs/client/src/content/deco-studio/en/studio/agentic-cms.mdx b/apps/docs/client/src/content/deco-studio/en/studio/agentic-cms.mdx
index 1987812338..4f774f45d8 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/agentic-cms.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/agentic-cms.mdx
@@ -52,6 +52,16 @@ If you're coming from deco.cx, the Agentic CMS is the same product line — same
Existing deco.cx projects continue to work. Migration adds the agent layer; it doesn't replace your codebase.
+## Blocks form: field descriptions
+
+When you edit a section or block's props, each field's description (from its schema's `.describe()`) shows as text underneath the field's title by default — the same layout deco.cx has always used.
+
+You can switch a site to show descriptions as a tooltip instead: hover the field's title to reveal it, which keeps forms shorter and easier to scan, especially on dense blocks. This is opt-in and set **per site**, from the site's **Settings**, next to the **Production URL** field. Turning it on doesn't change anything for other sites in your org.
+
+
+ Prefer the tooltip on content-heavy blocks with many fields — it keeps the form compact without losing the schema's guidance text.
+
+
## Getting started
Open Studio, find the **deco Site Editor** agent and point it at your site.
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/agents.mdx b/apps/docs/client/src/content/deco-studio/en/studio/agents.mdx
index 96f4975a34..ba36150dec 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/agents.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/agents.mdx
@@ -60,37 +60,63 @@ Authoring an MCP app uses the `@decocms/runtime` framework (React 19 + Tailwind
In a future release, Studio will let you build simple views directly inside the agent UI, without scaffolding a repo. For anything custom or production-grade today, start from the template repo above.
+### Files and skills
+
+In an agent's **Settings** tab, **Files and skills** lets you attach files (reference docs, data) and skills the agent can always read, alongside its tools and instructions.
+
+
+ Each attached file is capped at 25MB. Selecting a larger file skips the upload and shows a warning naming the rejected file — split large files or trim them before attaching.
+
+
### Sandbox
An agent can be backed by code. Link it to a GitHub repository in **Settings → Sandbox** and Studio will run the repo as an isolated dev environment scoped to that agent — typically the agent's own MCP server, but it can be any service the agent needs. The sandbox starts on demand, lives only as long as the agent needs it, and never leaks across agents.
+The repo picker lists forks alongside your own repositories, marked with a **Fork** badge. A fork only imports successfully if the GitHub App installation was also granted access to it — if not, importing fails with a prompt to add the fork under **GitHub → Settings → Installations**.
+
When the agent is running with a local code-editor runtime, **Open in VSCode** and **Open in Cursor** buttons appear directly in the tab bar for one-click access to the repo on your machine. In other runtime modes the same options are available in the tab bar's three-dot (⋯) menu.
-## Where an agent runs
+### Fast Preview
-Above the chat input, next to the model picker, is the **runtime picker**. It controls *where* the agent executes and *which harness* drives it. There are two groups:
+For agents backed by the Agentic CMS, **Settings → CMS** groups content-editing options into three subsections:
-**Cloud**
+- **Preview** — a **preview server** URL (your live site's address) and a **Fast Preview** switch. With Fast Preview on, the **Preview** tab renders the current draft directly against your preview server instead of booting the sandbox's dev server — useful for a much faster preview loop once a preview server is configured. The switch stays disabled until a preview server URL is set.
+- **Publishing** — the existing publish-policy picker (who can publish changes).
+- **Editing** — content-editing preferences: **Compact descriptions** (show field descriptions as tooltips instead of inline text), **Auto-open editor** (open the CMS automatically when the agent's Preview tab loads), and **Team sync** (agents linked to a GitHub repo only — see [Sync with your team](#sync-with-your-team) below).
-- **Decopilot** — _"Runs in an agent sandbox."_ The agent executes in a sandbox managed by Studio. This is the default, always available, with nothing to install.
+
+ Fast Preview never renders your published site — it always shows the sandbox's draft (or a "booting" state while the sandbox provisions), just sourced from your preview server instead of a locally running dev server.
+
-**Local** — run the agent on your own machine. Until a local runtime is connected, these options read **"Desktop not detected"** and stay disabled.
+### Sync with your team
-- **Decopilot** — the Decopilot harness, running on your desktop
-- **Claude Code** — drives the agent with the [Claude Code](https://claude.com/claude-code) CLI
-- **Codex** — drives the agent with the Codex CLI
+For agents linked to a GitHub repo, turning on **Team sync** (**Settings → CMS → Editing**) adds a **Sync** button next to the review/publish actions in the thread header. It's off by default.
-Running locally means the agent's sandbox lives on your machine: it can read and write your local files, use your installed tooling, and run with your own credentials — while Studio still handles the chat, connections, and logging. The cloud sandbox, by contrast, is fully managed and isolated per agent.
+Clicking **Sync** sends one deterministic instruction to the agent: commit any pending local changes, `git pull --rebase` the branch (picking up commits a teammate pushed straight to it), rebase onto the latest base branch, resolve any conflicts, and push. This lets a teammate who doesn't know git catch a branch up with everyone else's work in one click, instead of having to ask what commands to run.
-To enable the local options, connect a desktop runtime with `deco link`. Studio detects the connection and lights up whichever harnesses it exposes — **Claude Code** and **Codex** appear once their CLI is available on the linked machine.
+## Where an agent runs
+
+Above the chat input, next to the model picker, is the **runtime picker**. It controls *which harness* drives the agent.
+
+- **Decopilot** — _"Runs in an agent sandbox."_ The agent executes in a sandbox managed by Studio. This is the default, always available, with nothing to install.
+
+The agent's sandbox is fully managed and isolated per agent — Studio handles the chat, connections, logging, and the runtime itself, so there is nothing to install or connect on your own machine.
- Cloud is the right default for unattended runs and teammates who shouldn't need a local setup. Reach for a local runtime when the agent needs your machine — your files, your credentials, or a coding harness like Claude Code or Codex.
+ The managed sandbox is the right default for every run, attended or unattended — teammates never need a local setup to use an agent.
-## Windows
+### Studio Native: coding-agent terminals
+
+The Studio Native desktop app adds a second, separate way to work with code. Starting a brand-new thread in Studio Native shows a **"Choose a coding agent"** picker instead of the usual chat composer — pick **Claude Code**, **Codex**, or **OpenCode** and Studio launches that CLI as a live, interactive terminal (an embedded `xterm.js` session) inside the thread, using whichever installation it detects on your machine. If a CLI isn't detected, a **"try anyway"** option launches it regardless.
+
+The choice is permanent for that thread: reopening it reattaches to the running session (or resumes the CLI's own saved conversation) instead of showing the picker again. Studio still tracks the thread in your sidebar and gives the CLI a scoped MCP connection (`cms`) back into your org's tools, but everything you type goes straight to the CLI's own interface — Studio does not parse or replay its output as chat messages.
+
+
+ This picker only appears in the Studio Native desktop app, and only for a brand-new thread — it is unrelated to the managed **Decopilot** runtime described above, which is available in both the desktop app and the web app.
+
-The daemon runs natively on Windows with one prerequisite: **[Git for Windows](https://gitforwindows.org)** — it provides both `git` and the bash shell used to run your project's dev scripts. If the daemon reports "POSIX shell (sh) not found", install Git for Windows or set the `DECO_SHELL` environment variable to a bash-compatible shell. WSL2 remains a fully supported alternative. Org file mounts are not yet available on Windows.
+In Studio Native, opening a branch clones a local working tree for it on disk, which stays there as long as at least one thread on that branch is open. Archiving the **last** open thread on a branch now offers to reclaim it — stopping everything running on that branch and deleting its files from your computer. This is opt-in per archive, only affects the local clone, and does not touch the branch itself or anything already pushed to the remote.
## An agent is a virtual MCP
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/ai-providers.mdx b/apps/docs/client/src/content/deco-studio/en/studio/ai-providers.mdx
index 9fbda2117d..86ed5d1f5b 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/ai-providers.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/ai-providers.mdx
@@ -71,6 +71,21 @@ When Studio runs locally (via `bunx -p decocms deco`), two extra providers light
These don't appear in the cloud product.
+## Your Claude subscription (bring your own plan)
+
+Sandbox-hosted coding runs (Task Board's Super Agent, and other flows that dispatch a `claude-code` run into a cloud sandbox) normally bill against the organization's connected AI credit. If you'd rather pay for your own coding runs out of your personal **Claude Pro or Max** plan, link it under **Settings → AI Providers → Your Claude subscription**:
+
+1. On your own machine, run `claude setup-token` and copy the token it prints.
+2. Paste the token into the **Your Claude subscription** card and click **Link**.
+
+Once linked, your own runs use your plan instead of the org's credit — it outranks the org's configured Thinking-tier provider for sandbox-hosted `claude-code` runs specifically. If Anthropic invalidates the token (e.g. it expires), Studio falls back to the org's credential automatically rather than failing the run; the card shows an **expired** state so you know to generate a new token.
+
+Click **Disconnect** to unlink your subscription at any time.
+
+
+This only affects sandbox-hosted `claude-code` runs. It's unrelated to the **Claude Code** local-only provider above, which drives a CLI on your own machine.
+
+
## How a provider gets connected
**API key** — the most common method. Paste the key from your provider's dashboard. It's stored encrypted and never exposed to your team.
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/architecture.mdx b/apps/docs/client/src/content/deco-studio/en/studio/architecture.mdx
index 387125b7e0..fbf40b3e47 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/architecture.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/architecture.mdx
@@ -1,6 +1,6 @@
---
title: "Architecture"
-description: How Studio is wired end to end — edge, cloud cluster, and desktop — and how requests, runs, and sandboxes flow between the tiers.
+description: How Studio is wired end to end — edge and cloud cluster — and how requests, runs, and sandboxes flow between the tiers.
icon: Network
---
@@ -9,31 +9,29 @@ import ArchitectureDiagram from "../../../../components/ArchitectureDiagram.astr
This page describes how a running Studio deployment is wired together: the tiers, what each one does, and how a request becomes an agent run, a tool call, or a sandbox preview. It's useful background whether you self-host or use the cloud, and it's the conceptual companion to the [Kubernetes](/en/studio/self-hosting/deploy/kubernetes) and [Docker Compose](/en/studio/self-hosting/deploy/docker-compose) deploy guides.
-## The three tiers
+## The two tiers
-Studio spans three trust/locality boundaries:
+Studio spans two trust/locality boundaries:
- **Edge** — the public internet path: a CDN and an L4 load balancer.
- **Cloud cluster** — the Kubernetes deployment: web, API, workers, Postgres, NATS, and cloud sandboxes.
-- **Desktop** — the user's laptop, connected by `deco link`, where the desktop loop and desktop sandbox can run.
The same flow as text:
```
-EDGE CLOUD CLUSTER DESKTOP
-──── ───────────── ───────
+EDGE CLOUD CLUSTER
+──── ─────────────
Client ─▶ CF ─┬─▶ NLB ─▶ Web(nginx) ─▶ API ──┬─▶ MCP Proxy ─▶ Downstream MCP (ext)
│ ├─▶ Files/Storage ─▶ Object Store (ext)
│ ├─▶ DB (Postgres)
- │ ├─▶ NATS ───────────────▶ Link Daemon
- │ └─▶ Worker │
- │ │ model ▼
- │ ├──────────▶ LLM Desktop Loop ─▶ Desktop Sandbox
- │ ├─▶ DB │ └─ Org FS (mount)
- │ ├─▶ Files/Storage └─(MCP presigned)─▶ API
+ │ └─▶ Worker
+ │ │ model
+ │ ├──────────▶ LLM
+ │ ├─▶ DB
+ │ ├─▶ Files/Storage
│ ├─▶ Downstream MCP (in-process bridge)
│ └─▶ Cloud Sandbox ─┬─ Daemon API (/_sandbox/*)
│ └─ Org FS (sidecar) ─▶ /api/:org/fs ─▶ S3
@@ -70,7 +68,7 @@ The set of queues a worker pod listens on is configured by env (`listenQueues`).
| Component | Role |
| --- | --- |
| **DB** (PostgreSQL, via Kysely) | System of record: orgs, connections, credential vault, audit, threads + messages, and `sandbox_runner_state`. It also holds the **DBOS queues and `workflow_status` journal** that make runs durable and recoverable. |
-| **NATS** | Live messaging infrastructure with three jobs: (1) JetStream `/stream` fan-out (`decopilot.stream.`) → UI live tail; (2) the pull work-queue (`link.work.`) → desktop; (3) the link-claim KV (`studio_links`) tracking which pod owns each user's link. |
+| **NATS** | Live messaging infrastructure: JetStream `/stream` fan-out (`decopilot.stream.`) → UI live tail. |
**The event bus is dormant.** The CloudEvents pub/sub *feature* (`EVENT_PUBLISH`/`EVENT_SUBSCRIBE`, the durable event queue, `ON_EVENTS` subscribers) is only consumed by the workflow plugin, which is not in use. NATS itself is **not** dormant — it serves the live jobs listed above. Don't conflate the two.
@@ -86,10 +84,18 @@ The set of queues a worker pod listens on is configured by env (`listenQueues`).
4. Output chunks are published to NATS and tailed back to the UI over `/stream`.
5. If the pod crashes, **DBOS journal replay** resumes retriable steps on another pod — recovery is the framework's job, not hand-rolled.
-There are two transports for step 3:
+The run executes in-process on the worker and uses a **cloud sandbox**.
-- **Hosted** (default) — the run executes in-process on the worker and uses a **cloud sandbox**.
-- **Pull** — the run is published to NATS `link.work.`; the user's **desktop** picks it up and runs the loop locally against a **desktop sandbox**.
+### Harnesses: where the agent loop actually runs
+
+The step above is the default path — it doesn't cover every hosted run. Two harnesses can back a hosted run:
+
+- **Decopilot** (default) — runs in-process on the worker, as described above.
+- **claude-code** — runs *inside the sandbox pod* instead, next to the checkout the daemon already cloned, driven by the Claude Agent SDK. The daemon execs `packages/harness-runner` per run over the `/_sandbox/dispatch` control surface (one process per run over stdin/stdout, not a long-lived server) and streams frames back over NDJSON. The runner translates the SDK's message stream into the same `UIMessageChunk`s Decopilot produces, so the run projector, `thread_message_parts`, and the chat UI need no new part types.
+
+claude-code is opt-in per org (`claude_code_sandbox_enabled`, default off). Task Board's Super Agent tasks use it only when the org has opted in **and** has at least one importable repo. With exactly one repo, dispatch resolves and checks it out up front; with several, the run dispatches into an empty working directory and the `TASK_ADD_REPO` tool lets the agent clone the right repo into the already-running pod once it decides which one to use. Otherwise those tasks run Decopilot exactly as before.
+
+Credential resolution for a sandbox-hosted claude-code run checks the dispatching user's own linked Claude subscription first (see [AI Providers](/en/studio/ai-providers)) — a live, unexpired token there outranks the org's Thinking-tier provider, since the user asked for their own plan to pay. It falls back to the org's credential when no personal subscription is linked or the token has expired, rather than failing the run.
## MCP: in-process vs. the proxy routes
@@ -110,36 +116,18 @@ File and object-storage routes are the genuine "called by both" surface, and the
## Sandboxes
-A sandbox clones the repo, runs the dev server, and exposes an in-pod **daemon**. Its HTTP surface splits in two:
+A sandbox clones the repo, runs the dev server, and exposes an in-pod **daemon**, provisioned by the agent-sandbox operator as a `SandboxClaim` pod per (user, projectRef). Its HTTP surface splits in two:
| Surface | Auth | Purpose | Caller |
| --- | --- | --- | --- |
| **Preview** (catch-all `*`) | None — the handle (subdomain) is the secret | Reverse-proxies the running dev server (the live app preview); injects HMR. `/_sandbox/*` is actively rejected here. | The end user's browser at `.preview.`, through **Cloudflare** (LB) → a **Kubernetes Gateway** (Istio Gateway API / HTTPRoute) → the daemon |
| **Daemon API** (`/_sandbox/*`) | Bearer `DAEMON_TOKEN` | Control surface: fs ops (read/write/edit/bash/grep), git (status/diff/publish), exec scripts, setup (clone → install → start), tasks, SSE events, harness dispatch. | The cluster (worker for agent fs/git/bash tools; API for UI setup + events) |
-### Cloud vs. desktop sandboxes
-
-| | Cloud sandbox | Desktop sandbox |
-| --- | --- | --- |
-| Where | agent-sandbox operator + a `SandboxClaim` pod per (user, projectRef) | Same daemon, spawned locally on the laptop |
-| Reached over | k8s port-forward / in-cluster Service (control); ingress or port-forward (preview) | loopback (control); `.localhost:` (preview) |
-| Selected when | the default for hosted runs | a `deco link` is live — `user-desktop` is the default provider then |
-
### Org filesystem (org-fs)
Each sandbox can mount the **org filesystem** at `/org/`, so the agent and dev server read and write org files as ordinary paths. The mount stack is `rclone (NFS/FUSE) → the daemon's loopback WebDAV → /api/:org/fs/* → S3` — the same object store as the file routes, surfaced as a mounted volume. This is the same filesystem you browse in the [Library](/en/studio/library).
-It is wired on **both** providers, with different mount mechanics:
-
-| | Cloud sandbox | Desktop sandbox |
-| --- | --- | --- |
-| Who mounts | a **privileged sidecar** container (the unprivileged daemon can't mount) | the **daemon directly** (it has full permissions) |
-| Config delivery | post-bind: Studio `POST /_sandbox/orgfs-config`; the daemon relays it to a shared control volume the sidecar watches (warm-pool claims reject `spec.env`) | boot env: `ORGFS_CONFIG`, mounted at daemon startup |
-| Propagation | `rclone` with `allowOther` so the mount propagates to the main container | single client — no propagation needed |
-
-## Desktop
-
-When a user runs `deco link`, a **Link Daemon** on their laptop long-polls the cluster (`/api/links/work` for chat, `/api/links/proxy` for sandbox control) and heartbeats presence into the NATS link-claim KV. Pulled runs execute in the **Desktop Loop** (`runNativeAgentLoopCore`) — a portable copy of the agent loop. The thinking model is injected by the cluster, and MCP is reached over HTTP via a presigned URL back to the cluster.
+The mount is wired via a **privileged sidecar** container (the unprivileged daemon can't mount itself): Studio delivers config post-bind via `POST /_sandbox/orgfs-config`, the daemon relays it to a shared control volume the sidecar watches (warm-pool claims reject `spec.env`), and `rclone` mounts with `allowOther` so the mount propagates to the main container.
## At a glance
@@ -148,4 +136,5 @@ When a user runs `deco link`, a **Link Daemon** on their laptop long-polls the c
- **MCP tool calls are in-process** on the worker; the `/mcp/*` proxy routes are for external clients only.
- **File/object-storage routes** are the shared API+worker surface.
- **NATS is live**; the CloudEvents event-bus feature is dormant.
-- **Sandboxes** expose a public preview and a token-protected control API, in the cloud (k8s) or on the desktop (`deco link`).
+- **Sandboxes** expose a public preview and a token-protected control API in the cloud (k8s).
+- **Hosted runs** default to the Decopilot harness (in-process on the worker); the opt-in claude-code harness runs inside the sandbox pod instead, one `harness-runner` process per run.
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/automations.mdx b/apps/docs/client/src/content/deco-studio/en/studio/automations.mdx
index a7cf0f61cb..6aed39c9de 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/automations.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/automations.mdx
@@ -77,7 +77,7 @@ Fires when an external system sends an HTTP request to a dedicated URL. When you
- Each run times out after 5 minutes
- Event payloads are capped at 1 MB
-If the person who created an automation leaves the organization, it's automatically deactivated.
+If the person who created an automation leaves the organization, it's automatically deactivated. The same happens if a run hits an unrecoverable error — for example, the automation's configured model is no longer allowed for its role after a permission change — so it stops retrying and failing silently and shows a clear deactivation reason in [Monitoring](/en/studio/monitoring) instead.
---
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/concepts.mdx b/apps/docs/client/src/content/deco-studio/en/studio/concepts.mdx
index 196f6fa910..cbb3bc4b8e 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/concepts.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/concepts.mdx
@@ -17,6 +17,7 @@ Studio uses a small set of concepts that build on each other. Once you understan
- **Automation** — an agent run that fires on a schedule or in response to an event. See [Automations](/en/studio/automations).
- **AI Provider** — a configured AI model (Anthropic, Google, OpenRouter, or the Deco AI Gateway) that powers your agents and Decopilot. See [AI Providers](/en/studio/ai-providers).
- **Member** — a person in your organization with a role and permissions.
+- **Task Board** — a kanban board for tracking work items an agent is doing on your behalf, with optional automated review before changes ship. See [Task Board](/en/studio/task-board).
---
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/connections.mdx b/apps/docs/client/src/content/deco-studio/en/studio/connections.mdx
index 56837e4a5e..77c7394e6a 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/connections.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/connections.mdx
@@ -47,6 +47,10 @@ Connections solve this by being the single source of truth:
All connection types work the same way: configure once at the org level, attach to whichever agents need them.
+
+ A connection's URL must resolve to a public address. Studio blocks URLs that point at private or internal-network addresses (including ones reached via a redirect) — this applies when you create or update a **Custom Connection**, and on every health check Studio runs against it afterward. A connection pointing at a private address is reported as unhealthy rather than probed.
+
+
### Transports
Under the hood, every connection uses one of these transports. You don't usually need to think about it — Studio picks the right form based on the catalog entry or what you paste into **Custom Connection** — but it matters when you're wiring up an MCP server yourself:
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/decopilot/context-and-tasks.mdx b/apps/docs/client/src/content/deco-studio/en/studio/decopilot/context-and-tasks.mdx
index 8879d092fb..f9f1cf3d50 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/decopilot/context-and-tasks.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/decopilot/context-and-tasks.mdx
@@ -15,12 +15,26 @@ A **task** is your conversation with Decopilot — where you chat, Decopilot use
Every task has one of four states:
- **In progress** — the agent is working or waiting for your next message
-- **Requires action** — paused, waiting for your input (a tool needs approval, or it asked you a question)
+- **Requires action** — paused, waiting for your input. This is set only when there's a pending tool call that needs you — a tool-approval request or a `user_ask` — never just because the reply's text happens to contain a question mark (e.g. a rhetorical question, or a URL with a `?` query string)
- **Completed** — work finished successfully
- **Failed** — something went wrong, or the task timed out
Tasks time out after **30 minutes of inactivity**. If you're working on something longer, send a message periodically to keep it active.
+Tasks assigned to a specialist agent show up as cards on the **task board**, where you can filter, prioritize, and track them across lanes.
+
+### Re-running a stuck task
+
+Occasionally a task assigned to the agent never actually starts a run, or its run gets wedged — the card sits in **In progress** or **Requires action** indefinitely with no activity. Since there's no state change left to react to, the agent won't pick it back up on its own.
+
+Select **Re-run** on the card (or from the task dialog) to force a fresh run. This closes out any run still open on the task and queues a new one from the same assignee.
+
+
+Re-run is a takeover: it stops whatever run is currently open on the task, even if it's still streaming, before starting the new one. Use it only when you're confident the current run is stuck, not just slow.
+
+
+Re-run only applies to tasks already assigned to the agent — reassigning a task to an agent already queues a run on its own, so it doesn't need this action.
+
---
## How memory fills up
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/decopilot/overview.mdx b/apps/docs/client/src/content/deco-studio/en/studio/decopilot/overview.mdx
index 45b2eed031..679fa59fb4 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/decopilot/overview.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/decopilot/overview.mdx
@@ -80,16 +80,6 @@ When an agent is backed by a sandbox (a linked GitHub repo), Decopilot also gets
Sandboxes also mount the **organization filesystem** under `org/`: `org/home/` is the org's shared home — editable, free-form, shared across every member, agent, and run, where agents record durable knowledge and check for context before starting work; `org/upload` holds the files attached to the current conversation (chat attachments land there automatically — no copy step); `org/output` is the current run's shared output folder; and `org/public/` exposes curated read-only skill sets synced from versioned repositories. Files written to the home folder and `org/output` sync to your organization's cloud storage and are visible to every member and agent; external changes appear inside the sandbox within about a second.
-
- **macOS desktop links:** when a sandbox runs on your machine (`deco link`),
- the `org/` folders are network volumes, and macOS asks once per app for
- permission to access them. Approve the "access files on a network volume"
- prompt for your terminal or editor — or enable it manually under **System
- Settings → Privacy & Security → Files & Folders → _your app_ → Network
- Volumes**. Without the grant, reads and writes in `org/` fail with
- "Operation not permitted".
-
-
For the full reference, see [Tools](/en/studio/decopilot/tools).
---
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/quickstart.mdx b/apps/docs/client/src/content/deco-studio/en/studio/quickstart.mdx
index 7886750ed0..bd7cb6dcf3 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/quickstart.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/quickstart.mdx
@@ -53,7 +53,7 @@ When you're ready to build a focused, reusable worker, create a dedicated agent.
Use the **+** / "Browse agents" button in the sidebar to create a new agent. Once it's open, the screen splits in two:
-- **Left** — the chat. Above the input are the **model-tier picker** and the **runtime picker** (where the agent runs — cloud or your own machine; see [Agents](/en/studio/agents#where-an-agent-runs)).
+- **Left** — the chat. Above the input are the **model-tier picker** and the **runtime picker** (where the agent runs; see [Agents](/en/studio/agents#where-an-agent-runs)).
- **Right** — a tabbed panel. The **Settings** tab holds instructions, connections, and files; **Automations** holds schedules and triggers. Other tabs (Preview, Content, Review changes) appear only for agents backed by a repo or site.
Open the **Settings** tab and write a one-line instruction describing what this agent should do.
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/authentication.mdx b/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/authentication.mdx
index 5387f08749..8f661ead56 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/authentication.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/authentication.mdx
@@ -17,10 +17,10 @@ deco Studio uses Better Auth and supports:
## Configure auth (self-hosting)
-Self-hosted deployments load an `auth-config.json` file at startup (see your deployment guides for mounting details).
+Self-hosted deployments are configured entirely through `AUTH_*` environment variables (schema: `apps/api/src/auth/auth-env.ts`). There is no config file to mount — set the variables below on the `studio` service/container.
- Keep provider secrets out of Git. In production, use Secrets management (Kubernetes Secrets, External Secrets Operator, etc.).
+ Keep provider secrets out of Git. In production, use Secrets management (Kubernetes Secrets, External Secrets Operator, etc.), not plain `.env` files.
## Key environment variables
@@ -28,6 +28,43 @@ Self-hosted deployments load an `auth-config.json` file at startup (see your dep
- `BETTER_AUTH_SECRET` (required)
- `BETTER_AUTH_URL` / `BASE_URL` (recommended to set explicitly in production)
+### Email/password
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AUTH_EMAIL_PASSWORD_ENABLED` | `true` | Set to `false` to disable email/password sign-in. |
+
+### Social login
+
+| Variable | Description |
+| --- | --- |
+| `AUTH_GOOGLE_CLIENT_ID` / `AUTH_GOOGLE_CLIENT_SECRET` | Google OAuth app credentials. |
+| `AUTH_GITHUB_CLIENT_ID` / `AUTH_GITHUB_CLIENT_SECRET` | GitHub OAuth app credentials. |
+
+### Email providers (invites, reset password, magic link, OTP)
+
+| Variable | Description |
+| --- | --- |
+| `AUTH_RESEND_API_KEY` / `AUTH_RESEND_FROM_EMAIL` | Resend provider credentials. |
+| `AUTH_SENDGRID_API_KEY` / `AUTH_SENDGRID_FROM_EMAIL` | SendGrid provider credentials. |
+| `AUTH_INVITE_EMAIL_PROVIDER` | `resend` or `sendgrid` — which provider sends org invite emails. |
+| `AUTH_RESET_PASSWORD_EMAIL_PROVIDER` | `resend` or `sendgrid` — which provider sends password reset emails. |
+
+### Magic link and email OTP
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AUTH_MAGIC_LINK_ENABLED` | `false` | Enable passwordless sign-in via emailed link. |
+| `AUTH_MAGIC_LINK_EMAIL_PROVIDER` | — | `resend` or `sendgrid`. Required if magic link is enabled. |
+| `AUTH_EMAIL_OTP_ENABLED` | `false` | Enable passwordless sign-in via emailed one-time code. |
+| `AUTH_EMAIL_OTP_EMAIL_PROVIDER` | — | `resend` or `sendgrid`. Required if email OTP is enabled. |
+| `AUTH_EMAIL_OTP_LENGTH` | provider default | Code length. |
+| `AUTH_EMAIL_OTP_EXPIRES_IN` | provider default | Code expiry, in seconds. |
+
+
+ Any `*_EMAIL_PROVIDER` variable must reference a provider that has its API key set (`AUTH_RESEND_API_KEY` or `AUTH_SENDGRID_API_KEY`) — the app fails validation at startup otherwise.
+
+
## Deployment-wide SSO (OIDC)
For self-hosted deployments where every user should authenticate through a
@@ -89,9 +126,9 @@ so only users from your domain can sign in.
### Social login vs. SSO
These env vars wire up **OIDC SSO** (the `@better-auth/sso` plugin). They are
-separate from the **social login** buttons configured via `auth-config.json`
-(`socialProviders.google`, `socialProviders.github`) or via
-`AUTH_GOOGLE_CLIENT_ID` / `AUTH_GITHUB_CLIENT_ID`. Social login lets users
-authenticate with their personal account; deployment-wide SSO routes everyone
-matching `AUTH_SSO_DOMAIN` through the corporate IdP.
+separate from the **social login** buttons configured via
+`AUTH_GOOGLE_CLIENT_ID` / `AUTH_GITHUB_CLIENT_ID` (see [Social
+login](#social-login) above). Social login lets users authenticate with
+their personal account; deployment-wide SSO routes everyone matching
+`AUTH_SSO_DOMAIN` through the corporate IdP.
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/docker-compose.mdx b/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/docker-compose.mdx
index 96bb8d7758..d542007bef 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/docker-compose.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/docker-compose.mdx
@@ -67,9 +67,22 @@ Set these in `.env` alongside the compose file:
| `BASE_URL` / `BETTER_AUTH_URL` | `http://localhost:3000` | Public URLs for the app |
| `DATABASE_URL` | see below | PostgreSQL connection string |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `studio_user` / — / `studio_db` | Credentials for the bundled Postgres (postgres compose file only) |
+| `STUDIO_TOPUP_FEE_PERCENT` | `15` | Percentage fee applied to AI Gateway credit top-ups. Accepts `0`–`100`; set to `0` to waive the fee entirely for a self-hosted deployment |
+| `STUDIO_TASK_QUOTA_ENFORCED` | `false` | Gate Super Agent task delegation behind the auto-task subscription (see [Task Board](/en/studio/task-board#billing-and-auto-task-quota)). Unset or `false` means auto-task runs are unlimited — the default for self-hosted deployments |
+| `STUDIO_FREE_TASKS` | `3` | Lifetime free auto-task runs before a subscription is required. Only relevant when `STUDIO_TASK_QUOTA_ENFORCED` is set |
+| `STUDIO_MONTHLY_TASKS` | `10` | Auto-task runs allowed per billing cycle once subscribed. Only relevant when `STUDIO_TASK_QUOTA_ENFORCED` is set |
+| `STUDIO_MAX_RUNS_PER_TASK` | `5` | Maximum re-runs allowed for a single task, regardless of subscription status. Only relevant when `STUDIO_TASK_QUOTA_ENFORCED` is set |
+
+
+ `STUDIO_TOPUP_FEE_PERCENT` and the `STUDIO_TASK_QUOTA_ENFORCED` family only matter if you enable Stripe-backed billing (`STRIPE_SECRET_KEY` / `STRIPE_ORG_PRICE_ID`). Most self-hosted deployments don't set these and can ignore them — auto-task runs and credit top-ups stay unmetered.
+
The container runs as user `1001:1001` and persists data to the `studio-data` volume; the bundled Postgres persists to `postgres-data`.
+
+ `PORT` must be a valid TCP port (1–65535). Studio validates this at boot and fails fast with a clear error if it's out of range, instead of failing later when the HTTP server tries to bind it.
+
+
## Using your own PostgreSQL
To point Studio at an external database, use the base `docker-compose.yml` and set `DATABASE_URL`:
@@ -99,7 +112,7 @@ AUTH_GITHUB_CLIENT_ID=...
AUTH_GITHUB_CLIENT_SECRET=...
```
-For richer configuration (SAML/SSO, email providers, magic links), mount an `auth-config.json` into the container at `/app/apps/api/auth-config.json` by adding a volume to the `studio` service, using [`apps/api/auth-config.example.json`](https://github.com/decocms/studio/blob/main/apps/api/auth-config.example.json) as a starting point. See [Authentication](/en/studio/self-hosting/authentication) for the full reference.
+For richer configuration (SAML/SSO, email providers, magic links, email OTP), set the additional `AUTH_*` variables in the compose `environment` block (or your `.env`) — see [Authentication](/en/studio/self-hosting/authentication) for the full reference. There is no config file to mount; everything is env-var driven.
## Operations
@@ -150,4 +163,4 @@ docker compose -f docker-compose.postgres.yml up -d
- Always generate a strong `BETTER_AUTH_SECRET` (`openssl rand -base64 32`) and a real `POSTGRES_PASSWORD`.
- Don't commit `.env` (`echo ".env" >> .gitignore`; `chmod 600 .env`).
-- Don't commit secrets (client secrets, API keys) into any mounted `auth-config.json`.
+- Don't commit secrets (client secrets, API keys) into your `.env` file or any mounted secret files.
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/kubernetes.mdx b/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/kubernetes.mdx
index 0b47b0db45..02f5bdd630 100644
--- a/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/kubernetes.mdx
+++ b/apps/docs/client/src/content/deco-studio/en/studio/self-hosting/deploy/kubernetes.mdx
@@ -242,9 +242,74 @@ If `sentinel.token` is omitted, the chart generates and preserves a Secret for s
The optional warm-pool HPA requires `warmPool.enabled: true`, `warmPool.autoscaling.enabled: true`, and at least one explicit `autoscaling/v2` metric. The chart intentionally provides no default metric.
+### Tenant warm pools
+
+The generic warm pool above pre-warms *empty* pods. Tenant warm pools go one step further: each pod is already cloned, installed, and running the dev server for **one org's repo**, so a member of an opted-in org opens a project with no clone, no install, and no boot. This is additive to the generic warm pool — it does not replace it, and every path still works at size 0.
+
+A tenant pool is per-org opt-in and every warm slot is a permanently billed pod, so configure it deliberately. Each pool needs a matching entry on both sides:
+
+1. In `sandbox-env`'s `values.yaml`, add an entry to `tenantPools`. The chart shares the `agent-sandbox-system` namespace across releases, so the name must end with `-` (validated at template time, not derived, so both sides must use the identical literal):
+
+```yaml
+tenantPools:
+ - name: tenant-acme-site-production # DNS label ending in -
+ size: 2 # keep this many warm pods ready
+```
+
+2. On Studio's side, set `STUDIO_SANDBOX_TENANT_POOLS` to a JSON array with the matching `name` plus the org, repo, and (for private repos) connection details:
+
+```json
+[
+ {
+ "name": "tenant-acme-site-production",
+ "orgId": "acme",
+ "repo": "acme/site",
+ "connectionId": "github-connection-id",
+ "branch": "main",
+ "workload": { "runtime": "node", "packageManager": "pnpm" }
+ }
+]
+```
+
+`connectionId` is required for private repos and provides the short-lived clone credential; omit it only for a public repo. Studio resolves which pool (if any) to hand a claim from the **authenticated user's org** — never from a request field — so a pool never leaks across orgs.
+
+The reconciler also needs read access to the `SandboxWarmPool` it manages: grant the runner Role `sandboxwarmpools: get` (included by default when you install via the umbrella chart or the `self-host-studio` skill).
+
+An optional GitHub push webhook makes pool refresh immediate instead of waiting for the periodic refresh cycle. Configure `GITHUB_WEBHOOK_SECRET` on Studio and point a push webhook at `POST /api/_github/webhook`; without the secret configured, the route answers `503` and pools simply refresh on their own schedule.
+
+
+ Dispatches that only need a checkout — a Claude Code or other harness run against a specific branch, not an interactive dev server — never bind to a tenant warm pool. Binding one would de-warm it for no benefit: the dispatch's branch checkout is classified as a branch change, and a branch change stops the pod's running dev server. These `cloneOnly` claims always fall back to the generic pool (or a cold claim) instead. Separately, if a task asks a sandbox to start a process that's already running (typically `dev`), the daemon now returns the existing task instead of starting a second one — two dev servers on one pod's memory limit was a reliable way to OOM it.
+
+
+### Admission and capacity
+
+Before making a claim, Studio checks whether the cluster can actually schedule another sandbox pod. `SANDBOX_MAX_CONCURRENT_HOSTED_RUNS` still caps concurrency per pod, but it has no visibility into whether any node has room — on a full node, a burst of runs used to produce a pile of pods stuck `Pending` with `FailedScheduling: Insufficient memory`, each one failing only after the 180s readiness timeout.
+
+The capacity check reads the scheduler's own verdict instead of forecasting: a pod the scheduler could not place stays `Pending` with a `PodScheduled=False`/`Unschedulable` condition, and Studio treats that as "the cluster is full." A run that would add to that pile is **parked** — held, not claimed — until a pod becomes schedulable again, instead of being dispatched straight into a node with no room. This is cluster-wide and complements, not replaces, the per-pod concurrency limit.
+
+The check fails open: if the probe itself errors, Studio treats capacity as available rather than turning a broken health check into a global stop on all sandbox runs.
+
+### Daemon telemetry (OTLP metrics)
+
+The sandbox daemon can export OTLP metrics to an OpenTelemetry collector. This is separate from — and unrelated to — Studio's own monitoring export described in [Monitoring](/en/studio/self-hosting/monitoring): here the metrics come from the sandbox daemon itself (process/runtime health), not from Studio's tool-call logs.
+
+It's off by default. Enabling it opens exactly one additional in-cluster egress destination in the sandbox's iptables policy — the collector — since sandbox pods otherwise cannot reach in-cluster services.
+
+```yaml
+telemetry:
+ enabled: true
+ otlp:
+ ip: "10.0.12.34" # the collector Service's ClusterIP — see below
+ port: 4318 # 4318 = OTLP/HTTP, 4317 = OTLP/gRPC
+```
+
+
+ `telemetry.otlp.ip` must be a bare IPv4 address, not a DNS name. Sandbox pods run with `dnsPolicy: None` against public resolvers, so in-cluster service names (like `gateway-otlp.opentelemetry-collector`) do not resolve inside them. Get the collector's ClusterIP with `kubectl -n opentelemetry-collector get svc gateway-otlp -o jsonpath='{.spec.clusterIP}'`. If the collector Service is later recreated, its ClusterIP can change — the daemon logs export failures and keeps serving, but re-read the IP and upgrade the release to restore metrics.
+
+
### Idle housekeeper
-Studio refreshes claim activity, while the optional housekeeper CronJob cleans up idle or unrecoverable claims and orphaned routes/pods. Its defaults run every five minutes and reap claims idle for 15 minutes.
+Studio refreshes claim activity from two sources: agent runs, and any open preview stream. As long as a user has a preview open, a heartbeat renews the claim's TTL every five minutes, so a sandbox someone is actively watching is never reaped just because its agent is idle — this renewal only ever pushes the shutdown time later, never earlier. The optional housekeeper CronJob still cleans up claims that are idle or unrecoverable on both fronts, plus orphaned routes/pods. Its defaults run every five minutes and reap claims idle for 15 minutes.
```yaml
housekeeper:
@@ -313,17 +378,27 @@ These defaults come from `deploy/helm/studio/values.yaml`:
## Main sandbox values
+
+ The Go daemon is the only sandbox implementation — the image itself
+ determines the daemon, so there is no runtime switch or org-level flag to
+ choose between a TypeScript and a Go daemon. `image.repository` points
+ directly at the `studio-sandbox-go` image.
+
+
| Parameter | Description | Default |
| --- | --- | --- |
| `envName` | DNS-label suffix for environment resources | Required |
-| `image.repository` / `image.tag` | Sandbox daemon image | `ghcr.io/decocms/studio/studio-sandbox` / `1.17.8` |
+| `image.repository` / `image.tag` | Sandbox daemon image | `ghcr.io/decocms/studio/studio-sandbox-go` / `1.17.8` |
| `resources.requests` | Per-sandbox request | `500m` CPU / `1Gi` memory |
| `resources.limits` | Per-sandbox limit | `2` CPU / `4Gi` memory / `10Gi` ephemeral storage |
| `terminationGracePeriodSeconds` | Time for final git sync and unmount | `90` |
| `netinit.enabled` | Install default iptables egress policy | `true` |
| `readOnlyRootFilesystem` | Read-only sandbox root filesystem | `true` |
| `depsCache.enabled` / `depsCache.golden` | Node-local dependency caches | `false` / `false` |
+| `telemetry.enabled` | Export sandbox daemon OTLP metrics to a collector | `false` |
+| `telemetry.otlp.ip` / `telemetry.otlp.port` | Collector ClusterIP (required if enabled) / port | `""` / `4318` |
| `warmPool.enabled` / `warmPool.size` | Pre-warmed sandboxes | `false` / `0` |
+| `tenantPools` | Per-org warm pools already running that org's dev server (needs a matching `STUDIO_SANDBOX_TENANT_POOLS` entry) | `[]` |
| `previewGateway.enabled` | Wildcard preview Gateway | `false` |
| `housekeeper.enabled` | Idle-claim cleanup CronJob | `false` |
diff --git a/apps/docs/client/src/content/deco-studio/en/studio/task-board.mdx b/apps/docs/client/src/content/deco-studio/en/studio/task-board.mdx
new file mode 100644
index 0000000000..d5110c5d4b
--- /dev/null
+++ b/apps/docs/client/src/content/deco-studio/en/studio/task-board.mdx
@@ -0,0 +1,138 @@
+---
+title: Task Board
+description: Track work assigned to agents on a kanban board, with automated review before it ships
+icon: LayoutBoard
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+## What is the Task Board?
+
+The **Task Board** is a kanban-style workspace for tracking work items — cards move through columns such as Backlog, To Do, In Progress, In Review, and Done as an agent (usually a **Super Agent**) works on them. Each card can carry a linked pull request, comments, tags, priority, and an activity feed of everything that happened on it.
+
+
+ The **Task Manager** agent can create, prioritize, assign, and track cards on
+ the board for you — just describe the work in chat.
+
+
+## Comments
+
+Every task card's activity feed supports threaded comments: post a comment, and anyone can reply to it — one level of replies deep. A comment thread can be marked **resolved** once it's settled, and reopened later if needed. Comments are persisted per task and scoped to your organization.
+
+
+ Anyone in the organization can resolve or reopen a comment thread, but only
+ the comment's author can edit its body or delete it.
+
+
+## Working across multiple repositories
+
+When a task is assigned to a **Super Agent**, it runs inside a sandbox that needs a checked-out repository to work in. If your organization has exactly one importable repository, the task run starts already checked out into it. If it has more than one, the run starts with an empty working directory and the Super Agent picks the right repository itself before reading files or running git — no manual repo selection step is required from you.
+
+## Auto-fix
+
+Any card in **Triage** or **To Do** that isn't already assigned to the Super Agent shows an **Auto-fix** button (lightning-bolt icon) — both on the card itself and inside the task dialog. Clicking it hands the task straight to the Super Agent, the same as assigning it manually from the assignee picker, and draws from the same auto-task quota (see [Billing and auto-task quota](#billing-and-auto-task-quota)).
+
+
+ Inside the task dialog, the **Save** button only appears once you've actually
+ changed something — Auto-fix and New chat don't need a dirty form to work.
+
+
+## Re-running tasks
+
+Any card that's delegated to the Super Agent and not yet **Done** shows a **Re-run** action — on the card itself, and in bulk from the selection bar when you select multiple cards.
+
+- Selecting one or more cards adds a **Re-run** button to the selection bar, next to **Auto-fix**.
+- It's only enabled when every selected card is delegated to the Super Agent and not Done — if even one selected card doesn't qualify, the action doesn't fire for the rest of the selection either.
+- Confirming starts a fresh run on each selected task and stops any run still in progress on it. This "takeover" warning is shown unconditionally for a selection, since the board can't tell a streaming run from a stuck one across multiple cards at once.
+- Each task in the selection still counts against its own [per-task re-run cap](#billing-and-auto-task-quota) (5 re-runs per task).
+
+
+ There's no bulk re-run API call — each selected task fires its own re-run request individually. If one hits the auto-task quota or a paywall, that error surfaces once rather than once per task.
+
+
+## Automated review before shipping
+
+Once a task's pull request is **In Review** (its checks are passing, or it has none), Studio can run automated reviewers on it before a human ships the change. Configure this under **Settings → Organization → Reviewers & merge**:
+
+- **QA Agent** — exercises the feature itself, not just the diff, to verify the task actually solved the problem.
+- **Code Reviewer** — reviews the code using review skills appropriate to the repository's stack.
+- **Auto-merge** — when every enabled reviewer approves, merge the pull request automatically instead of waiting for a human to click merge.
+- **Auto-assign report tasks to the Super Agent** — assigns cards pushed by a report to the Super Agent as soon as they're created, instead of leaving them unassigned. See [Findings pushed by a report](#findings-pushed-by-a-report).
+
+Each reviewer that runs shows up as its own session on the task card, and its verdict is posted to the card's activity feed:
+
+- An **approval** (with optional notes) moves the task closer to shipping.
+- **Requested changes** hands the task back to the Super Agent to address the feedback, along with any notes from the reviewer.
+
+
+ QA Agent and Code Reviewer are both off by default. Enable the ones you want
+ under **Settings → Organization → Reviewers & merge** — you can turn on
+ either one independently, or both.
+
+ **Exception:** the first time an organization switches to reports-only mode,
+ both reviewers default on automatically — reports-only orgs hide the agent
+ navigation the review flow would otherwise rely on, so the task-board PR
+ review needs them on to keep working. This only fires once, when
+ `reports_only` itself is first defaulted on, and never overrides a flag you
+ already set explicitly.
+
+
+Each reviewer runs with its own persona, not the Super Agent's — even though it borrows the Super Agent's model and MCP tools, its system instructions describe the reviewer's job, not the org agent that wrote the PR under review. The reviewer's built-in toolset is also restricted so it can only review, not ship:
+
+- **QA Agent** can't edit existing files, but keeps `Write` for scratch files it creates to exercise the change (a curl script, a throwaway test).
+- **Code Reviewer** can't write or edit any file — it reads the diff and reasons about it.
+- Neither reviewer can push commits or merge the pull request; both keep `Bash` and `git`/`gh` read access to inspect and run the change.
+
+
+ These restrictions are enforced at the tool level, not just by prompt — a
+ reviewer physically cannot call the disallowed tools, even if it decides to
+ try.
+
+
+## Shipping to production
+
+When every enabled reviewer has approved a task's pull request — or no reviewers are enabled — the task card shows a **Ship to production** button. Clicking it merges the pull request. If auto-merge is enabled, this happens automatically once the review gate is satisfied instead of waiting for someone to click the button.
+
+Each card's PR panel also shows the pull request's live state (draft, open, merged, closed) and its check status (passing, pending, or failing), so you can see at a glance whether a task is ready to move forward.
+
+## Findings pushed by a report
+
+Some cards aren't created by a person — a report (for example, the **Report Agent**) can push diagnostic findings straight onto the board. These cards behave like any other, with one difference: deleting one **dismisses the underlying finding**, not just the card.
+
+
+ Once a finding is dismissed, the next report run skips it instead of
+ recreating the card. Deleting a report-generated card is reversible — ask
+ the **Task Manager** agent to restore a dismissed finding (or all of them)
+ and its card comes back with its comments, activity, and any linked PR
+ intact.
+
+
+The Task Manager agent tells you when a card you're deleting came from a report, so you know deleting it also suppresses that finding going forward.
+
+By default, a card pushed by a report lands unassigned. Turn on **Auto-assign report tasks to the Super Agent** under **Settings → Organization → Reviewers & merge** to have these cards delegated to the Super Agent automatically as soon as they're created, instead of waiting for someone to pick them up.
+
+## Billing and auto-task quota
+
+Delegating a task to the **Super Agent** — from the task dialog, or by assigning a card to it from a lane or the assignee picker — draws from your organization's auto-task quota. Tasks you create and work on yourself are never limited.
+
+- **Free trial**: every organization gets **3 free lifetime auto-task runs** before a subscription is required.
+- **Subscribed**: **$50/month** for **10 auto-task runs per billing cycle**. The quota renews automatically at the start of each cycle.
+- **Per-task cap**: any single task can be re-run up to **5 times**, regardless of subscription status.
+
+When a delegation is blocked by quota, a dialog explains why:
+
+- **Trial used up** — shows the subscription benefits and a **Subscribe** button that opens Stripe-hosted checkout in a new tab.
+- **Monthly quota used up** — informational only; the quota renews on its own at the next billing cycle.
+- **Task re-run limit reached** — informational only; create a new task to keep going.
+
+
+ This paywall never blocks you from creating or editing tasks yourself — it only applies to Super Agent delegation.
+
+
+### Managing billing
+
+Go to **Settings → Billing** to see your organization's current status (**Free trial**, **Active**, or **Payment issue**), runs used this cycle, and the renewal date. From there you can subscribe or, once subscribed, open the Stripe-hosted billing portal to manage your payment method or cancel.
+
+
+ Self-hosted deployments don't enforce this quota by default — auto-task runs are unlimited unless the deployment operator explicitly enables billing enforcement. See [Docker Compose](/en/studio/self-hosting/deploy/docker-compose) for the relevant environment variables.
+
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/agentic-cms.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/agentic-cms.mdx
index b19a21c0e9..09cf77eb31 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/agentic-cms.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/agentic-cms.mdx
@@ -52,6 +52,16 @@ Se você está vindo do deco.cx, o Agentic CMS é a mesma linha de produto — o
Projetos deco.cx existentes continuam funcionando. A migração adiciona a camada de agents; ela não substitui sua base de código.
+## Formulário de blocks: descrições de campo
+
+Ao editar as props de uma section ou block, a descrição de cada campo (vinda do `.describe()` do schema) aparece por padrão como texto abaixo do título do campo — o mesmo layout que o deco.cx sempre usou.
+
+Você pode alternar um site para exibir as descrições como tooltip: passe o mouse sobre o título do campo para revelá-la, o que mantém os formulários mais curtos e fáceis de escanear, especialmente em blocks densos. Isso é opcional e configurado **por site**, nas **Settings** do site, ao lado do campo **Production URL**. Ativar essa opção não muda nada para os outros sites da sua org.
+
+
+ Prefira o tooltip em blocks com muitos campos e bastante conteúdo — ele mantém o formulário compacto sem perder o texto de orientação do schema.
+
+
## Primeiros passos
Abra o Studio, encontre o agent **deco Site Editor** e aponte-o para o seu site.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/agents.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/agents.mdx
index d36029bfdb..4483a693df 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/agents.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/agents.mdx
@@ -60,34 +60,64 @@ Para criar um MCP app você usa o framework `@decocms/runtime` (React 19 + Tailw
Em um release futuro, o Studio permitirá que você construa views simples diretamente dentro da UI do agent, sem precisar criar um repo. Para qualquer coisa custom ou de nível de produção hoje, comece pelo template repo acima.
+### Files and skills
+
+Na aba **Settings** de um agent, **Files and skills** permite anexar arquivos (docs de referência, dados) e skills que o agent sempre pode ler, junto com suas tools e instruções.
+
+
+ Cada arquivo anexado tem um limite de 25MB. Selecionar um arquivo maior pula o upload e mostra um aviso citando o arquivo rejeitado — divida ou reduza arquivos grandes antes de anexá-los.
+
+
### Sandbox
Um agent pode ser respaldado por código. Vincule-o a um repositório do GitHub em **Settings → Sandbox** e o Studio executará o repo como um ambiente de dev isolado com escopo daquele agent — tipicamente o próprio MCP server do agent, mas pode ser qualquer serviço que o agent precise. O sandbox inicia sob demanda, vive apenas enquanto o agent precisar dele, e nunca vaza entre agents.
+O repo picker lista forks junto com seus próprios repositórios, marcados com um badge **Fork**. Um fork só é importado com sucesso se a instalação do GitHub App também tiver acesso concedido a ele — caso contrário, a importação falha com uma indicação para adicionar o fork em **GitHub → Settings → Installations**.
+
Quando o agent está rodando com um runtime local de code-editor, os botões **Open in VSCode** e **Open in Cursor** aparecem diretamente na barra de abas para acesso com um clique ao repositório na sua máquina. Em outros modos de runtime, as mesmas opções ficam disponíveis no menu de três pontos (⋯) da barra de abas.
-## Onde um agent roda
+### Fast Preview
-Acima do input do chat, ao lado do model picker, está o **runtime picker**. Ele controla *onde* o agent executa e *qual harness* o conduz. Há dois grupos:
+Para agents respaldados pelo Agentic CMS, **Settings → CMS** agrupa as opções de edição de conteúdo em três subseções:
-**Cloud**
+- **Preview** — uma URL de **preview server** (o endereço do seu site em produção) e um switch de **Fast Preview**. Com o Fast Preview ativado, a aba **Preview** renderiza o draft atual diretamente contra o seu preview server em vez de inicializar o dev server do sandbox — útil para um loop de preview muito mais rápido depois que um preview server é configurado. O switch fica desabilitado até que uma URL de preview server seja definida.
+- **Publishing** — o seletor de publish policy já existente (quem pode publicar mudanças).
+- **Editing** — preferências de edição de conteúdo: **Compact descriptions** (mostrar as descrições dos campos como tooltips em vez de texto inline), **Auto-open editor** (abrir o CMS automaticamente quando a aba Preview do agent carrega) e **Team sync** (apenas para agents vinculados a um repositório do GitHub — veja [Sincronizando com o time](#sincronizando-com-o-time) abaixo).
-- **Decopilot** — _"Roda em um agent sandbox."_ O agent executa em um sandbox gerenciado pelo Studio. Este é o padrão, sempre disponível, sem nada para instalar.
+
+ O Fast Preview nunca renderiza o seu site publicado — ele sempre mostra o draft do sandbox (ou um estado de "inicializando" enquanto o sandbox provisiona), apenas obtido a partir do seu preview server em vez de um dev server rodando localmente.
+
-**Local** — rode o agent na sua própria máquina. Até que um runtime local seja conectado, essas opções exibem **"Desktop not detected"** e ficam desabilitadas.
+### Sincronizando com o time
-- **Decopilot** — o harness do Decopilot, rodando no seu desktop
-- **Claude Code** — conduz o agent com o CLI do [Claude Code](https://claude.com/claude-code)
-- **Codex** — conduz o agent com o CLI do Codex
+Para agents vinculados a um repositório do GitHub, ativar **Team sync** (**Settings → CMS → Editing**) adiciona um botão **Sync** ao lado das ações de review/publish no header da thread. Vem desativado por padrão.
-Rodar localmente significa que o sandbox do agent vive na sua máquina: ele pode ler e escrever seus arquivos locais, usar suas ferramentas instaladas e rodar com suas próprias credenciais — enquanto o Studio continua tratando o chat, as connections e o logging. O cloud sandbox, por outro lado, é totalmente gerenciado e isolado por agent.
+Clicar em **Sync** envia uma única instrução determinística para o agent: commitar quaisquer mudanças locais pendentes, `git pull --rebase` na branch (trazendo commits que um colega tenha enviado direto para ela), rebase sobre a base branch mais recente, resolver eventuais conflitos e fazer push. Isso permite que um colega sem conhecimento de git atualize uma branch com o trabalho do resto do time em um clique, sem precisar perguntar quais comandos rodar.
-Para habilitar as opções locais, conecte um runtime de desktop com `deco link`. O Studio detecta a connection e acende quaisquer harnesses que ela expõe — **Claude Code** e **Codex** aparecem assim que seu CLI estiver disponível na máquina vinculada.
+## Onde um agent roda
+
+Acima do input do chat, ao lado do model picker, está o **runtime picker**. Ele controla *qual harness* conduz o agent.
+
+- **Decopilot** — _"Roda em um agent sandbox."_ O agent executa em um sandbox gerenciado pelo Studio. Este é o padrão, sempre disponível, sem nada para instalar.
+
+O sandbox do agent é totalmente gerenciado e isolado por agent — o Studio trata o chat, as connections, o logging e o próprio runtime, então não há nada para instalar ou conectar na sua máquina.
- Cloud é o padrão certo para execuções sem supervisão e para colegas de time que não deveriam precisar de uma configuração local. Recorra a um runtime local quando o agent precisar da sua máquina — seus arquivos, suas credenciais ou um coding harness como Claude Code ou Codex.
+ O sandbox gerenciado é o padrão certo para toda execução, supervisionada ou não — colegas de time nunca precisam de uma configuração local para usar um agent.
+
+
+### Studio Native: terminais de coding agent
+
+O app de desktop Studio Native adiciona uma segunda forma, separada, de trabalhar com código. Ao iniciar uma thread nova no Studio Native, aparece um seletor **"Choose a coding agent"** no lugar do composer de chat normal — escolha **Claude Code**, **Codex** ou **OpenCode** e o Studio inicia essa CLI como um terminal interativo ao vivo (uma sessão `xterm.js` embutida) dentro da thread, usando a instalação que ele detectar na sua máquina. Se uma CLI não for detectada, uma opção **"try anyway"** a inicia mesmo assim.
+
+A escolha é permanente para aquela thread: reabri-la reconecta à sessão em execução (ou retoma a conversa salva pela própria CLI) em vez de mostrar o seletor de novo. O Studio continua rastreando a thread na sua sidebar e injeta na CLI uma connection MCP com escopo limitado (`cms`) de volta para as tools da sua org, mas tudo que você digita vai direto para a interface da própria CLI — o Studio não interpreta nem reproduz essa saída como mensagens de chat.
+
+
+ Esse seletor só aparece no app de desktop Studio Native, e apenas para uma thread nova — ele não tem relação com o runtime gerenciado do **Decopilot** descrito acima, que está disponível tanto no app de desktop quanto no app web.
+No Studio Native, abrir uma branch clona uma working tree local para ela no disco, que permanece enquanto pelo menos uma thread daquela branch estiver aberta. Arquivar a **última** thread aberta de uma branch agora oferece a opção de reclamá-la — parando tudo que estiver rodando naquela branch e apagando seus arquivos do seu computador. Isso é opt-in a cada arquivamento, afeta apenas o clone local, e não altera a branch em si nem nada que já tenha sido enviado ao remoto.
+
## Um agent é um MCP virtual
Cada agent no Studio é exposto como seu próprio **endpoint MCP**: um pacote curado de tools, resources e instruções ao qual qualquer client compatível com MCP pode se conectar. Você pode pensar em um agent como um "MCP server virtual" que você monta visualmente — escolha algumas tools das suas connections, adicione instruções, e você publicou um endpoint MCP focado que seu time (ou seus outros agents) pode usar.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/ai-providers.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/ai-providers.mdx
index fa7da468b0..a017006cf6 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/ai-providers.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/ai-providers.mdx
@@ -71,6 +71,21 @@ Quando o Studio roda localmente (via `bunx -p decocms deco`), dois providers ext
Eles não aparecem no produto cloud.
+## Sua assinatura Claude (use seu próprio plano)
+
+Runs de coding hosted em sandbox (as tasks do Super Agent no Task Board, e outros fluxos que despacham um run `claude-code` para uma cloud sandbox) normalmente cobram do crédito de IA conectado da organização. Se você preferir pagar seus próprios runs de coding com seu plano pessoal **Claude Pro ou Max**, vincule-o em **Settings → AI Providers → Sua assinatura Claude**:
+
+1. Na sua própria máquina, execute `claude setup-token` e copie o token exibido.
+2. Cole o token no card **Sua assinatura Claude** e clique em **Link**.
+
+Depois de vinculado, seus próprios runs usam o seu plano em vez do crédito da org — ele tem prioridade sobre o provider configurado no tier Thinking da org, especificamente para runs `claude-code` hosted em sandbox. Se a Anthropic invalidar o token (por exemplo, quando ele expira), o Studio faz fallback automático para a credencial da org em vez de falhar o run; o card mostra um estado de **expirado** para que você saiba que precisa gerar um novo token.
+
+Clique em **Disconnect** para desvincular sua assinatura a qualquer momento.
+
+
+Isso afeta apenas runs `claude-code` hosted em sandbox. Não tem relação com o provider **Claude Code** somente local descrito acima, que conduz um CLI na sua própria máquina.
+
+
## Como um provider é conectado
**API key** — o método mais comum. Cole a key do dashboard do seu provider. Ela é armazenada criptografada e nunca exposta ao seu time.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/architecture.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/architecture.mdx
index 14b2ce1ee5..3e13b016fa 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/architecture.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/architecture.mdx
@@ -1,6 +1,6 @@
---
title: "Arquitetura"
-description: Como o Studio é conectado de ponta a ponta — edge, cloud cluster e desktop — e como requests, runs e sandboxes fluem entre as camadas.
+description: Como o Studio é conectado de ponta a ponta — edge e cloud cluster — e como requests, runs e sandboxes fluem entre as camadas.
icon: Network
---
@@ -9,31 +9,29 @@ import ArchitectureDiagram from "../../../../components/ArchitectureDiagram.astr
Esta página descreve como um deployment do Studio em execução é montado: as camadas, o que cada uma faz e como um request vira um run de agent, uma chamada de tool ou um preview de sandbox. É um bom material de fundo tanto se você faz self-host quanto se usa a cloud, e é o complemento conceitual dos guias de deploy de [Kubernetes](/pt-br/studio/self-hosting/deploy/kubernetes) e [Docker Compose](/pt-br/studio/self-hosting/deploy/docker-compose).
-## As três camadas
+## As duas camadas
-O Studio abrange três fronteiras de confiança/localidade:
+O Studio abrange duas fronteiras de confiança/localidade:
- **Edge** — o caminho da internet pública: um CDN e um load balancer L4.
- **Cloud cluster** — o deployment no Kubernetes: web, API, workers, Postgres, NATS e cloud sandboxes.
-- **Desktop** — o laptop do usuário, conectado via `deco link`, onde o desktop loop e o desktop sandbox podem rodar.
O mesmo fluxo em texto:
```
-EDGE CLOUD CLUSTER DESKTOP
-──── ───────────── ───────
+EDGE CLOUD CLUSTER
+──── ─────────────
Client ─▶ CF ─┬─▶ NLB ─▶ Web(nginx) ─▶ API ──┬─▶ MCP Proxy ─▶ Downstream MCP (ext)
│ ├─▶ Files/Storage ─▶ Object Store (ext)
│ ├─▶ DB (Postgres)
- │ ├─▶ NATS ───────────────▶ Link Daemon
- │ └─▶ Worker │
- │ │ model ▼
- │ ├──────────▶ LLM Desktop Loop ─▶ Desktop Sandbox
- │ ├─▶ DB │ └─ Org FS (mount)
- │ ├─▶ Files/Storage └─(MCP presigned)─▶ API
+ │ └─▶ Worker
+ │ │ model
+ │ ├──────────▶ LLM
+ │ ├─▶ DB
+ │ ├─▶ Files/Storage
│ ├─▶ Downstream MCP (in-process bridge)
│ └─▶ Cloud Sandbox ─┬─ Daemon API (/_sandbox/*)
│ └─ Org FS (sidecar) ─▶ /api/:org/fs ─▶ S3
@@ -70,7 +68,7 @@ O conjunto de queues que um pod worker escuta é configurado por env (`listenQue
| Componente | Função |
| --- | --- |
| **DB** (PostgreSQL, via Kysely) | Sistema de registro: orgs, connections, credential vault, audit, threads + mensagens e `sandbox_runner_state`. Também mantém as **queues do DBOS e o journal `workflow_status`** que tornam os runs duráveis e recuperáveis. |
-| **NATS** | Infraestrutura de mensageria ao vivo com três tarefas: (1) fan-out do JetStream `/stream` (`decopilot.stream.`) → live tail da UI; (2) a work-queue de pull (`link.work.`) → desktop; (3) o KV de link-claim (`studio_links`) que rastreia qual pod é dono do link de cada usuário. |
+| **NATS** | Infraestrutura de mensageria ao vivo: fan-out do JetStream `/stream` (`decopilot.stream.`) → live tail da UI. |
**O event bus está dormente.** O *recurso* de pub/sub de CloudEvents (`EVENT_PUBLISH`/`EVENT_SUBSCRIBE`, a queue de eventos durável, os subscribers `ON_EVENTS`) só é consumido pelo plugin de workflow, que não está em uso. O NATS em si **não** está dormente — ele serve as tarefas ao vivo listadas acima. Não confunda as duas coisas.
@@ -86,10 +84,18 @@ O conjunto de queues que um pod worker escuta é configurado por env (`listenQue
4. Os chunks de output são publicados no NATS e acompanhados de volta para a UI via `/stream`.
5. Se o pod cair, o **replay do journal do DBOS** retoma os steps retriáveis em outro pod — a recuperação é trabalho do framework, não feito à mão.
-Há dois transportes para o passo 3:
+O run executa in-process no worker e usa um **cloud sandbox**.
-- **Hosted** (padrão) — o run executa in-process no worker e usa um **cloud sandbox**.
-- **Pull** — o run é publicado no NATS `link.work.`; o **desktop** do usuário o pega e roda o loop localmente contra um **desktop sandbox**.
+### Harnesses: onde o agent loop de fato executa
+
+O passo acima é o caminho padrão — ele não cobre todo run hosted. Dois harnesses podem sustentar um run hosted:
+
+- **Decopilot** (padrão) — executa in-process no worker, como descrito acima.
+- **claude-code** — executa *dentro do pod da sandbox*, ao lado do checkout que o daemon já clonou, guiado pelo Claude Agent SDK. O daemon executa o `packages/harness-runner` uma vez por run através da superfície de controle `/_sandbox/dispatch` (um processo por run via stdin/stdout, não um servidor de longa duração) e transmite os frames de volta via NDJSON. O runner traduz o stream de mensagens do SDK para os mesmos `UIMessageChunk`s que o Decopilot produz, então o run projector, o `thread_message_parts` e a chat UI não precisam de novos tipos de part.
+
+O claude-code é opt-in por org (`claude_code_sandbox_enabled`, desligado por padrão). As tasks do Super Agent no Task Board só o usam quando a org optou por ele **e** tem pelo menos um repo importável. Com exatamente um repo, ele é resolvido e clonado antes do dispatch; com mais de um, a execução começa com o diretório de trabalho vazio, e a ferramenta `TASK_ADD_REPO` permite que o agent clone o repo correto no pod que já está em execução, depois de decidir qual usar. Caso contrário, essas tasks rodam no Decopilot exatamente como antes.
+
+A resolução de credencial para um run claude-code hosted em sandbox verifica primeiro a assinatura Claude pessoal vinculada pelo usuário que despachou o run (veja [AI Providers](/pt-br/studio/ai-providers)) — um token válido e não expirado ali tem prioridade sobre o provider do tier Thinking da org, já que o usuário pediu para seu próprio plano pagar. Ele faz fallback para a credencial da org quando nenhuma assinatura pessoal está vinculada ou o token expirou, em vez de falhar o run.
## MCP: in-process vs. as rotas de proxy
@@ -110,36 +116,18 @@ As rotas de file e object-storage são a verdadeira superfície "chamada por amb
## Sandboxes
-Uma sandbox clona o repo, roda o dev server e expõe um **daemon** in-pod. Sua superfície HTTP se divide em duas:
+Uma sandbox clona o repo, roda o dev server e expõe um **daemon** in-pod, provisionado pelo operador agent-sandbox como um pod `SandboxClaim` por (user, projectRef). Sua superfície HTTP se divide em duas:
| Superfície | Auth | Propósito | Quem chama |
| --- | --- | --- | --- |
| **Preview** (catch-all `*`) | Nenhuma — o handle (subdomínio) é o segredo | Faz reverse-proxy do dev server em execução (o preview ao vivo da app); injeta HMR. `/_sandbox/*` é ativamente rejeitado aqui. | O navegador do usuário final em `.preview.`, através do **Cloudflare** (LB) → um **Kubernetes Gateway** (Istio Gateway API / HTTPRoute) → o daemon |
| **Daemon API** (`/_sandbox/*`) | Bearer `DAEMON_TOKEN` | Superfície de controle: operações de fs (read/write/edit/bash/grep), git (status/diff/publish), exec de scripts, setup (clone → install → start), tasks, eventos SSE, dispatch do harness. | O cluster (worker para as tools de fs/git/bash do agent; API para setup + eventos da UI) |
-### Cloud vs. desktop sandboxes
-
-| | Cloud sandbox | Desktop sandbox |
-| --- | --- | --- |
-| Onde | operador agent-sandbox + um pod `SandboxClaim` por (user, projectRef) | Mesmo daemon, iniciado localmente no laptop |
-| Acessado via | port-forward do k8s / Service in-cluster (controle); ingress ou port-forward (preview) | loopback (controle); `.localhost:` (preview) |
-| Selecionado quando | é o padrão para runs hosted | um `deco link` está ativo — `user-desktop` é o provider padrão então |
-
### Org filesystem (org-fs)
Cada sandbox pode montar o **org filesystem** em `/org/`, para que o agent e o dev server leiam e escrevam arquivos da org como paths comuns. A stack de mount é `rclone (NFS/FUSE) → o WebDAV de loopback do daemon → /api/:org/fs/* → S3` — o mesmo object store das rotas de arquivo, exposto como um volume montado. É o mesmo filesystem que você navega na [Library](/pt-br/studio/library).
-Ele é conectado em **ambos** os providers, com mecânicas de mount diferentes:
-
-| | Cloud sandbox | Desktop sandbox |
-| --- | --- | --- |
-| Quem monta | um container **sidecar privilegiado** (o daemon não-privilegiado não consegue montar) | o **daemon diretamente** (ele tem permissões completas) |
-| Entrega da config | pós-bind: Studio `POST /_sandbox/orgfs-config`; o daemon a repassa para um control volume compartilhado que o sidecar observa (claims do warm-pool rejeitam `spec.env`) | env de boot: `ORGFS_CONFIG`, montada na inicialização do daemon |
-| Propagação | `rclone` com `allowOther` para que o mount se propague ao container principal | client único — sem necessidade de propagação |
-
-## Desktop
-
-Quando um usuário roda `deco link`, um **Link Daemon** no laptop dele faz long-poll no cluster (`/api/links/work` para chat, `/api/links/proxy` para controle de sandbox) e envia heartbeats de presença para o KV de link-claim do NATS. Os runs puxados (pulled) executam no **Desktop Loop** (`runNativeAgentLoopCore`) — uma cópia portável do agent loop. O thinking model é injetado pelo cluster, e o MCP é acessado via HTTP por uma presigned URL de volta para o cluster.
+O mount é conectado via um container **sidecar privilegiado** (o daemon não-privilegiado não consegue montar por conta própria): o Studio entrega a config pós-bind via `POST /_sandbox/orgfs-config`, o daemon a repassa para um control volume compartilhado que o sidecar observa (claims do warm-pool rejeitam `spec.env`), e o `rclone` monta com `allowOther` para que o mount se propague ao container principal.
## Em resumo
@@ -148,4 +136,5 @@ Quando um usuário roda `deco link`, um **Link Daemon** no laptop dele faz long-
- **As chamadas de tool de MCP são in-process** no worker; as rotas de proxy `/mcp/*` são apenas para clients externos.
- **As rotas de file/object-storage** são a superfície compartilhada entre API e worker.
- **O NATS está ao vivo**; o recurso de event-bus de CloudEvents está dormente.
-- **As sandboxes** expõem um preview público e uma control API protegida por token, na cloud (k8s) ou no desktop (`deco link`).
+- **As sandboxes** expõem um preview público e uma control API protegida por token na cloud (k8s).
+- **Runs hosted** usam por padrão o harness Decopilot (in-process no worker); o harness opt-in claude-code executa dentro do pod da sandbox, um processo `harness-runner` por run.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/automations.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/automations.mdx
index a96d62741a..d317677386 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/automations.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/automations.mdx
@@ -77,7 +77,7 @@ Dispara quando um sistema externo envia uma requisição HTTP para uma URL dedic
- Cada execução expira após 5 minutos
- Payloads de evento são limitados a 1 MB
-Se a pessoa que criou uma automation sai da organização, ela é automaticamente desativada.
+Se a pessoa que criou uma automation sai da organização, ela é automaticamente desativada. O mesmo acontece quando uma execução encontra um erro irrecuperável — por exemplo, quando o model configurado para a automation deixa de ser permitido para o seu role após uma mudança de permissão — assim ela para de tentar de novo e falhar silenciosamente, mostrando um motivo claro de desativação em [Monitoring](/pt-br/studio/monitoring).
---
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/concepts.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/concepts.mdx
index c0275be279..1dc4d5f128 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/concepts.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/concepts.mdx
@@ -17,6 +17,7 @@ O Studio usa um pequeno conjunto de conceitos que se constroem uns sobre os outr
- **Automation** — uma execução de agent que dispara em um schedule ou em resposta a um evento. Veja [Automations](/pt-br/studio/automations).
- **AI Provider** — um modelo de IA configurado (Anthropic, Google, OpenRouter ou o Deco AI Gateway) que alimenta seus agents e o Decopilot. Veja [AI Providers](/pt-br/studio/ai-providers).
- **Member** — uma pessoa na sua organização com um role e permissões.
+- **Task Board** — um kanban para acompanhar itens de trabalho que um agent está fazendo por você, com revisão automatizada opcional antes de a mudança ir para produção. Veja [Task Board](/pt-br/studio/task-board).
---
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/connections.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/connections.mdx
index ab970006e5..d16cdf2c31 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/connections.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/connections.mdx
@@ -47,6 +47,10 @@ As connections resolvem isso sendo a fonte única da verdade:
Todos os tipos de connection funcionam da mesma forma: configure uma vez no nível da org, anexe a quaisquer agents que precisem delas.
+
+ A URL de uma connection precisa resolver para um endereço público. O Studio bloqueia URLs que apontem para endereços privados ou de rede interna (inclusive quando alcançados via redirecionamento) — isso vale ao criar ou atualizar uma **Custom Connection**, e em cada health check que o Studio executa nela depois disso. Uma connection apontando para um endereço privado é reportada como unhealthy em vez de ser sondada.
+
+
### Transports
Por baixo dos panos, toda connection usa um destes transports. Você normalmente não precisa pensar nisso — o Studio escolhe o formato certo com base na entrada do catálogo ou no que você cola em **Custom Connection** — mas isso importa quando você está conectando um MCP server por conta própria:
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/context-and-tasks.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/context-and-tasks.mdx
index b3fa9f2fdb..d7765f608a 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/context-and-tasks.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/context-and-tasks.mdx
@@ -15,12 +15,26 @@ Uma **task** é sua conversa com o Decopilot — onde você conversa, o Decopilo
Toda task tem um destes quatro estados:
- **In progress** — o agent está trabalhando ou aguardando sua próxima mensagem
-- **Requires action** — pausada, aguardando seu input (uma tool precisa de aprovação ou ele fez uma pergunta)
+- **Requires action** — pausada, aguardando seu input. Esse estado só é definido quando há uma tool call pendente que precisa de você — um pedido de aprovação ou um `user_ask` — nunca apenas porque o texto da resposta contém um ponto de interrogação (por exemplo, uma pergunta retórica, ou uma URL com uma query string `?`)
- **Completed** — o trabalho terminou com sucesso
- **Failed** — algo deu errado ou a task expirou
Tasks expiram após **30 minutos de inatividade**. Se você está trabalhando em algo mais longo, envie uma mensagem periodicamente para mantê-la ativa.
+Tasks atribuídas a um agent especialista aparecem como cards no **task board**, onde você pode filtrar, priorizar e acompanhá-las entre as lanes.
+
+### Re-executando uma task travada
+
+De vez em quando, uma task atribuída ao agent nunca chega a iniciar um run, ou o run trava — o card fica parado em **In progress** ou **Requires action** indefinidamente, sem nenhuma atividade. Como não há mais nenhuma mudança de estado para reagir, o agent não retoma a task por conta própria.
+
+Selecione **Re-run** no card (ou na task dialog) para forçar um novo run. Isso encerra qualquer run ainda aberto na task e coloca um novo na fila, com o mesmo assignee.
+
+
+Re-run é uma tomada de controle: ele interrompe qualquer run atualmente aberto na task, mesmo que ainda esteja em streaming, antes de iniciar o novo. Use apenas quando tiver certeza de que o run atual está travado, e não apenas lento.
+
+
+Re-run só se aplica a tasks já atribuídas ao agent — reatribuir uma task a um agent já coloca um run na fila por conta própria, então essa ação não é necessária nesse caso.
+
---
## Como a memory se enche
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/overview.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/overview.mdx
index 4d6646cac6..c4629103ca 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/overview.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/overview.mdx
@@ -80,16 +80,6 @@ Quando um agent é apoiado por um sandbox (um repo do GitHub vinculado), o Decop
Sandboxes também montam o **filesystem da organização** em `org/`: `org/home/` é a home compartilhada da org — editável, livre, compartilhada entre todos os membros, agents e runs, onde os agents registram conhecimento durável e checam contexto antes de começar a trabalhar; `org/upload` guarda os arquivos anexados à conversa atual (anexos do chat caem ali automaticamente — sem etapa de cópia); `org/output` é a pasta de saída compartilhada da run atual; e `org/public/` expõe skill sets somente leitura e curados, sincronizados a partir de repos versionados. Arquivos escritos na pasta home e em `org/output` sincronizam com o cloud storage da sua organização e ficam visíveis para todos os membros e agents; mudanças externas aparecem dentro do sandbox em cerca de um segundo.
-
- **Links de desktop no macOS:** quando um sandbox roda na sua máquina (`deco link`),
- as pastas `org/` são volumes de rede, e o macOS pede uma vez por app
- permissão para acessá-las. Aprove o prompt de "acessar arquivos em um volume de
- rede" para o seu terminal ou editor — ou habilite manualmente em **System
- Settings → Privacy & Security → Files & Folders → _seu app_ → Network
- Volumes**. Sem essa permissão, leituras e escritas em `org/` falham com
- "Operation not permitted".
-
-
Para a referência completa, veja [Tools](/pt-br/studio/decopilot/tools).
---
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/quickstart.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/quickstart.mdx
index d8869fafc8..7c7fe11edb 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/quickstart.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/quickstart.mdx
@@ -53,7 +53,7 @@ Quando estiver pronto para criar um worker focado e reutilizável, crie um agent
Use o botão **+** / "Browse agents" na sidebar para criar um novo agent. Assim que ele abrir, a tela se divide em duas partes:
-- **Esquerda** — o chat. Acima do input ficam o **model picker** (nível do modelo) e o **runtime picker** (onde o agent roda — na cloud ou na sua própria máquina; veja [Agents](/pt-br/studio/agents#where-an-agent-runs)).
+- **Esquerda** — o chat. Acima do input ficam o **model picker** (nível do modelo) e o **runtime picker** (onde o agent roda; veja [Agents](/pt-br/studio/agents#where-an-agent-runs)).
- **Direita** — um painel com abas. A aba **Settings** guarda instruções, connections e arquivos; **Automations** guarda schedules e triggers. Outras abas (Preview, Content, Review changes) aparecem apenas para agents vinculados a um repo ou site.
Abra a aba **Settings** e escreva uma instrução de uma linha descrevendo o que este agent deve fazer.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/authentication.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/authentication.mdx
index 3ec9e32632..1743ab830c 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/authentication.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/authentication.mdx
@@ -17,10 +17,10 @@ O deco Studio usa Better Auth e suporta:
## Configurar autenticação (self-hosting)
-Implantações self-hosted carregam um arquivo `auth-config.json` na inicialização (consulte seus guias de deploy para detalhes de montagem).
+Implantações self-hosted são configuradas inteiramente por variáveis de ambiente `AUTH_*` (schema: `apps/api/src/auth/auth-env.ts`). Não há arquivo de configuração para montar — defina as variáveis abaixo no serviço/container `studio`.
- Mantenha os secrets dos provedores fora do Git. Em produção, use gerenciamento de Secrets (Kubernetes Secrets, External Secrets Operator, etc.).
+ Mantenha os secrets dos provedores fora do Git. Em produção, use gerenciamento de Secrets (Kubernetes Secrets, External Secrets Operator, etc.), não arquivos `.env` simples.
## Variáveis de ambiente principais
@@ -28,6 +28,43 @@ Implantações self-hosted carregam um arquivo `auth-config.json` na inicializa
- `BETTER_AUTH_SECRET` (obrigatório)
- `BETTER_AUTH_URL` / `BASE_URL` (recomendado definir explicitamente em produção)
+### Email/senha
+
+| Variável | Padrão | Descrição |
+| --- | --- | --- |
+| `AUTH_EMAIL_PASSWORD_ENABLED` | `true` | Defina como `false` para desabilitar o login por email/senha. |
+
+### Login social
+
+| Variável | Descrição |
+| --- | --- |
+| `AUTH_GOOGLE_CLIENT_ID` / `AUTH_GOOGLE_CLIENT_SECRET` | Credenciais do app OAuth do Google. |
+| `AUTH_GITHUB_CLIENT_ID` / `AUTH_GITHUB_CLIENT_SECRET` | Credenciais do app OAuth do GitHub. |
+
+### Provedores de email (convites, reset de senha, magic link, OTP)
+
+| Variável | Descrição |
+| --- | --- |
+| `AUTH_RESEND_API_KEY` / `AUTH_RESEND_FROM_EMAIL` | Credenciais do provedor Resend. |
+| `AUTH_SENDGRID_API_KEY` / `AUTH_SENDGRID_FROM_EMAIL` | Credenciais do provedor SendGrid. |
+| `AUTH_INVITE_EMAIL_PROVIDER` | `resend` ou `sendgrid` — qual provedor envia os emails de convite para a organização. |
+| `AUTH_RESET_PASSWORD_EMAIL_PROVIDER` | `resend` ou `sendgrid` — qual provedor envia os emails de reset de senha. |
+
+### Magic link e email OTP
+
+| Variável | Padrão | Descrição |
+| --- | --- | --- |
+| `AUTH_MAGIC_LINK_ENABLED` | `false` | Habilita login sem senha via link enviado por email. |
+| `AUTH_MAGIC_LINK_EMAIL_PROVIDER` | — | `resend` ou `sendgrid`. Obrigatório se o magic link estiver habilitado. |
+| `AUTH_EMAIL_OTP_ENABLED` | `false` | Habilita login sem senha via código único enviado por email. |
+| `AUTH_EMAIL_OTP_EMAIL_PROVIDER` | — | `resend` ou `sendgrid`. Obrigatório se o email OTP estiver habilitado. |
+| `AUTH_EMAIL_OTP_LENGTH` | padrão do provedor | Tamanho do código. |
+| `AUTH_EMAIL_OTP_EXPIRES_IN` | padrão do provedor | Expiração do código, em segundos. |
+
+
+ Qualquer variável `*_EMAIL_PROVIDER` deve referenciar um provedor com a API key definida (`AUTH_RESEND_API_KEY` ou `AUTH_SENDGRID_API_KEY`) — caso contrário o app falha na validação na inicialização.
+
+
## SSO no deployment inteiro (OIDC)
Para deployments self-hosted onde todos os usuários devem autenticar através
@@ -91,8 +128,8 @@ organização para que apenas usuários do seu domínio consigam logar.
### Login social vs. SSO
Essas envs configuram **SSO via OIDC** (plugin `@better-auth/sso`). São
-diferentes dos botões de **login social** configurados via `auth-config.json`
-(`socialProviders.google`, `socialProviders.github`) ou via
-`AUTH_GOOGLE_CLIENT_ID` / `AUTH_GITHUB_CLIENT_ID`. Login social deixa os
-usuários autenticarem com suas contas pessoais; o SSO de deployment inteiro
-roteia todo mundo que casar com `AUTH_SSO_DOMAIN` para o IdP corporativo.
+diferentes dos botões de **login social** configurados via
+`AUTH_GOOGLE_CLIENT_ID` / `AUTH_GITHUB_CLIENT_ID` (veja [Login
+social](#login-social) acima). Login social deixa os usuários autenticarem
+com suas contas pessoais; o SSO de deployment inteiro roteia todo mundo que
+casar com `AUTH_SSO_DOMAIN` para o IdP corporativo.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/docker-compose.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/docker-compose.mdx
index 929a60f7ae..320e52b2d6 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/docker-compose.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/docker-compose.mdx
@@ -67,9 +67,22 @@ Defina estas no `.env` ao lado do arquivo de compose:
| `BASE_URL` / `BETTER_AUTH_URL` | `http://localhost:3000` | URLs públicas da aplicação |
| `DATABASE_URL` | veja abaixo | Connection string do PostgreSQL |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `studio_user` / — / `studio_db` | Credenciais do Postgres embutido (apenas no compose postgres) |
+| `STUDIO_TOPUP_FEE_PERCENT` | `15` | Percentual de taxa aplicado a recargas de créditos do AI Gateway. Aceita `0`–`100`; defina `0` para dispensar a taxa completamente em um deployment self-hosted |
+| `STUDIO_TASK_QUOTA_ENFORCED` | `false` | Bloqueia a delegação de tasks ao Super Agent atrás da subscription de auto-task (veja [Task Board](/pt-br/studio/task-board#billing-e-cota-de-auto-tasks)). Ausente ou `false` significa execuções de auto-task ilimitadas — o padrão para deployments self-hosted |
+| `STUDIO_FREE_TASKS` | `3` | Execuções de auto-task gratuitas por toda a vida antes de exigir uma subscription. Só relevante quando `STUDIO_TASK_QUOTA_ENFORCED` está definido |
+| `STUDIO_MONTHLY_TASKS` | `10` | Execuções de auto-task permitidas por ciclo de billing após assinar. Só relevante quando `STUDIO_TASK_QUOTA_ENFORCED` está definido |
+| `STUDIO_MAX_RUNS_PER_TASK` | `5` | Máximo de re-execuções permitidas para uma mesma task, independente do status da subscription. Só relevante quando `STUDIO_TASK_QUOTA_ENFORCED` está definido |
+
+
+ `STUDIO_TOPUP_FEE_PERCENT` e a família `STUDIO_TASK_QUOTA_ENFORCED` só importam se você habilitar o billing baseado em Stripe (`STRIPE_SECRET_KEY` / `STRIPE_ORG_PRICE_ID`). A maioria dos deployments self-hosted não define essas variáveis e pode ignorá-las — execuções de auto-task e recargas de crédito ficam sem medição.
+
O container roda como usuário `1001:1001` e persiste dados no volume `studio-data`; o Postgres embutido persiste em `postgres-data`.
+
+ `PORT` precisa ser uma porta TCP válida (1–65535). O Studio valida isso na inicialização e falha rapidamente com um erro claro se estiver fora do intervalo, em vez de falhar depois quando o servidor HTTP tenta se vincular a ela.
+
+
## Usando seu próprio PostgreSQL
Para apontar o Studio para um banco externo, use o `docker-compose.yml` base e defina `DATABASE_URL`:
@@ -99,7 +112,7 @@ AUTH_GITHUB_CLIENT_ID=...
AUTH_GITHUB_CLIENT_SECRET=...
```
-Para configurações mais ricas (SAML/SSO, provedores de email, magic links), monte um `auth-config.json` dentro do container em `/app/apps/api/auth-config.json` adicionando um volume ao serviço `studio`, usando [`apps/api/auth-config.example.json`](https://github.com/decocms/studio/blob/main/apps/api/auth-config.example.json) como ponto de partida. Veja [Autenticação](/pt-br/studio/self-hosting/authentication) para a referência completa.
+Para configurações mais ricas (SAML/SSO, provedores de email, magic links, email OTP), defina as variáveis `AUTH_*` adicionais no bloco `environment` do compose (ou no seu `.env`) — veja [Autenticação](/pt-br/studio/self-hosting/authentication) para a referência completa. Não há arquivo de configuração para montar; tudo é orientado por variáveis de ambiente.
## Operações
@@ -150,4 +163,4 @@ docker compose -f docker-compose.postgres.yml up -d
- Sempre gere um `BETTER_AUTH_SECRET` forte (`openssl rand -base64 32`) e um `POSTGRES_PASSWORD` de verdade.
- Não faça commit do `.env` (`echo ".env" >> .gitignore`; `chmod 600 .env`).
-- Não faça commit de secrets (client secrets, API keys) em nenhum `auth-config.json` montado.
+- Não faça commit de secrets (client secrets, API keys) no seu arquivo `.env` ou em qualquer arquivo de secret montado.
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/kubernetes.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/kubernetes.mdx
index 0d18b35418..94657930b7 100644
--- a/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/kubernetes.mdx
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/self-hosting/deploy/kubernetes.mdx
@@ -242,9 +242,84 @@ Se `sentinel.token` for omitido, o chart gera e preserva um Secret para os pods,
O HPA opcional do warm pool exige `warmPool.enabled: true`, `warmPool.autoscaling.enabled: true` e pelo menos uma métrica explícita no formato `autoscaling/v2`. O chart intencionalmente não fornece uma métrica padrão.
+### Tenant warm pools
+
+O warm pool genérico acima pré-aquece pods *vazios*. Um tenant warm pool vai além: cada pod já está executando o repositório e o dev server de uma org, então um membro dessa org abre um projeto sem clone, sem instalação e sem boot do dev server. Isso é opt-in por org, aditivo ao warm pool genérico e cada slot é um pod permanentemente cobrado — está desabilitado por padrão (`tenantPools: []`).
+
+Um pool é identificado por `(org, repo)`. O Studio inicializa e atualiza cada pod não vinculado do pool; um claim vindo da org do pool vincula um desses pods em vez de começar do zero.
+
+Declare cada pool nos dois lados, com o **mesmo** `name`:
+
+1. Nos values do chart `sandbox-env` — renderiza um `SandboxWarmPool` contra o `SandboxTemplate` compartilhado:
+
+ ```yaml
+ tenantPools:
+ - name: tenant-acme-site-production # DNS label, precisa terminar em -
+ size: 2 # quantidade de pods aquecidos a manter prontos
+ ```
+
+ O sufixo `-` é obrigatório e validado (não derivado): o `sandbox-env` compartilha o namespace `agent-sandbox-system` entre releases, então um nome sem o sufixo deixaria staging e produção disputarem o mesmo pool.
+
+2. Na variável de ambiente `STUDIO_SANDBOX_TENANT_POOLS` do Studio — um array JSON que carrega os detalhes do tenant que a entrada do chart não expressa:
+
+ ```json
+ [
+ {
+ "name": "tenant-acme-site-production",
+ "orgId": "org_acme",
+ "repo": "acme/site",
+ "connectionId": "github-connection-id",
+ "branch": "main",
+ "workload": { "runtime": "node" }
+ }
+ ]
+ ```
+
+ - `orgId` é a única org cujos membros podem ser vinculados aos pods desse pool.
+ - `connectionId` gera uma credencial de clone de curta duração a cada bootstrap e nunca é armazenada; omita apenas para um repositório público, já que sem ela os pods clonam anonimamente.
+ - `branch` é o branch em que os pods ociosos ficam — um claim pode trocar de branch após o vínculo sem perder as dependências instaladas.
+
+
+ Defina um `GITHUB_WEBHOOK_SECRET` opcional no Studio e registre um webhook de push do GitHub em `https:///api/_github/webhook` para atualizar um pool imediatamente após um push. Sem ele, os pools continuam recebendo novos commits no próprio ciclo periódico — o webhook apenas torna essa atualização imediata.
+
+
+
+ Conceda ao Role do runner a permissão `sandboxwarmpools: get` (o chart faz isso automaticamente a partir da versão 0.12.0 do `sandbox-env`) — o reconciler lê o `status.selector` de cada pool para encontrar seus pods, e uma permissão faltante bloqueia silenciosamente toda tentativa de aquecimento.
+
+
+
+ Dispatches que só precisam de um checkout — uma execução do Claude Code ou de outro harness contra um branch específico, sem dev server interativo — nunca se vinculam a um tenant warm pool. Vincular um seria destrutivo sem benefício: o checkout de branch do dispatch é classificado como troca de branch, e uma troca de branch para o dev server em execução no pod. Esses claims `cloneOnly` sempre caem para o pool genérico (ou um claim frio). Separadamente, se uma task pede para um sandbox iniciar um processo que já está em execução (normalmente `dev`), o daemon agora retorna a task existente em vez de iniciar uma segunda — dois dev servers no limite de memória de um único pod era uma forma confiável de matar o pod por OOM.
+
+
+### Admissão e capacidade
+
+Antes de fazer um claim, o Studio verifica se o cluster consegue de fato agendar outro pod de sandbox. `SANDBOX_MAX_CONCURRENT_HOSTED_RUNS` continua limitando a concorrência por pod, mas não tem visibilidade sobre se algum node tem espaço — em um node cheio, uma explosão de runs costumava gerar uma pilha de pods parados em `Pending` com `FailedScheduling: Insufficient memory`, cada um falhando somente após o timeout de 180s de readiness.
+
+A verificação de capacidade lê o próprio veredito do scheduler em vez de prever: um pod que o scheduler não conseguiu posicionar fica `Pending` com uma condição `PodScheduled=False`/`Unschedulable`, e o Studio trata isso como "o cluster está cheio". Um run que aumentaria essa pilha é **estacionado** — mantido em espera, sem claim — até que um pod volte a ser agendável, em vez de ser despachado direto para um node sem espaço. Isso é validado no nível do cluster e complementa, sem substituir, o limite de concorrência por pod.
+
+A verificação falha aberta: se a própria sondagem der erro, o Studio trata a capacidade como disponível em vez de transformar uma verificação de saúde quebrada em uma parada global de todos os runs de sandbox.
+
+### Telemetria do daemon (métricas OTLP)
+
+O daemon do sandbox pode exportar métricas OTLP para um collector OpenTelemetry. Isso é separado — e não relacionado — à exportação de monitoramento do próprio Studio descrita em [Monitoring](/pt-br/studio/self-hosting/monitoring): aqui as métricas vêm do próprio daemon do sandbox (saúde do processo/runtime), não dos logs de chamadas de ferramentas do Studio.
+
+Por padrão está desabilitado. Habilitar essa opção abre exatamente um destino de egress adicional dentro do cluster na política de iptables do sandbox — o collector — já que os pods de sandbox não conseguem alcançar serviços internos do cluster de outra forma.
+
+```yaml
+telemetry:
+ enabled: true
+ otlp:
+ ip: "10.0.12.34" # o ClusterIP do Service do collector — veja abaixo
+ port: 4318 # 4318 = OTLP/HTTP, 4317 = OTLP/gRPC
+```
+
+
+ `telemetry.otlp.ip` precisa ser um endereço IPv4 puro, não um nome DNS. Os pods de sandbox rodam com `dnsPolicy: None` contra resolvers públicos, então nomes de serviço internos ao cluster (como `gateway-otlp.opentelemetry-collector`) não são resolvidos dentro deles. Obtenha o ClusterIP do collector com `kubectl -n opentelemetry-collector get svc gateway-otlp -o jsonpath='{.spec.clusterIP}'`. Se o Service do collector for recriado depois, o ClusterIP pode mudar — o daemon registra falhas de exportação nos logs e continua funcionando, mas releia o IP e atualize o release para restaurar as métricas.
+
+
### Housekeeper de recursos ociosos
-O Studio atualiza a atividade dos claims, enquanto o CronJob housekeeper opcional remove claims ociosos ou irrecuperáveis, além de routes e pods órfãos. Os padrões executam a cada cinco minutos e removem claims ociosos há 15 minutos.
+O Studio atualiza a atividade dos claims a partir de duas fontes: execuções de agentes e qualquer preview stream aberto. Enquanto um usuário mantiver um preview aberto, um heartbeat renova o TTL do claim a cada cinco minutos, então um sandbox que alguém está observando ativamente nunca é removido só porque seu agente está ocioso — essa renovação só empurra o horário de shutdown para mais tarde, nunca para mais cedo. O CronJob housekeeper opcional continua removendo claims ociosos ou irrecuperáveis em ambas as frentes, além de routes e pods órfãos. Os padrões executam a cada cinco minutos e removem claims ociosos há 15 minutos.
```yaml
housekeeper:
@@ -313,17 +388,27 @@ Estes padrões vêm de `deploy/helm/studio/values.yaml`:
## Valores principais do sandbox
+
+ O daemon Go é a única implementação de sandbox — a própria imagem
+ determina o daemon, então não há mais um switch de runtime ou uma flag no
+ nível da organização para escolher entre um daemon TypeScript e um Go.
+ `image.repository` aponta diretamente para a imagem `studio-sandbox-go`.
+
+
| Parâmetro | Descrição | Padrão |
| --- | --- | --- |
| `envName` | Sufixo DNS-label dos recursos do ambiente | Obrigatório |
-| `image.repository` / `image.tag` | Imagem do daemon do sandbox | `ghcr.io/decocms/studio/studio-sandbox` / `1.17.8` |
+| `image.repository` / `image.tag` | Imagem do daemon do sandbox | `ghcr.io/decocms/studio/studio-sandbox-go` / `1.17.8` |
| `resources.requests` | Request por sandbox | `500m` CPU / `1Gi` memória |
| `resources.limits` | Limite por sandbox | `2` CPU / `4Gi` memória / `10Gi` armazenamento efêmero |
| `terminationGracePeriodSeconds` | Tempo para sync final do git e unmount | `90` |
| `netinit.enabled` | Instalar política padrão de egress no iptables | `true` |
| `readOnlyRootFilesystem` | Root filesystem do sandbox somente leitura | `true` |
| `depsCache.enabled` / `depsCache.golden` | Caches de dependências locais ao node | `false` / `false` |
+| `telemetry.enabled` | Exportar métricas OTLP do daemon do sandbox para um collector | `false` |
+| `telemetry.otlp.ip` / `telemetry.otlp.port` | ClusterIP do collector (obrigatório se habilitado) / porta | `""` / `4318` |
| `warmPool.enabled` / `warmPool.size` | Sandboxes pré-aquecidos | `false` / `0` |
+| `tenantPools` | Warm pools por org, já executando o repositório e o dev server dessa org | `[]` |
| `previewGateway.enabled` | Gateway wildcard de preview | `false` |
| `housekeeper.enabled` | CronJob de limpeza de claims ociosos | `false` |
diff --git a/apps/docs/client/src/content/deco-studio/pt-br/studio/task-board.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/task-board.mdx
new file mode 100644
index 0000000000..1b364658a0
--- /dev/null
+++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/task-board.mdx
@@ -0,0 +1,141 @@
+---
+title: Task Board
+description: Acompanhe o trabalho atribuído aos agents em um kanban, com revisão automatizada antes de ir para produção
+icon: LayoutBoard
+---
+
+import Callout from "../../../../components/ui/Callout.astro";
+
+## O que é o Task Board?
+
+O **Task Board** é um workspace no estilo kanban para acompanhar itens de trabalho — os cards se movem por colunas como Backlog, To Do, In Progress, In Review e Done enquanto um agent (geralmente um **Super Agent**) trabalha neles. Cada card pode ter um pull request vinculado, comentários, tags, prioridade e um feed de atividade com tudo o que aconteceu nele.
+
+
+ O agent **Task Manager** pode criar, priorizar, atribuir e acompanhar cards
+ no board para você — basta descrever o trabalho no chat.
+
+
+## Comentários
+
+O feed de atividade de todo card de task suporta comentários em thread: publique um comentário, e qualquer pessoa pode responder a ele — até um nível de respostas. Uma thread de comentários pode ser marcada como **resolvida** quando estiver encerrada, e reaberta depois se necessário. Os comentários são persistidos por task e escopados à sua organização.
+
+
+ Qualquer pessoa da organização pode resolver ou reabrir uma thread de
+ comentários, mas apenas o autor do comentário pode editar o corpo dele ou
+ excluí-lo.
+
+
+## Trabalhando com múltiplos repositórios
+
+Quando uma task é atribuída a um **Super Agent**, ele roda dentro de um sandbox que precisa de um repositório já clonado para trabalhar. Se sua organização tiver exatamente um repositório importável, a execução da task já começa com esse repositório clonado. Se houver mais de um, a execução começa com o diretório de trabalho vazio, e o próprio Super Agent escolhe o repositório correto antes de ler arquivos ou executar comandos git — nenhuma seleção manual de repositório é necessária.
+
+## Auto-fix
+
+Qualquer card em **Triage** ou **To Do** que ainda não esteja atribuído ao Super Agent mostra um botão **Auto-fix** (ícone de raio) — tanto no próprio card quanto dentro do diálogo da task. Clicar nele entrega a task diretamente ao Super Agent, do mesmo jeito que atribuí-la manualmente pelo seletor de responsável, e consome a mesma cota de auto-task (veja [Billing and auto-task quota](#billing-and-auto-task-quota)).
+
+
+ Dentro do diálogo da task, o botão **Save** só aparece depois que você
+ realmente muda algo — Auto-fix e New chat não precisam de um formulário
+ alterado para funcionar.
+
+
+## Revisão automatizada antes de ir para produção
+
+Quando o pull request de uma task fica **In Review** (seus checks estão passando, ou não há nenhum), o Studio pode executar revisores automatizados nele antes que um humano coloque a mudança em produção. Configure isso em **Settings → Organization → Reviewers & merge**:
+
+- **QA Agent** — exercita a própria feature, não só o diff, para verificar se a task realmente resolveu o problema.
+- **Code Reviewer** — revisa o código usando skills de revisão apropriadas para o stack do repositório.
+- **Auto-merge** — quando todos os revisores habilitados aprovam, o pull request é mesclado automaticamente em vez de esperar um humano.
+- **Auto-assign report tasks to the Super Agent** — atribui automaticamente ao Super Agent os cards publicados por um report logo quando são criados, em vez de deixá-los sem responsável. Veja [Findings publicados por um report](#findings-publicados-por-um-report).
+
+Cada revisor que roda aparece como sua própria sessão no card da task, e o veredito dele é publicado no feed de atividade do card:
+
+- Uma **aprovação** (com notas opcionais) aproxima a task de ir para produção.
+- **Solicitação de mudanças** devolve a task para o Super Agent resolver o feedback, junto com as notas do revisor.
+
+
+ QA Agent e Code Reviewer vêm desabilitados por padrão. Habilite os que você
+ quiser em **Settings → Organization → Reviewers & merge** — você pode ativar
+ um independentemente do outro, ou os dois.
+
+ **Exceção:** na primeira vez que uma organização passa para o modo
+ reports-only, os dois revisores são habilitados automaticamente — orgs
+ reports-only escondem a navegação de agents da qual o fluxo de revisão
+ dependeria, então a revisão de PR do task-board precisa deles ativos para
+ continuar funcionando. Isso só acontece uma vez, quando `reports_only` em
+ si é definido por padrão pela primeira vez, e nunca sobrescreve uma flag
+ que você já tenha definido explicitamente.
+
+
+Cada revisor roda com sua própria persona, não a do Super Agent — mesmo usando o modelo e as tools MCP do Super Agent, suas instruções de sistema descrevem o trabalho do revisor, não o org agent que escreveu o PR sob revisão. O conjunto de tools nativas do revisor também é restrito, para que ele só possa revisar, não enviar para produção:
+
+- **QA Agent** não pode editar arquivos existentes, mas mantém `Write` para arquivos descartáveis criados para exercitar a mudança (um script curl, um teste temporário).
+- **Code Reviewer** não pode escrever nem editar nenhum arquivo — ele lê o diff e raciocina sobre ele.
+- Nenhum dos dois revisores pode enviar (push) commits ou fazer merge do pull request; ambos mantêm acesso de leitura via `Bash` e `git`/`gh` para inspecionar e executar a mudança.
+
+
+ Essas restrições são aplicadas no nível das tools, não apenas via prompt —
+ um revisor não consegue de fato chamar as tools desabilitadas, mesmo que
+ tente.
+
+
+## Re-executando tasks
+
+Qualquer card que esteja delegado ao Super Agent e ainda não esteja **Done** mostra uma ação **Re-run** — tanto no próprio card quanto em lote, pela barra de seleção quando você seleciona vários cards.
+
+- Selecionar um ou mais cards adiciona um botão **Re-run** à barra de seleção, ao lado do **Auto-fix**.
+- Ele só fica habilitado quando todos os cards selecionados estão delegados ao Super Agent e não estão Done — se mesmo um card da seleção não atender a esse critério, a ação não é disparada para o restante da seleção.
+- Ao confirmar, uma nova execução é iniciada em cada task selecionada, e qualquer execução ainda em andamento nela é interrompida. Esse aviso de "takeover" é exibido incondicionalmente para uma seleção, já que o board não consegue diferenciar uma execução em streaming de uma travada quando são vários cards ao mesmo tempo.
+- Cada task da seleção continua contando para o seu próprio [limite de re-execuções por task](#billing-e-cota-de-auto-tasks) (5 re-execuções por task).
+
+
+ Não existe uma chamada de API de re-run em lote — cada task selecionada dispara sua própria requisição de re-run individualmente. Se uma delas atingir a cota de auto-task ou um paywall, esse erro aparece uma vez, não uma vez por task.
+
+
+## Enviando para produção
+
+Quando todos os revisores habilitados aprovaram o pull request de uma task — ou nenhum revisor está habilitado — o card da task mostra um botão **Ship to production**. Clicar nele mescla o pull request. Se o auto-merge estiver habilitado, isso acontece automaticamente assim que o gate de revisão é satisfeito, em vez de esperar alguém clicar no botão.
+
+O painel de PR de cada card também mostra o estado ao vivo do pull request (draft, open, merged, closed) e o status dos checks (passing, pending ou failing), para você ver de imediato se uma task está pronta para avançar.
+
+## Findings publicados por um report
+
+Alguns cards não são criados por uma pessoa — um report (por exemplo, o **Report Agent**) pode publicar findings de diagnóstico direto no board. Esses cards se comportam como qualquer outro, com uma diferença: excluir um deles **descarta (dismiss) o finding subjacente**, não só o card.
+
+
+ Depois que um finding é descartado, a próxima execução do report o ignora
+ em vez de recriar o card. Excluir um card gerado por report é reversível —
+ peça ao agent **Task Manager** para restaurar um finding descartado (ou
+ todos eles) e o card volta com seus comentários, atividade e qualquer PR
+ vinculado intactos.
+
+
+O agent Task Manager avisa quando o card que você está excluindo veio de um report, para que você saiba que excluí-lo também suprime esse finding a partir de então.
+
+Por padrão, um card publicado por um report fica sem responsável. Ative **Auto-assign report tasks to the Super Agent** em **Settings → Organization → Reviewers & merge** para que esses cards sejam atribuídos automaticamente ao Super Agent assim que forem criados, em vez de esperar alguém pegá-los.
+
+## Billing e cota de auto-tasks
+
+Delegar uma task ao **Super Agent** — pelo diálogo da task, ou atribuindo um card a ele em uma lane ou no seletor de assignee — consome a cota de auto-task da sua organização. Tasks que você mesmo cria e trabalha nunca são limitadas.
+
+- **Trial gratuito**: toda organização recebe **3 execuções de auto-task gratuitas por toda a vida** antes de precisar de uma subscription.
+- **Assinado (subscribed)**: **$50/mês** para **10 execuções de auto-task por ciclo de billing**. A cota renova automaticamente no início de cada ciclo.
+- **Limite por task**: qualquer task individual pode ser re-executada até **5 vezes**, independente do status da subscription.
+
+Quando uma delegação é bloqueada pela cota, um diálogo explica o motivo:
+
+- **Trial esgotado** — mostra os benefícios da subscription e um botão **Subscribe** que abre o checkout hospedado no Stripe em uma nova aba.
+- **Cota mensal esgotada** — apenas informativo; a cota renova por conta própria no próximo ciclo de billing.
+- **Limite de re-execuções da task atingido** — apenas informativo; crie uma nova task para continuar.
+
+
+ Esse paywall nunca bloqueia você de criar ou editar tasks você mesmo — ele se aplica apenas à delegação ao Super Agent.
+
+
+### Gerenciando billing
+
+Vá em **Settings → Billing** para ver o status atual da sua organização (**Free trial**, **Active** ou **Payment issue**), as execuções usadas no ciclo atual e a data de renovação. A partir daí você pode assinar ou, uma vez assinante, abrir o portal de billing hospedado no Stripe para gerenciar sua forma de pagamento ou cancelar.
+
+
+ Deployments self-hosted não aplicam essa cota por padrão — as execuções de auto-task são ilimitadas a menos que o operador do deployment habilite explicitamente a aplicação de billing. Veja [Docker Compose](/pt-br/studio/self-hosting/deploy/docker-compose) para as variáveis de ambiente relevantes.
+
diff --git a/client.ts b/client.ts
new file mode 100644
index 0000000000..a45d411509
--- /dev/null
+++ b/client.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by @decocms/typegen. Do not edit manually.
+// Regenerate with: bunx @decocms/typegen --mcp --key --output
+
+import { createStudioClient } from "@decocms/typegen";
+
+export interface Tools {}
+
+export const client = createStudioClient({
+ mcpId: "vir_tFfcM9madOxKe0krs7XoR",
+ apiKey: process.env.STUDIO_API_KEY ?? process.env.MESH_API_KEY,
+ baseUrl: process.env.STUDIO_BASE_URL ?? process.env.MESH_BASE_URL,
+});