docs: align plugin with capability platform

Author: erickkkyt

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "beatapi-agent-plugin",
   "version": "0.3.0",
-  "description": "Create and manage BeatAPI text, image, video, Effect, workflow, and analysis APIs from Codex.",
+  "description": "Use BeatAPI models, Social Data, Effects, and workflows from Codex.",
   "author": {
     "name": "BeatAPI",
     "email": "support@beatapi.io",
@@ -12,6 +12,8 @@
   "license": "MIT",
   "keywords": [
     "beatapi",
+    "agent-toolkit",
+    "social-data",
     "ai-video",
     "music-video",
     "ecommerce-video",
@@ -26,8 +28,8 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "BeatAPI",
-    "shortDescription": "Manage BeatAPI text, media, and workflows",
-    "longDescription": "Use one existing BeatAPI account and API key from Codex to discover models and Effects, create text responses, upload explicitly approved inputs, check USD balance and concurrency, create image, video, Effect, Video Analysis, Music Video, and Ecommerce Video tasks, monitor progress, retrieve hosted results, and manage existing Realtime sessions and webhooks.",
+    "shortDescription": "Use BeatAPI models, data, and workflows",
+    "longDescription": "Use one existing BeatAPI account and API key from Codex to discover current Model, Social Data, Effect, and Workflow capabilities; create text responses; upload explicitly approved inputs; check USD balance and concurrency; create image, video, Effect, Video Analysis, Music Video, and Ecommerce Video tasks; monitor progress; retrieve hosted results; and manage existing Realtime sessions and webhooks.",
     "developerName": "BeatAPI",
     "category": "Creativity",
     "capabilities": [

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "beatapi-agent-plugin",
   "version": "0.3.0",
-  "description": "Use BeatAPI text, image, video, Effects, workflows, and analysis APIs from Cursor and Grok Bot.",
+  "description": "Use BeatAPI models, Social Data, Effects, and workflows from Cursor and Grok Bot.",
   "author": {
     "name": "BeatAPI",
     "email": "support@beatapi.io"
@@ -12,6 +12,7 @@
   "keywords": [
     "beatapi",
     "agent-toolkit",
+    "social-data",
     "ai-video",
     "ai-image",
     "text-generation",

.grok-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "beatapi-agent-plugin",
   "version": "0.3.0",
-  "description": "Use BeatAPI text, image, video, Effects, workflows, and analysis APIs from Grok Build.",
+  "description": "Use BeatAPI models, Social Data, Effects, and workflows from Grok Build.",
   "author": {
     "name": "BeatAPI",
     "url": "https://beatapi.io"
@@ -12,6 +12,7 @@
   "keywords": [
     "beatapi",
     "beatapi agent toolkit",
+    "beatapi social data",
     "beatapi video",
     "beatapi image",
     "beatapi workflows"

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- Synchronized the locked public OpenAPI contract with current capability,
+  Social Data, onboarding, model, media, Effect, Workflow, and Realtime routes.
+- Distinguished the stable three-tool Hosted MCP from the plugin's 26 focused
+  local MCP tools and documented the current Model/Data/Workflow catalog shape.
+- Updated Skill and CLI references to the published 0.3.0 capability interface.
+
 - Renamed the repository and package to `beatapi-agent-plugin`.
 - Added a Cursor/Grok Bot manifest and root `mcp.json` alongside the existing
   Codex manifest, sharing the same Skill and MCP runtime.

README.md

@@ -16,9 +16,15 @@ For a host-independent onboarding prompt, use
 mirrors that setup contract; the detailed installable Skill remains under
 `skills/beatapi-video/`.
 
-A cross-host Agent Toolkit plugin for discovering live BeatAPI models and
-running text, image, video, Effect, analysis, and production workflow
-APIs through one local MCP interface.
+A cross-host Agent Toolkit plugin for discovering live BeatAPI Model, Social
+Data, and Workflow capabilities and running text, image, video, Effect,
+analysis, and production APIs through one local MCP interface.
+
+For hosts that support remote MCP, BeatAPI also provides the stable Hosted MCP
+endpoint `https://beatapi.io/mcp` with three provider-neutral tools:
+`capabilities_search`, `capabilities_inspect`, and `capabilities_run`. The
+bundled local MCP keeps focused workflow, upload, account, and task tools for
+host-native use; both surfaces discover model IDs dynamically.
 
 The repository packages the same canonical `beatapi-video` Skill, bundled MCP
 server, typed client, and locked OpenAPI contract for four agent surfaces:
@@ -82,13 +88,13 @@ grok plugin install .
 The recommended credential path is the operating-system credential manager:
 
 ```bash
-npm install --global beatapi@0.2.0
+npm install --global beatapi@0.3.0
 beatapi auth login
 export BEATAPI_CLI_PATH="$(command -v beatapi)"
 ```
 
-The reviewed npm integrity for `beatapi@0.2.0` is
-`sha512-7a7XF/tCc5u2p/ZnonSkLq1JF4OPpv3yaj7mFqnQcK9/HjOtj5hMny5bax4VcTbjgHRfDc1QlFXSbF3tzIL19Q==`.
+The reviewed npm integrity for `beatapi@0.3.0` is
+`sha512-zqWqP2CSYbbPLdy3qo8umEE4U4YiMgKrtt5pnOw14ErcaMUSTU5cmxvLw02Lkkn+7mS3w+pTvxuAHTFiqAafkA==`.
 
 Alternatively, export the key only in the shell that launches Grok Build:
 
@@ -126,6 +132,11 @@ Model IDs are discovered at runtime rather than hardcoded into the plugin:
 | Effects | Public list and detail endpoints | Versioned Effect task creation |
 | Workflows | Public `GET /v1/workflows` | Music Video, Ecommerce Video, Video Analysis, and Realtime tools |
 
+The provider-neutral capability catalog unifies those surfaces with Social
+Data. As verified on 2026-09-22, full pagination returned 60 Model
+capabilities, 1,000+ Data actions, and three Workflows. These are dated catalog
+observations, not plugin constants; always Search and Inspect again.
+
 The generic image and video tools accept a current model ID plus its
 model-specific `parameters`. New models can therefore appear in discovery
 without requiring a new plugin release. The bundled OpenAPI snapshot remains the
@@ -135,6 +146,8 @@ source for each model's supported fields and constraints.
 
 - discover text models, image/video model aliases, workflows, and published
   Effects;
+- search and inspect Model, Social Data, and Workflow contracts through the
+  Hosted MCP or official CLI when a provider-neutral catalog flow is needed;
 - create non-streaming text responses when the user explicitly requests
   BeatAPI text generation;
 - create image, video, Effect, Video Analysis, Music Video, and Ecommerce Video
@@ -147,8 +160,9 @@ source for each model's supported fields and constraints.
 - inspect USD balance, usage, and active concurrency;
 - inspect, update, and delete existing webhook endpoints.
 
-The MCP server exposes 26 focused tools. Paid mutations are labeled as such;
-read-only and destructive annotations are set independently.
+The bundled local MCP server exposes 26 focused tools. Paid mutations are
+labeled as such; read-only and destructive annotations are set independently.
+This is intentionally distinct from the Hosted MCP's three meta-tools.
 
 Realtime-session and webhook creation return one-time secrets. Those two create
 operations are intentionally not exposed to an agent until a host secret broker
@@ -220,6 +234,11 @@ Do not edit synchronized Skill or client files directly. Refresh them through
 4. **OpenAI Plugin Directory:** `npm run submission:build` creates the separate
    Skills-only review artifact. It does not claim a hosted HTTPS MCP server.
 
+For Muse and other remote-MCP hosts, connect to the Hosted MCP endpoint rather
+than installing this local plugin. A runnable Muse setup guide lives in the
+[`beatapi-examples`](https://github.com/BeatAPI/beatapi-examples/tree/main/integrations/muse)
+repository. Documentation does not imply an approved directory listing.
+
 See [submission/SUBMISSION.md](submission/SUBMISSION.md) for the separate public
 directory review boundary.