Refine public documentation

docs/actions-and-polling.md

@@ -43,6 +43,3 @@ if (action.Status == BinaryLaneValues.ActionStatus.Completed)
     // Continue with the next step.
 }
 ```
-
-If an action request has an uncertain outcome, retrieve the action or server
-state before submitting it again.

docs/api-coverage.md

@@ -10,8 +10,8 @@ version change.
 
 The raw document contains virtual paths such as
 `/v2/servers/{server_id}/actions#PowerOn`. These are API-reference aliases for
-action payload variants, not real HTTP routes. Coverage and generated-code
-checks must use the normalized contract and count only the real
+action payload variants, not real HTTP routes. Coverage checks and route
+reviews use the normalized contract and count only the real
 `POST /v2/servers/{server_id}/actions` route.
 
 | API area | Public resource boundary |

docs/configuration.md

@@ -3,24 +3,25 @@
 ## Standard registration
 
 In an ASP.NET Core or generic-host application, `AddBinaryLaneApi` configures
-`IBinaryLaneClient` and the individual resource interfaces.
+`IBinaryLaneClient`, individual resource interfaces, and the underlying typed
+`HttpClient`.
 
 ```csharp
 builder.Services.AddBinaryLaneApi(options =>
 {
     options.ApiToken = builder.Configuration["BinaryLane:ApiToken"];
-    options.RequestTimeoutSeconds = 100;
 });
 ```
 
 | Setting | Default | Description |
 | --- | --- | --- |
-| `BaseUrl` | `https://api.binarylane.com.au/` | API base address. Leave unchanged for BinaryLane's public API. |
+| `BaseUrl` | `https://api.binarylane.com.au/` | Root URI used for API requests. |
 | `ApiToken` | none | Bearer token used by the default provider. |
 | `RequestTimeoutSeconds` | `100` | Timeout for an individual HTTP request. |
 
-The base URL must be an HTTPS URL without credentials, a query string, or a
-fragment. Options are validated when the application starts.
+`BaseUrl` must be an HTTPS URL without credentials, a query string, or a
+fragment. `BaseUrl` and `RequestTimeoutSeconds` are validated when the host
+starts; request timeouts can range from 1 to 300 seconds.
 
 ## Rotating tokens
 
@@ -36,7 +37,7 @@ builder.Services.AddSingleton<IBinaryLaneTokenProvider, VaultTokenProvider>();
 builder.Services.AddBinaryLaneApi(options => options.RequestTimeoutSeconds = 100);
 ```
 
-The provider is called for every request. Do not log the returned token.
+The provider is called for every outgoing request.
 
 ## Use without dependency injection
 
@@ -63,10 +64,10 @@ var client = new BinaryLaneClient(
 telemetry, or other application-specific handlers.
 
 ```csharp
-builder.Services.AddBinaryLaneApi(options => options.ApiToken = token)
+builder.Services.AddBinaryLaneApi(options =>
+    options.ApiToken = builder.Configuration["BinaryLane:ApiToken"])
     .ConfigureHttpClient(client => client.DefaultRequestHeaders.Add("X-App", "my-service"));
 ```
 
-Only add automatic retries when the request is safe to repeat. In particular,
-POST, PUT, PATCH, and DELETE requests may have already been applied when a
-network failure is reported.
+The client does not apply retries itself. Applications can add their own
+handlers through the returned `IHttpClientBuilder`.

docs/errors.md

@@ -1,13 +1,15 @@
 # Error handling
 
-All API failures derive from `BinaryLaneApiException`.
+`BinaryLaneApiException` represents a non-success response from the BinaryLane
+API. Network, timeout, cancellation, and client-configuration failures use
+their standard .NET exception types.
 
 | Exception | When it is used |
 | --- | --- |
-| `BinaryLaneUnauthorizedException` | The token is missing, invalid, or expired. |
-| `BinaryLaneForbiddenException` | The token does not have access to the resource. |
-| `BinaryLaneNotFoundException` | The requested resource does not exist or is not visible to the token. |
-| `BinaryLaneValidationException` | BinaryLane rejected the request payload. |
+| `BinaryLaneUnauthorizedException` | BinaryLane returned HTTP 401. |
+| `BinaryLaneForbiddenException` | BinaryLane returned HTTP 403. |
+| `BinaryLaneNotFoundException` | BinaryLane returned HTTP 404. |
+| `BinaryLaneValidationException` | BinaryLane returned HTTP 400 or 422. |
 | `BinaryLaneApiException` | Any other non-success HTTP response. |
 
 ```csharp
@@ -32,9 +34,9 @@ catch (BinaryLaneApiException exception)
 ```
 
 Each exception provides `StatusCode`, `RequestUri`, `Headers`, and, when
-available, `Problem` and `ResponseBody`. Provider detail text can contain user
-data. Do not write `Problem`, `Headers`, or `ResponseBody` to application logs
-without appropriate redaction.
+available, `Problem` and `ResponseBody`. `ResponseBody` contains at most the
+first 32,768 characters of diagnostic text, followed by an ellipsis when
+truncated.
 
-Successful JSON responses are limited to 16 MiB. A larger response throws
+Successful response bodies are limited to 16 MiB. A larger response throws
 `HttpRequestException` before the client buffers it in memory.

docs/getting-started.md

@@ -9,25 +9,24 @@
 dotnet add package BinaryLane.Api --prerelease
 ```
 
-## 2. Store the token safely
+## 2. Configure the API token
 
-For local development, initialise user secrets for your application and add
-the token:
+For local development, .NET user secrets can provide the
+`BinaryLane:ApiToken` configuration value:
 
 ```bash
 dotnet user-secrets init
 dotnet user-secrets set "BinaryLane:ApiToken" "your-token"
 ```
 
-For hosted applications, use the platform's secret store or supply
-`BINARYLANE_API_TOKEN` at runtime.
+The registration below reads that value first, then falls back to
+`BINARYLANE_API_TOKEN`.
 
 ## 3. Register the client
 
 ```csharp
 using BinaryLane.Api.V2;
 using BinaryLane.Api.V2.DependencyInjection;
-using BinaryLane.Api.V2.Models;
 
 builder.Services.AddBinaryLaneApi(options =>
 {
@@ -42,6 +41,9 @@ builder.Services.AddBinaryLaneApi(options =>
 Inject `IBinaryLaneClient`, then select the resource you need:
 
 ```csharp
+using BinaryLane.Api.V2;
+using BinaryLane.Api.V2.Models;
+
 public sealed class ServerReader(IBinaryLaneClient binaryLane)
 {
     public IAsyncEnumerable<Server> ListAsync(CancellationToken cancellationToken) =>

docs/pagination.md

@@ -27,5 +27,4 @@ await foreach (var server in client.Servers.ListAllAsync(cancellationToken: canc
 }
 ```
 
-Pass a cancellation token from the calling request, worker, or command so a
-stopped operation does not continue fetching pages.
+The cancellation token is carried across page requests made by `ListAllAsync`.

docs/releasing.md

@@ -57,7 +57,8 @@ section for release notes.
 
 ## Recovery
 
-NuGet packages cannot be overwritten. If a release has a packaging defect,
-unlist it if appropriate, publish a new version, and document the correction
-in the changelog. Do not retag a version or attempt to reuse a published
-package version.
+NuGet packages cannot be overwritten. If a published release has a packaging
+defect, unlist it if appropriate, publish a new version, and document the
+correction in the changelog. A tag can be replaced only before the workflow
+publishes its matching NuGet version; published package versions are never
+reused.

docs/upstream-contract.md

@@ -28,8 +28,7 @@ snapshot makes those changes visible during SDK maintenance.
 The raw document includes virtual `#ActionName` paths for individual server
 action variants. They exist to improve the provider's reference UI but are not
 HTTP paths. `eng/normalize-openapi.sh` strips them when producing a normalized
-document for code generation or coverage checks. Do not issue requests to
-those virtual paths.
+document for route and coverage validation.
 
 ## Monitoring and updating