docs(integrations): add Mastra and Pi examples

Author: erickkkyt

README.md

@@ -165,6 +165,12 @@ published launch checks are complete.
 
 ## Examples
 
+Framework integrations: [Mastra](integrations/mastra/README.md) has a runnable
+agent using an account-selected text model; [Pi](integrations/pi/README.md)
+has a user-managed OpenAI Responses provider configuration.
+The separately maintained [Pi BeatAPI Provider](https://github.com/BeatAPI/pi-beatapi-provider)
+offers a GitHub-installable extension with a scoped three-model catalog.
+
 | Example | cURL | Node.js | Python |
 | --- | --- | --- | --- |
 | Search and inspect capabilities | [`capabilities.sh`](examples/curl/capabilities.sh) | [`capabilities.mjs`](examples/node/capabilities.mjs) | [`capabilities.py`](examples/python/capabilities.py) |

integrations/mastra/README.md

@@ -0,0 +1,29 @@
+# BeatAPI with Mastra
+
+This example gives a Mastra agent one BeatAPI text model through the
+OpenAI-compatible Chat Completions route. It uses an explicit AI SDK provider;
+it does not add BeatAPI to Mastra's built-in model router or list every BeatAPI
+capability in Mastra Studio.
+
+## Run
+
+Requires Node.js 22.13 or later.
+
+```bash
+cd integrations/mastra
+npm ci
+export BEATAPI_API_KEY="<your private BeatAPI key>"
+curl https://api.beatapi.io/v1/models \
+  -H "Authorization: Bearer $BEATAPI_API_KEY"
+export BEATAPI_MODEL="<an enabled text model ID from the response>"
+npm start -- "Summarize what an industrial agent should check before acting."
+```
+
+The API key remains in the local process. Mastra sends the prompt to BeatAPI's
+`POST /v1/chat/completions`; this can consume BeatAPI credits. For reasoning,
+tools, and other model-specific features, verify the exact model and request
+contract before relying on them in an agent workflow.
+
+`npm run check` verifies the TypeScript integration. A successful type check is
+not proof of a live model call; run the example with your own account-enabled
+model to verify that path.