docs(api): order client pages for first-time readers

docs/api/async.md

@@ -1,7 +1,8 @@
 # SwgohComlinkAsync API
 
-`SwgohComlinkAsync` provides the same API as `SwgohComlink` with `async`/`await` support.
-All public methods have identical signatures — just add `await` to each call.
+`SwgohComlinkAsync` provides the same API as [`SwgohComlink`](comlink.md) with
+`async`/`await` support. All public methods have identical signatures — just
+add `await` to each call.
 
 ## Quick Start
 
@@ -23,6 +24,23 @@ finally:
     await comlink.aclose()
 ```
 
+## Connecting to Comlink
+
+`SwgohComlinkAsync` takes the same constructor arguments as the synchronous
+client: `url` or `host`/`port` to choose the service, and `access_key`/
+`secret_key` (or the `ACCESS_KEY`/`SECRET_KEY` environment variables) for HMAC
+signing. See [Connecting to Comlink](comlink.md#connecting-to-comlink).
+
+```python
+async with SwgohComlinkAsync(host="192.168.1.10", port=3000) as comlink:
+    ...
+```
+
+## Handling Errors
+
+Failed calls raise the same [typed HTTP errors](exceptions.md#http-errors) as
+the synchronous client.
+
 ## Retries and Pacing
 
 The `retry` argument takes the same [`RetryPolicy`](comlink.md#retries-and-pacing)
@@ -41,16 +59,13 @@ async with SwgohComlinkAsync(retry=RetryPolicy(min_interval=0.4)) as comlink:
     players = await asyncio.gather(*(comlink.get_player(allycode=code) for code in allycodes))
 ```
 
-Failed calls raise the same [typed HTTP errors](exceptions.md#http-errors) as
-the synchronous client.
-
-## Async Stat Calculation
+## Stat Calculation
 
 For local stat calculation in async code, use `StatCalcAsync` which fetches
 game data without blocking the event loop:
 
 ```python
-from swgoh_comlink import SwgohComlinkAsync, StatCalcAsync
+from swgoh_comlink import StatCalcAsync, SwgohComlinkAsync
 
 async with SwgohComlinkAsync() as comlink:
     calc = await StatCalcAsync.create()

docs/api/comlink.md

@@ -1,5 +1,57 @@
 # SwgohComlink API
 
+`SwgohComlink` is the synchronous client for a running `swgoh-comlink` service.
+Each method sends one request and returns the decoded JSON response. For
+`async`/`await` code, use [`SwgohComlinkAsync`](async.md), which has the same
+methods and constructor arguments.
+
+## Quick Start
+
+```python
+from swgoh_comlink import SwgohComlink
+
+with SwgohComlink() as comlink:
+    player = comlink.get_player(allycode=245866537)
+    guild = comlink.get_guild(guild_id=player["guildId"])
+```
+
+Without a context manager, call `close()` when done:
+
+```python
+comlink = SwgohComlink()
+try:
+    player = comlink.get_player(allycode=245866537)
+finally:
+    comlink.close()
+```
+
+## Connecting to Comlink
+
+The client connects to `http://localhost:3000` by default. Point it at another
+service with either a full `url`, or a `host` and `port`:
+
+```python
+comlink = SwgohComlink(url="http://comlink.example.com:3000")
+comlink = SwgohComlink(host="192.168.1.10", port=3000)
+```
+
+When `host` is given, `url` and `stats_url` are ignored.
+
+If your comlink service requires HMAC signing, pass `access_key` and
+`secret_key`. When they are not passed, the client reads them from the
+`ACCESS_KEY` and `SECRET_KEY` environment variables. Signing is turned on only
+when both keys are set.
+
+See the [API Reference](#swgoh_comlink.swgoh_comlink.SwgohComlink) below for
+every constructor argument.
+
+## Handling Errors
+
+When comlink answers with an HTTP error status, the client raises a
+[typed HTTP error](exceptions.md#http-errors), such as
+`SwgohComlinkRateLimitError` for a rate refusal or `SwgohComlinkClientError`
+for a rejected request. All of them subclass `SwgohComlinkException`.
+
 ## Retries and Pacing
 
 By default a client makes exactly one attempt per call and raises the
@@ -31,17 +83,35 @@ so 0.4 seconds keeps a burst well under that limit.
 from swgoh_comlink import RetryPolicy, SwgohComlink
 
 comlink = SwgohComlink(retry=RetryPolicy(attempts=3, min_interval=0.4))
-player = comlink.get_player(allycode=123456789)
+player = comlink.get_player(allycode=245866537)
 ```
 
-`SwgohComlinkAsync` accepts the same argument.
+`SwgohComlinkAsync` accepts the same argument; see
+[its retries section](async.md#retries-and-pacing) for how waits behave with
+concurrent tasks.
 
 ::: swgoh_comlink.retry.RetryPolicy
     options:
       show_root_heading: true
       show_root_full_path: false
       show_if_no_docstring: false
 
+## Stat Calculation
+
+To add stats and Galactic Power to the units in a player profile, pass the
+roster to `StatCalc`, which runs the calculation locally:
+
+```python
+from swgoh_comlink import StatCalc, SwgohComlink
+
+with SwgohComlink() as comlink:
+    calc = StatCalc()
+    player = comlink.get_player(allycode=245866537)
+    calc.calc_roster_stats(player["rosterUnit"])
+```
+
+See the [StatCalc API](statcalc.md) for full details.
+
 ## API Reference
 
 ::: swgoh_comlink.swgoh_comlink.SwgohComlink