@cursor/july 0.1.105 → 0.1.108

package/dist/docs/llms-full.txt

@@ -660,7 +660,7 @@ exposes a stable URL while Cursor manages its runtime lifecycle.
 ### Before you deploy
 
 - Confirm managed hosting is enabled for the account and team.
-- Sign in with an account holding team-admin deployment permission.
+- Sign in as a team member, or use a team service-account API key with agent access.
 - Add `@cursor/july` to the agent project.
 
 For a GitHub source, install the Cursor GitHub App on the repository
@@ -689,6 +689,11 @@ Enter hostnames without schemes, ports, or paths. One leading `*.`
 wildcard is allowed. Declared domains allow HTTPS and TLS traffic, not
 arbitrary TCP ports.
 
+The base policy already covers the hosts the platform itself uses: the
+Cursor API (`api.cursor.com` and `api2.cursor.sh`), GitHub and GitLab,
+the npm and Yarn registries, Slack, and Cursor's own artifact storage.
+Declare a domain only for a host your own code reaches.
+
 `secretNames` lists the environment variables the agent expects. Names
 use `UPPER_SNAKE_CASE`. Commit names only; set their values after
 creating the deployment. Names beginning with `CURSOR_` are reserved.
@@ -941,7 +946,7 @@ A self-hosted server can read these credentials.
 
 | Credential | Used for | Provide it as |
 | --- | --- | --- |
-| Cursor API key | model turns, cloud runtime, Cursor account MCP connections | `agent-sdk login` (stores a revocable key), `CURSOR_API_KEY`, or `--api-key` / `serve({ apiKey })` |
+| Cursor API key | model turns, cloud runtime, Cursor account MCP connections | `agent-sdk login` (stores a revocable key), `CURSOR_API_KEY`, `CURSOR_SERVICE_ACCOUNT_KEY`, or `--api-key` / `serve({ apiKey })` |
 | Slack tokens | Slack channels | `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent |
 | GitHub webhook secret | delivery signature verification | `GITHUB_WEBHOOK_SECRET`, same value on server and signer |
 | GitHub API | outbound API calls | a GitHub App (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` + installation id) or `GITHUB_TOKEN` / `gh auth login` |
@@ -3538,8 +3543,9 @@ keep live progress off stderr. A TTY streams turn progress by default.
 `--verbose` still writes `t.log` lines to stderr and adds reply snippets
 to text results.
 
-Model turns need a Cursor credential from `agent-sdk login` or
-`CURSOR_API_KEY`.
+Model turns need a Cursor credential: `CURSOR_API_KEY`, then
+`CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`), then
+`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`.
 
 See [CLI: eval](/docs/reference/cli.md#eval) for flags and exit codes.
 
@@ -3849,9 +3855,10 @@ export default cursorCloudAgents({
 });
 ```
 
-Launches run under the host's signed-in account (`agent-sdk login` or
-`CURSOR_API_KEY`) and spend its cloud-agent budget. Name the
-repositories the agent may target, and keep approval on when you can't.
+Launches run under the host's signed-in account (`agent-sdk login`,
+`CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`) and spend its
+cloud-agent budget. Name the repositories the agent may target, and
+keep approval on when you can't.
 
 Mount it on an agent that runs on the local runtime; that is where
 launches park for approval. On the cloud runtime approvals don't
@@ -4105,7 +4112,8 @@ The companion skill for coding agents is
 Connect GitHub in Cursor for the repositories you care about (Settings or
 [cursor.com/dashboard](https://cursor.com/dashboard)). That gives your
 account access and lets Cursor receive the repo's webhooks. Sign the host
-in (`agent-sdk login` or `CURSOR_API_KEY`), then opt the channel into the
+in (`agent-sdk login`, `CURSOR_API_KEY`, or
+`CURSOR_SERVICE_ACCOUNT_KEY`), then opt the channel into the
 Cursor account connection:
 
 ```ts
@@ -4403,8 +4411,8 @@ export default cursorGrokBotAgents({
 
 `agents` is the allowlist. List every Grok Bot the model may talk to;
 a name outside the list is refused. Calls run under the host's
-signed-in account (`agent-sdk login` or `CURSOR_API_KEY`). Keep
-approval on when you can't.
+signed-in account (`agent-sdk login`, `CURSOR_API_KEY`, or
+`CURSOR_SERVICE_ACCOUNT_KEY`). Keep approval on when you can't.
 
 Start from the [Grok Bot agents template](/docs/templates/grokbot-agents.md)
 when you want a project that already mounts this.
@@ -4596,6 +4604,102 @@ Continue with these pages:
 
 ---
 
+Source: /docs/guides/improve.md
+
+# Self-improvement
+
+The `improve` extension lets an agent change how it behaves by changing
+its own source. Someone asks it to answer more briefly, to stop reaching
+for a tool, or to learn a procedure. The agent writes a brief, a one-off
+Cursor cloud agent makes the change on a branch and opens a pull
+request, and the agent reports that pull request. Nothing changes until
+a person reviews it and deploys.
+
+The tree the agent runs from is never edited; nothing changed there
+survives a deploy. The pull request is the only path.
+
+## Mount it
+
+The extension ships with `@cursor/july`. It relies on a
+[`cursor-cloud-agents`](/docs/guides/cloud-agents.md) mount beside it, with the
+agent's own repository among its `cloud.repos`.
+
+```ts
+// agent/extensions/cloud.ts
+import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
+
+export default cursorCloudAgents({
+  cloud: {
+    repos: [{ url: "https://github.com/acme/agents", startingRef: "main" }],
+  },
+});
+```
+
+```ts
+// agent/extensions/improve.ts
+import improve from "@cursor/july/extensions/improve";
+
+export default improve({
+  repo: "https://github.com/acme/agents",
+  path: "agents/concierge",
+});
+```
+
+`repo` is the repository that holds the agent's source and `path` is
+the agent's directory in it, the same values `agent-sdk deploy --repo`
+and `--path` take. Mount it as `improve`: the skill then reads
+`improve__yourself`, which is what a person asks for.
+
+An agent on the
+[cloud runtime](/docs/reference/agent-config.md#choose-a-runtime) already
+runs each turn on a VM with the repository checked out. It mounts
+`improve` alone, and the skill has it branch in that checkout instead of
+launching a second agent.
+
+## What the agent does
+
+With the extension mounted, "change how you work" becomes a procedure:
+
+- **Locate the change.** The skill maps the ask onto the Agent SDK tree:
+  instructions for the always-on prompt, a skill for a procedure, a tool
+  for behavior that must be right every time, `agent.ts` for the model.
+- **Brief a cloud agent.** The agent writes a self-contained brief: who
+  is asking and why, the repository, ref, and path, the files it expects
+  to change, your notes about the tree, and the rules. Follow the
+  repository's conventions, keep the diff to the change, run the
+  repository's checks, open a pull request against the deployed ref,
+  never merge.
+- **Follow up and report.** It gives the person the cloud agent's URL,
+  checks on the run, reads the pull request before repeating its claims,
+  and reports the pull request, not the delegation. It says the change
+  takes effect at the next deploy, never that it has changed already.
+
+Ask it directly. "Improve yourself: stop opening with a summary" is
+enough.
+
+## Configure it
+
+| Option | What it controls |
+| --- | --- |
+| `repo` | The repository holding the agent's source. One of the cloud mount's `cloud.repos`. |
+| `path` | The agent's directory in the repository, as `agent-sdk deploy --path` names it. |
+| `ref` | The ref the deployment tracks. Branches start there and pull requests target it. Defaults to `main`. |
+| `notes` | What a coding agent must know about this tree beyond the standard layout: a house skill format, a manifest that forces a reinstall, a pull request convention. Copied into every brief. |
+| `deploy` | Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." |
+
+## What's next
+
+Continue with these pages:
+
+- [Cursor cloud agents](/docs/guides/cloud-agents.md): the mount that does the
+  coding, and how to gate its launches
+- [Extensions](/docs/reference/extensions.md): how mounts, namespaces, and
+  overrides work
+- [Deployment](/docs/deployment.md): how a merged change reaches the
+  running agent
+
+---
+
 Source: /docs/guides/mcp-oauth.md
 
 # Host MCP OAuth
@@ -4861,10 +4965,9 @@ is `serve({ otel })` over `agent/otel.ts` over env. An empty
 `defineOtel()` still records traces; export starts when
 `OTEL_EXPORTER_OTLP_*` or a factory-returned `exporters` list appears.
 
-Hosted v2 binds deployment secrets after bake, onto the already-listening
-process. Pass a factory so flush can re-read them. Spans record from
-bake; the hosted handler flush constructs the OTLP client and sends the
-queued batch.
+Hosted deployments can bind secrets after startup. Pass a factory so
+flush can re-read them. The hosted handler constructs the OTLP client
+when it flushes and sends the queued batch.
 
 ```ts
 export default defineOtel(() => resolveMyOtelConfig());
@@ -5155,7 +5258,8 @@ agent-sdk slack create --dir .
 agent-sdk slack create --dir . --prod
 ```
 
-Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). Finish **Add
+Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). A team
+service-account key cannot create Slack apps. Finish **Add
 Slack to this agent** as the same Cursor account. Then run
 `agent-sdk slack doctor --prefix MY_AGENT` and serve:
 
@@ -5883,6 +5987,7 @@ npx @cursor/july docs
 | Driving PRs from a cloud VM | [PR autofixer template](/docs/templates/pr-autofixer.md) |
 | Handing coding work to Cursor cloud agents | [Cursor cloud agents](/docs/guides/cloud-agents.md) |
 | Talking to your Grok Bot agents | [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md) |
+| Letting an agent change its own source | [Self-improvement](/docs/guides/improve.md) |
 | Driving an agent from Linear (or another tracker) | [Webhooks guide: Linear example](/docs/guides/webhooks.md#example-linear-as-the-control-plane) |
 | Making an existing agent measurably better | [Evals](/docs/evals.md), then [Hillclimbing](/docs/hillclimbing.md) |
 | Comparing variants on live traffic | [Live A/B metrics](/docs/ab.md) |
@@ -5953,6 +6058,9 @@ npx @cursor/july docs
   and steer cloud agents through the `cursor-cloud-agents` extension.
 - [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): let the agent
   talk to Grok Bot agents through the `cursor-grokbot-agents` extension.
+- [Self-improvement](/docs/guides/improve.md): let the agent change its own
+  source through a one-off cloud agent and a pull request with the
+  `improve` extension.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): push session, turn, and
   tool traces to an OTLP collector you run.
 
@@ -6614,8 +6722,11 @@ console.log(`listening on ${handle.url}`);
 Host settings match the documented [CLI](/docs/reference/cli.md) `serve` flags.
 `serve()` also accepts `discovery` (project-loading options) and
 `mode: "single" | "multi"`. The Cursor credential resolves in one order
-everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then the key
-stored by `agent-sdk login`.
+everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then
+`CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
+when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the key stored by
+`agent-sdk login`. On a host that has both the service-account key and a
+bind file, the file principal wins.
 
 ## What's next
 
@@ -6965,20 +7076,16 @@ events. Declare `events` and handle each one in `onEvent`. Each event
 carries `deploySourceUri` and `deployVersion`. Author
 `agent/channels/deployments.ts` with `deploymentsChannel()`.
 
-Omit `deploySourceUris` on hosted v2. The control plane binds
-`deploy_source` edges from the deploy's watched `repositories` and the
-channel admits what it is sent, which is what makes it multi-tenant
-safe.
-
-Name sources to narrow below that scope, or to drive the self-hosted
-pull relay, which has no deploy scope to inherit. There, subscribe per
-deploy source with `deploySourceUris` and narrow with `environments` /
-`events`. Each entry must match `Deployment.deploy_source_uri` as your
-deployment writer records it; matching is case-insensitive but
+On Cursor-managed hosting, omit `deploySourceUris`. The deployment's
+watched repositories bind the event scope automatically. Name sources
+to narrow the scope or to drive the self-hosted pull relay. Subscribe
+per deploy source with `deploySourceUris` and narrow with `environments`
+or `events`. Each entry must match `Deployment.deploy_source_uri` as
+your deployment writer records it. Matching is case-insensitive but
 otherwise literal. It uses the host credential. A restart resumes
-rather than dropping events. An empty `deploySourceUris` list mounts
-the channel but starts no pull, so an env-configured agent stays inert
-until its deploy sources are set.
+rather than dropping events. An empty `deploySourceUris` list mounts the
+channel but starts no pull, so an env-configured agent stays inert until
+its deploy sources are set.
 
 **Change Monitors** (`@cursor/july/channels/change-monitors`): Change
 Monitor Checkpoint events. The channel publishes Factory
@@ -6987,18 +7094,14 @@ result (for example to the `issues` arm). The payload contains the
 full Checkpoint resource. This channel is scoped to Change Monitors,
 not generic Factory Checkpoints. There is no repository filter or
 resource filter. Author `agent/channels/change-monitors.ts` with
-`changeMonitorsChannel()`. It uses the host credential. The v1 omitted
-continuation is `none/v1`. A v2 agent defaults to
-`change_monitors.checkpoint/v2`, which keys the session as
-`cont:change_monitors:{checkpointName}`.
+`changeMonitorsChannel()`. It uses the host credential.
 
 **Issues** (`@cursor/july/channels/issues`): Factory issue events.
 The channel publishes `issue.created` for every Issue create. The
 agent filters if it needs a subset. The payload contains the full
 Issue resource. There is no repository filter or resource filter.
 Author `agent/channels/issues.ts` with `issuesChannel()`. It uses the
-host credential. The v1 omitted continuation is `none/v1`. A v2 agent
-defaults to `issues.issue/v2`, which keys the session by issue name.
+host credential.
 
 For other platforms like Discord or Teams, use the authored
 `defineChannel` webhook form.
@@ -7131,7 +7234,7 @@ the agent project. Slugged mounts get a subdirectory named for the slug.
 | `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
 | `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and widen playground session access on loopback. |
 | `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
-| `--api-key` | Use this Cursor API key. The command falls back to `CURSOR_API_KEY`, then the stored login. |
+| `--api-key` | Use this Cursor API key. Otherwise the command uses `CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY` when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login. |
 | `--state-root` | Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository. |
 | `--bearer-token` | Require this bearer token on routes without authored auth. Mutually exclusive with `--allow-anonymous`. |
 | `--allow-anonymous` | Admit every caller as one `anonymous` principal. Use only behind a trusted network boundary. |
@@ -7579,10 +7682,14 @@ runtime, and Cursor account MCP connections. `--key-name` changes the
 name of a browser-minted key. `login --api-key` validates and stores a
 key you already created.
 
-`whoami` shows which credential is active and why. `CURSOR_API_KEY`
-takes precedence over the stored login. `logout` removes the local
-credential file but doesn't revoke the API key. Revoke it in the Cursor
-dashboard when it should stop working.
+`whoami` shows which credential is active and why. An explicit key
+wins, then `CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default
+`/run/cursor/secrets/CURSOR_API_KEY` when unset), then
+`CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login. A host that has
+both the service-account key and a bind file authenticates as the file
+principal. `logout` removes the local credential file but doesn't
+revoke the API key. Revoke it in the Cursor dashboard when it should
+stop working.
 
 Login and account RPCs honor `CURSOR_API_BASE_URL`. The SDK harness
 honors `CURSOR_BACKEND_URL`. Set both to the same URL, or keys minted
@@ -7620,9 +7727,9 @@ agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
                 [--no-wait] [--json]
 ```
 
-Managed hosting requires team-admin permission and the team's
-cloud-agent entitlement. `--team` defaults to the signed-in account's
-team.
+Managed hosting requires team membership and the team's cloud-agent
+entitlement. A team service-account API key with agent access can
+deploy. `--team` defaults to the signed-in account's team.
 
 For a single project, the slug defaults to a normalized version of the
 directory name. Deployment slugs contain lowercase letters, digits, `_`,
@@ -7696,14 +7803,17 @@ The command polls for up to ten minutes until the status reaches
 
 ## delete
 
-`delete` removes a deployment.
+`delete` removes a hosted deployment. You can delete a deployment that
+still runs. The command frees the slug. A later deploy can use the same
+name. Spend stays on the archived service account.
 
 ```bash
 agent-sdk delete <slug> [--team <id>] [--no-wait] [--json]
 ```
 
 The command waits until the deployment is gone. `--no-wait` returns after
-the delete request is accepted.
+the delete request is accepted. Architecture v2 slugs use the Agent SDK
+control plane. Architecture v1 slugs use the Agent Serve control plane.
 
 ## rotate-token
 
@@ -7862,8 +7972,9 @@ checklist. It doesn't change files.
 `slack create` opens the signed-in Cursor dashboard wizard. Finish Slack
 consent and the bot name there. The CLI writes the token pair into
 `<dir>/.env.local` and runs `doctor`. It requires a signed-in host
-(`agent-sdk login` or `CURSOR_API_KEY`). `--prod` provisions the
-production app; the default is the development app. `--name` / `--icon`
+(`agent-sdk login` or `CURSOR_API_KEY`). A team service-account key
+cannot create Slack apps. `--prod` provisions the production app; the
+default is the development app. `--name` / `--icon`
 / `--channel-posts` prefill the wizard. A second create for the same
 slug and env overwrites the live Slack app. If Slack needs a workspace
 admin's approval, the wizard waits; keep the CLI running, open Slack's
@@ -7976,7 +8087,9 @@ These environment variables affect the CLI and its channel packs.
 
 | Variable | Meaning |
 | --- | --- |
-| `CURSOR_API_KEY` | Cursor credential. It takes precedence over the stored login. |
+| `CURSOR_API_KEY` | Cursor credential. It takes precedence over `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, and the stored login. |
+| `CURSOR_API_KEY_FILE` | Path to a Cursor credential file. Used when `CURSOR_API_KEY` is unset. When this variable is unset, the hosted default `/run/cursor/secrets/CURSOR_API_KEY` is tried. A present file takes precedence over `CURSOR_SERVICE_ACCOUNT_KEY` and the stored login. |
+| `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential. Used when `CURSOR_API_KEY` and `CURSOR_API_KEY_FILE` (including the hosted default path) are unset. It takes precedence over the stored login. |
 | `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs. |
 | `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness. |
 | `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. Defaults to the CLI config directory under `~/.config`. |
@@ -8218,7 +8331,8 @@ Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor`
 MCP namespace. `advertiseTools: true` puts connector tools on local
 turns by name. Without it they sit behind harness meta-tools.
 
-The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
+The host must be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
+`CURSOR_SERVICE_ACCOUNT_KEY`).
 `serve` fails fast at startup otherwise, and logs each connector's live
 status (`connected`, `needsAuth`, `error`) as it starts.
 
@@ -8565,6 +8679,8 @@ Continue with these pages:
   lets an agent launch and steer cloud agents
 - [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): the extension
   that lets an agent talk to Grok Bot agents
+- [Self-improvement](/docs/guides/improve.md): the extension that lets an
+  agent change its own source through a cloud agent and a pull request
 - [Tools](/docs/reference/tools.md): the tool contract extensions contribute to
 - [Skills](/docs/reference/skills.md): the skill forms an extension can carry
 - [Project layout](/docs/reference/project-layout.md): where `agent/extensions/` sits
@@ -10522,7 +10638,8 @@ Cursor checks the project in this order:
 
 Validation, discovery, direct server-tool calls, and server startup work
 without a Cursor credential. Model turns and evals need
-`CURSOR_API_KEY` or a saved `agent-sdk login`.
+`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`), then `CURSOR_SERVICE_ACCOUNT_KEY`, then a saved
+`agent-sdk login`.
 
 ## What happens after the first agent works?
 
@@ -10728,7 +10845,7 @@ npx tsc --noEmit -p ./<slug>
 tsx does not typecheck. Tool `execute` must return JSON-shaped
 values: object literals or `type` aliases, not `interface` types.
 
-Model turns need `CURSOR_API_KEY`. Without one, finish the
+Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`). Without one, finish the
 key-free checks, confirm `run` fails with only the API-key error,
 and hand these over:
 
@@ -10794,7 +10911,7 @@ Local `agent-sdk serve`. Hosted start or health failures:
 | `403` on stream | Wrong principal. Same auth as create; beyond loopback send `--bearer-token`. |
 | Works on loopback, blocked via tunnel | `localDevStrict()` rejects forwarded headers. Use `--bearer-token`. Never `--allow-anonymous` with account MCP. |
 | Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
-| Immediate API-key error | Model turns need `CURSOR_API_KEY`. |
+| Immediate API-key error | Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`). |
 | Approvals or sandbox seeds missing | `runtime: "cloud"`. Those are local only. `validate` warns. |
 | `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
 
@@ -10829,7 +10946,7 @@ agent-sdk eval --dir . --tag smoke
 | `evals/weather.eval.ts` + `{ id: "nyc" }` | `weather/nyc` |
 
 `eval` boots an ephemeral server and a temp state root. `--url`
-points at a running agent. Model turns need `CURSOR_API_KEY`.
+points at a running agent. Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`).
 
 ## Seeding
 
@@ -10933,8 +11050,10 @@ Public docs: `node_modules/@cursor/july/dist/docs/llms.txt` or
    per-project cache directory under `~/.cache`. Point cwd at a
    checkout only when the agent must inherit that tree.
 5. **Attached MCP is nameless** until `advertiseTools: true`.
-6. **Model turns need `CURSOR_API_KEY`.** `validate`, `info`, `call`,
-   and `serve` bring-up do not.
+6. **Model turns need a Cursor credential** (`CURSOR_API_KEY`, then
+   `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then
+   `agent-sdk login`). `validate`,
+   `info`, `call`, and `serve` bring-up do not.
 
 ## Folder structure
 
@@ -11055,7 +11174,7 @@ at deploy. Repos must share one GitHub owner.
 
 | Source | When |
 | --- | --- |
-| `cursorAccount` + `serve --cursor-events` | Preferred. Signed-in host (`agent-sdk login` / `CURSOR_API_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
+| `cursorAccount` + `serve --cursor-events` | Preferred. Signed-in host (`agent-sdk login`, `CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
 | HTTP `POST /<slug>/v1/channels/github` with a webhook secret | `allowAll()` + `X-Hub-Signature-256` |
 | HTTP, no secret | Loopback only. `serve --dev` also admits unsigned loopback (fixtures / forward) |
 
@@ -11307,9 +11426,9 @@ export default defineOtel({
 3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
-Hosted v2 secrets arrive after bake. Use `defineOtel(() => …)` so flush
-re-resolves exporters. Authored `agent/otel.ts` records from process
-start even when the factory returns no exporters yet.
+Hosted secrets can arrive after startup. Use `defineOtel(() => …)` so
+flush re-resolves exporters. Authored `agent/otel.ts` records from
+process start even when the factory returns no exporters yet.
 
 | Signal | Default |
 | --- | --- |
@@ -12513,7 +12632,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
-| The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
+| The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY` or `CURSOR_SERVICE_ACCOUNT_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
 | Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
 | Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Server tools, skills, or workspace seed files never appear | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `validate` warns when this combination is present. |

package/dist/docs/llms.txt

@@ -41,6 +41,7 @@
 - [GitHub](/docs/guides/github.md): Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.
 - [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval.
 - [Human-in-the-loop](/docs/guides/human-in-the-loop.md): Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout.
+- [Self-improvement](/docs/guides/improve.md): Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens.
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): Push session, turn, and tool traces from the serve process to an OTLP collector you run.
 - [Slack](/docs/guides/slack.md): Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.