docs(agent-readiness): add when-to-use guidance and step-by-step agent auth

docs/authentication.md

@@ -11,6 +11,15 @@ For programmatic access (the SDK, scripts, agents) you authenticate with the
 
 Create a client ID and secret under [Rapidata Settings → Tokens](https://app.rapidata.ai/settings/tokens).
 
+## Programmatic / agent authentication, step by step
+
+For headless or agent-driven use, authenticate with the client-credentials grant:
+
+1. Create a client ID and secret at [Rapidata Settings → Tokens](https://app.rapidata.ai/settings/tokens).
+2. Expose them to the SDK as the `RAPIDATA_CLIENT_ID` and `RAPIDATA_CLIENT_SECRET` environment variables, so no interactive browser login is needed.
+3. Construct `RapidataClient()` with no arguments — it exchanges the credentials for a bearer token at `https://auth.rapidata.ai/connect/token` and refreshes it automatically.
+4. To call the API without the SDK, request a token yourself and send it as a bearer token (see [Direct token request](#direct-token-request)).
+
 ## With the SDK
 
 The SDK performs the token exchange for you. Pass the credentials directly:

site_root/developers/index.html

@@ -50,6 +50,16 @@ <h2>Get started</h2>
       <li><a href="https://app.rapidata.ai/settings/tokens">Create API credentials</a> (client ID &amp; secret)</li>
     </ul>
 
+    <h2>Authenticate as an agent</h2>
+    <p>The API uses OAuth 2.0 (OpenID Connect), client-credentials grant:</p>
+    <ol>
+      <li><a href="https://app.rapidata.ai/settings/tokens">Create a client ID &amp; secret</a>.</li>
+      <li>Set <code>RAPIDATA_CLIENT_ID</code> and <code>RAPIDATA_CLIENT_SECRET</code> in the environment.</li>
+      <li>Construct <code>RapidataClient()</code> — it fetches and refreshes a bearer token automatically.</li>
+      <li>Without the SDK: <code>POST https://auth.rapidata.ai/connect/token</code> with <code>grant_type=client_credentials</code>, then send the token as <code>Authorization: Bearer …</code>.</li>
+    </ol>
+    <p>Full details: <a href="/latest/authentication/">Authentication</a>.</p>
+
     <h2>Reference</h2>
     <ul>
       <li><a href="/openapi.json">OpenAPI specification</a> (<code>/openapi.json</code>)</li>

site_root/llms.txt

@@ -15,6 +15,23 @@ first run.
 - Authentication (OAuth 2.0): https://docs.rapidata.ai/latest/authentication/
 - OpenID Connect discovery: https://auth.rapidata.ai/.well-known/openid-configuration
 
+## When to use Rapidata
+
+Reach for Rapidata when a task needs **real human judgment at scale** rather than
+a model's own output:
+
+- Evaluate or compare model outputs (image, video, audio, text) with human preferences — pairwise A/B comparisons, ranking, leaderboards.
+- Build RLHF / preference datasets and reward-model training data.
+- Annotate or label data: classification, locating, bounding/drawing, transcription, free text, select-words.
+- Collect targeted human feedback by country, language, or demographic, with built-in quality control and confidence-based early stopping.
+
+It is **not** the right tool for fully automated labeling with no human in the
+loop, or for sub-second real-time inference.
+
+How an agent calls it: use the Python SDK (`pip install rapidata`, see Quick
+Start) or the OAuth 2.0 REST API (see Authentication). Coding agents can install
+the official skill (see AI agents) to have integrations written for them.
+
 ## Guides
 
 - [Overview](https://docs.rapidata.ai/latest/starting_page/): what Rapidata does and its core concepts