Add composer mentions and Sprite Inspector guidance

README.md

@@ -11,6 +11,7 @@ With this plugin enabled, you can ask Codex to:
 - List your active sprites.
 - Create a fresh remote environment for a task.
 - Inspect a sprite's files, services, logs, checkpoints, and network policy.
+- Select a specific Sprite in the desktop composer and inspect it beside the conversation.
 - Run commands, tests, builds, and diagnostics inside a selected sprite.
 - Start long-running services such as dev servers, background workers, and databases.
 - Create checkpoints before risky changes.
@@ -73,6 +74,27 @@ only — it is never used for access control, gating, or rate-limiting.
 - "Use Sprites to inspect services and logs for a selected sprite."
 - "Create a checkpoint in my `api-debug` sprite, then run the failing test."
 - "Start the web service in my sprite and give me the URL."
+- "Open the Sprite Inspector for `api-debug`."
+
+## Composer Mentions and Sprite Inspector
+
+With the matching MCP server update deployed, supported desktop clients can search
+for individual Sprites in the composer. Search uses a name prefix and shows up to
+20 environments accessible to the authenticated organization and token. Selecting
+a result adds a reference containing the Sprite's organization, name, and ID.
+Codex verifies that identity before using the environment.
+
+The **Sprite Inspector** opens beside the conversation. Ask Codex to open it, or
+use its conversation-panel entrypoint where the host supports one. You can browse
+and filter environments, load more results, attach a selected Sprite to chat,
+inspect services and checkpoints, and read the last 100 lines of a service's logs.
+Opening the panel lists metadata; loading runtime details or logs may wake a
+sleeping Sprite. The panel is read-only and refreshes on request.
+
+The hosted MCP server supplies the UI and extension metadata. No extra local
+server or credentials are needed. Existing text-based tools remain available on
+clients without extension support. After the server update is deployed, refresh
+the plugin connection or restart Codex to discover the new tools.
 
 ## How Codex Uses Sprites
 

plugins/sprites/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sprites",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Use Sprites from Codex to create, inspect, and operate remote isolated development environments.",
   "author": {
     "name": "Fly.io",
@@ -19,7 +19,7 @@
   "interface": {
     "displayName": "Sprites",
     "shortDescription": "Manage remote development sprites from Codex.",
-    "longDescription": "Create, list, inspect, and operate remote Sprites environments from Codex using Sprites MCP tools and workflow guidance.",
+    "longDescription": "Create, list, inspect, and operate remote Sprites environments from Codex. Select individual Sprites in supported desktop composers and open a read-only Sprite Inspector for services, checkpoints, and recent logs.",
     "developerName": "Fly.io",
     "category": "Developer Tools",
     "capabilities": [

plugins/sprites/skills/sprites/SKILL.md

@@ -24,6 +24,8 @@ Keep user-facing progress concise. Report the result, not MCP registration detai
 Use the smallest direct tool for the request:
 
 - List sprites: `list_sprites`.
+- Inspect a mentioned Sprite's identity: `get_sprite_info` with `sprite` and `sprite_id`.
+- Open a visual inspection panel: `open_sprite_inspector`, optionally with `sprite`.
 - Create a sprite: `create_sprite`, then `list_sprites` only if the user asked to see the updated list.
 - Delete a sprite: `destroy_sprite`, only after explicit delete/destroy/remove intent.
 - Run a one-off command in a sprite: `exec`. Inspect or stop exec sessions with `exec_list` and `exec_kill`.
@@ -35,6 +37,16 @@ Use the smallest direct tool for the request:
 
 Sprite-scoped tools usually require a `sprite` argument. If the user did not name a sprite and the task needs one, call `list_sprites` and choose the obvious match; ask a short clarification only when there is no clear choice.
 
+## Composer Mentions and Inspector
+
+On supported desktop clients, users can select individual Sprites from the composer. A Sprite reference uses `sprites://org/<org_id>/<encoded-name>?id=<sprite_id>` and identifies an environment in a particular organization. The Inspector can also attach a selected Sprite's name, ID, and organization to the conversation.
+
+Use that explicit selection as the target. Verify it with `get_sprite_info`, passing the decoded name as `sprite` and the reference's ID as `sprite_id`, and check that the returned organization matches the reference. Pass `sprite_id` alongside `sprite` to subsequent sprite-scoped tools that advertise it. If access fails or the identity has changed, report that the reference is stale or unavailable; do not substitute a similarly named environment. When multiple selections leave the target ambiguous, ask which one the user means. A selection supplies context, not permission to delete or restore an environment.
+
+When the user asks for a visual overview, open `open_sprite_inspector`. It lists environments and provides explicit reads for services, checkpoints, and the last 100 service-log lines. Runtime reads may wake the selected Sprite. The Inspector has no mutation controls; use the existing tools for requested changes. Its current selection is contextual and may be removed from the composer.
+
+These extensions require support from both the host and the hosted MCP server. If only the extension tools or UI are unavailable, continue using the existing list and inspection tools and summarize their results in chat. Do not attempt to register a second server. Composer search is host-driven; `search_sprite_mentions` is an app-only tool.
+
 ## Common Flows
 
 List sprites: