diff --git a/README.md b/README.md
index 1966ab2..7c9d438 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,22 @@
 # private-packagist/oidc-identities
 
-GitHub Action to publish artifacts as package versions to Private Packagist.
+A PHP library that obtains [OpenID Connect (OIDC)](https://openid.net/connect/)
+ID tokens from the CI/CD platform it is running on.
+
+Modern CI/CD platforms can issue short-lived, signed OIDC tokens that prove the
+identity of the running workflow (which repository, which workflow, which branch,
+etc.). These tokens can be exchanged for credentials with a service that trusts the
+platform's OIDC provider — removing the need to store long-lived secrets in your CI
+configuration. This library handles the platform-specific work of detecting the
+environment and requesting such a token, then hands you back the parsed result.
 
 ## Requirements
 
-PHP >= 7.2
+PHP >= 7.2.5
+
+The library relies on [HTTPlug](https://httplug.io/) / PSR-18 discovery, so you also
+need a PSR-18 HTTP client and PSR-17 factories available in your project (for example
+`symfony/http-client` and `nyholm/psr7`).
 
 ## Install
 
@@ -13,12 +25,46 @@ Via Composer:
 $ composer require private-packagist/oidc-identities
 ```
 
+## Supported platforms
+
+| Platform       | Detected via             |
+|----------------|--------------------------|
+| GitHub Actions | `GITHUB_ACTIONS` env var |
+
+The `TokenGenerator` tries each supported platform in turn and uses the first one
+that reports it is the current environment. When none of them match — for example
+when running locally — `generate()` returns `null`.
+
+## What is the `TokenGenerator`?
+
+`TokenGenerator` is the main entry point of the library. You give it an `$audience`
+(the identifier of the service that will consume the token, e.g. Private Packagist),
+and it:
+
+1. Detects which supported platform the code is currently running on.
+2. Performs the platform-specific request to mint an OIDC ID token for that audience.
+3. Returns a `Token` value object containing the raw JWT together with its decoded
+   `header`, `payload` and `signature` parts.
+
+You would use it whenever your code runs inside a CI/CD pipeline and needs to prove
+its identity to an external service via OIDC, instead of relying on a stored secret.
+Because it abstracts away the per-platform details, the same call works on any
+supported platform without branching in your own code.
+
 ## Usage
 
 Initiate a `TokenGenerator` instance and call the `generate` method with `$audience`.
-The `TokenGenerator` will automatically try all supported platforms.
+The `TokenGenerator` will automatically try all supported platforms and return a
+`Token` for the first matching one, or `null` if the current environment is not
+supported.
 
 ```php
+use Http\Client\Common\HttpMethodsClient;
+use Http\Discovery\Psr17FactoryDiscovery;
+use Http\Discovery\Psr18ClientDiscovery;
+use PrivatePackagist\OIDC\Identities\TokenGenerator;
+use Psr\Log\NullLogger;
+
 // Configure a HttpMethodsClient instance
 $oidcHttpClient = new HttpMethodsClient(
     Psr18ClientDiscovery::find(),
@@ -28,8 +74,21 @@ $oidcHttpClient = new HttpMethodsClient(
 
 $tokenGenerator = new TokenGenerator(new NullLogger(), $oidcHttpClient);
 $token = $tokenGenerator->generate($audience);
+
+if ($token === null) {
+    // Not running on a supported platform, or no OIDC token available.
+    return;
+}
+
+// $token->token     — the raw JWT string
+// $token->header    — decoded header
+// $token->payload   — decoded payload
+// $token->signature — the signature part
 ```
 
+The constructor also accepts any PSR-3 `LoggerInterface`; pass a real logger instead
+of `NullLogger` to get debug output about platform detection and the token request.
+
 ## Copyright and License
 
-The  GitHub Action is licensed under the MIT License.
+The library is licensed under the MIT License.