From e88e957c0795f14364e277fda3d874d2573ca8b2 Mon Sep 17 00:00:00 2001
From: Daniel Perrefort <djperrefort@gmail.com>
Date: Sat, 27 Dec 2025 20:43:56 -0500
Subject: [PATCH] Documentation pass

---
 docs/index.md   | 11 ++---------
 docs/logging.md | 25 +++++++++++--------------
 docs/session.md |  5 +++++
 3 files changed, 18 insertions(+), 23 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index ef2f6bb..09575b0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,19 +1,12 @@
 # Keystone Python Client
 
-The Keystone platform includes an official Python client that simplifies integration with the application's REST API.
+Keystone includes an official Python client designed to simplify integration with the platform's [REST API](../keystone-api).
 It handles authentication, request execution, and response parsing, allowing developers to concentrate on application
 logic rather than API mechanics.
 
-The client is published on the BHPC package registry and can be installed in the standard fashion.
+The client is published on the BHPC package registry and can be installed using the `pip` package manager:
 
 ```sh
 BHPC_REPO="https://dl.cloudsmith.io/public/better-hpc/keystone/python/simple/"
 pip install --extra-index-url=$BHPC_REPO keystone-api-client
 ```
-
-!!! danger "Version Compatibility"
-
-    The API client version should match the major and minor version of the upstream API server.
-    For example, if the API version is `2.3.x`, the compatible client version is `2.3.y`.
-    Using a mismatched client version may still function, but compatibility is not guaranteed and may
-    result in inconsistent behavior.
diff --git a/docs/logging.md b/docs/logging.md
index f4f6968..7681c24 100644
--- a/docs/logging.md
+++ b/docs/logging.md
@@ -1,14 +1,9 @@
 # Application Logging
 
-The Keystone Python client exposes a dedicated logger (`kclient`) that records structured request metadata using the
-standard Python logging framework. The logger is registered automatically when the package is imported and can be
-configured like any other Python logger.
-
-## Logger Configuration
-
-Custom handlers, formatters, and filters may be attached directly to the kclient logger.
-Because the logger behaves like any standard Python logger, you can control output destinations, define
-message structures, adjust verbosity, and apply filtering based on logged metadata.
+The Keystone Python Client includes a dedicated logger named `kclient`, which is automatically registered on package
+import. The logger provides full compatibility with the standard Python `logging` module, including support for custom
+handlers, formatters, and filters.
+The logger can be accessed and customized in the standard fashion, demonstrated below.
 
 ```python
 import logging
@@ -22,7 +17,10 @@ handler.setFormatter(
 logging.getLogger('kclient').addHandler(handler)
 ```
 
-In addition to the standard Python logging attributes, the `kclient` logger includes the following package-specific fields:
+## Custom Logging Fields
+
+In addition to Python's built-in message fields, the `kclient` logger also exposes the following package-specific values.
+These fields are passed to all log messages and may be accessed via custom formatters or filters.
 
 | Field Name | Description                                                                |
 |------------|----------------------------------------------------------------------------|
@@ -34,10 +32,9 @@ In addition to the standard Python logging attributes, the `kclient` logger incl
 
 ## Session IDs
 
-Each client session is assigned a unique correlation ID (CID) that accompanies all emitted log records.
-This identifier provides a reference value for correlating client and API logs across multiple endpoints and requests.
-CID values are suitable for inclusion in log messages, passing to downstream services, or correlating requests
-for debugging and performance monitoring.
+Each client session is assigned a unique correlation ID (CID) that accompanies all emitted log records and requests.
+This identifier provides a reference value for correlating client and API logs across multiple endpoints and services.
+CID values are accessible as logging fields or directly from an active client session, demonstrated below:
 
 === "Synchronous"
 
diff --git a/docs/session.md b/docs/session.md
index 17046a9..8e04638 100644
--- a/docs/session.md
+++ b/docs/session.md
@@ -1,8 +1,13 @@
 # Starting a Session
 
 Interacting with the Keystone API begins by creating a client session. 
+<<<<<<< Updated upstream
 Session objects encapsulate the connection state and request configuration, allowing the
 client to efficiently reuse connections and manage resources across multiple API calls.
+=======
+Session objects encapsulate the connection state, authentication details, and request configuration, allowing the
+client to efficiently reuse connections across multiple API calls.
+>>>>>>> Stashed changes
 
 ## Instantiating a Client