docs: clarify API access and SDK docs

README.md

@@ -2,6 +2,36 @@
 
 Official SDKs for the Socialhose Public API.
 
+Socialhose is a social-listening and media-monitoring API for turning large streams of public mentions into usable campaign intelligence. It helps applications answer questions like:
+
+- What are people saying about a campaign, brand, organization, product, policy, person, or event?
+- Which platforms are driving the conversation?
+- Is sentiment improving or deteriorating?
+- Which mentions have the most reach or engagement?
+- Which keywords, topics, or entities are trending?
+- Who should receive alerts or mailing-list updates?
+
+## What you can build
+
+Use Socialhose SDKs to build:
+
+- Social-listening dashboards for campaigns, topics, brands, people, organizations, or locations.
+- Monitoring tools that search public mentions across supported platforms.
+- Analytics views showing volume, reach, engagement, sentiment, platform mix, and growth.
+- Trend and keyword reports.
+- High-impact mention feeds ordered by recency or engagement.
+- Entity pages that summarize one term/person/company/topic using mention-search facets.
+- Alerting and mailing-list workflows backed by Socialhose mailing lists.
+- Batch jobs, CLI scripts, or serverless functions that pull Socialhose data into another system.
+
+## API access
+
+API access is available with paid Socialhose subscriptions. See [Socialhose pricing](https://socialhose.net/pricing) for current plans, or use a publicly provided API key if Socialhose offers one from time to time.
+
+API keys are provisioned by Socialhose or your account administrator. The SDKs consume existing keys; they do not create, rotate, or manage keys.
+
+Keep API keys server-side. Do not commit keys, expose them in frontend bundles, or send them to browsers. For browser applications, call Socialhose from your own backend and return only the data your frontend needs.
+
 ## SDKs
 
 - `sdks/javascript` — npm package `@socialhose/api`
@@ -10,7 +40,7 @@ Future SDKs can live beside it, e.g. `sdks/python`, `sdks/go`, or `sdks/php`.
 
 ## JavaScript / TypeScript
 
-API keys are provisioned by Socialhose or your account administrator. Set the key server-side before using the SDK:
+Set the key server-side before using the SDK:
 
 ```bash
 export SOCIALHOSE_API_KEY="sh_your_key_here"

sdks/javascript/README.md

@@ -2,47 +2,24 @@
 
 Official TypeScript SDK for the Socialhose Public API.
 
-Socialhose is a social-listening and media-monitoring API for turning large streams of public mentions into usable campaign intelligence. It helps backend applications answer questions like:
-
-- What are people saying about a campaign, brand, organization, product, policy, person, or event?
-- Which platforms are driving the conversation?
-- Is sentiment improving or deteriorating?
-- Which mentions have the most reach or engagement?
-- Which keywords, topics, or entities are trending?
-- Who should receive alerts or mailing-list updates?
-
 The SDK wraps the Socialhose REST API with typed JavaScript/TypeScript methods for campaign discovery, analytics dashboards, mention search, mailing lists, and SDK-composed entity analytics. It handles API-key auth, browser-compatible headers, retries, timeouts, GET caching, and normalized response shapes so product code can focus on the analysis instead of raw HTTP plumbing.
 
-## What you can build with it
-
-Use `@socialhose/api` from server-side JavaScript/TypeScript to build:
-
-- Social-listening dashboards for campaigns, topics, brands, people, organizations, or locations.
-- Monitoring tools that search public mentions across supported platforms.
-- Analytics views showing volume, reach, engagement, sentiment, platform mix, and growth.
-- Trend and keyword reports.
-- High-impact mention feeds ordered by recency or engagement.
-- Entity pages that summarize one term/person/company/topic using mention-search facets.
-- Alerting and mailing-list workflows backed by Socialhose mailing lists.
-- Batch jobs, CLI scripts, or serverless functions that pull Socialhose data into another system.
-
 This package is intended for **backend code only**. Do not ship your Socialhose API key to browsers.
 
 ## Getting an API key
 
-API keys are issued by Socialhose. The SDK does not create keys, and there is no self-service key-generation flow documented in this package.
+See the repository [API access notes](../../README.md#api-access) for subscription and key-provisioning details. This package consumes an existing key; it does not create keys, and there is no self-service key-generation flow documented here.
 
 To use the SDK:
 
-1. Request Socialhose Public API access from the Socialhose team or your account administrator.
+1. Get a Socialhose API key with access to the campaigns you need to query.
-2. Ask for an API key with access to the campaigns you need to query.
+2. Store it as a server-side environment variable:
-3. Store it as a server-side environment variable:
 
 ```bash
 export SOCIALHOSE_API_KEY="sh_your_key_here"
 ```
 
-4. Pass it to the client:
+3. Pass it to the client:
 
 ```ts
 const socialhose = new SocialhoseClient({

sdks/javascript/docs/API.md

@@ -66,7 +66,7 @@ Type exports:
 
 ## Authentication
 
-Socialhose API keys are provisioned by Socialhose or by your account administrator. This SDK consumes an existing key; it does not create or manage keys.
+See the repository [API access notes](../../../README.md#api-access) for subscription and key-provisioning details. This SDK consumes an existing key; it does not create or manage keys.
 
 Every request sends:
 

sdks/javascript/docs/GUIDE.md

@@ -22,9 +22,9 @@ Requires Node 18+ or a custom `fetch` implementation.
 
 ## Getting API access
 
-Socialhose API keys are provisioned by Socialhose. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you.
+See the repository [API access notes](../../../README.md#api-access) for subscription and key-provisioning details. This SDK only consumes an existing key; it cannot create, rotate, or discover keys for you.
 
-Ask the Socialhose team or your account administrator for a Public API key and confirm which campaigns it can access. Then set it in your server environment:
+Use your provided Public API key and confirm which campaigns it can access. Then set it in your server environment:
 
 ```bash
 export SOCIALHOSE_API_KEY="sh_your_key_here"