docs: add ParkSmarter API usage guide + endpoint reference

- docs/PARKSMARTER_API.md: narrative guides (bootstrap/auth, finding parking,
  estimates, initiating a transaction, sessions/receipts, account) + per-endpoint
  reference + a behaviors/gotchas table (200-on-error, stale-token empty body,
  multi-estimate fallback, free windows, flat-rate zones, no free check-in).
- client README: link the guide; promote PastSession/ParkingReceipt to CONFIRMED
  (ActiveSession still pending — no active session at capture time).
- Main README: mark "Start a paid session" as working (confirmed live end-to-end).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

parksmarter-client/README.md

@@ -12,6 +12,11 @@ Node 18+. It has **zero runtime dependencies** (uses `fetch`). If you specifical
 want a native-Kotlin client instead, the `environments.ts` + endpoint table below map
 directly onto Retrofit/OkHttp — ask and it can be ported.
 
+> **Usage guide:** for narrative walk-throughs (searching, quoting a price, running a
+> transaction) plus per-endpoint commentary and the behavioral quirks, see
+> **[`docs/PARKSMARTER_API.md`](../docs/PARKSMARTER_API.md)**. The tables below are the
+> quick reference.
+
 ## Install / build
 
 ```bash
@@ -170,19 +175,26 @@ Request shapes were recovered from the app code and are exact. Response models w
 - **CONFIRMED via live capture:** login (`AuthResponse`), `UserDetail`, `VehicleDetail`,
   `CreditCardDetail`, `Zone`/`Space`/`SpacePolicy`, `ParkingLot`/`ParkingLotDetail`, all
   three estimate responses (`ParkingDetail` price ladder), notification-settings envelope,
-  states wrapper, the password-reset flow, and the shared `Response` envelope.
-- **UNCONFIRMED (no session history on the test account):** `ActiveSession`,
-  `PastSession`, `ParkingReceipt`. Field names are from static analysis; capture from an
-  account with at least one past/active session to confirm.
+  states wrapper, the password-reset flow, the shared `Response` envelope, and — from a real
+  DL-zone session — `PastSession` and `ParkingReceipt`.
+- **UNCONFIRMED:** `ActiveSession` (no *active* session existed on the account at capture
+  time — field names are from static analysis; capture while parked to confirm).
+- `capture-dl.mjs` records a full DL-zone request/response set; `sweep.mjs` refreshes the
+  PII-free schema skeletons.
 
-Two behaviors worth knowing (both confirmed live):
+Behaviors worth knowing (all confirmed live — full list in
+[`docs/PARKSMARTER_API.md`](../docs/PARKSMARTER_API.md)):
 
-1. **Meter search requires auth.** `/api/Meter` and `/api/MeterList` return **401** without a
-   valid `Auth_Token`, despite being data lookups.
-2. **`Response` envelope + token refresh.** Most authenticated responses embed
-   `Response: { Auth_Token, Message, Status }`. When `Response.Auth_Token` (or a top-level
-   `Auth_Token`) is non-empty, it's a rolling refresh of your user token — the client stores
-   it automatically.
+1. **200-on-error.** Failed login, declined payment, and some bad requests return **HTTP
+   200** with `Response.Status: "Error"`. Check the envelope, not just the status code.
+2. **Meter/estimate search requires auth.** `/api/Meter`, `/api/MeterList`, and estimates
+   **401** without a valid `Auth_Token`, despite being data lookups.
+3. **Rolling token refresh.** A non-empty `Response.Auth_Token` (or top-level) replaces your
+   user token — the client stores it automatically.
+4. **Stale token ≠ 401.** An expired token makes `GET /api/User` return an **empty body**
+   (not a 401); validate by requiring real user fields before trusting the session.
+5. **Estimate quirks.** Multi is unsupported on some zones (falls back to single);
+   `MaxTime: 0`/`$0.00` means a free window; some zones are flat-rate.
 
 To capture the remaining UNCONFIRMED models, re-run `sweep.mjs` on an account that has a
 saved card and session history. There's **no TLS pinning**, so a proxy capture on a rooted