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..d5513e8716 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,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. + + + 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 -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. + + + The managed sandbox is the right default for every run, attended or unattended — teammates never need a local setup to use an agent. + -- **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. - - 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. + + 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. -## 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 index 387125b7e0..8a0649cc27 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,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.`; 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 `.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 +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 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..37b64dea12 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,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 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..dfcb05905f 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,6 +67,11 @@ 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_TOPUP_FEE_PERCENT` only matters if you enable Stripe-backed billing (`STRIPE_SECRET_KEY` / `STRIPE_ORG_PRICE_ID`). Most self-hosted deployments don't set these and can ignore it. + The container runs as user `1001:1001` and persists data to the `studio-data` volume; the bundled Postgres persists to `postgres-data`. @@ -99,7 +104,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 +155,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..101f6b678c 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,6 +242,24 @@ 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. +### 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. @@ -313,16 +331,25 @@ 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` | | `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..a4ba9b0d56 --- /dev/null +++ b/apps/docs/client/src/content/deco-studio/en/studio/task-board.mdx @@ -0,0 +1,45 @@ +--- +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. + +## 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. + +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. + + +## 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. 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..ba115f6c91 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,46 @@ 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 -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: - -**Cloud** +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. -**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. +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. + + + 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. + -- **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 +### Studio Native: terminais de coding agent -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. +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. -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. +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. - - 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. + + 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/architecture.mdx b/apps/docs/client/src/content/deco-studio/pt-br/studio/architecture.mdx index 14b2ce1ee5..179bf64da4 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,16 @@ 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 exatamente um repo importável — o repo precisa ser resolvido antes do dispatch, já que o harness vincula seu checkout no início do run. Caso contrário, essas tasks rodam no Decopilot exatamente como antes. ## MCP: in-process vs. as rotas de proxy @@ -110,36 +114,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 +134,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/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..69a0eb9594 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,7 +15,7 @@ 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 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..e5aef4d5f7 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,6 +67,11 @@ 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_TOPUP_FEE_PERCENT` só importa 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á-la. + O container roda como usuário `1001:1001` e persiste dados no volume `studio-data`; o Postgres embutido persiste em `postgres-data`. @@ -99,7 +104,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 +155,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..cbbcf85ef2 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,6 +242,24 @@ 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. +### 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. @@ -313,16 +331,25 @@ 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` | | `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..e26f9b26fd --- /dev/null +++ b/apps/docs/client/src/content/deco-studio/pt-br/studio/task-board.mdx @@ -0,0 +1,45 @@ +--- +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. + +## 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. + +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. + + +## 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.