Correct MCP tool reference and close migration coverage gaps

README.md

@@ -4,9 +4,10 @@ The official portable Agent Plugin for [Sprites](https://sprites.dev): isolated,
 persistent cloud development environments that agents can create, operate,
 checkpoint, and clean up.
 
-The package targets [Agent Plugins v1.0.0](https://agent-plugins.org/specification).
-It connects compatible clients to the hosted Sprites MCP server and bundles
-Agent Skills for common workflows. There is no local server process to install.
+The package targets [Agent Plugins v1.0.0](https://agent-plugins.org/specification),
+currently a Working Draft. It connects compatible clients to the hosted Sprites
+MCP server and bundles Agent Skills for common workflows. There is no local
+server process to install.
 
 ## What it provides
 
@@ -38,17 +39,23 @@ for its current local, Git, workspace, or marketplace install flow.
 ## Current client compatibility
 
 The Agent Plugins project currently lists VS Code, Cursor, GitHub Copilot,
-ChatGPT and Codex, and Kiro as compatible clients. This package is designed to
-replace the reusable skills-and-MCP core of the existing Codex and Cursor
-packages; marketplace publication remains a separate client-owned step.
+ChatGPT and Codex, and Kiro as compatible clients. All five load Agent Skills
+and speak Streamable HTTP MCP, so the single server entry in `mcp.json` reaches
+every one of them. This package is designed to replace the reusable
+skills-and-MCP core of the existing Codex and Cursor packages; marketplace
+publication remains a separate client-owned step.
 
 Google's August 2026 announcement says Agents CLI and Data Agent Kit currently
 support the format and that support is expected in more Google products. It
 mentions Antigravity as an agent that can consume Agents CLI's skills, but does
 not identify Antigravity itself as a conforming Agent Plugins client. Keep the
 existing Antigravity package for its hooks, rules, and native installation until
-that support is documented and tested. Grok is likewise not on the current
-compatible-client list.
+that support is documented and tested.
+
+Grok and Claude Code are likewise not on the current compatible-client list.
+Keep their existing packages too — the Claude package in particular enforces
+destructive-operation confirmation through a pre-tool hook, which v1 has no
+portable equivalent for.
 
 ## Example prompts
 
@@ -113,8 +120,8 @@ rules. They do not make network calls.
 ## Source material
 
 This package consolidates the reusable behavior from the existing Sprites
-plugins for Codex, Cursor, Antigravity, and Grok. The MCP tool model is checked
-against the Sprites platform source and the public
+plugins for Codex, Cursor, Antigravity, Grok, and Claude Code. The MCP tool
+model is checked against the Sprites platform source and the public
 [Sprites MCP server reference](https://github.com/superfly/sprites-mcp).
 See [migration coverage](docs/migration-coverage.md) for the artifact-by-artifact
 mapping and the client-specific behavior that Agent Plugins v1 cannot carry.

docs/migration-coverage.md

@@ -7,26 +7,29 @@ or remove the existing client-specific repositories.
 
 | Existing artifact | Portable destination | Coverage |
 | --- | --- | --- |
-| Codex and Cursor root workflow skill | `skills/sprites/` | Consolidated and expanded with progressive references. |
-| Codex `.mcp.json`, Cursor `mcp.json`, Grok MCP configs, Antigravity `mcp_config.json` | Root `mcp.json` | Converted to Agent Plugins v1 `streamable-http`. |
+| Codex, Cursor, and Claude root workflow skill | `skills/sprites/` | Consolidated and expanded with progressive references. |
+| Codex `.mcp.json`, Cursor `mcp.json`, Claude `.mcp.json`, Grok MCP configs, Antigravity `mcp_config.json` | Root `mcp.json` | Converted to Agent Plugins v1 `streamable-http`. |
 | Antigravity `/sprites:list` command and skill | `skills/sprites-list/` | Workflow preserved as an invokable/discoverable skill. |
 | Antigravity `/sprites:new` command and skill | `skills/sprites-new/` | Workflow preserved as an invokable/discoverable skill. |
 | Antigravity `/sprites:run` command and skill | `skills/sprites-run/` | Workflow preserved as an invokable/discoverable skill. |
 | Antigravity `/sprites:service` command and skill | `skills/sprites-service/` | Workflow preserved as an invokable/discoverable skill. |
 | Antigravity `/sprites:checkpoint` command and skill | `skills/sprites-checkpoint/` | Workflow preserved as an invokable/discoverable skill. |
 | Antigravity `/sprites:cleanup` command and skill | `skills/sprites-cleanup/` | Workflow preserved as an invokable/discoverable skill. |
-| Grok `sprites-status` skill | `skills/sprites-status/` | Generalized to client-neutral setup and OAuth diagnostics. |
-| Grok `sprites-smoke` skill | `skills/sprites-smoke/` | Preserved with safe optional teardown. |
-| Grok auth, compute, file, service, safety, and smoke references | `skills/sprites/references/` | Consolidated, corrected against the current MCP surface, and made client-neutral. |
+| Antigravity `deployment.md` reference | `skills/sprites/references/deployment.md` | Sync flow and do-not-sync boundaries preserved and expanded. |
+| Grok and Claude `sprites-status` skill | `skills/sprites-status/` | Generalized to client-neutral setup and OAuth diagnostics. |
+| Grok and Claude `sprites-smoke` skill | `skills/sprites-smoke/` | Preserved with safe optional teardown. |
+| Grok and Claude auth, compute, file, service, safety, and smoke references | `skills/sprites/references/` | Consolidated, corrected against the current MCP surface, and made client-neutral. |
+| Claude `sprites_guard.py` destructive-tool warnings | `skills/sprites/references/safety.md` and `tools.md` | Warning text for `destroy_sprite`, `checkpoint_restore`, and replace-not-merge `policy_network_update` retained as guidance. |
+| Claude `sprites_guard.py` checkpoint-command heuristics | `skills/sprites/references/safety.md` | Checkpoint-first triggers retained as prose rather than pattern matching. |
 | Logos and MIT license | `assets/` and `LICENSE` | Preserved. |
 
 ## Intentionally not portable in v1
 
 | Artifact | Reason |
 | --- | --- |
-| Codex, Cursor, and Grok marketplace catalogs and rich UI metadata | Distribution and install UI are outside Agent Plugins v1. |
+| Codex, Cursor, Claude, and Grok marketplace catalogs and rich UI metadata | Distribution and install UI are outside Agent Plugins v1. |
 | Client-specific manifests | Root `plugin.json` is the only portable manifest. |
-| Antigravity hooks and hook script | Hooks are not a v1 portable component and no documented client extension namespace is available here. Safety behavior is retained as model guidance, not mechanical enforcement. |
+| Antigravity and Claude hooks and hook scripts | Hooks are not a v1 portable component and no documented client extension namespace is available here. Safety behavior is retained as model guidance, not mechanical enforcement. |
 | Antigravity rules file | Rules are not a v1 portable component; relevant behavior is included in the core skill. |
 | Antigravity command TOML | Commands are not a v1 portable component; focused skills preserve their workflows. |
 | Client-specific request-attribution headers | A portable package cannot truthfully hard-code a single host identity. |
@@ -35,16 +38,21 @@ or remove the existing client-specific repositories.
 ## Compatibility implications
 
 The portable package can replace the skills-and-MCP core for conforming clients.
-It cannot claim feature parity with enforced Antigravity pre-tool hooks or any
-marketplace presentation until those behaviors are represented by documented
-client extensions or retained compatibility packages.
-
-As of August 2026, the Agent Plugins compatible-client list includes Cursor and
-ChatGPT/Codex but not Antigravity or Grok. Google's launch announcement says its
-current format integrations are Agents CLI and Data Agent Kit; Antigravity is
-named as an agent that can consume Agents CLI skills, not as a native plugin
-client. Treat Antigravity replacement as unverified until its loader explicitly
-documents the v1 root manifest and MCP configuration.
+It cannot claim feature parity with enforced Antigravity or Claude pre-tool
+hooks or any marketplace presentation until those behaviors are represented by
+documented client extensions or retained compatibility packages.
+
+As of August 2026, the Agent Plugins compatible-client list is ChatGPT and
+Codex, VS Code, Kiro, GitHub Copilot, and Cursor. All five support Agent Skills
+and Streamable HTTP MCP, so this package's single server entry reaches every
+listed client. Antigravity, Grok, and Claude Code are not on that list; keep
+their existing packages until each loader documents the v1 root manifest and
+MCP configuration.
+
+Google's launch announcement says its current format integrations are Agents CLI
+and Data Agent Kit; Antigravity is named as an agent that can consume Agents CLI
+skills, not as a native plugin client. Treat Antigravity replacement as
+unverified on the same grounds.
 
 Before deleting a legacy repository, test installation, OAuth, skill discovery,
 all 18 live tools, and destructive-action behavior in each target client.

skills/sprites/SKILL.md

@@ -72,7 +72,10 @@ the MCP tool accepts a shell command string. Use a shell explicitly only when
 the requested operation needs shell syntax. Prefer non-interactive flags.
 
 For environment bootstrap, repositories, or file-transfer work, read
-[remote compute](references/compute.md) and [files](references/files.md).
+[remote compute](references/compute.md) and [files](references/files.md). When
+copying local project state into a sprite, follow the sync boundaries in
+[deployment](references/deployment.md); never sync `.git/`, dependency caches,
+or local secrets by default.
 
 ### Run a service
 

skills/sprites/references/compute.md

@@ -16,6 +16,8 @@ performed remotely.
      can access.
    - For small generated files, use the reliable patterns in
      [files.md](files.md).
+   - When copying local project state, follow the sync boundaries in
+     [deployment.md](deployment.md).
    - Ask how private code should be transferred when no authorized path exists;
      never invent credentials.
 5. Run bounded work with `exec`; use services for processes that must persist.

skills/sprites/references/deployment.md

@@ -0,0 +1,42 @@
+# Deploying and syncing into a sprite
+
+Use this reference when copying local project state into a sprite, building
+inside one, or running a preview service from synced code.
+
+## Recommended flow
+
+1. Confirm the target sprite and the remote working directory.
+2. Create or verify a checkpoint before overwriting remote files.
+3. Sync selected paths, not the whole workspace by default.
+4. Install dependencies or build inside the sprite only when the task needs it.
+5. Run tests or a smoke check inside the sprite.
+6. Start or update a service for a long-running preview.
+7. Report the sprite URL, expected access mode, log highlights, and any manual
+   step left for the user.
+
+Prefer `git clone` inside the sprite over copying a working tree. It is faster,
+avoids most of the boundaries below, and gives the sprite a real repository.
+See [files](files.md) for transfer patterns when no repository is available.
+
+## Do not sync
+
+- `.git/`. Clone or fetch inside the sprite instead of copying history.
+- Dependency and build caches such as `node_modules/`, `_build/`, `deps/`,
+  `.venv/`, `target/`, `dist/`, and `.next/`. Reinstall inside the sprite; host
+  artifacts are frequently built for a different platform.
+- Local secrets: `.env` and its variants, key files, certificates, token
+  caches, cloud credential stores, and shell history.
+- Large generated artifacts, media, datasets, and databases unless they are the
+  intended payload and the user asked for them.
+- Editor, OS, and agent state such as `.DS_Store`, `.idea/`, and local client
+  configuration directories.
+
+When a sync would pull in a secret, stop and ask how the sprite should obtain
+it. Provide credentials as service or exec environment values at run time
+rather than writing them into the remote filesystem.
+
+## After syncing
+
+Verify what actually landed with a file count, `du`, or a checksum before
+building. Report the paths you synced and the paths you deliberately skipped so
+the user can correct the boundary.

skills/sprites/references/safety.md

@@ -5,12 +5,19 @@
 - Destroying a sprite.
 - Restoring a checkpoint.
 - Killing sessions or stopping services not clearly owned by the current task.
-- Widening outbound network policy.
+- Changing outbound network policy in either direction.
 - Exposing a new public HTTP surface.
 - Broad destructive filesystem commands inside a sprite.
 
 Resolve exact resource names and inspect current state before these operations.
 
+## Network policy replaces, it does not merge
+
+`policy_network_update` overwrites the entire rule set. A change intended to
+narrow or add a single domain will silently drop every rule you did not send.
+Always read the current policy with `policy_network_get`, build the complete
+intended set from it, and confirm that full set with the user before writing.
+
 ## Create a checkpoint first
 
 Checkpoint valuable state before package upgrades, migrations, bulk rewrites or

skills/sprites/references/tools.md

@@ -3,42 +3,72 @@
 The live MCP server's `tools/list` response is authoritative. This reference
 summarizes the current 18-tool surface.
 
+## Reading the risk column
+
+The `Risk` column below is editorial guidance for deciding when to confirm with
+the user. It is not the server's own classification.
+
+The server derives MCP annotations from the underlying HTTP method: `GET`
+endpoints get `readOnlyHint: true` and every other endpoint gets
+`destructiveHint: true`. So `create_sprite`, `exec`, `checkpoint_create`,
+`service_create`, and `service_start` all arrive annotated destructive even
+though they are ordinary write operations. Do not treat that mismatch as a bug,
+and do not use `destructiveHint` alone to decide whether to ask permission.
+
+Every sprite-scoped tool requires the exact `sprite` name.
+
 ## Sprite management
 
-| Tool | Access | Purpose |
+| Tool | Risk | Purpose |
 | --- | --- | --- |
 | `list_sprites` | read | List visible sprites; supports pagination and optional prefix filtering. |
 | `create_sprite` | write | Create a sprite by name, optionally waiting for capacity. |
 | `destroy_sprite` | destructive | Permanently destroy a sprite by name. |
 
+- `list_sprites` — `prefix` (string, optional), `max_results` (integer,
+  optional), `continuation_token` (string, optional). Pass the returned token
+  back as `continuation_token` for a complete inventory.
+- `create_sprite` — `name` (string, required), `wait_for_capacity` (boolean,
+  optional). Set `wait_for_capacity` rather than polling or retrying in a loop.
+- `destroy_sprite` — `name` (string, required).
+
 ## Commands
 
-| Tool | Access | Purpose |
+| Tool | Risk | Purpose |
 | --- | --- | --- |
 | `exec` | write | Run a non-TTY command inside a sprite. |
 | `exec_list` | read | List active exec sessions. |
 | `exec_kill` | destructive | Signal an exec session and wait for termination. |
 
-`exec` accepts a required repeatable `cmd` value representing the command and
-arguments, plus optional path, stdin, environment, and working-directory
-fields. Follow the live input schema rather than flattening arguments into one
-shell string.
+- `exec` — `cmd` (string, required, repeatable for the executable and each
+  argument), `path` (string, optional), `stdin` (boolean, optional), `env`
+  (string, optional, repeatable, each entry formatted `KEY=VALUE`), `dir`
+  (string, optional).
+- `exec_kill` — `session_id` (string, required), `signal` (string, optional,
+  default `SIGTERM`), `timeout` (string, optional, default `10s`).
+
+Follow the live input schema rather than flattening arguments into one shell
+string.
 
 ## Checkpoints
 
-| Tool | Access | Purpose |
+| Tool | Risk | Purpose |
 | --- | --- | --- |
 | `checkpoint_create` | write | Snapshot current state, optionally with a comment. |
 | `checkpoint_list` | read | List checkpoints. |
 | `checkpoint_get` | read | Get one checkpoint by ID, such as `v7`. |
 | `checkpoint_restore` | destructive | Restore a checkpoint and discard later filesystem state. |
 
+- `checkpoint_create` — `comment` (string, optional).
+- `checkpoint_get` — `checkpoint_id` (string, required, such as `v7`).
+- `checkpoint_restore` — `checkpoint_id` (string, required).
+
 Individual checkpoints cannot currently be deleted through MCP. Destroying a
 sprite removes all of its checkpoints.
 
 ## Services
 
-| Tool | Access | Purpose |
+| Tool | Risk | Purpose |
 | --- | --- | --- |
 | `service_list` | read | List configured services and state. |
 | `service_get` | read | Get one service by name. |
@@ -47,15 +77,32 @@ sprite removes all of its checkpoints.
 | `service_stop` | destructive | Stop a service. |
 | `service_logs` | read | Read or stream service logs. |
 
+- `service_create` — `service_name` (string, required), `cmd` (string,
+  required, the executable only), `args` (array, optional), `needs` (array,
+  optional dependency service names), `http_port` (integer, optional),
+  `duration` (string, optional). Unlike `exec`, `cmd` here is a single string
+  and arguments belong in `args`.
+- `service_get` — `service_name` (string, required).
+- `service_start` / `service_stop` — `service_name` (string, required), plus an
+  optional `duration`/`timeout` (string).
+- `service_logs` — `service_name` (string, required), `lines` (integer,
+  optional), `duration` (string, optional).
+
 There is no separate restart tool: stop, then start the affected service.
 
 ## Network policy
 
-| Tool | Access | Purpose |
+| Tool | Risk | Purpose |
 | --- | --- | --- |
 | `policy_network_get` | read | Read outbound DNS-based network policy. |
 | `policy_network_update` | destructive | Replace outbound network policy rules. |
 
-All sprite-scoped tools require the exact `sprite` name. Resource-specific
-tools also require values such as `session_id`, `checkpoint_id`, or
-`service_name`.
+- `policy_network_update` — `rules` (array, required; each rule has `domain`,
+  `action`, and an optional `include`).
+
+`policy_network_update` replaces the entire rule set rather than merging into
+it. Read the current policy with `policy_network_get` first and send the
+complete intended set, or unrelated rules are silently dropped.
+
+Resource-specific tools require values such as `session_id`, `checkpoint_id`,
+or `service_name` in addition to `sprite`.