@cursor/july 0.1.113 → 0.2.0

package/docs/reference/project-layout.md

@@ -29,7 +29,7 @@ to the directory name. When serving multiple agents, the slug is the
 directory name and must match `[A-Za-z0-9][A-Za-z0-9_-]*` (and not the
 reserved `v1`, `playground`, or `docs` segments).
 
-## Project overview
+## Project tree
 
 Most projects start with this shape.
 
@@ -54,8 +54,8 @@ my-agent/
 ```
 
 Evals live in `evals/` at the project root, a sibling of `agent/`, never
-inside it. `agent/evals/` is silently ignored. See
-[Evals](../evals.md).
+inside it. `agent/evals/` is ignored, and `validate` warns about it.
+See [Evals](../evals.md).
 
 ## Folder reference
 
@@ -73,30 +73,26 @@ Each path maps to a capability and a reference page.
 | `agent/extensions/<ns>.ts` or `agent/extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](./extensions.md) |
 | `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` | Factory-only OTLP authoring (`defineOtel`). Public path is env / `serve({ otel })`. | [OpenTelemetry](../guides/opentelemetry.md) |
-| `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | None |
 | `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 (`throw` or `ctx.reject`) | None |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
-| `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
-| `agent/playground/` | Custom playground tool chips | [Playground](./playground.md) |
+| `agent/reminders/*.ts` | Named reminder handlers that stay armed across restarts | [Schedules](./schedules.md#reminders) |
+| `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#local-session-workspace) |
 | `agent/lib/` | Import-only shared code, never discovered | None |
 | `evals/evals.config.ts` | Shared eval settings (e.g. `maxConcurrency`); required when evals exist | [Evals](../evals.md) |
 | `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](../evals.md) |
 
-`agent/lib/` is the only place for shared code. Everything else under
-`agent/` is discovery surface. A stray `.ts` file in one of these
-folders is treated as a definition.
+Use `agent/lib/` for shared imports. A `.ts` file in one of the listed
+discovery folders loads as a definition; unrecognized directories
+produce a validation warning.
 
-## Why didn't the Agent SDK discover my file?
+## Inspect discovery
 
 Run `agent-sdk validate --dir .` and `agent-sdk info --dir .`.
 `validate` prints diagnostics, and `serve` refuses to start on
 error-severity ones. Warnings, such as cloud runtime combined with
 local-only capabilities, print but don't block. `info` lists the discovered
-surface, so a missing tool or channel shows up immediately. From
-there, check the folder reference: the file is usually in the wrong directory
-or has the wrong extension.
+surface, so a missing tool or channel shows up immediately.
 
 ```bash
 agent-sdk validate --dir .    # diagnostics; non-zero exit on errors
@@ -104,9 +100,8 @@ agent-sdk info --dir .        # human-readable surface
 agent-sdk info --dir . --json # machine-readable project info (same shape as GET /v1/info)
 ```
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Agent config](./agent-config.md): the runtime config at the root
 - [Tools](./tools.md): add typed actions under `agent/tools/`
+- [CLI](./cli.md): commands that discover this tree

package/docs/reference/prompt.md

@@ -1,42 +1,42 @@
 ---
-title: "prompt"
-description: "Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors."
+title: "Prompt strings"
+description: "Write indented multi-line strings without carrying source indentation into their values."
 ---
 
-# `prompt`
+# Prompt strings
 
-Authoring helper for long strings that live next to indented TypeScript:
-tool descriptions, reminder `prompt` fields, GitHub channel `context`,
-and error messages.
+The `prompt` template tag keeps multi-line strings aligned with the
+surrounding TypeScript while returning dedented text. Use it for tool
+descriptions, reminder prompts, channel context, and errors. Import it
+from the package root or the dedicated entrypoint:
 
 ```ts
 import { prompt } from "@cursor/july";
 // or: import { prompt } from "@cursor/july/prompt";
 ```
 
-## `prompt\`…\``
+## Dedented strings
 
-Returns a single dedented string. Common leading whitespace is stripped;
-a leading newline after the opening backtick is dropped so the usual
-multiline form stays readable in source.
+`prompt` returns one string. It removes the common leading whitespace
+and one newline immediately after the opening backtick.
 
 ```ts
 throw new Error(prompt`
-  It is outside business hours (Mon–Fri 9am–5pm ET).
+  It is outside business hours (Mon-Fri 9am-5pm ET).
   Use request_author_approval, or pass approval=human_request.
 `);
 ```
 
 Blank lines inside the body are preserved. Relative indentation after the
-common prefix is kept (handy for nested bullet lists).
+common prefix is preserved, so nested lists keep their shape.
 
 When interpolating multi-line values (for example a list of services), give
 those lines the same indent as the `prompt` body so dedent stays consistent.
 
-## `prompt.lines\`…\``
+## Line arrays
 
-Same dedent rules, but returns `string[]`, one entry per line. Use this
-where an API wants separate lines (for example GitHub channel `context`):
+`prompt.lines` applies the same rules and returns `string[]`, with one
+entry per line. Use it when an API accepts separate context lines:
 
 ```ts
 context: prompt.lines`
@@ -45,3 +45,8 @@ context: prompt.lines`
   Call plan_deploy, then follow its nextStep.
 `
 ```
+
+## Related
+
+- [Tools](./tools.md)
+- [Channels](./channels.md)

package/docs/reference/schedules.md

@@ -5,7 +5,7 @@ description: "Cron-driven runs defined at deploy time, and per-session durable w
 
 # Schedules and reminders
 
-Two ways an agent acts without an inbound message. A schedule is
+An agent can act without an inbound message in two ways. A schedule is
 deploy-time cron: "every weekday at 09:00, summarize open incidents." A
 reminder is a runtime wake bound to one conversation: "re-check this
 PR's CI in two hours." Schedules live in the filesystem; reminders are
@@ -16,10 +16,9 @@ created by running code.
 Cron expressions are standard 5-field, evaluated in UTC with minute
 granularity.
 
-### Schedules in Markdown
+### Markdown schedules
 
-A plain markdown file with `cron:` frontmatter is a fire-and-forget
-task:
+A markdown file with `cron:` frontmatter is a fire-and-forget task:
 
 ```md
 ---
@@ -33,10 +32,10 @@ Each firing starts a task-mode session: the body is the prompt, the
 session runs to `session.completed` or `session.failed`, and it isn't
 followable.
 
-### Schedules as handlers
+### Schedule handlers
 
-`defineSchedule` with a `run` handler gives you full control, most
-usefully to hand the work into a channel so its delivery events fire:
+Use `defineSchedule` with a `run` handler to call tools or hand work into
+a channel so its delivery events fire:
 
 ```ts
 import { defineSchedule } from "@cursor/july/schedules";
@@ -45,7 +44,6 @@ import webhook from "../channels/webhook.js";
 export default defineSchedule({
   cron: "*/30 * * * *",
   async run({ receive, waitUntil, appAuth, host }) {
-    // optional: await host.mcp.callTool("units", "celsius_to_fahrenheit", { value: 0 });
     waitUntil(
       receive(webhook, {
         message:
@@ -64,14 +62,12 @@ schedule-scoped principal for work the agent does on its own behalf),
 and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
 `host.reminders`).
 
-### Dispatch and dev mode
+### Dispatch a schedule
 
-In production (`agent-sdk serve`), schedules fire on their cron
-cadence. Disable them with `--no-schedules`. There's no cross-host
-coordination, so run them in exactly one process per project.
-
-In dev (`serve --dev`), schedules never fire automatically. Dispatch one
-by hand, exactly once, through the same path production uses:
+| Mode | What fires |
+| --- | --- |
+| Production `agent-sdk serve` | Cron cadence. `--no-schedules` disables them. Run them in exactly one process per project |
+| `serve --dev` | Nothing automatic. Dispatch by hand through the same path production uses |
 
 ```bash
 curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
@@ -83,104 +79,67 @@ The playground can dispatch schedules in dev mode too, and
 
 ## Reminders
 
-A reminder is created at runtime and bound to a channel continuation.
-When it fires, it wakes that conversation. Recurring reminders behave
-like `setInterval`, one-shots like `setTimeout`, and both are durable on
-disk.
+A reminder is created at runtime and bound to a channel continuation. A
+prompt reminder wakes that conversation when it fires; a handler reminder
+runs host code, which can call `followup` to wake it. Recurring reminders
+behave like `setInterval`, and one-shots behave like `setTimeout`. Prompt
+and named-handler reminders stay armed across restarts.
 
 ```ts
 await handle.createReminder({
   purpose: "ci_recheck",
   channelId: "drive",
-  continuationToken: "pr:owner/repo#1",
-  delay: "2h", // or a cron / explicit schedule
+  continuationToken: "pr:acme/checkout#42",
+  delay: "2h",
   prompt: "Re-check CI. Only act if still failing.",
   until: "Cancel once CI is green or the PR is merged.",
 });
 ```
 
-Use `run` when host code should decide what happens on each tick:
+When host code must decide what happens on each tick, author a named
+handler and pass its default export with serializable `args`:
 
 ```ts
-await handle.createReminder({
-  purpose: "ci_recheck",
-  channelId: "drive",
-  continuationToken: "pr:owner/repo#1",
-  every: "30m",
-  async run({ fireCount, followup }) {
-    if (fireCount >= 3) {
-      return { action: "stop" };
-    }
+// agent/reminders/ci_recheck.ts
+import { defineReminder } from "@cursor/july/reminders";
 
+export default defineReminder({
+  async run({ args, followup }) {
     await followup({
-      message: "Re-check CI and report only if the status changed.",
+      message: `Re-check CI for ${String(args.prUrl)}. Report only if the status changed.`,
     });
     return { action: "delivered" };
   },
 });
 ```
 
-This reminder wakes the conversation three times, then stops itself.
-
-The same API is `host.reminders` on channel handlers, tools, and
-schedule runs. An agent can even be given a tool that creates its own
-reminders.
-
-For example, create `agent/tools/remind_me.ts`:
-
 ```ts
-import { defineTool } from "@cursor/july/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Schedule a one-time reminder in this conversation.",
-  inputSchema: z.object({
-    delay: z
-      .string()
-      .describe("When to wake the conversation, such as 20m or 2h"),
-    prompt: z
-      .string()
-      .min(1)
-      .describe("What the agent should do when it wakes"),
-  }),
-  async execute({ delay, prompt }, ctx) {
-    const reminders = ctx.host.reminders;
-    if (reminders === undefined) {
-      throw new Error("Reminders are disabled on this host.");
-    }
-
-    const continuationToken = ctx.session.continuationKey;
-    if (continuationToken == null) {
-      throw new Error("This session cannot receive reminder follow-ups.");
-    }
-
-    const reminder = await reminders.create({
-      purpose: "user_follow_up",
-      channelId: ctx.session.channelId,
-      continuationToken,
-      delay,
-      prompt,
-    });
+import ciRecheck from "./agent/reminders/ci_recheck.js";
 
-    return {
-      reminderId: reminder.id,
-      nextFireAt: reminder.nextFireAt,
-    };
-  },
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:acme/checkout#42",
+  every: "30m",
+  handler: ciRecheck,
+  args: { prUrl: "https://github.com/acme/checkout/pull/42" },
 });
 ```
 
-The tool binds the reminder to the current channel conversation. When
-the delay expires, the prompt returns to the same session as a follow-up.
+Use an anonymous `run` handler only for legacy projects that can re-arm
+it after a restart. New projects should use a named handler.
 
-Reminders fire in one of two styles. The **prompt form** (above) sends
-`prompt` into the session, with `until` stating the standing
-cancellation condition for the model to honor. The **run form** passes a
-`run` handler instead: it returns `stop`, `skip`, or `delivered` per
-tick. That's silent host-side policy with no model turn. Run handlers are
-in-memory, so after a restart those reminders are disarmed
-(`handler_lost_on_restart`); re-arm them from the code path that created
-them, or prefer the prompt form.
+| Form | What it does | After a restart |
+| --- | --- | --- |
+| Prompt | Sends `prompt` into the session. `until` is the standing cancellation condition for the model | Stays armed |
+| Named handler | Runs a discovered handler with serializable `args`; it starts a model turn only if the handler calls `followup` | Stays armed |
+| Anonymous `run` | Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
+
+The same API is `host.reminders` on channel handlers, tools, and
+schedule runs. `builtinTools: { reminders: true }` adds
+`reminders_create`, `reminders_list`, and `reminders_cancel` on the
+current conversation; see
+[Agent config: built-in tools](./agent-config.md#built-in-tools).
 
 `--dev` does not auto-fire reminders. Dispatch one by hand:
 
@@ -191,27 +150,21 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/reminders/<id>  # fire one
 
 `handle.dispatchReminder(id)` is the programmatic equivalent.
 
-Two habits worth copying: cancel reminders when their subject
-dies (say, cancel PR-scoped reminders on `pull_request.closed`), and keep
-wake prompts generic. A plain "re-check the PR" works better than
-replaying stale payload details, because the agent re-reads the live
-state when it wakes.
+Cancel reminders when their subject dies, for example on
+`pull_request.closed`. Keep wake prompts generic so the agent re-reads
+live state instead of replaying a stale payload.
 
-## Schedule or reminder?
-
-The split comes down to scope and timing.
+## Schedules vs reminders
 
 |          | Schedule                                                   | Reminder                                        |
 | -------- | ---------------------------------------------------------- | ----------------------------------------------- |
 | Defined  | at deploy time, `agent/schedules/*`                        | at runtime, `createReminder` / `host.reminders` |
 | Scope    | global to the agent                                        | one channel continuation (one conversation)     |
 | Session  | starts a new task session (or hands off through `receive`) | wakes an existing conversation                  |
-| Cadence  | cron (UTC)                                                 | delay, cron, or explicit schedule               |
+| Cadence  | cron (UTC)                                                 | `every`, `cron`, `delay`, or `at`                |
 | Dev mode | manual dispatch only                                       | manual dispatch only (timers off)               |
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Channels](./channels.md): `receive` and the delivery events
 - [GitHub guide](../guides/github.md): reminders in a real webhook loop

package/docs/reference/sessions.md

@@ -6,9 +6,12 @@ description: "Understand how conversations continue, how events stream, and wher
 # Sessions, events, and streaming
 
 A session keeps one conversation, its workspace, and an append-only
-record of every message and tool call.
+record of every message and tool call. Continue it with a continuation
+token, inspect it with a session ID, and follow progress on the NDJSON
+stream. Chat sessions wait for follow-ups; task sessions run once and
+stop.
 
-## What does a session contain?
+## Session contents
 
 Each session combines:
 
@@ -16,12 +19,12 @@ Each session combines:
 - A conversation the caller can continue
 - A workspace for local turns
 - An NDJSON event stream
-- Runtime state needed to resume after a server restart
+- State that lets the conversation resume after a restart
 
 Sessions belong to the principal that created them. Follow-up, stream,
 and list routes return `403` when another caller tries to access one.
 
-## Which session identifier should I use?
+## Session identifiers
 
 Sessions have two identifiers because conversation routing and
 inspection are different jobs.
@@ -39,7 +42,7 @@ accepted follow-up. Reusing a stale HTTP token returns `409`.
 Use the continuation token to keep talking. Use the session ID to
 observe or manage the stored session.
 
-## Which session modes are available?
+## Session modes
 
 | Mode | Created by | What happens after a turn |
 | --- | --- | --- |
@@ -48,7 +51,7 @@ observe or manage the stored session.
 
 Task sessions don't accept follow-ups. Trying one returns `409`.
 
-## What happens when I send a follow-up?
+## Follow-ups
 
 A follow-up to an idle chat session starts another turn. Admission when
 the session is already busy depends on the channel:
@@ -56,23 +59,21 @@ the session is already busy depends on the channel:
 | Path | Busy-session policy |
 | --- | --- |
 | HTTP playground / `POST /v1/session/:id` / MCP `ask` | **Preempt** (default): interrupt the in-flight turn, wait for it to settle, then run the new message |
-| Slack mentions / DMs / alert-watch | **Coalesce**: leave the active turn running, enqueue the follow-up, and drain queued asks into one follow-up turn when the active turn finishes (no mid-turn tool/hook inject) |
+| Slack mentions / DMs / alert-watch | **Coalesce**: leave the active turn running and queue the follow-up. The running turn may receive it at a tool boundary; any asks that remain become one follow-up turn when it finishes |
 
 Pass `admission: "coalesce"` on `send()` to opt into the Slack policy from
 other callers. Omit it (or pass `"preempt"`) to keep interrupt semantics.
 
 `POST /v1/session/:id/stop` interrupts a turn without sending a new
-message. Interrupted turns record `turn.failed` with
-`"turn interrupted"`. This means the turn was preempted. A whole-message
-Slack `stop` / `@agent stop` does the same for that thread and clears
-pending coalesced nudges.
+message. The stream records `turn.failed` with `status: "cancelled"`;
+the session stays a chat session and can take another follow-up. A
+whole-message Slack `stop` / `@agent stop` does the same for that thread
+and clears pending coalesced follow-ups.
 
-Session-bound deterministic tool calls share the lock only for writes: a
-write-effect call returns `409 session_busy` while a model turn is
-running, a read-effect call runs alongside the turn (see
-[Tools](./tools.md#call-a-tool-without-a-model-turn)).
+See [Tools](./tools.md#call-a-tool-without-a-model-turn) for direct-call
+behavior while a session is busy.
 
-## Which events can I stream?
+## Stream events
 
 Each NDJSON line uses this envelope:
 `{ type, index, sessionId, turnId?, at, data }`. The `index` increases
@@ -94,13 +95,11 @@ within one session. The `at` field is an ISO-8601 timestamp.
 
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
-cache token counts. When `agent/result.ts` is authored, a thrown
-`commit`, a `ctx.reject` that exhausts the two-repair budget, or empty
-assistant text emits `turn.failed` instead of `turn.completed`.
-`ctx.reject(message)` re-runs the same turn with that message so the
-model can revise while tools and the session filesystem are still up.
+cache token counts. With `agent/result.ts`, `turn.failed` is emitted when
+`commit` throws, the turn has no assistant text, or `ctx.reject(message)`
+doesn't lead to an accepted revision.
 
-## How do I stream or replay session events?
+## Stream or replay events
 
 One endpoint handles both live streaming and replay:
 
@@ -108,27 +107,27 @@ One endpoint handles both live streaming and replay:
 curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
 ```
 
-Pass `startIndex` to continue after the last event you received. Omit it
-or pass `0` to replay the full session before following new events.
+Pass `startIndex` to continue after the last event you received,
+including after a server restart. Omit it or pass `0` to replay the
+full session before following new events.
 `GET /v1/session/:id/events` returns a one-time dump without staying
 connected.
 
-Event streams replay from disk after a server restart. Conversation
-state resumes from the Cursor SDK store.
-
-## What goes into a local session workspace?
+## Local session workspace
 
 The Agent SDK creates a workspace before the first local turn:
 
 | Source path                        | Lands as                                                                |
 | ---------------------------------- | ----------------------------------------------------------------------- |
-| `instructions.*`                   | `AGENTS.md`                                                             |
 | `skills/*`                         | `.cursor/skills/<name>/SKILL.md`                                        |
 | agent tools (`execution: "agent"`) | scripts in the session workspace, with a catalog in `AGENTS.md` |
 | `sandbox/workspace/**`             | copied in as seed files                                                 |
 | per-send `workspaceFiles`          | written before the turn                                                 |
 
-The local harness uses this workspace as its working directory. Parent
+Instructions reach the model as its system prompt; they aren't written
+into the workspace. See [Instructions](./instructions.md#delivery).
+
+Local turns use this workspace as their working directory. Parent
 directories can contribute `AGENTS.md` and `.cursor` settings. Set
 `local.cwd` when you need a clean parent directory. A channel can also
 provide a different working directory for one session, such as a PR
@@ -137,20 +136,16 @@ worktree.
 See [Agent config: local cwd](./agent-config.md#local-cwd) for the
 inheritance rules.
 
-## Where does the Agent SDK store session data?
+## Session storage
 
-Local state lives under `--state-root`. Slugged mounts store it under
-a subdirectory named for the slug.
+Local session state lives under `--state-root`. A slugged mount stores
+it in a subdirectory named for the slug.
 
 Deleting a session directory removes the session from the server: it
 disappears from listings and can no longer be streamed or continued.
 Cloud conversations remain on the Cursor backend.
 
-Nested git checkouts already default `local.cwd` outside the enclosing
-repo. See
-[What goes into a local session workspace?](#what-goes-into-a-local-session-workspace).
-
-## How do I inspect a saved event stream?
+## Inspect a saved event stream
 
 Use `trajectory` with a saved trace:
 
@@ -159,10 +154,11 @@ agent-sdk trajectory --events <state-root>/traces/<sessionId>.ndjson
 ```
 
 The command prints tool calls, the reply, and token usage in the same
-JSON shape as `run`. Use **Open trace** in the playground for a visual
-view.
+JSON shape as `run`. Open the session's **Trace** view in the playground
+for a visual timeline.
 
 ## Related
 
 - [HTTP API](./http-api.md)
 - [Hooks](./hooks.md)
+- [Tools](./tools.md)

package/docs/reference/skills.md

@@ -13,15 +13,15 @@ always-on [instructions](./instructions.md).
 
 ## Authoring forms
 
-Three forms cover every case.
+Skills support three authoring forms.
 
 | Form | Reach for it when |
 | --- | --- |
-| `agent/skills/<name>.md` | Flat markdown. Optional `description` frontmatter; the first body line is the fallback. |
+| `agent/skills/<name>.md` | Static Markdown. Optional `description` frontmatter; the first body line is the fallback. |
 | `agent/skills/<name>/SKILL.md` plus siblings | A packaged directory with reference files (`references/…`). Requires `description` frontmatter. |
 | `agent/skills/<name>.ts` | Generated content, with `defineSkill` from `@cursor/july/skills`. |
 
-Flat markdown:
+Use flat Markdown for static content:
 
 ```md
 ---
@@ -35,8 +35,8 @@ description: Use when a pull request needs a structured approval checklist.
 3. Call `approve_pr` only after an explicit request; it requires approval.
 ```
 
-TypeScript, when the content must be generated or carry inline sibling
-files:
+Use TypeScript when the content must be generated or include inline
+sibling files:
 
 ```ts
 import { defineSkill } from "@cursor/july/skills";
@@ -48,40 +48,29 @@ export default defineSkill({
 });
 ```
 
-## How skills reach the model
+## Skill delivery
 
-On the local runtime, skills land in the session workspace at
-`.cursor/skills/<name>/SKILL.md`, and the harness advertises and loads
-them natively. On the cloud runtime there is no session workspace, so
-the engine copies the same SKILL.md tree onto an Agent Store for native
-discovery:
+Local turns receive authored skills automatically. Hosted deployments
+and local `serve` or `run` processes with a personal `CURSOR_API_KEY`
+also make them available to cloud turns. Otherwise, a cloud turn sees
+only skills already in its checkout. `agent-sdk validate` warns when
+`runtime: "cloud"` is combined with authored skills.
 
-- Hosted deployments write store-root `skills/<name>/`.
-- `agent-sdk serve` / `run` with a personal `CURSOR_API_KEY` write
-  namespaced skills on the USER store so they cannot collide with the
-  user's own skills.
-
-`validate` still warns about the combination so the store path is
-visible. Cloud turns with neither a hosted store nor an API key see
-only skills already in the cloud repo.
-
-## Instructions, skills, or tools?
+## Skills, instructions, and tools
 
 Instructions are always in context: identity, tool-choice rules, the
 output contract. Keep them short. Skills load when relevant: procedures,
 checklists, house style. Reach for a skill when the model needs to
-*follow* something but only sometimes needs it loaded. Tools are typed,
+follow something but only sometimes needs it loaded. Tools are typed,
 executable behavior: anything that must be correct every time belongs in
 tool code, not in prose the model might paraphrase.
 
-A good skill description is a routing rule, not a title. Say *when* to
+A good skill description is a routing rule, not a title. Say when to
 use it, like "Use when a pull request needs a structured approval
 checklist," because the description is all the model sees before
 deciding to load it.
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Instructions](./instructions.md): what stays always-on
 - [Tools](./tools.md): when prose needs to become code