From ecb8c65bc0250aaa353c20156b9af5f4e6a3e876 Mon Sep 17 00:00:00 2001
From: dadachann <185672915+dadachann@users.noreply.github.com>
Date: Sat, 12 Sep 2026 05:19:50 +0000
Subject: [PATCH] docs(space): sync Runner usage recommendation contract

---
 skills/skills/langbot-space-ops/SKILL.md | 35 +++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/skills/skills/langbot-space-ops/SKILL.md b/skills/skills/langbot-space-ops/SKILL.md
index c360d4e3f..241cc1238 100644
--- a/skills/skills/langbot-space-ops/SKILL.md
+++ b/skills/skills/langbot-space-ops/SKILL.md
@@ -25,7 +25,10 @@ CLI uses. Create one in your Space account (Profile → Personal Access Tokens),
 then send it as a Bearer token:
 
 ```
-Authorization: Bearer lbpat_...uests without a valid PAT get `401 Unauthorized`.
+Authorization: Bearer <your-pat>
+```
+
+Requests without a valid PAT get `401 Unauthorized`.
 
 ## Client configuration
 
@@ -66,6 +69,36 @@ All tools are read-only.
    state (available, unprobed, unavailable), then Space recommendation. Each
    item includes `availability.up`, `last_probed_at`, latency, and HTTP status.
 
+## Runner usage recommendations
+
+Use `search_plugins` with `runner_usage: "agent"` for Agent, pipeline, and
+setup-wizard recommendations, or `runner_usage: "event"` for event processors.
+The component kind remains `Runner`. Only these two exact values are accepted;
+omit the optional field to preserve unfiltered browsing.
+
+```json
+{"query":"", "runner_usage":"agent", "page":1, "page_size":100}
+```
+
+Plugin results include `latest_version` and `runner_usages: string[]`, the
+explicit union of usages in that latest installable version. Only recommend a
+plugin when this array explicitly contains the target usage. Missing, empty,
+malformed, or unknown usages must never mean agent-compatible. Event-only
+plugins must never enter Agent recommendations. Empty filtered results are
+valid while legacy packages await corrected releases; never remove the filter
+to fill a recommendation list.
+
+REST callers use `runner_usage` on both
+`POST /api/v1/marketplace/extensions/search` and the compatibility
+`POST /api/v1/marketplace/plugins/search`; preserve it during fallback. Add
+`"type_filter":"plugin", "component_filter":"Runner"` on the unified endpoint.
+Usage is ANDed with other filters before pagination and `total`; MCP/Skill items
+do not match. Invalid REST values return HTTP 400.
+
+Open the same filter in the webpage:
+`https://space.langbot.app/market?type=plugin&component=Runner&runner_usage=agent`
+(or `runner_usage=event`). Switch All / Agent / Event in the Runner usage row.
+
 ## Implementation & maintenance (for Space developers)
 
 - Server: `internal/controller/mcp/server.go` (official Go MCP SDK