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"