@cursor/july 0.1.111 → 0.1.113

package/docs/reference/extensions.md

@@ -1,212 +1,167 @@
 ---
 title: "Extensions"
-description: "Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."
+description: "Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."
 ---
 
 # Extensions
 
-An extension packages the same contributions an agent authors under
-`agent/` and installs them as one unit. You mount it with a single file
-under `agent/extensions/`, and its contributions join the agent under a
-namespace. The package updates like any other dependency; nothing is
-copied into your project. A Cursor plugin mounts the same way; see
-[Mount a Cursor plugin](#mount-a-cursor-plugin).
+An extension packages capabilities that would otherwise live under
+`agent/`: tools, skills, instructions, connections, hooks, channels,
+schedules, subagents, artifacts, and workspace seeds. One mount file
+adds them under a namespace without copying their source into your
+project.
 
-Extensions are native to the Agent SDK. Slot files use the `@cursor/july`
-helpers, so a package built on another agent framework fails
-`agent-sdk validate` until you rewrite it onto `@cursor/july`.
+Extensions and Cursor plugins execute as trusted host code. A namespace
+prevents name collisions; it does not sandbox the package or limit its
+side effects. Review the package before mounting it.
 
 ## Mount an extension
 
-Install the package, then add one file. The filename is the namespace.
+Install the package and add one file under `agent/extensions/`. The
+filename becomes the namespace, so this mount contributes names such as
+`ci__failed_jobs` and `ci__triage`.
 
 ```ts
 // agent/extensions/ci.ts
 import ci from "@acme/ci-triage";
 
-export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
+export default ci({
+  org: "acme",
+  token: process.env.BUILDKITE_TOKEN,
+});
 ```
 
-Every contribution is exposed as `<namespace>__<name>`. A `failed_jobs`
-tool from this mount runs in the agent as `ci__failed_jobs`, and a
-`triage` skill loads as `ci__triage`. `agent-sdk info` lists each mount
-with what it contributed, and `GET /v1/info` returns the same under
-`extensions`.
+The extension validates its configuration while the project loads.
+Missing or mistyped settings fail `agent-sdk validate` before a turn
+can call the contributed code.
 
-Pass the configuration the extension asks for. The extension validates it
-when the agent loads, so a missing or mistyped field fails
-`agent-sdk validate` instead of a tool call later.
+Extension instructions are appended to the agent's prompt. The root
+agent still needs its own `agent/instructions.md`.
 
-Namespaces follow the tool-name rule, and `__` is reserved: an authored
-`agent/tools/ci__failed_jobs.ts` fails discovery, so nothing outside a
-mount can pose as one of its tools.
+## See what the extension added
 
-## What an extension can contribute
+Run discovery after mounting or upgrading an extension:
 
-An extension tree uses the same slots as [`agent/`](./project-layout.md).
-Each shareable contribution lands on the agent under the mount's
-namespace:
+```bash
+agent-sdk validate --dir .
+agent-sdk info --dir . --json
+```
 
-| Path | Becomes |
-| --- | --- |
-| `tools/<name>.ts` | tool `<ns>__<name>` |
-| `skills/<name>` | skill `<ns>__<name>` |
-| `mcp-connections/<name>.ts` | connection `<ns>__<name>` |
-| `host-connections/<name>.ts` | host connection `<ns>__<name>` |
-| `hooks/<name>.ts` | hook `<ns>__<name>` |
-| `channels/<name>.ts` | channel `<ns>__<name>` |
-| `schedules/<name>` | schedule `<ns>__<name>` |
-| `subagents/<id>/` | subagent `<ns>__<id>` |
-| `instructions.md` / `.ts` / dir | appended to the agent's system prompt |
-| `sandbox/workspace/**` | seeded into each local session workspace |
-| `artifacts.ts` | artifact kinds `<ns>__<kind>` |
-
-The root agent still needs its own `instructions.md`. Extension
-instructions are extra fragments, not a substitute.
-
-The built-in HTTP session channel stays on the agent. An extension
-authors `defineChannel` only; a file named `http.ts` becomes `<ns>__http`.
-
-These stay on the agent that mounts the extension. Each is a singleton
-or is outside discovery:
-
-| Path | Why it stays on the agent |
-| --- | --- |
-| `agent.ts` | One `defineAgent` runtime per agent |
-| `storage.ts` | One `host.kv` / `host.files` backend |
-| `otel.ts` | One OTLP exporter |
-| `playground/` | Custom chips are a Vite glob of the agent tree, not a discovery walk |
-| `extensions/` | Nested mounts are not loaded |
-| `sandbox.ts` | Custom sandbox backends stay on the agent |
-
-`agent-sdk validate` warns when a tree carries those paths.
+`info` lists each mount and its namespaced tools, skills, connections,
+hooks, channels, schedules, subagents, and artifact kinds. The same
+data appears under `extensions` in `GET /v1/info`.
+
+Names inside the extension stay short. A tool authored as
+`tools/failed_jobs.ts` appears to the mounting agent as
+`<namespace>__failed_jobs`. The `__` separator is reserved, so root
+contributions cannot impersonate a mounted one.
 
 ## Adjust a mounted extension
 
-To replace or remove a contribution, mount the extension as a directory
-and overlay the slot you want to change.
+Mount as a directory when you need to replace or remove one
+contribution. Keep the package mount in `extension.ts`, then overlay the
+extension's short name beneath it.
 
 ```text
 agent/extensions/ci/
-├── extension.ts        # the mount: export default ci({ ... })
-├── tools/
-│   ├── job_log.ts      # replaces ci__job_log with your own defineTool
-│   └── retry_job.ts    # export default disableTool() removes ci__retry_job
-├── hooks/
-│   └── audit.ts        # export default disableHook() removes ci__audit
-└── skills/
-    └── triage.ts       # export default disableSkill() removes ci__triage
+  extension.ts
+  tools/
+    job_log.ts
+    retry_job.ts
 ```
 
-Use the extension's own names inside the directory, without the
-namespace. A file with a name the extension doesn't contribute adds a
-new contribution under the namespace. Each helper comes from
-`@cursor/july/extensions` and fails discovery when it names a
-contribution the extension doesn't have, so a typo can't silently keep
-it alive.
-
-| Slot | Helper |
-| --- | --- |
-| `tools/<name>.ts` | `disableTool()` |
-| `mcp-connections/<name>.ts` / `host-connections/<name>.ts` | `disableConnection()` |
-| `skills/<name>.ts` | `disableSkill()` |
-| `hooks/<name>.ts` | `disableHook()` |
-| `channels/<name>.ts` | `disableChannel()` |
-| `schedules/<name>.ts` | `disableSchedule()` |
-| `subagents/<id>.ts` | `disableSubagent()` |
-| `instructions.ts` | `disableInstructions()` |
-| `artifacts.ts` | `disableArtifacts()` |
-
-`disable()` is the same brand as the slot helpers above and works in
-any of those files.
-
-A Cursor plugin mount overlays its MCP servers the same way; see below.
+```ts
+// agent/extensions/ci/tools/job_log.ts
+import { defineTool } from "@cursor/july/tools";
+import {
+  jobLogInput,
+  readRedactedLog,
+} from "../../../lib/ci.js";
+
+export default defineTool({
+  description: "Read a redacted CI log.",
+  inputSchema: jobLogInput,
+  execute: readRedactedLog,
+});
+```
+
+```ts
+// agent/extensions/ci/tools/retry_job.ts
+import { disableTool } from "@cursor/july/extensions";
+
+export default disableTool();
+```
+
+The first file replaces `ci__job_log`; the second removes
+`ci__retry_job`. Use the matching `disable*` helper for another slot, or
+generic `disable()` when the file location already identifies it.
+Validation fails when an overlay names a contribution the package does
+not provide.
 
 ## Mount a Cursor plugin
 
-A Cursor plugin is a directory with `.cursor-plugin/plugin.json` (or
-`.claude-plugin/plugin.json`, or `plugin.json`) and any of `skills/`,
-`commands/`, `agents/`, and `mcp.json`. Copy the plugin into your project
-and mount it with `cursorPlugin`. The filename is the namespace, as with
-any extension.
+`cursorPlugin()` adapts a vendored Cursor or Claude plugin into the same
+namespace model. Skills, commands, agents, and MCP servers become Agent
+SDK skills, subagents, and connections.
 
 ```ts
 // agent/extensions/notion.ts
 import { cursorPlugin } from "@cursor/july/extensions";
 
 export default cursorPlugin({
-  path: "plugins/notion-workspace", // relative to the project root
-  variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
+  path: "plugins/notion-workspace",
+  variables: {
+    NOTION_TOKEN: process.env.NOTION_TOKEN,
+  },
 });
 ```
 
-The plugin joins the agent under that namespace:
-
-| Plugin content | Becomes |
-| --- | --- |
-| `skills/<name>/SKILL.md` | skill `notion__<name>` |
-| `commands/<name>.md` | skill `notion__<name>`, since a command is a procedure the model runs on request |
-| `agents/<name>.md` | subagent `notion__<name>` |
-| MCP servers in `mcp.json` or the manifest | connection `notion__<server>` |
-
-`variables` fills the `${NAME}` placeholders the plugin's MCP config
-declares; names you leave out come from the environment by exact name. A
-placeholder nothing fills fails `agent-sdk validate`, so a server never
-attaches half configured. A server that declares an OAuth client
-authorizes through [host MCP OAuth](../guides/mcp-oauth.md) as
-`agent-sdk mcp oauth notion__<server>`; its secret names collapse the
-namespace separator, so `notion__notion` stores `MCP_OAUTH_NOTION_NOTION_*`.
-A server that lists `enabledTools` mounts as an advertised connection with
-that allowlist and requires the local runtime; `agent-sdk validate` fails
-otherwise.
-
-Mounting a plugin trusts it like authored code: its servers run the
-commands and read the environment variables its config names. Review a
-plugin before you vendor it.
-
-Plugin rules and hooks are not mounted; `agent-sdk validate` warns when a
-plugin carries them. To drop or reconfigure one of the plugin's servers,
-mount as a directory and overlay `mcp-connections/<server>.ts`. An
-overlaid server is never read from the plugin, so it needs no variables.
+`path` is relative to the project root. `variables` fills placeholders
+declared by the plugin's MCP configuration; unresolved placeholders
+fail validation instead of mounting a partial server.
 
-```text
-agent/extensions/cloudflare/
-├── extension.ts                        # export default cursorPlugin({ path: "plugins/cloudflare" })
-└── mcp-connections/
-    ├── cloudflare-docs.ts              # replaces cloudflare__cloudflare-docs with your defineConnection
-    └── cloudflare-bindings.ts          # export default disableConnection() drops it
-```
+Plugin rules and hooks are not mounted. Overlay a generated
+`mcp-connections/<server>.ts` file to replace or disable one plugin
+server. OAuth-backed plugin servers use
+[Host MCP OAuth](../guides/mcp-oauth.md); transport and tool-filter
+details live in [MCP connections](./connections.md).
+
+## What an extension can contain
+
+Share capabilities that can safely join another agent under a
+namespace:
 
-`disableConnection()` comes from `@cursor/july/extensions` and fails
-discovery when it names a server the plugin doesn't declare.
+- Instructions, tools, skills, MCP and host connections
+- Hooks, channels, schedules, and subagents
+- Artifact kinds and local workspace seed files
+
+Agent-wide configuration does not compose through a mount.
+`agent.ts`, storage, OpenTelemetry, playground code, custom sandbox
+backends, and nested extensions are ignored in an extension package;
+`agent-sdk validate` reports unsupported paths.
 
 ## Build an extension
 
-An extension is a directory laid out like `agent/`. `extension.ts`
-declares it; the slots in [What an extension can contribute](#what-an-extension-can-contribute)
-use the same authoring forms as the rest of this reference.
+Lay out the package like the shareable part of `agent/`. The root
+`extension.ts` supplies a description and validates any settings the
+consumer must provide.
 
 ```text
 @acme/ci-triage/
-├── package.json
-├── extension.ts        # defineExtension
-├── tools/
-│   ├── failed_jobs.ts
-│   ├── job_log.ts
-│   └── retry_job.ts
-├── skills/
-│   └── triage.md
-├── hooks/
-│   └── audit.ts
-├── mcp-connections/
-│   └── buildkite.ts
-└── lib/
-    └── buildkite.ts    # shared code, never discovered
+  package.json
+  extension.ts
+  instructions.md
+  tools/
+    failed_jobs.ts
+    job_log.ts
+  skills/
+    triage.md
+  hooks/
+    audit.ts
+  lib/
+    buildkite.ts
 ```
 
-Declare the extension with its root and, when consumers must configure
-it, a schema for their settings.
-
 ```ts
 // extension.ts
 import { defineExtension } from "@cursor/july/extensions";
@@ -214,7 +169,7 @@ import { z } from "zod";
 
 export default defineExtension({
   root: import.meta.dirname,
-  description: "Investigate failing CI builds on Buildkite.",
+  description: "Investigate failing Buildkite jobs.",
   config: z.object({
     org: z.string(),
     token: z.string(),
@@ -223,48 +178,22 @@ export default defineExtension({
 });
 ```
 
-The default export is what consumers call to mount the extension, and it
-is also how your own modules read the consumer's settings. Import it and
-read `extension.config`; the value is validated and has defaults applied.
-
-```ts
-// tools/job_log.ts
-import { defineTool } from "@cursor/july/tools";
-import { z } from "zod";
-import extension from "../extension.js";
-import { jobLogTail } from "../lib/buildkite.js";
-
-export default defineTool({
-  description: "Read the tail of a CI job's log.",
-  effect: "read",
-  inputSchema: z.object({ pipeline: z.string(), build: z.number(), job: z.string() }),
-  async execute({ pipeline, build, job }) {
-    const { org, token, logTailLines } = extension.config;
-    return jobLogTail({ org, token, pipeline, build, job, lines: logTailLines });
-  },
-});
-```
-
-Because the consumer picks the namespace, have skills and tool
-descriptions refer to sibling tools by their short names and say they
-appear under the mount's namespace (`<namespace>__job_log`).
-
-Publish the built `extension.js` as the package entry point with the
-slot directories beside it. `root` is read from the built file, so copy
-`skills/*.md` and `instructions.md` into the build output or author them
-as `.ts`.
-
-## What's next
-
-Continue with these pages:
-
-- [Cursor cloud agents](../guides/cloud-agents.md): the extension that
-  lets an agent launch and steer cloud agents
-- [Cursor Grok Bot agents](../guides/grokbot-agents.md): the extension
-  that lets an agent talk to Grok Bot agents
-- [Self-improvement](../guides/improve.md): the extension that lets an
-  agent change its own source through a cloud agent and a pull request
-- [Tools](./tools.md): the tool contract extensions contribute to
-- [Skills](./skills.md): the skill forms an extension can carry
-- [Project layout](./project-layout.md): where `agent/extensions/` sits
-  in the tree
+Modules inside the package import this definition and read
+`extension.config`, which is already validated and has defaults
+applied. Publish the built entry point with its slot directories and
+prose assets beside it.
+
+The [Project layout](./project-layout.md) owns each contribution's
+authoring contract. Keep extension instructions and tool descriptions
+namespace-neutral because the consumer chooses the final prefix.
+
+## Related
+
+- [Cloud agents](../guides/cloud-agents.md): delegate repository work
+  through an extension
+- [Grok Bot agents](../guides/grokbot-agents.md): consult named bots
+- [Jev](../guides/jev.md): typed answers, then gated writes
+- [Self-improvement](../guides/improve.md): propose source changes
+  through pull requests
+- [Project layout](./project-layout.md): contribution slots
+- [Tools](./tools.md) and [Skills](./skills.md): capability contracts

package/docs/reference/hooks.md

@@ -73,31 +73,31 @@ stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
 
 The payloads hooks read most often:
 
-| Event | `event.data` |
-| --- | --- |
-| `message.received` | `{ text }` |
-| `turn.completed` | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
-| `turn.failed` | `{ message }` |
-| `actions.requested` | `{ calls: [{ callId, toolName, args? }] }`. A call with `parentCallId` belongs to a subagent |
-| `action.result` | `{ callId, toolName, output?, isError, stubbed? }`. `stubbed` means a dry-run session answered a write without running it |
+| Event               | `event.data`                                                                                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `message.received`  | `{ text }`                                                                                                                                                                                                  |
+| `turn.completed`    | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
+| `turn.failed`       | `{ message }`                                                                                                                                                                                               |
+| `actions.requested` | `{ calls: [{ callId, toolName, args? }] }`. A call with `parentCallId` belongs to a subagent                                                                                                                |
+| `action.result`     | `{ callId, toolName, output?, isError, stubbed? }`. `stubbed` means a dry-run session answered a write without running it                                                                                   |
 
 The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
 exported from `@cursor/july`.
 
 ## Handler context
 
-| Member | What it is |
-| --- | --- |
-| `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set |
-| `ctx.agent` | `{ name }` of the agent the event belongs to |
-| `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
-| `ctx.host.kv` | Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
-| `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
-| `ctx.host.otel` | Counters, histograms, and tags, attributed to this session |
-| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
-| `ctx.host.reminders` | Per-session [reminders](./schedules.md), the same API tools get |
-| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId` |
-| `ctx.stateRoot` | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files` |
+| Member                                              | What it is                                                                                                                                                                    |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.session`                                       | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set                            |
+| `ctx.agent`                                         | `{ name }` of the agent the event belongs to                                                                                                                                  |
+| `ctx.channel`                                       | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups                                                                                       |
+| `ctx.host.kv`                                       | Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
+| `ctx.host.files`                                    | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files                                                                                     |
+| `ctx.host.otel`                                     | Counters, histograms, and tags, attributed to this session                                                                                                                    |
+| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get                                                                                                                                             |
+| `ctx.host.reminders`                                | Per-session [reminders](./schedules.md), the same API tools get                                                                                                               |
+| `ctx.artifacts`                                     | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId`                                                                                     |
+| `ctx.stateRoot`                                     | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files`                                                  |
 
 ## When hooks run
 
@@ -123,24 +123,24 @@ the hook's copy is the source of truth.
 
 All of them consume the same stream, for different jobs:
 
-| | Hooks | Channel `events` | Evals |
-| --- | --- | --- | --- |
-| Scope | every session of the agent | sessions the channel owns | one test turn |
-| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory |
-| Context | `ctx.host`, `ctx.artifacts`, session info | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers |
-| Can affect the run | no | yes, it owns the surface | n/a |
-| Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` |
+|                    | Hooks                                           | Channel `events`                                                  | Evals                             |
+| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------- |
+| Scope              | every session of the agent                      | sessions the channel owns                                         | one test turn                     |
+| Job                | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface                    | assert: gates over the trajectory |
+| Context            | `ctx.host`, `ctx.artifacts`, session info       | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers         |
+| Can affect the run | no                                              | yes, it owns the surface                                          | n/a                               |
+| Authored at        | `agent/hooks/*.ts`                              | channel config                                                    | `evals/**/*.eval.ts`              |
 
 ## When not to use a hook
 
-| You want to | Use instead |
-| --- | --- |
-| Add context before the model runs | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
-| Reply on Slack, comment on a PR, or post any other delivery | The channel's `events` map, or the Slack and GitHub packs |
-| Show PR progress (merge-box check, sticky banner) | `githubChannel({ progress: { commitStatus, banner } })`; see [Show PR progress](../guides/github.md#show-pr-progress) |
-| Block, approve, or rewrite a tool call | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool |
-| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult` |
-| Gate a change on behavior | [Evals](../evals.md) |
+| You want to                                                                           | Use instead                                                                                                      |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Add context before the model runs                                                     | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
+| Reply on Slack, comment on a PR, or post any other delivery                           | The channel's `events` map, or the Slack and GitHub packs                                                        |
+| Show PR progress (merge-box check, sticky banner)                                     | `githubChannel({ progress: { commitStatus, banner } })`; see the [PR autofixer](../templates/pr-autofixer.md)    |
+| Block, approve, or rewrite a tool call                                                | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool                                          |
+| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult`                                                                                                   |
+| Gate a change on behavior                                                             | [Evals](../evals.md)                                                                                             |
 
 ## Patterns
 

package/docs/reference/subagents.md

@@ -54,7 +54,7 @@ subagent."
 Subagents split one job into roles inside a single agent. When the
 specialist is independently useful, with its own tools, sessions, and
 playground, make it a full agent. See
-[Agent-to-agent](../guides/agent-to-agent.md#peer-or-subagent).
+[Peer agents](../guides/agent-to-agent.md#peer-or-subagent).
 
 ## Patterns
 

package/docs/reference/tools.md

@@ -42,6 +42,10 @@ code that runs it. With a Zod `inputSchema`, the input is validated before
 `execute` runs and the input type is inferred. A plain JSON Schema
 object is forwarded as-is and the input arrives as raw JSON.
 
+A server tool can call `decide` from
+[`@cursor/july/extensions/jev`](../guides/jev.md) for a risk tier or a
+finding gate without a second model turn.
+
 For multi-line descriptions, reminder prompts, and error messages, use
 [`prompt`](./prompt.md) so the string can sit indented with the surrounding
 TypeScript:

package/docs/templates/thermo-quality-review.md

@@ -0,0 +1,80 @@
+---
+title: "Review pull requests for structural code quality"
+description: "Scaffold the agent, deploy it, and open a PR."
+---
+
+# Review pull requests for structural code quality
+
+This agent reads a pull request diff and posts one review comment. It
+reports missing abstractions, spaghetti branches, feature logic
+leaking into shared paths, and files pushed past 1,000 lines. Style
+nits and behavior disputes stay out.
+
+This template is one model turn: read the diff, then post one comment.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./thermo-quality-review --template thermo-quality-review
+cd thermo-quality-review
+```
+
+## Deploy
+
+Sign in once, then deploy from a pushed checkout:
+
+```bash
+agent-sdk login
+agent-sdk deploy --cursor-events-repo acme/api
+```
+
+Repeat `--cursor-events-repo` for each repo. Every repo must share one
+owner. The deployment watches those repos through your team's Cursor
+GitHub connection and reviews each opened PR. No webhook or local
+server.
+
+Change repos later without redeploying:
+
+```bash
+agent-sdk event-repos thermo-quality-review --repo acme/api --repo acme/web
+```
+
+## Try it locally
+
+Skip the deploy while you iterate. Start the relay for one repo:
+
+```bash
+agent-sdk dev --cursor-events --repo acme/api
+```
+
+Open a PR, or replay a known one without pushing:
+
+```bash
+agent-sdk github replay https://github.com/acme/api/pull/12 --dir .
+```
+
+`replay` needs pull access. Draft PRs are ignored. The channel writes
+`pr/diff.patch`, then starts a model turn. The model calls
+`post_findings` once. Chat replies stay in the playground.
+`post_findings` writes the GitHub comment.
+
+Connect GitHub in Cursor first (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)) so the relay and
+API calls use your account. See the [GitHub guide](../guides/github.md).
+
+## Evals
+
+Two smoke cases: one spaghetti-branch fixture and one clean fix. They
+need no GitHub access.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## What to edit
+
+- `agent/instructions.md`: what counts as a finding and the comment
+  shape
+- `evals/review.eval.ts`: smoke cases