decocms · deco-cms · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
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
@@ -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.
+
+<Callout type="tip">
+  Prefer the tooltip on content-heavy blocks with many fields — it keeps the form compact without losing the schema's guidance text.
+</Callout>
+
 ## 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
@@ -60,37 +60,45 @@ 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.
+
+<Callout type="tip">
+  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.
+</Callout>
+
 ### 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
 
-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:
-
-**Cloud**
+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.
 
-**Local** — run the agent on your own machine. Until a local runtime is connected, these options read **"Desktop not detected"** and stay disabled.
+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.
+
+<Callout type="tip">
+  The managed sandbox is the right default for every run, attended or unattended — teammates never need a local setup to use an agent.
+</Callout>
 
-- **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
+### Studio Native: coding-agent terminals
 
-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.
+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.
 
-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.
+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.
 
-<Callout type="tip">
-  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.
+<Callout type="info">
+  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.
 </Callout>
 
-## Windows
-
-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/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.
 
 <ArchitectureDiagram />
 
 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.<thread>`) → UI live tail; (2) the pull work-queue (`link.work.<user>`) → 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.<thread>`) → UI live tail. |
 
 <Callout type="warning">
   **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,16 @@ 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.<user>`; 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 exactly one importable repo — the repo has to be resolved before dispatch, since the harness binds its checkout at run start. Otherwise those tasks run Decopilot exactly as before.
 
 ## MCP: in-process vs. the proxy routes
 
@@ -110,36 +114,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 `<handle>.preview.<domain>`, 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); `<handle>.localhost:<port>` (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 `<appRoot>/org/<volume>`, 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 +134,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/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
@@ -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.
 
+<Callout type="warning">
+  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.
+</Callout>
+
 ### 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
@@ -15,7 +15,7 @@ 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