docs: refresh README, FAQ, package metadata, and repo social preview

README.md

@@ -1,10 +1,19 @@
-# SeatLayer Java SDK
+# SeatLayer Java Server SDK for Reserved Seating
 
 [![CI](https://github.com/seatlayer/seatlayer-java/actions/workflows/ci.yml/badge.svg)](https://github.com/seatlayer/seatlayer-java/actions/workflows/ci.yml)
 [![Maven Central](https://img.shields.io/maven-central/v/io.seatlayer/seatlayer-java.svg)](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java)
 [![License: MIT](https://img.shields.io/badge/license-MIT-111827.svg)](LICENSE)
 
-Official Java server SDK for the [SeatLayer](https://seatlayer.io) reserved-seating API.
+The official SeatLayer Java server SDK is the **trusted side** of a reserved-seating
+integration: inspect the holds a buyer created, price from server data, and book with a
+stable `bookingRef`. From Java or Kotlin you manage seating charts, events, sales channels,
+and live seat inventory through one typed ticketing API client.
+
+[SeatLayer artifact on Maven Central](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) ·
+[SeatLayer server SDK documentation](https://docs.seatlayer.io/server-sdk/install/) ·
+[SeatLayer reserved-seating platform](https://seatlayer.io/) ·
+[SeatLayer JavaScript seat map SDK](https://www.npmjs.com/package/@seatlayer/js) ·
+[SeatLayer AI Toolkit](https://github.com/seatlayer/seatlayer-ai-toolkit)
 
 > **Server-side only.** This library authenticates with your secret key. Never ship it in an
 > Android app or anything a ticket buyer can reach — browser and mobile surfaces get short-lived,
@@ -16,15 +25,16 @@ Official Java server SDK for the [SeatLayer](https://seatlayer.io) reserved-seat
 <dependency>
   <groupId>io.seatlayer</groupId>
   <artifactId>seatlayer-java</artifactId>
-  <version>0.5.0</version>
+  <version>0.6.0</version>
 </dependency>
 ```
 
 ```groovy
-implementation 'io.seatlayer:seatlayer-java:0.5.0'
+implementation 'io.seatlayer:seatlayer-java:0.6.0'
 ```
 
-Requires Java 17 or newer. **Zero runtime dependencies** — the SDK uses
+Published on Maven Central as `io.seatlayer:seatlayer-java`; `0.6.0` is the current release, so no
+extra repository declaration is needed. Requires Java 17 or newer. **Zero runtime dependencies** — the SDK uses
 `java.net.http.HttpClient` and `javax.crypto.Mac` from the JDK plus a small hand-written JSON
 codec, so it never forces a Jackson or OkHttp version on an application that already has one.
 
@@ -274,6 +284,43 @@ seatlayer.request("POST", "/v1/events/ev_1/some-new-route", null, Map.of("qty",
 
 Full reference: [docs.seatlayer.io/server-sdk](https://docs.seatlayer.io/server-sdk/install/)
 
+## Frequently asked questions
+
+### How do I book seats from Java?
+
+Add the [`io.seatlayer:seatlayer-java` artifact](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java),
+construct a `SeatLayer` instance with your secret key, and call `inventory().book(...)` with the
+hold id and a stable `bookingRef`. When your own backend picks the seats — phone orders, box
+office, comps — `inventory().bookBestAvailable(...)` and `inventory().boxOfficeBook(...)` book
+outright with no prior hold. A booking reference is required on every booking call, so each sale is
+tied to an immutable order id you can reconcile against later.
+
+### What does the server SDK do that the buyer SDK does not?
+
+The buyer SDK runs in the browser or mobile app and only **selects and holds** seats. This Java SDK
+runs on your trusted server and **inspects and books** them. Your secret key never reaches a buyer
+surface: browsers and mobile apps receive short-lived, origin-bound tokens minted here through
+`sessions().createManageSession(...)` or `channels().createBuyerAccessSession(...)`. Always price a
+sale from `inventory().retrieveHold(...)`, never from values the client sent you.
+
+### How do temporary seat holds work server-side?
+
+A hold reserves seats against concurrent buyers for a limited checkout window. From Java you
+retrieve it with `inventory().retrieveHold(...)`, whose items and currency are authoritative for
+pricing, and confirm it with `inventory().book(...)`. Use `inventory().extendHold(...)` for a long
+checkout instead of releasing and re-holding, which would hand the seats to whoever is racing for
+them. Booking is a single automatic attempt: after an unknown network outcome you may reconcile and
+repeat the exact same event, hold, and `bookingRef` — seats already booked under that reference are
+not sold again.
+
+### Can I use my own payment provider?
+
+Yes. SeatLayer never processes payment. Charge through Stripe, Adyen, Braintree, or any provider
+you already use, calculating the total from the server-inspected hold items rather than from client
+input, then call `inventory().book(...)` with your charge or order id as the `bookingRef`. The
+[holds and checkout guide](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/) walks through
+the full handoff.
+
 ## Related resources
 
 - [Server SDK guide](https://docs.seatlayer.io/server-sdk/install/)
@@ -284,23 +331,24 @@ Full reference: [docs.seatlayer.io/server-sdk](https://docs.seatlayer.io/server-
 - [Agent-readable documentation](https://docs.seatlayer.io/llms.txt)
 - [SeatLayer GitHub organization](https://github.com/seatlayer)
 
-### Other SeatLayer SDKs
+## SeatLayer SDK ecosystem
 
-| Surface | Package |
+| Surface | Package or source |
 |---|---|
-| Browser (vanilla) | [`@seatlayer/js`](https://www.npmjs.com/package/@seatlayer/js) |
+| JavaScript | [`@seatlayer/js`](https://www.npmjs.com/package/@seatlayer/js) |
 | React | [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react) |
 | React Native | [`@seatlayer/react-native`](https://www.npmjs.com/package/@seatlayer/react-native) |
 | iOS | [`seatlayer-ios`](https://github.com/seatlayer/seatlayer-ios) |
-| Android | [`seatlayer-android`](https://github.com/seatlayer/seatlayer-android) |
 | Flutter | [`seatlayer`](https://pub.dev/packages/seatlayer) |
+| Android | [`seatlayer-android`](https://github.com/seatlayer/seatlayer-android) |
+| Server SDKs | [Node.js, Python, PHP, Ruby, .NET, Java, and Go](https://docs.seatlayer.io/server-sdk/install/) |
 | Node.js (server) | [`@seatlayer/server`](https://www.npmjs.com/package/@seatlayer/server) |
 | Python (server) | [`seatlayer`](https://pypi.org/project/seatlayer/) |
 | PHP (server) | [`seatlayer/seatlayer-php`](https://packagist.org/packages/seatlayer/seatlayer-php) |
-| Java (server) | [`io.seatlayer:seatlayer-java`](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) |
-| Go (server) | [`github.com/seatlayer/seatlayer-go`](https://pkg.go.dev/github.com/seatlayer/seatlayer-go) |
 | Ruby (server) | [`seatlayer`](https://rubygems.org/gems/seatlayer) |
 | .NET (server) | [`SeatLayer`](https://www.nuget.org/packages/SeatLayer) |
+| Java (server) | [`io.seatlayer:seatlayer-java`](https://central.sonatype.com/artifact/io.seatlayer/seatlayer-java) (this artifact) |
+| Go (server) | [`github.com/seatlayer/seatlayer-go`](https://pkg.go.dev/github.com/seatlayer/seatlayer-go) |
 
 ## Development
 

pom.xml

@@ -10,7 +10,7 @@
   <packaging>jar</packaging>
 
   <name>SeatLayer Java SDK</name>
-  <description>Official Java server SDK for the SeatLayer reserved-seating API.</description>
+  <description>Official Java server SDK for the SeatLayer reserved-seating ticketing API. Server-side only: inspect seat holds, price from server data, book seats with a stable booking reference, and manage seating charts, seat maps, events, sales channels, and live seat inventory from Java or Kotlin.</description>
   <url>https://seatlayer.io/</url>
 
   <licenses>