docs: sync CLI with capability catalog

Author: erickkkyt

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Changed
+
+- Synchronize the reviewed OpenAPI contract with current capability, Social
+  Data, onboarding, model, media, Effect, Workflow, and Realtime routes.
+- Reframe package documentation around the live Model/Data/Workflow catalog;
+  model and action IDs remain dynamically discovered rather than hardcoded.
+
+## [0.3.0] - 2026-09-13
+
 ### Added
 
 - Prepare 0.3.0: unified capabilities Search, Inspect, Run and status in the
@@ -57,7 +66,8 @@ and this project uses [Semantic Versioning](https://semver.org/).
 - Structured errors, request IDs, bounded retries, CI, package checks, and npm
   release automation.
 
-[Unreleased]: https://github.com/BeatAPI/beatapi-cli/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/BeatAPI/beatapi-cli/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/BeatAPI/beatapi-cli/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/BeatAPI/beatapi-cli/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/BeatAPI/beatapi-cli/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/BeatAPI/beatapi-cli/releases/tag/v0.1.0

README.md

@@ -1,12 +1,14 @@
 # BeatAPI CLI and TypeScript Client
 
-Unified Model/Data/Workflow commands are documented in
-[the capability guide](docs/capabilities.md). The 0.3.0 source adds Search,
-Inspect, Run and status while preserving existing commands. Check npm release
-availability and installed `--help` before using these new commands.
+Official command-line interface and TypeScript client for BeatAPI's Model,
+Data, and Workflow capabilities. Version 0.3.0 provides the unified Search,
+Inspect, Run, and status commands while preserving the existing media,
+workflow, task, webhook, and Realtime commands.
 
-Official command-line interface and TypeScript client for BeatAPI's public
-asynchronous workflows and Realtime Video API.
+The live catalog is intentionally not hardcoded into the packages. Discover
+current text, image, and video models plus 1,000+ Social Data actions at runtime,
+then inspect the selected contract before execution. See
+[the capability guide](docs/capabilities.md).
 
 The repository contains two independently publishable npm packages:
 
@@ -72,6 +74,12 @@ beatapi auth login
 beatapi auth status
 beatapi auth logout
 
+beatapi capabilities search --query image --kind model --limit 5
+beatapi capabilities search --query search --kind data --platform twitter --limit 5
+beatapi capabilities inspect REFERENCE
+beatapi capabilities run REFERENCE --file ./input.json --idempotency-key REQUEST_KEY
+beatapi capabilities status REFERENCE TASK --wait
+
 beatapi workflows list
 beatapi usage
 beatapi files upload ./input.mp3
@@ -143,9 +151,12 @@ try {
 }
 ```
 
-The client exposes every public contract operation: workflows, usage, file
-upload, music-video automatic and manual composition, ecommerce-video tasks,
-task polling, webhook CRUD, and Realtime session create/get/close.
+The client exposes typed methods for capability discovery and execution,
+workflows, usage, file upload, music-video automatic and manual composition,
+ecommerce-video tasks, task polling, webhook CRUD, and Realtime session
+create/get/close. Generated request and response types track the complete
+reviewed public OpenAPI contract, including newer onboarding and capability
+routes even when a convenience method is not provided.
 
 Create Realtime sessions only on a trusted server. The returned `client_secret`
 is short lived and may be handed to the browser SDK; never expose the long-lived

contract/beatapi.openapi.yaml

@@ -1,6 +1,6 @@
 {
   "source": "https://github.com/BeatAPI/beatapi-examples",
-  "ref": "83a139a123a3139cf53a362132b7b1d8a0066e1f",
+  "ref": "586c5f9227d87c763d7b647af593ec45284abbba",
   "openapiVersion": "1.0.0-launch",
-  "sha256": "bcd8dfb2124e7815ea52e513c99a2522e749316fc41f02a6f70957d3e3ebe293"
+  "sha256": "0dfcad26d8a7086576085dd721011222c3176fc657dfc5b23ce47f42340607ae"
 }

contract/contract.lock.json

@@ -1,8 +1,8 @@
 # Unified capabilities (0.3.0)
 
-These commands are implemented in this checkout. Publish both `beatapi-client`
-and `beatapi` before advertising them as available from npm. Check the installed
-`beatapi --version` and `beatapi --help`; 0.2.0 does not have these commands.
+These commands are available in the published `beatapi` 0.3.0 CLI and
+`beatapi-client` 0.3.0 package. Check `beatapi --version` and installed `--help`
+when diagnosing an older installation; 0.2.0 does not have these commands.
 
 ## Read-only setup and discovery
 
@@ -61,21 +61,19 @@ supported. CLI key storage does not configure an unrelated MCP host's credential
 
 This additive capability surface follows the gateway's public three-tool manifest
 at https://beatapi.io/capabilities-mcp-tools.json and observed REST envelopes.
-The existing generated OpenAPI snapshot remains unchanged. Public capability
-projections are typed separately and keep incomplete schema fields optional;
-they do not claim the gateway provides a complete input or output contract.
+The generated OpenAPI snapshot now includes capability, Social Data, and
+onboarding routes. Public capability projections keep incomplete schema fields
+optional; they do not claim every gateway entry provides a complete input or
+output contract.
 
 Verification: HTTP-boundary tests cover discovery, partial schema handling,
 same-key start retries, status routing, synchronous results and bounded polling.
 No paid end-to-end result is implied by those tests. Live smoke should first run
 Search/Inspect; a real paid example needs its own recorded result and authorization.
 
-### Recorded read-only live example
+### Current catalog behavior
 
-The built 0.3.0 binary was run against the production API with
-`capabilities search --query image --kind model --limit 1`. It returned
-`model:gpt-image-2` and cursor `1`. Inspect of that returned reference succeeded
-and preserved `validation.state: partial` plus `input_modes: [text, image]`,
-printing the missing-contract warning separately from JSON. This proves discovery
-and inspection, not image generation. The result ID is an observation, not a
-permanent default; search again when performing a user task.
+As verified on 2026-09-22, production Search returned 60 Model capabilities,
+1,000+ Data actions, and three Workflows when fully paginated. This is a dated
+observation, not a package constant or availability promise. Search again for
+every user task and choose only a current returned reference.

docs/capabilities.md

@@ -2,7 +2,7 @@
   "name": "beatapi-cli-workspace",
   "version": "0.3.0",
   "private": true,
-  "description": "Official TypeScript client and CLI for BeatAPI async and realtime AI video APIs.",
+  "description": "Official CLI and TypeScript client for BeatAPI models, Social Data, and workflows.",
   "type": "module",
   "workspaces": [
     "packages/*"

package.json

@@ -1,9 +1,10 @@
 # beatapi
 
 Official BeatAPI command-line interface for people, scripts, and AI agents.
+Discover current Model, Data, and Workflow capabilities instead of relying on
+a copied model list.
 
-The 0.3.0 source adds unified capability commands (check the installed `--help`
-and npm availability before use):
+Version 0.3.0 adds unified capability commands:
 
 ```sh
 beatapi capabilities search --query image --kind model --limit 5

packages/cli/README.md

@@ -1,7 +1,7 @@
 {
   "name": "beatapi",
   "version": "0.3.0",
-  "description": "Command-line interface for BeatAPI async and realtime AI video APIs.",
+  "description": "Command-line interface for BeatAPI models, Social Data, and workflows.",
   "type": "module",
   "bin": {
     "beatapi": "dist/bin.js"
@@ -41,6 +41,8 @@
   "keywords": [
     "beatapi",
     "cli",
+    "agent-toolkit",
+    "social-data",
     "ai-video",
     "music-video",
     "ecommerce-video",

packages/cli/package.json

@@ -1,7 +1,7 @@
 # beatapi-client
 
-Official TypeScript client for the public BeatAPI asynchronous and Realtime
-Video APIs.
+Official TypeScript client for BeatAPI Model, Data, Workflow, asynchronous
+media, and Realtime APIs.
 
 ```bash
 npm install beatapi-client

packages/client/README.md

@@ -1,7 +1,7 @@
 {
   "name": "beatapi-client",
   "version": "0.3.0",
-  "description": "Type-safe JavaScript and TypeScript client for BeatAPI async and realtime video APIs.",
+  "description": "Type-safe JavaScript and TypeScript client for BeatAPI models, data, and workflows.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,6 +39,8 @@
   "homepage": "https://docs.beatapi.io/",
   "keywords": [
     "beatapi",
+    "agent-toolkit",
+    "social-data",
     "ai-video",
     "music-video",
     "ecommerce-video",