ci: separate validation and document HTTP transport

.github/workflows/build-and-test.yml

@@ -1,17 +1,33 @@
-name: Python Build MLBstats API 
+name: Offline CI
 
 on:
+  pull_request:
+    branches:
+      - main
+      - release/0.8.0
   push:
-    branches-ignore:
-      - 'main'
-      - 'development'
+    branches:
+      - main
+      - release/0.8.0
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  build:
+  offline-tests:
+    name: Offline tests - Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
 
     steps:
       - uses: actions/checkout@v4
@@ -26,7 +42,29 @@ jobs:
           virtualenvs-in-project: true
       - name: Install dependencies
         run: poetry install --no-interaction
-      - name: Test external tests with pytest
-        run: poetry run pytest tests/external_tests/
+      - name: Run offline tests
+        run: |
+          poetry run pytest \
+            tests/ \
+            --ignore=tests/external_tests
+
+  build-package:
+    name: Build package
+    needs: offline-tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+      - name: Install dependencies
+        run: poetry install --no-interaction
       - name: Build package
         run: poetry build

.github/workflows/external-tests.yml

@@ -0,0 +1,34 @@
+name: External MLB API Tests
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 12 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  external-tests:
+    name: External MLB API tests - Python 3.12
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+      - name: Install dependencies
+        run: poetry install --no-interaction
+      - name: Run external MLB API tests
+        run: |
+          poetry run pytest \
+            tests/external_tests/ \
+            -v

README.md

@@ -5,7 +5,7 @@
 **The Unofficial Python Wrapper for the MLB Stats API**
 
 [![PyPI version](https://badge.fury.io/py/python-mlb-statsapi.svg)](https://badge.fury.io/py/python-mlb-statsapi)
-![Development Branch Status](https://github.com/zero-sum-seattle/python-mlb-statsapi/actions/workflows/build-and-test-mlbstatsapi-test.yml/badge.svg?event=push)
+[![Offline CI](https://github.com/zero-sum-seattle/python-mlb-statsapi/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/zero-sum-seattle/python-mlb-statsapi/actions/workflows/build-and-test.yml)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-mlb-statsapi)
 ![GitHub](https://img.shields.io/github/license/zero-sum-seattle/python-mlb-statsapi)
 
@@ -65,6 +65,29 @@ Ty France
 Seattle Mariners Seattle
 ```
 
+## HTTP Reliability and Configuration
+
+The client remains synchronous. Sessions and retries are handled automatically for ordinary users, and existing `Mlb()` construction remains valid.
+
+Prefer a context manager when you want automatic cleanup:
+
+```python
+import mlbstatsapi
+
+with mlbstatsapi.Mlb() as mlb:
+    player = mlb.get_person(664034)
+```
+
+Customize connect and read timeouts when needed:
+
+```python
+mlb = mlbstatsapi.Mlb(
+    timeout=(5.0, 60.0),
+)
+```
+
+For shared Sessions, Session injection, retries, and structured exceptions, see [HTTP Transport](docs/http-transport.md).
+
 ## Working with Pydantic Models
 
 All returned objects are Pydantic models, giving you access to powerful serialization and validation features.
@@ -180,17 +203,35 @@ Contributions are welcome! Whether it's bug fixes, new features, or documentatio
 
 ### Development
 
+Offline tests are deterministic and should run before every pull request:
+
 ```bash
-# Run tests
-poetry run pytest
+poetry run pytest \
+  tests/ \
+  --ignore=tests/external_tests
+```
+
+External tests contact the live MLB API. They require internet access and are separate from normal offline CI:
+
+```bash
+poetry run pytest \
+  tests/external_tests/
+```
+
+These live tests may fail because the MLB service is unavailable or because MLB changes undocumented payloads.
 
-# Run external tests (requires internet)
-poetry run pytest tests/external_tests/
+Full local validation:
+
+```bash
+poetry run pytest tests/
+poetry build
 ```
 
+Offline CI is the normal pull-request gate. External tests are available manually, on a weekly schedule, and before releases.
+
 ### Pull Request Guidelines
 
-- **All tests must pass** before submitting a PR
+- Run offline tests before submitting a PR
 - Use the [PR template](.github/pull_request_template.md) when creating your pull request
 - Follow the branch naming convention:
   - `feat/` - New features
@@ -207,14 +248,6 @@ Found a bug or have a feature request? Please [open an issue](https://github.com
 - Expected vs actual behavior
 - Python version and package version
 
-### Note on External Tests
-
-Some tests make real API calls to the MLB Stats API. These may occasionally fail due to:
-- API changes (new fields, removed endpoints)
-- Season/data availability
-
-If you notice external test failures, please check if the MLB API has changed and update the models accordingly.
-
 
 ## Examples