@cursor/july 0.1.107 → 0.1.109

package/docs/reference/http-api.md

@@ -152,12 +152,11 @@ These read-only routes describe the running agent.
 
 | Route                  | What it does                                                                                                                                                                             |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics |
+| `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, diagnostics |
 | `GET /v1/tools`        | The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light `{ name, title?, source? }` entries. `session` / `continuationToken` query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in `connectionErrors` |
 | `GET /v1/tools/:name`  | One catalog tool's full description: description, execution, `needsApproval`, `effect`, input and output schemas, source connection. Same session binding as the listing; unknown names get `404` with the available names |
 | `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
 | `GET /v1/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
-| `GET /v1/abs`          | [Live A/B metrics](../ab.md): per-session assignments and aggregate arm totals                                                                                                           |
 
 ## Artifacts
 
@@ -216,7 +215,7 @@ the final `completed` or `failed` status. Batch errors appear on the
 snapshot returned by the poll. Entries within `filterIds` and `tags`
 use OR semantics. When both fields are present, a case must match one
 entry from each field. Listed runs persist across restarts when storage is configured; see
-[Storage](../storage.md#eval-and-a-b-tables). Otherwise they are
+[Storage](../storage.md#eval-table). Otherwise they are
 process-memory only.
 
 ## Dev-mode routes

package/docs/reference/playground.md

@@ -37,8 +37,6 @@ Use the playground to chat, try channel routes, and inspect sessions.
   an [extension](./extensions.md) cannot contribute them.
 - **Raw events pane**: flip it on to inspect the event stream.
 - **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
-- **A/Bs tab**: per-session and aggregate
-  [live A/B metrics](../ab.md) from `GET /v1/abs`.
 
 In multi-agent mode each agent has its own playground at
 `/<slug>/playground`, and `/` is an index of them all.
@@ -61,5 +59,3 @@ Continue with these pages:
 - [Sessions and streaming](./sessions.md): the streams it renders
 - [Human-in-the-loop](../guides/human-in-the-loop.md): the approval
   buttons in context
-- [Live A/B metrics](../ab.md): the assignments and results in the A/Bs
-  tab

package/docs/reference/project-layout.md

@@ -11,8 +11,7 @@ how the Agent SDK loads it.
 
 ## Folder structure
 
-For the capabilities below, identity usually comes from the path. A/B
-experiments can override their file-derived name.
+For the capabilities below, identity comes from the path.
 
 | Path | Resolves to |
 | --- | --- |
@@ -24,8 +23,6 @@ experiments can override their file-derived name.
 | `agent/extensions/ci.ts` | extension mount `ci`; its contributions become `ci__<name>` |
 | `agent/extensions/notion.ts` | Cursor plugin mount `notion` (`cursorPlugin`); its skills, agents, and MCP servers become `notion__<name>` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
-| `agent/ab.ts` | A/B experiment `ab` unless `name` overrides it |
-| `agent/ab/concise.ts` | A/B experiment `concise` unless `name` overrides it |
 
 The root agent takes its name from `package.json` `name`, falling back
 to the directory name. When serving multiple agents, the slug is the
@@ -77,8 +74,6 @@ Each path maps to a capability and a reference page.
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
 | `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](../guides/opentelemetry.md) |
-| `agent/ab.ts`, `agent/ab/*.ts` | `defineAB` experiments with sticky variants and live metrics | [Live A/B metrics](../ab.md) |
-| `agent/ab.config.ts` | `defineABConfig` shared A/B settings | [Live A/B metrics](../ab.md) |
 | `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
 | `agent/result.ts` | `defineResult` host `commit` on the final assistant text | [Turn result](./result.md) |
@@ -115,6 +110,4 @@ Continue with these pages:
 
 - [Agent config](./agent-config.md): the runtime config at the root
 - [Tools](./tools.md): add typed actions under `agent/tools/`
-- [Live A/B metrics](../ab.md): compare variants from `agent/ab.ts` or
-  `agent/ab/`
 - [Concepts](../concepts.md): why the filesystem is the interface

package/docs/reference/sessions.md

@@ -80,7 +80,7 @@ within one session. The `at` field is an ISO-8601 timestamp.
 
 | Phase | Events | What they tell you |
 | --- | --- | --- |
-| Session | `session.started`, [`ab.assigned`](../ab.md#assign-sticky-variants), `session.waiting`, `session.completed`, `session.failed` | Session creation, A/B enrollment, readiness, and task completion |
+| Session | `session.started`, `session.waiting`, `session.completed`, `session.failed` | Session creation, readiness, and task completion |
 | Agent | `agent.bound` | Cloud conversation URL |
 | Input | `message.received` | A user message was accepted |
 | Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queue position under a [`maxRunningTurns` cap](./agent-config.md#concurrency), then turn status, final result, and token usage |
@@ -164,5 +164,4 @@ view.
 
 - [HTTP API](./http-api.md)
 - [Hooks](./hooks.md)
-- [Live A/B metrics](../ab.md)
 - [How the Agent SDK works](../concepts.md)

package/docs/scaffolding-agents.md

@@ -113,7 +113,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?
 

package/docs/skills/index.md

@@ -1,6 +1,6 @@
 ---
 title: "Coding-agent skills"
-description: "Task guides that ship with the Agent SDK for scaffolding, evals, channels, and hillclimbing."
+description: "Task guides that ship with the Agent SDK for scaffolding, deployment, evals, channels, and hillclimbing."
 ---
 
 # Coding-agent skills
@@ -17,10 +17,10 @@ to use each one.
 | [framework-map](./framework-map.md) | Learn the project layout and runtimes |
 | [create-agent](./create-agent.md) | Scaffold and verify a new agent |
 | [evals](./evals.md) | Write fixtures and regression checks |
-| [ab](./ab.md) | Compare variants on live traffic |
 | [otel](./otel.md) | Export OpenTelemetry traces |
 | [hillclimb](./hillclimb.md) | Improve an agent against fixed inputs |
 | [github](./github.md) | Add GitHub webhooks and replay events |
 | [setup-slack](./setup-slack.md) | Connect an agent to Slack |
 | [mcp-auth](./mcp-auth.md) | Authorize host MCP OAuth |
+| [deploy](./deploy.md) | Deploy with an attached service account |
 | [debug](./debug.md) | Diagnose a local run |

package/docs/storage.md

@@ -6,8 +6,8 @@ description: "Point the Agent SDK's durable storage at a backend you own with de
 # Storage
 
 The Agent SDK owns durable storage for sessions, continuation tokens,
-reminders, playground eval history, and live A/B samples. It chooses the
-keys, when to read and write, and how to restore after restart.
+reminders, and playground eval history. It chooses the keys, when to
+read and write, and how to restore after restart.
 
 The Agent SDK owns key encoding. Backends must accept the keys they are
 given. Do not fail `put` to enforce a shorter cap.
@@ -41,9 +41,9 @@ export default defineStorage({
 ## Which fields to provide
 
 Implement the small KV core (`put`/`get`/`delete`/`list` plus the `cas`
-group) and you get **full functionality**: eval-run and A/B history are
-derived over the core automatically. The dedicated `evals` / `abs` groups
-are backend-native optimizations, not required-or-lose-history hooks.
+group) and you get **full functionality**: eval-run history is derived
+over the core automatically. The dedicated `evals` group is a
+backend-native optimization, not a required-or-lose-history hook.
 
 | Field | Required | Role |
 | --- | --- | --- |
@@ -54,36 +54,28 @@ are backend-native optimizations, not required-or-lose-history hooks.
 | `delete` | For cleanup | Remove a key |
 | `name` | No | Label surfaced on `GET /v1/info` diagnostics |
 | `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
-| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
+| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval table](#eval-table) |
 
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
 follow-up so a store outage does not open a new session. Return
 `undefined` only for a real miss.
 
-## Eval and A/B tables
+## Eval table
 
-Two dedicated table groups carry structured rows instead of opaque KV
-values. Both are **optional optimizations**: when a group is not
-authored, `defineStorage` derives it over the KV core, so a backend that
-implements only the core loses nothing. Author a group only when the
-backend has a better native shape (a real database table, an analytics
-pipeline). The built-in `fileKv` and `cursorHostedStorage` both do.
+The dedicated `evals` table group carries structured rows instead of
+opaque KV values. It is an **optional optimization**: when the group is
+not authored, `defineStorage` derives it over the KV core, so a backend
+that implements only the core loses nothing. Author the group only when
+the backend has a better native shape (a real database table, an
+analytics pipeline). The built-in `fileKv` and `cursorHostedStorage`
+both do.
 
 `evals` keeps playground eval batches across restarts (`put`, `delete`,
 `list` over run snapshots keyed by `runId`). A core missing `delete` or
 `list` leaves eval history in memory until restart.
 See [Evals](./evals.md#configure-eval-runs).
 
-`abs` exports live A/B metrics: `putSample` appends one cumulative
-metric sample per enrolled experiment on each completed or failed turn;
-optional `putSnapshot` / `getSnapshot` store and serve back the latest
-aggregate so a replacement host can still serve the A/Bs surface.
-`putSample` and `putSnapshot` need only core `put`; `getSnapshot` needs
-core `get`. Session event logs remain the assignment source of truth
-either way. See [Live A/B metrics](./ab.md).
-
 ## Policy
 
 Two knobs change behavior:
@@ -118,8 +110,7 @@ With `get` and `list`, serve can rebuild local state from your store:
 - At startup, the Agent SDK loads recent sessions up to the restore caps.
 - On demand, a missing continuation token resolves through the store
   and resumes that session.
-- Playground eval history and A/B aggregates can load from the same
-  sink.
+- Playground eval history can load from the same sink.
 
 A turn in flight at crash time is not replayed. The next follow-up
 resumes from the last flushed state.

package/docs/troubleshooting.md

@@ -30,7 +30,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.107",
+  "version": "0.1.109",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -146,6 +146,13 @@
       "import": "./dist/extensions/cursor-grokbot-agents/extension.js",
       "default": "./dist/extensions/cursor-grokbot-agents/extension.js"
     },
+    "./extensions/improve": {
+      "anysphere-source": "./src/extensions/improve/extension.ts",
+      "bun": "./dist/extensions/improve/extension.js",
+      "types": "./dist/extensions/improve/extension.d.ts",
+      "import": "./dist/extensions/improve/extension.js",
+      "default": "./dist/extensions/improve/extension.js"
+    },
     "./schedules": {
       "anysphere-source": "./src/schedules.ts",
       "types": "./dist/schedules.d.ts",
@@ -207,12 +214,6 @@
       "import": "./dist/evals/loaders.js",
       "default": "./dist/evals/loaders.js"
     },
-    "./ab": {
-      "anysphere-source": "./src/ab.ts",
-      "types": "./dist/ab.d.ts",
-      "import": "./dist/ab.js",
-      "default": "./dist/ab.js"
-    },
     "./artifacts": {
       "anysphere-source": "./src/artifacts.ts",
       "types": "./dist/artifacts.d.ts",

package/skills/create-agent/SKILL.md

@@ -133,7 +133,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:
 

package/skills/debug/SKILL.md

@@ -34,7 +34,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`. |
 

package/skills/deploy/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: agentsdk-deploy
+description: >-
+  Deploy or redeploy an Agent SDK project to Cursor-managed hosting
+  with an attached service account. Use when asked to deploy,
+  redeploy, publish, or update a hosted Agent SDK agent.
+---
+
+# Deploy an Agent SDK agent
+
+Use this skill only after a person asks for a deployment. It deploys a
+pushed Git ref to Cursor-managed hosting. Local files never upload.
+
+Use the exact published `@cursor/july` release embedded in the installed
+skill. Do not use a floating npm tag or a workspace build of the CLI.
+
+## Gather the target
+
+Resolve these values from the request and checkout:
+
+- Agent directory. Default to the current directory only when it contains
+  one Agent SDK project.
+- Deployment slug. Default to the normalized directory name.
+- Git ref. Default to the exact pushed `HEAD` commit.
+- Team. Use the service account's team unless the request names another.
+- Cursor-event repositories and CLI-only egress domains.
+
+Ask one focused question when the target or requested ref is ambiguous.
+Do not ask for values the checkout or existing deployment supplies.
+
+## Use the attached service account
+
+Continue only when `CURSOR_SERVICE_ACCOUNT_KEY` is present. Never print
+the value. Do not run `agent-sdk login`.
+
+On Linux and macOS, run every Agent SDK command through this wrapper:
+
+```bash
+CURSOR_JULY_VERSION="__CURSOR_JULY_VERSION__"
+case "$CURSOR_JULY_VERSION" in
+  __CURSOR_JULY_*__)
+    echo "The Agent SDK deploy skill is not bound to a package version." >&2
+    exit 1
+    ;;
+esac
+
+run_agent_sdk() {
+  env -u NODE_OPTIONS -u CURSOR_API_KEY \
+    CURSOR_API_KEY_FILE=/dev/null \
+    npx --yes "@cursor/july@$CURSOR_JULY_VERSION" "$@"
+}
+```
+
+The installed copy pins the release it came from. The wrapper isolates that
+published CLI and the attached service account. The presence check prevents a
+stored personal login from being used when the attachment is missing.
+
+Verify the principal before any write:
+
+```bash
+test -n "${CURSOR_SERVICE_ACCOUNT_KEY:-}" || {
+  echo "No attached Cursor service account." >&2
+  exit 1
+}
+run_agent_sdk whoami --json
+```
+
+Continue only when `credentialSource` is `service-account`. Record the
+team and complete service-account ID for the final report. Stop on an
+authentication, team-access, repository-scope, or hosting-entitlement
+error.
+
+## Pin pushed source
+
+Find the Git root and commit:
+
+```bash
+GIT_ROOT="$(git -C "$AGENT_DIR" rev-parse --show-toplevel)"
+SOURCE_REF="$(git -C "$GIT_ROOT" rev-parse HEAD)"
+git -C "$GIT_ROOT" status --short
+git -C "$GIT_ROOT" branch -r --contains "$SOURCE_REF"
+```
+
+Use a ref from the request instead of `SOURCE_REF` when the person names
+one. Confirm the selected commit exists on the remote. If intended
+changes are uncommitted or unpushed, stop and explain they will not ship.
+Do not commit or push unless the request includes that work.
+
+The CLI infers the normalized HTTPS `origin`, agent path, and slug from
+`--dir`. Pass `--repo`, `--path`, or `--slug` when the request overrides
+the inferred value. Never print a remote URL that contains credentials.
+
+## Preserve deployment inputs
+
+A redeploy replaces its source, Cursor-event repositories, and
+CLI-supplied egress domains. Preserve the existing
+`cursorEventRepos` and `egressAllowedDomains` unless the request or
+project changes them. Reapply each value with:
+
+```text
+--cursor-events-repo <owner/repo>
+--allow-domain <hostname>
+```
+
+Read existing settings through a filter that selects only those two
+fields:
+
+```bash
+run_agent_sdk deployment "$SLUG" --json |
+  node -e '
+    let raw = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { raw += chunk; });
+    process.stdin.on("end", () => {
+      const value = JSON.parse(raw);
+      console.log(JSON.stringify({
+        cursorEventRepos: value.cursorEventRepos ?? [],
+        egressAllowedDomains: value.egressAllowedDomains ?? [],
+      }, null, 2));
+    });
+  '
+```
+
+Never print or save the full response because it can contain short-lived
+engine-access headers.
+
+For a new SCM-channel deployment, ask which repositories should wake the
+agent when the project does not declare the answer. The source repository
+is not always the event repository.
+
+## Validate, deploy, and verify
+
+Validate with the same published package and principal:
+
+```bash
+run_agent_sdk validate --dir "$AGENT_DIR"
+```
+
+Stop on validation errors. Review hosting warnings about secret names,
+egress domains, and channel configuration before continuing.
+
+Deploy the pinned source. Add the preserved or requested repeatable
+flags:
+
+```bash
+run_agent_sdk deploy \
+  --dir "$AGENT_DIR" \
+  --ref "$SOURCE_REF"
+```
+
+The command waits for a terminal deployment state. Do not treat
+`pending`, `accepted`, or `deploying` as success. If the command is
+interrupted, resume inspection with:
+
+```bash
+run_agent_sdk deployment "$SLUG"
+```
+
+A first deployment prints a one-time alias token. Never paste it into
+chat or expose it in an agent-captured terminal. Before a first deploy,
+ask for a secure destination or ask the person to run the final command
+in a private terminal. When writing the token, use mode `0600` and print
+only the path. Redeploys do not print the token. JSON deployment output
+can also contain credentials, so filter it before display.
+
+Finish only when the deployment reports `running`. Report the slug,
+team, generation, pinned ref, and complete service-account ID. On
+failure, report the deployment status and sanitized error without
+retrying a different ref or principal.

package/skills/evals/SKILL.md

@@ -3,17 +3,17 @@ name: agentsdk-evals
 description: >-
   Author and run defineEval cases. Use when writing, fixing, seeding,
   or hillclimbing evals. Ask whether to generate samples or take
-  uploaded data. Materialize API-backed fixtures first. Live A/B is
-  defineAB (skills/ab), not defineEval.
+  uploaded data. Materialize API-backed fixtures first.
 ---
 
 # Agent SDK evals
 
 Fixed input, model turn, gates on the trajectory. Files live at
 project-root `evals/**/*.eval.ts`. `agent/evals/` is ignored.
+Guide: `docs/evals.md`.
 
-Live traffic variants: `skills/ab/SKILL.md`. That is not a test
-runner.
+Observing production: hooks. Tool logic without a model:
+`agent-sdk call <tool> --input '{...}'`.
 
 ```bash
 agent-sdk eval --dir . --list
@@ -27,9 +27,13 @@ agent-sdk eval --dir . --tag smoke
 | `evals/weather.eval.ts` + `test` | `weather` |
 | `evals/weather/nyc.eval.ts` + `test` | `weather/nyc` |
 | `evals/weather.eval.ts` + `{ id: "nyc" }` | `weather/nyc` |
+| `evals/sql.eval.ts` exporting an array of `defineEval` calls | `sql/0000`, `sql/0001`, ... |
 
 `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`); `--list` does
+not. Node 22.13+, never Bun.
 
 ## Seeding
 
@@ -79,9 +83,30 @@ export default defineEvalConfig({
 });
 ```
 
-Either `test(t)` or `cases`, not both. `t.send` waits for park/fail.
-`workspaceFiles` seeds the first turn. Assert with `t.succeeded()`,
-`calledTool` / `notCalledTool`, `t.check(t.reply, …)`, `t.metric`.
+Either `test(t)` or `cases`, not both. `t.send` waits for the turn to
+settle (complete, park, or fail) and returns it; `turn.calledTool(...)`
+reads only that turn, `t.*` reads the whole run. First-send options:
+`workspaceFiles`, `workspaceDir`, `cloud`.
+
+Gates: `t.succeeded()` / `t.parked()`,
+`calledTool(name, { input, output, status, count })` / `notCalledTool`,
+`toolOrder`, `maxToolCalls`, `taggedArtifact`, `event` / `notEvent`,
+`t.check(value, includes | equals | matches | similarity | satisfies)`.
+Records: `t.metric`, `t.log`, `t.score` (soft 0-1).
+
+Severity is on the handle: default gate; `.soft()` tracked;
+`.atLeast(0.8)` soft with a bar (verdict `scored`, exit 1 only under
+`--strict`); `.gate(0.8)` hard. `t.judge.factuality`, `summarizes`,
+`closedQA`, and `sql` are soft by default and need a judge model
+(`judge` in `evals.config.ts`, on the eval or case, or per-call
+`{ model }`).
+
+## Side effects
+
+Eval sessions run real tools. Guard actuation with
+`ctx.session.purpose === "eval"` in the tool, hook, or `defineResult`
+and return a shaped result so `calledTool` can still assert the
+decision.
 
 ## What to gate
 
@@ -103,6 +128,18 @@ drifting inputs (pin them).
 | GitHub | `github replay … --dry-run --out fixtures/github` |
 | Host-prep PR review | A team-owned PR; gate findings shape, not counts |
 | Workspace | `workspaceFiles` in `t.send` |
+| Dataset | `loadJson` / `loadJsonl` / `loadYaml` from `@cursor/july/evals/loaders`, paths from the project root |
+
+## Debug and CI
+
+A failed local run leaves `evals/<case-id>.json` (assertions, inputs,
+tool I/O, final text, logs) under `evals/<stamp>/` in the project state
+directory (the CLI prints the path); read it before editing the eval.
+`--state-root <path>` keeps the raw session events too.
+
+CI: `agent-sdk eval --dir . --json --no-stream --junit reports/evals.xml`.
+Exit `1` on a failed gate, `2` when nothing matched, `--strict` to fail
+on `scored`.
 
 Every kept hillclimb change lands an eval that would have failed
 before it. Never weaken a gate to pass a round.

package/skills/framework-map/SKILL.md

@@ -28,8 +28,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
 
@@ -49,7 +51,6 @@ Path is identity. Full list: README "Folder structure".
 | `agent/hooks/*.ts` | Observe-only |
 | `agent/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
 | `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`) |
-| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
 | `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
 | `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
 | `agent/sandbox/workspace/` | Session seed files (local only) |
@@ -97,10 +98,10 @@ only this agent's directory.
 | --- | --- |
 | Scaffold | `skills/create-agent/SKILL.md` |
 | Evals | `skills/evals/SKILL.md` |
-| Live A/B | `skills/ab/SKILL.md` |
 | OpenTelemetry | `skills/otel/SKILL.md` |
 | GitHub | `skills/github/SKILL.md` |
 | Slack | `skills/setup-slack/SKILL.md` |
 | Host MCP OAuth | `skills/mcp-auth/SKILL.md` |
+| Managed deployment | `skills/deploy/SKILL.md` |
 | Local triage | `skills/debug/SKILL.md` |
 | Measured improvement | `skills/hillclimb/SKILL.md` |

package/skills/github/SKILL.md

@@ -48,7 +48,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) |