@cursor/bdk 0.2.2 → 0.2.3

package/dist/docs/llms-full.txt

@@ -232,24 +232,55 @@ values without echoing them; `secrets list` returns names and creation
 times only. Do not pass `NAME=VALUE`, print a secret to verify it, or
 put names beginning with reserved `CURSOR_` in `secretNames`.
 
-Enter egress hosts without schemes, ports, or paths. The
+A hosted deployment receives its secrets per request, after its modules
+are loaded, so code that reads `process.env` while a module is still
+loading sees nothing. Read a secret inside the handler, tool, or callback
+that needs it, and give an MCP connection its credential as a `${NAME}`
+template, which resolves when the connection opens. See
+[credentials in headers and env](/docs/reference/connections.md#credentials-in-headers-and-env).
+
+Enter egress hosts without schemes or paths. An HTTPS host needs no port;
+add one, as `clickhouse.example.com:9440`, only for a protocol the proxy
+reads no hostname from. The
 [Host MCP OAuth guide](/docs/guides/mcp-oauth.md) owns the extra secret and
 egress steps for OAuth-backed MCP servers.
 
 ## Use the hosted agent
 
-The `--prod` commands authenticate through your Cursor credential and
-connect to the deployment directly. Open the playground, run a turn,
-then inspect the same session in logs.
+### Verify a hosted turn
+
+Start a turn on the deployment:
 
 ```text
-bdk playground --prod --slug weather-agent
 bdk run --prod --slug weather-agent \
   --message "Forecast for Paris"
-bdk logs --prod --slug weather-agent
-bdk deployment weather-agent
 ```
 
+The command returns as soon as the deployment accepts the turn, so the output
+has a `deliveryId` but no `sessionId` yet. That's expected, with or without
+`--dry-run`. Open the deployment from **Deployed Agents** in the
+[dashboard](https://cursor.com/dashboard) and select **Sessions** to find the
+new session's `ses_...` ID.
+
+Check the session from the CLI:
+
+```text
+bdk session ses_... --prod --slug weather-agent
+```
+
+While the turn runs, the command reports how many events have arrived and
+prints `Turn running; runs may lag behind events.` Rerun it until the latest
+run shows a final status such as `finished`. High-effort turns can take about
+eight minutes, and runs can stay empty until the turn ends, so a growing event
+count is the progress signal. Escalate only when no new events arrive for about
+two to three minutes.
+
+Hosted deployments don't support `bdk call` or `bdk sessions`, so use
+`bdk run --prod` and `bdk session` instead. Dashboard links to a single session
+may not open yet, so confirm the result with `bdk session`.
+
+### Call the hosted HTTP API
+
 External HTTP clients use the stable alias URL and send the alias token
 on every request:
 
@@ -280,13 +311,12 @@ the new generation replaces the previous one.
 bdk deploy --dir . --slug weather-agent
 ```
 
-A redeploy replaces its source, Cursor-event repository list, and any
-egress domains supplied through CLI flags. Repass
-`--cursor-events-repo` and other CLI-only settings each time. Keep
-source-controlled egress in the `hosting` block when possible.
+A redeploy replaces its source, its watched repositories, and any egress
+domains supplied through CLI flags. Pass every `--cursor-events-repo` value
+again; without the flag, the deployment watches its GitHub source repository.
+Keep source-controlled egress in the `hosting` block when possible.
 
-Use `bdk deployment weather-agent` and
-`bdk logs --prod --slug weather-agent` to inspect a rollout.
+Use `bdk deployment weather-agent` to inspect a rollout.
 The [CLI reference](/docs/reference/cli.md#deploy) owns `--no-wait`,
 multi-agent deployment, stop, and delete behavior.
 
@@ -341,10 +371,10 @@ per-caller and channel-specific auth.
 
 ## Observability
 
-Use `bdk logs --prod` for runtime output,
+Use `bdk session <sessionId> --prod` for a hosted session's runs and logs,
 [OpenTelemetry](/docs/guides/opentelemetry.md) for traces and metrics, and
 [session traces](/docs/reference/sessions.md#inspect-a-saved-event-stream)
-for one conversation.
+for a local conversation.
 
 ## Related
 
@@ -1553,6 +1583,40 @@ Each hook returns one of three outcomes:
 
 [Channels](/docs/reference/channels.md) covers the shared session behavior.
 
+## Choose watched repositories
+
+The examples above list their repositories in the channel with
+`cursorAccount: { repos: [...] }`. A hosted deployment receives events for the
+repositories set at deploy time, so pass each one to `bdk deploy`:
+
+```text
+bdk deploy --dir . --cursor-events-repo acme/checkout
+```
+
+To keep the list out of source, set `cursorAccount: true` and pass the
+repositories on the command line instead. `bdk serve` takes repeatable
+`--repo` flags:
+
+```ts
+export default githubChannel({
+  cursorAccount: true,
+});
+```
+
+```text
+bdk serve --dir . --cursor-events \
+  --repo acme/checkout --repo acme/payments
+bdk deploy --dir . \
+  --cursor-events-repo acme/checkout \
+  --cursor-events-repo acme/payments
+```
+
+The `--cursor-events-repo` flags on a deploy form its complete list and
+replace the previous one, so pass every repository on each redeploy. A deploy
+without the flag watches the agent's GitHub source repository instead. Use
+[`bdk event-repos`](/docs/reference/cli.md#event-repos) to change or clear the
+list without redeploying.
+
 ## PR and agent affinity
 
 Every wake for the same repo and PR number resumes the same session. The
@@ -3254,6 +3318,11 @@ the browser and writes the resulting tokens to `.env.local` without
 printing them. You can open the same wizard from **Integrations** on
 [Deployed Agents](https://cursor.com/dashboard).
 
+If Slack requires workspace-admin approval, keep `slack create` running and
+open the **Request approval** link printed by the CLI. Installing from the
+dashboard doesn't send that request for you. After an admin approves it,
+return to the dashboard's **Add Slack** wizard and select **Retry**.
+
 If you already own the Slack app, initialize it with
 `bdk slack init --manual --dir . --name "Triage"` and follow the
 [Slack setup skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md) for installation
@@ -4063,12 +4132,18 @@ export default githubChannel({
     return {
       auth: defaultGitHubAuth(ctx),
       title: `Review ${ctx.repository.fullName}#${pr.number}`,
-      context: `Review ${pr.url}. Inspect it first, then submit your verdict with submit_review.`,
+      context: [
+        `Review ${pr.url}. Inspect it first, then submit your verdict with submit_review.`,
+      ],
     };
   },
 });
 ```
 
+Channel-turn `context` is a `readonly string[]`, so wrap each context block in
+an array. The `context` label under `progress.commitStatus` is a separate
+string option.
+
 Keep `bdk dev` running. In a second terminal, replay an open pull
 request. Pull access is enough; repo admin isn't required:
 
@@ -4335,7 +4410,7 @@ export default defineArtifacts({
 | --- | --- |
 | `kinds` | Map of accepted kind names to a non-empty `description` and optional Zod `schema` |
 | `agentTool` | Expose `tag_artifact` to the model; requires at least one declared kind |
-| `max` | Positive retention cap, default `1000`. Architecture v1 and self-hosted v2 evict the oldest-updated record. Hosted architecture v2 does not evict |
+| `max` | Positive retention cap, default `1000`. Local and self-hosted servers evict the oldest-updated record; hosted deployments don't evict. |
 
 With declared kinds, `tag` rejects any other kind. With no registry, it
 accepts free-form kind names and defaults an omitted kind to
@@ -4674,12 +4749,12 @@ provide their own `help` subcommands.
 | --- | --- |
 | [`chat`](#chat) | Talk to a running agent |
 | [`resume`](#resume) | Reattach chat to a previous session |
-| [`run`](#run) | Start or continue work on a local, running, or managed agent |
+| [`run`](#run) | Start or continue work on a local, running, or hosted agent |
 | [`call`](#call) | Call a server tool without a model turn |
 | [`skill`](#skill) | Read an authored skill without a model turn |
 | [`logs`](#logs) | Follow or dump agent logs |
 | [`sessions`](#sessions) | List sessions |
-| [`session`](#session) | Inspect a session or start a managed session turn |
+| [`session`](#session) | Inspect a session or start a hosted session turn |
 | [`cost`](#cost) | Report token usage and estimated cost |
 | [`playground`](#playground) | Open an agent's playground |
 | [`trajectory`](#trajectory) | Summarize a saved event stream |
@@ -4694,8 +4769,8 @@ provide their own `help` subcommands.
 | [`deployment`](#deployment) | Inspect one deployment |
 | [`stop`](#stop) | Stop a deployment |
 | [`cancel-runs`](#cancel-runs) | Cancel active runs and reminder wakes |
-| [`event-repos`](#event-repos) | Replace a managed application's event repositories |
-| [`upgrade`](#upgrade) | Move a managed application to a release |
+| [`event-repos`](#event-repos) | Replace a deployment's event repositories |
+| [`upgrade`](#upgrade) | Move a deployment to a release |
 | [`delete`](#delete) | Delete a deployment |
 | [`rotate-token`](#rotate-token) | Replace a deployment's alias token |
 | [`secrets`](#secrets) | Set, list, or remove deployment secrets |
@@ -4721,8 +4796,7 @@ Commands that send requests support these targets:
 | Ephemeral local server | Omit `--url` and `--prod` | `run`, `call`, `skill`, `eval` |
 | Running server | Pass `--url <baseUrl>` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
 | Default local server | Omit `--url` and `--prod`; uses `http://127.0.0.1:3000` | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground` |
-| Hosted deployment | Pass `--prod` | `chat`, `resume`, `run`, `call`, `skill`, `eval`, `logs`, `sessions`, `session`, `cost`, `playground`, `mcp` |
-| Managed application | Pass `--prod` | `run`, `session` |
+| Hosted deployment | Pass `--prod` | `run`, `session`, `playground` |
 
 An explicit `--url` must include the slug for a multi-agent server, such as
 `http://127.0.0.1:3000/pr-approver`. `--slug` never changes an explicit URL.
@@ -4732,7 +4806,7 @@ An explicit `--url` must include the slug for a multi-agent server, such as
 | --- | --- |
 | `--dir <path>` | Select the project root. The default is the current directory. |
 | `--url <baseUrl>` | Use a running agent instead of local project discovery. |
-| `--prod` | Use a hosted deployment or managed application. Command support depends on the target type as listed above. |
+| `--prod` | Use the hosted deployment. Only `run`, `session`, and `playground` accept it. |
 | `--slug <slug>` | Select an agent from a multi-agent project or a hosted resource. Under `--prod`, the default is the `--dir` basename. |
 | `--team <id>` | Select a Cursor team. The signed-in account's team is the default. |
 | `--api-key <key>` | Override the Cursor credential for commands that authenticate with Cursor. |
@@ -4810,9 +4884,9 @@ prints the URL without opening a browser.
 `chat` connects to a running server and never starts an ephemeral one:
 
 ```text
-bdk chat [--url <baseUrl> | --prod] [--message <text>]
+bdk chat [--url <baseUrl>] [--message <text>]
   [--session <id> | --resume] [--continuation-token <token>]
-  [--slug <slug>] [--team <id>] [--json] [--text] [--no-color]
+  [--slug <slug>] [--json] [--text] [--no-color]
 ```
 
 | Input mode | Behavior |
@@ -4834,9 +4908,9 @@ token. An explicit session ID takes precedence.
 `resume` provides the same reattachment contract as `chat --session`:
 
 ```text
-bdk resume [sessionId] [--url <baseUrl> | --prod]
+bdk resume [sessionId] [--url <baseUrl>]
   [--message <text>] [--json] [--text]
-  [--continuation-token <token>] [--slug <slug>] [--team <id>]
+  [--continuation-token <token>] [--slug <slug>]
 ```
 
 Omit the session ID to select the most recently updated followable session.
@@ -4858,27 +4932,28 @@ bdk run [--dir <path>] [--message <text>]...
 
 | Option | Contract |
 | --- | --- |
-| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. Managed starts accept one message. |
+| `--message <text>` | Send a user message. Repeat it for a multi-turn local or `--url` run. `--prod` starts accept one message. |
 | `--messages-file <path>` | Read a JSON array of strings. File messages run before repeated `--message` values. |
-| `--session <id>` | Continue a session. Managed session starts accept a hosted `ses_...` ID. |
-| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. Managed session starts use `--session` instead. |
+| `--session <id>` | Continue a session. With `--prod`, pass a hosted `ses_...` ID. |
+| `--continuation-token <token>` | Continue the session selected by `--session` on a running server. `--prod` starts use `--session` instead. |
 | `--events <file>` | Write the raw NDJSON stream to this path. |
 | `--no-events` | Skip the NDJSON trace. |
 | `--text` | Print a compact trajectory instead of JSON. |
 | `--timeout-ms <n>` | Stop waiting after a positive number of milliseconds. There is no default timeout. |
 | `--no-stream` | Hide live tool and reply progress on stderr. |
-| `--dry-run` | Mark a managed session turn as non-mutating. |
-| `--as-of <instant>` | Freeze a managed session's clock at a timezone-bearing ISO-8601 instant. |
-| `--component <key>` | Select a managed application's component instead of its default. |
+| `--dry-run` | Mark a `--prod` turn as non-mutating. |
+| `--as-of <instant>` | Freeze a `--prod` session's clock at a timezone-bearing ISO-8601 instant. |
+| `--component <key>` | Select a hosted deployment's component instead of its default. |
 
 For local and running-server targets, JSON output contains `ok`, `sessionId`,
 `continuationToken`, `trace`, `playgroundUrl`, `playgroundHint`, `visualize`,
 and `trajectory`. The `trace` value gives the saved path when event output is
-enabled. A managed session start confirms acceptance; a continuation also
-returns `sessionId`. Managed starts return before the turn finishes and ignore
-`--events`, `--no-events`, `--text`, `--timeout-ms`, and `--no-stream`.
-A successful managed start exits `0` on acceptance, before its turn outcome is
-known. A fresh start doesn't return `sessionId` synchronously.
+enabled. With `--prod`, `run` prints a `deliveryId` when the deployment accepts
+the turn and returns before the turn finishes. A fresh start has no
+`sessionId` yet, even with `--dry-run`; a continuation includes it. `--prod`
+starts ignore `--events`, `--no-events`, `--text`, `--timeout-ms`, and
+`--no-stream`, and a successful start exits `0` before the turn outcome is
+known. See [Verify a hosted turn](/docs/deployment.md#verify-a-hosted-turn).
 
 ### Call a tool {#call}
 
@@ -4886,8 +4961,8 @@ known. A fresh start doesn't return `sessionId` synchronously.
 
 ```text
 bdk call <tool> [--input <json>]
-  [--dir <path> | --url <baseUrl> | --prod]
-  [--session <id>] [--slug <slug>] [--team <id>]
+  [--dir <path> | --url <baseUrl>]
+  [--session <id>] [--slug <slug>]
 ```
 
 `--input` accepts JSON and defaults to `{}`. `--session` uses the session
@@ -4895,6 +4970,9 @@ workspace and records the call on its event stream. The command prints the
 server's JSON response and succeeds only when the HTTP response succeeds with
 `ok: true`.
 
+Hosted deployments don't support `call`. Start a model turn with `run --prod`
+and check it with [`session`](#session).
+
 See [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn) for validation,
 busy-session behavior, and error codes.
 
@@ -4903,8 +4981,8 @@ busy-session behavior, and error codes.
 `skill` reads an authored skill without a model turn:
 
 ```text
-bdk skill <name> [--dir <path> | --url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--text]
+bdk skill <name> [--dir <path> | --url <baseUrl>]
+  [--slug <slug>] [--text]
 ```
 
 The default output is the server's JSON response. `--text` prints the rendered
@@ -4913,14 +4991,18 @@ The default output is the server's JSON response. `--text` prints the rendered
 ### List sessions {#sessions}
 
 ```text
-bdk sessions [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--bearer-token <token>] [--json]
+bdk sessions [--url <baseUrl>]
+  [--slug <slug>] [--bearer-token <token>] [--json]
 ```
 
 Text output shows the session ID, channel, mode, turn count, running status,
 and update time. `--json` prints `{ sessions }`, including continuation
 tokens.
 
+Hosted deployments don't support `sessions`. Find a hosted session in the
+deployment's **Sessions** list in the dashboard, then check it with
+[`session <sessionId> --prod`](#session).
+
 ### Inspect a session {#session}
 
 ```text
@@ -4939,29 +5021,31 @@ bdk session --prod [<sessionId>] --slug <slug> --message <text>
 | `--json` | Print the trajectory object. |
 | `--events` | Print `{ sessionId, events }` with the raw event list. |
 | `--out <file.ndjson>` | Write the raw NDJSON trace instead of printing it. |
-| `--prod --message <text>` | Start a managed session or continue the supplied managed session ID. |
+| `--prod --message <text>` | Start a hosted session or continue the supplied hosted session ID. |
 
-`--events` and `--json` are mutually exclusive. Managed sessions without an
-event trajectory return hosted execution status and logs in text or JSON;
-`--events` and `--out` require an event trajectory. Use [`resume`](#resume) to
-continue a conversational session.
+`--events` and `--json` are mutually exclusive. With `--prod`, the command
+prints the session's runs and logs in text or JSON, and `--events` and `--out`
+aren't available. While a hosted turn is running, text output also reports the
+event count so far and prints `Turn running; runs may lag behind events.` Use
+[`resume`](#resume) to continue a conversational session.
 
 ### Follow logs {#logs}
 
 ```text
-bdk logs [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--once] [--json]
+bdk logs [--url <baseUrl>]
+  [--slug <slug>] [--once] [--json]
 ```
 
 The command follows logs until Ctrl-C. `--once` prints the current buffer and
-exits; `--json` emits newline-delimited JSON events. A hosted deployment
-reports deployment progress before runtime logs become available.
+exits; `--json` emits newline-delimited JSON events. For a hosted deployment,
+use [`deployment`](#deployment) for rollout status and
+[`session <sessionId> --prod`](#session) for a session's runs and logs.
 
 ### Report costs {#cost}
 
 ```text
-bdk cost [sessionId] [--url <baseUrl> | --prod]
-  [--slug <slug>] [--team <id>] [--json]
+bdk cost [sessionId] [--url <baseUrl>]
+  [--slug <slug>] [--json]
 ```
 
 With a session ID, `cost` prints per-turn token usage and estimated cost.
@@ -4979,6 +5063,8 @@ bdk playground [--url <baseUrl> | --prod] [--session <id>]
 The command prints the playground URL and opens it unless `--print` is set.
 `--session` opens a deep link. A running target with credentials that a
 browser can't send starts a loopback proxy and stays open until Ctrl-C.
+`--session` links for a hosted deployment may not open yet; check that session
+with [`session <sessionId> --prod`](#session) instead.
 
 ### Inspect a trajectory {#trajectory}
 
@@ -5001,8 +5087,7 @@ bdk eval [--dir <path>] [evalId...]
   [--timeout-ms <n>] [--strict] [--max-concurrency <n>]
   [--junit <path>] [--artifacts <dir> | --no-artifacts]
   [--skip-report] [--out <file.json>] [--no-stream]
-  [--url <baseUrl> | --prod] [--no-wait]
-  [--slug <slug>] [--team <id>]
+  [--url <baseUrl>] [--no-wait] [--slug <slug>]
 ```
 
 Select an exact case such as `weather/nyc`, a file prefix such as `weather`,
@@ -5025,22 +5110,18 @@ between 1 and 200.
 | `--no-artifacts` | Skip artifacts for an ephemeral local run. |
 | `--skip-report` | Ignore reporters from eval files and the eval config during an ephemeral local run. |
 | `--out <file.json>` | Also write the full result JSON. |
-| `--no-wait` | Return after a running server or hosted deployment accepts the batch. |
+| `--no-wait` | Return after a running server accepts the batch. |
 
-A running server or hosted deployment prints its Eval ID when it accepts the
-batch.
+A running server prints its Eval ID when it accepts the batch.
 Use these commands to inspect or cancel it:
 
 ```text
-bdk eval status [evalId] --prod [--slug <slug>] [--team <id>]
 bdk eval status [evalId] --url <baseUrl>
-bdk eval cancel <evalId> --prod [--slug <slug>] [--team <id>]
 bdk eval cancel <evalId> --url <baseUrl>
 ```
 
 `eval status` without an ID lists recent remote runs. `eval status --out`
-requires an ID. The `status` and `cancel` subcommands require `--url` or
-`--prod`.
+requires an ID. The `status` and `cancel` subcommands require `--url`.
 
 ## Projects
 
@@ -5192,7 +5273,7 @@ service-account API key with agent access can deploy.
 | `--repo <https-url>` | Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required. |
 | `--ref <git-ref>` | Set the source Git ref. The CLI infers the current branch when possible. |
 | `--path <agent-path>` | Set the project path relative to the repository root. |
-| `--cursor-events-repo <owner/name>` | Add a repository whose SCM events reach the deployment. Repeat for multiple repositories. |
+| `--cursor-events-repo <owner/name>` | Watch a repository's Cursor events. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository. |
 | `--allow-domain <domain>` | Add an egress hostname. Repeat for multiple domains; values are combined with `hosting.egressDomains`. |
 | `--no-wait` | Return after the deployment request is accepted. |
 | `--json` | Print one object for one target or an array for multiple targets. |
@@ -5200,7 +5281,8 @@ service-account API key with agent access can deploy.
 Deployment slugs contain lowercase letters, digits, `_`, or `-`, start with a
 letter or digit, and have at most 64 characters. Egress entries are lowercase
 hostnames with an alphabetic top-level domain; one leading `*.` wildcard is
-allowed, with at most 20 entries.
+allowed, or a trailing `:port` for a protocol that is not HTTPS, with at most
+64 entries.
 
 By default, `deploy` waits until the deployment is running and exits nonzero
 if it reaches a failed state. A first deployment can return an alias token
@@ -5235,8 +5317,7 @@ bdk stop <slug> [--team <id>] [--no-wait] [--cancel-runs] [--json]
 
 The command waits for `stopped` by default. `--no-wait` returns after the
 request is accepted. `--cancel-runs` also requests cancellation of active
-runs and reminder wakes for a managed application. Other deployment types
-reject this option.
+runs and reminder wakes.
 
 ### Cancel active runs {#cancel-runs}
 
@@ -5244,8 +5325,8 @@ reject this option.
 bdk cancel-runs <slug> [--team <id>] [--json]
 ```
 
-The command requests cancellation for a managed application's active runs and
-reminder wakes. Other deployment types reject it. For a multi-tenant
+The command requests cancellation for a deployment's active runs and reminder
+wakes. For a multi-tenant
 application, this cancels every install; use `stop --cancel-runs` for
 install-local cancellation. It exits nonzero if any cancellation request fails
 to start.
@@ -5257,11 +5338,11 @@ bdk event-repos <slug> [--repo <owner/name>]...
   [--team <id>] [--json]
 ```
 
-The supplied repositories replace the managed application's complete event
-repository list; they aren't merged with the previous list. Omit `--repo` to
-clear the list.
+The supplied repositories replace the deployment's complete event repository
+list; they aren't merged with the previous list. Omit `--repo` to clear the
+list.
 
-### Upgrade a managed application {#upgrade}
+### Upgrade a deployment {#upgrade}
 
 ```text
 bdk upgrade <slug> [--release <id-or-version>]
@@ -5316,11 +5397,8 @@ most 4096 bytes, and each deployment holds at most 32 secrets.
 ### Connect an MCP client {#mcp}
 
 ```text
-bdk mcp --prod [--slug <slug>] [--team <id>]
 bdk mcp --url <baseUrl> [--bearer-token <token>]
 
-bdk mcp install --prod [--slug <slug>] [--team <id>]
-  [--name <server-name>] [--print] [--json] [--remote]
 bdk mcp install --url <baseUrl> [--bearer-token <token>]
   [--name <server-name>] [--print] [--json]
 ```
@@ -5329,7 +5407,6 @@ bdk mcp install --url <baseUrl> [--bearer-token <token>]
 | --- | --- |
 | `mcp` | Read newline-delimited JSON-RPC from stdin and proxy it to the selected agent's MCP endpoint. stdout is reserved for MCP messages. A target is required. |
 | `mcp install` | Add the selected agent to `~/.cursor/mcp.json`. `--name` sets the server name, `--print` previews the entry, and `--json` prints a machine-readable result. A `--url` entry with `--bearer-token` contains that token; handle printed and written copies as credentials. |
-| `mcp install --remote --prod` | Write a remote HTTP entry for clients that can't spawn a stdio process. The entry contains the API key in plain text and must be handled as a credential. |
 
 ### Authorize MCP OAuth {#mcp-oauth}
 
@@ -5344,7 +5421,7 @@ bdk mcp oauth <connection> [--dir <path>] [--store]
 | Connection | Result |
 | --- | --- |
 | `defineConnection({ url, oauth: true })` | Open a browser PKCE flow and save tokens in `mcp-auth.json` under the CLI config directory. `--store` also sets the matching deployment secrets. |
-| `defineConnection({ cursorAccount: true })` | Authorize the managed deployment's service account through Cursor. `--store` isn't needed. |
+| `defineConnection({ cursorAccount: true })` | Authorize the hosted deployment's service account through Cursor. `--store` isn't needed. |
 
 Stored secret names are `MCP_OAUTH_<NAME>_ACCESS_TOKEN`,
 `MCP_OAUTH_<NAME>_REFRESH_TOKEN`, and `MCP_OAUTH_<NAME>_CLIENT_ID`. Declare
@@ -5558,11 +5635,37 @@ import { defineConnection } from "@cursor/bdk/connections";
 
 export default defineConnection({
   url: "https://mcp.linear.app/mcp",
-  headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
+  headers: { authorization: "Bearer ${LINEAR_TOKEN}" },
 });
 ```
 
-Tokens come from env vars. Never hardcode them in the file.
+## Credentials in headers and env
+
+Write a credential as a `${NAME}` template in `headers` on a remote
+connection or in `env` on a stdio one. The connection stores the template
+as you wrote it and reads `NAME` from the environment every time it opens a
+client, so the value can arrive after the project loads.
+
+```ts
+export default defineConnection({
+  command: "slack-mcp-server",
+  args: ["--transport", "stdio"],
+  env: { SLACK_MCP_XOXB_TOKEN: "${SLACK_BOT_TOKEN}" },
+});
+```
+
+That timing is the point of the template. Your connection file is imported
+once, when the project loads, and a hosted deployment has none of its
+secrets in the environment yet, because the platform passes them to the
+agent per request. So a `process.env.SLACK_BOT_TOKEN` read at the top of
+the file captures an empty string and keeps sending it for the life of the
+process, while the same file works locally because `.env.local` was read
+before the import. The template form is right in both places.
+
+`bdk validate` warns about a template the environment does not define and
+names the variable. It stays a warning rather than an error, since a
+hosted deployment resolves it later. An unset variable resolves to an
+empty value at connect time, which the server reports as an auth failure.
 
 ## Host MCP OAuth
 
@@ -6077,19 +6180,18 @@ disables them. This location is independent of `--state-root`.
 
 ## Run evals against a server
 
-The playground **Evals** view starts batches on its running server.
-`--url` targets a named running server, and `--prod --slug <slug>`
-targets a hosted deployment.
+The playground **Evals** view starts batches on its running server, and
+`--url` targets a named running server:
 
 ```text
-bdk eval --prod --slug vulnerability-scanner --tag smoke
-bdk eval status <eval-id> --prod --slug vulnerability-scanner
-bdk eval cancel <eval-id> --prod --slug vulnerability-scanner
+bdk eval --url http://127.0.0.1:3000/vulnerability-scanner --tag smoke
+bdk eval status <eval-id> --url http://127.0.0.1:3000/vulnerability-scanner
+bdk eval cancel <eval-id> --url http://127.0.0.1:3000/vulnerability-scanner
 ```
 
 Server-side batches use the target's discovered cases and return an eval
 ID for `status` or `cancel`. Local reporter and concurrency flags don't
-apply to `--url` or `--prod` runs.
+apply to `--url` runs.
 
 ## Related
 
@@ -8328,6 +8430,7 @@ Match the visible symptom below. The `bdk` binary ships with
 | File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
 | The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `bdk login`. |
 | Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
+| The first turn reports `[resource_exhausted]` | Treat it as a capacity-shaped error. For a GitHub wake, also check the connected GitHub credential and any GitHub `429` rate limit before assuming the model quota is exhausted. |
 
 ## A turn behaves unexpectedly
 
@@ -8354,9 +8457,12 @@ Match the visible symptom below. The `bdk` binary ships with
 | What you see | What to do |
 | --- | --- |
 | Local changes do not appear after deploy | `deploy` reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again. |
-| The deployment never becomes running | Run `bdk deployment <slug>` and `bdk logs --prod --slug <slug>`, then act on the reported build or startup error. |
+| The deployment never becomes running | Run `bdk deployment <slug>`, then act on the reported build or startup error. |
 | A secret or egress change has no effect | Confirm the name with `secrets list`, verify the `hosting` block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy. |
-| Cursor events stopped after redeploy | Redeploy replaces CLI-supplied event repositories. Pass every `--cursor-events-repo` value again. |
+| Cursor events stopped after redeploy | Each redeploy replaces the watched repositories. Pass every `--cursor-events-repo` value again; without the flag, the deployment watches only its GitHub source repository. |
+| `run --prod` prints a `deliveryId` but no `sessionId` | The deployment accepted the turn and is still starting it, which is expected with or without `--dry-run`. Find the session in the deployment's **Sessions** list in the dashboard, then follow [Verify a hosted turn](/docs/deployment.md#verify-a-hosted-turn). |
+| A high-effort turn runs for several minutes while runs look empty | Turns can take about eight minutes. Rerun `bdk session <sessionId> --prod --slug <slug>`; a growing event count means the turn is still working. Escalate only after about two to three minutes with no new events. |
+| A dashboard link to a single session returns 404 | Check the session with `bdk session <sessionId> --prod --slug <slug>`. |
 | External HTTP rejects the alias token | Update the caller with the current token. If the token is lost or exposed, run `bdk rotate-token <slug>` and replace it everywhere. |
 
 See [Deployment](/docs/deployment.md) for source, credential, and
@@ -8379,7 +8485,7 @@ direct webhooks.
 | What you see | What to do |
 | --- | --- |
 | Logs say `channel idle ... missing credentials` | Run `bdk slack create --dir <agent>`, then check the generated prefix with `bdk slack doctor`. Use `slack init --manual` only for an app you own. |
-| `slack create` is waiting for workspace approval | Open the approval link printed by the CLI, keep the command running, and retry after an admin approves. |
+| `slack create` is waiting for workspace approval | Keep the CLI running, open the **Request approval** link it prints, and select **Retry** in the dashboard's **Add Slack** wizard after an admin approves. See [Slack](/docs/guides/slack.md#connect). |
 | The bot ignores ordinary channel posts | Configure `engagement.channelPosts`, create the app with `--channel-posts`, and invite it to every allowed channel. |
 | Approval buttons do nothing | Set `toolApprovals: true`, then recreate the app if its interactivity is not enabled. |