From 9e9293d60be6759c179f6dd1dafd9ee17aaa88d5 Mon Sep 17 00:00:00 2001
From: Keysat <licensing@keysat.xyz>
Date: Wed, 17 Jun 2026 15:41:21 -0500
Subject: [PATCH] Document tier picker, seat management, and policy_slug
 purchase option

---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index e72c0d3..55f7be2 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,35 @@ license_key = client.wait_for_license(session.invoice_id)
 # Save license_key wherever you decided to store keys (config dir, keychain, env).
 ```
 
+To buy a specific tier, set `StartPurchaseOptions(policy_slug=...)` to a
+slug from `list_public_policies` (below); omit it to use the product's
+default policy.
+
+## Tier picker (public policies)
+
+List the buyer-visible tiers for a product — same data the server's
+`/buy/<slug>` page reads, so an in-app picker stays in sync with the
+operator's admin setup. No auth required.
+
+```python
+tiers = client.list_public_policies("my-product")
+for p in tiers.policies:
+    print(p.slug, p.name, p.price_sats, "sats", p.max_machines, "seats")
+# tiers.product.entitlements_catalog maps entitlement slugs -> human labels.
+```
+
+## Machine seat management
+
+For seat-limited licenses (`max_machines > 1`), claim and release seats by
+fingerprint. Each returns a `MachineResponse` (`ok`, `reason`,
+`active_count`, `max_machines`).
+
+```python
+client.activate(key, fingerprint, hostname="bob-laptop", platform="macos")
+client.heartbeat(key, fingerprint)   # call periodically to keep the seat live
+client.deactivate(key, fingerprint)  # release the seat
+```
+
 ## Free-license code redemption
 
 For codes the seller created with kind `free_license` (no payment):