Merge pull request #35 from kinde-oss/ev/improving_docs

Enhance README.md with Go import examples and clarify usage

Author: evgenyk

README.md

@@ -10,12 +10,9 @@ The Kinde SDK for Go.
 
 Requires Go 1.24+
 
-### Usage
+## OAuth 2.0 Flows
 
-```bash
-go get github.com/kinde-oss/kinde-go
-go mod tidy
-```
+For comprehensive information about OAuth 2.0 flows and how to choose the right flow for your application, see [OAuth 2.0 flows explained](https://kinde.com/learn/authentication/protocols/oauth-flows-explained/).
 
 ## Authorization Code Flow
 

jwt/README.md

@@ -2,6 +2,20 @@
 
 The `jwt` package provides comprehensive JWT (JSON Web Token) parsing, validation, and management capabilities for the Kinde Go SDK. This package is designed to work seamlessly with OAuth2 flows and provides flexible validation options.
 
+## Learn More About JWTs
+
+To better understand JSON Web Tokens, their structure, security features, and use cases, check out our comprehensive guide:
+
+**[A complete guide to JSON Web Tokens (JWTs)](https://kinde.com/learn/authentication/types-and-methods/json-web-tokens/)**
+
+This guide covers:
+
+- What JSON Web Tokens are and how they work
+- JWT structure (header, payload, signature)
+- Security considerations and best practices
+- Common use cases for authentication and authorization
+- JWT benefits compared to other token types
+
 ## Features
 
 - **Multiple Parsing Methods**: Parse JWT tokens from HTTP headers, strings, session storage, or OAuth2 tokens
@@ -10,10 +24,12 @@ The `jwt` package provides comprehensive JWT (JSON Web Token) parsing, validatio
 - **Comprehensive Token Access**: Easy access to token claims, subject, issuer, audience, and other standard JWT fields
 - **Error Handling**: Detailed validation error reporting
 
-## Installation
+## Go Imports
 
-```bash
-go get github.com/kinde-oss/kinde-go/jwt
+```go
+import (
+    "github.com/kinde-oss/kinde-go/jwt" // required
+)
 ```
 
 ## Quick Start
@@ -41,6 +57,10 @@ if token.IsValid() {
 }
 ```
 
+**Important**: All validation options (e.g., `WillValidateWithJWKSUrl`, `WillValidateAlgorithm`, `WillValidateAudience`) are applied **once during token parsing**, not every time the token is read. The validation results are cached in the token object, so subsequent calls to `GetSubject()`, `GetIssuer()`, `GetAudience()`, etc. do not re-validate the token.
+
+**Note for OAuth2 Flows**: When using the JWT package with OAuth2 flows (authorization_code or client_credentials), tokens are **re-validated every time they are retrieved from the token source**. This ensures that tokens remain valid throughout their lifecycle and any validation errors are caught when tokens are refreshed or retrieved from session storage.
+
 ## Parsing Methods
 
 ### ParseFromString

oauth2/authorization_code/README.md

@@ -6,6 +6,15 @@ The `authorization_code` package provides OAuth2 authorization code flow impleme
 
 The authorization code flow is a backend authorization flow that requires a client secret. It is designed to be used as a server-side auth flow and does not expose tokens to the browser. User sessions need to be managed by other means, for example via session cookies.
 
+## Go Imports
+
+```go
+import (
+    "github.com/kinde-oss/kinde-go/oauth2/authorization_code" // required
+    "github.com/kinde-oss/kinde-go/jwt" // optional - for JWT token validation
+)
+```
+
 ## Standard Authorization Code Flow
 
 ### Basic Usage

oauth2/client_credentials/README.md

@@ -6,6 +6,16 @@ The `client_credentials` package provides OAuth2 client credentials flow impleme
 
 The client credentials flow is designed for machine-to-machine communication which doesn't involve human input. It requires a Kinde M2M application and is ideal for server-to-server authentication scenarios.
 
+## Go Imports
+
+```go
+import (
+    "github.com/kinde-oss/kinde-go/oauth2/client_credentials" // required
+    "github.com/kinde-oss/kinde-go/oauth2/client_credentials/cli" // optional - for CLI session storage
+    "github.com/kinde-oss/kinde-go/jwt" // optional - for JWT token validation
+)
+```
+
 ## Basic Usage
 
 ```go