docs: align README with Agent Router positioning

Author: erickkkyt

README.md

@@ -1,9 +1,26 @@
-# BeatAPI CLI and TypeScript Client
+<p align="center">
+  <img src="assets/readme/cover.svg" alt="BeatAPI CLI and TypeScript SDK — route Agent capabilities from terminal and code" width="100%" />
+</p>
 
-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.
+<p align="center">
+  <a href="https://beatapi.io/"><strong>Explore BeatAPI</strong></a> ·
+  <a href="https://beatapi.io/dashboard/apikeys">Create an API key</a> ·
+  <a href="https://docs.beatapi.io/">Docs</a> ·
+  <a href="#install-the-cli">Install</a> ·
+  <a href="#command-reference">Commands</a>
+</p>
+
+# BeatAPI CLI and TypeScript SDK
+
+BeatAPI is the **Agent Router for Everything**: one route to Model, Data, Tool,
+and Workspace capabilities. This repository provides the official terminal and
+TypeScript interfaces, including the unified Search, Inspect, Run, and status
+loop.
+
+```bash
+npm install --global beatapi
+beatapi capabilities search --query video --limit 5
+```
 
 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,
@@ -20,6 +37,15 @@ Both packages are generated and tested against the reviewed OpenAPI snapshot in
 [`contract/beatapi.openapi.yaml`](./contract/beatapi.openapi.yaml). The lock file
 records the exact source commit and SHA-256 digest.
 
+## Where this repository fits
+
+```text
+Terminal or TypeScript app -> BeatAPI CLI / SDK -> BeatAPI -> Model · Data · Tool · Workspace
+```
+
+The packages route only capabilities exposed by the current BeatAPI catalog and
+public contract. They do not hardcode future catalog promises.
+
 ## Install the CLI
 
 Node.js 20.19+ or 22.12+ is required.
@@ -218,3 +244,7 @@ Release steps and ownership prerequisites are documented in
 ## License
 
 MIT
+
+<p align="center">
+  Built by <a href="https://beatapi.io/"><strong>BeatAPI</strong></a> — Agent Router for Everything.
+</p>

assets/readme/cover.svg

@@ -2,7 +2,7 @@
   "name": "beatapi-cli-workspace",
   "version": "0.3.0",
   "private": true,
-  "description": "Official CLI and TypeScript client for BeatAPI models, Social Data, and workflows.",
+  "description": "Official CLI and TypeScript SDK for BeatAPI, the Agent Router for Everything.",
   "type": "module",
   "workspaces": [
     "packages/*"

package.json

@@ -1,7 +1,7 @@
 {
   "name": "beatapi",
   "version": "0.3.0",
-  "description": "Command-line interface for BeatAPI models, Social Data, and workflows.",
+  "description": "Command-line interface for routing BeatAPI Model, Data, Tool, and Workspace capabilities.",
   "type": "module",
   "bin": {
     "beatapi": "dist/bin.js"

packages/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beatapi-client",
   "version": "0.3.0",
-  "description": "Type-safe JavaScript and TypeScript client for BeatAPI models, data, and workflows.",
+  "description": "Type-safe JavaScript and TypeScript SDK for BeatAPI capability routing.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",