docs(#1): Document release vs dev versioning scheme

- Add Versioning section to README with version format table and
  cross-SDK alignment note (Python PEP 440 vs JS semver)
- Add Versioning section to integration guide with install commands
  for stable and dev builds, pinning examples, and SDK format comparison
- Update API reference header to reflect dev version format

Refs #1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -197,6 +197,19 @@ config = TelemetryConfig(
 )
 ```
 
+## Versioning
+
+This SDK publishes two types of versions to the Mosaic Stack PyPI registry:
+
+| Channel | Version Format | Example | Branch | Install |
+|---------|---------------|---------|--------|---------|
+| **Stable** | `X.Y.Z` | `0.1.0` | `main` / tags | `pip install mosaicstack-telemetry` |
+| **Dev** | `X.Y.Z.devYYYYMMDDHHMMSS` | `0.1.0.dev20260215045901` | `develop` | `pip install mosaicstack-telemetry --pre` |
+
+Dev versions use a UTC timestamp suffix (PEP 440 format). This aligns with the JS client SDK which uses the equivalent semver format `X.Y.Z-dev.YYYYMMDDHHmmss`.
+
+By default, `pip install` resolves only stable releases. Pass `--pre` to include dev versions.
+
 ## Documentation
 
 - **[Integration Guide](docs/integration-guide.md)** -- Installation, configuration, FastAPI and generic Python examples, async vs sync patterns, prediction queries, error handling

docs/api-reference.md

@@ -2,7 +2,7 @@
 
 Complete reference for all public classes, methods, types, and enums exported by `mosaicstack-telemetry`.
 
-**SDK version:** 0.1.0
+**SDK version:** 0.1.0 (stable: `0.1.0`, dev: `0.1.0.devYYYYMMDDHHMMSS`)
 **Telemetry API version:** v1
 **Event schema version:** 1.0
 

docs/integration-guide.md

@@ -616,6 +616,36 @@ with TelemetryClient(config) as client:
 
 ---
 
+## Versioning
+
+This SDK publishes two types of versions to the Mosaic Stack PyPI registry at `git.mosaicstack.dev`:
+
+| Channel | Version Format | Example | Branch | Install |
+|---------|---------------|---------|--------|---------|
+| **Stable** | `X.Y.Z` | `0.1.0` | `main` / tags | `pip install mosaicstack-telemetry` |
+| **Dev** | `X.Y.Z.devYYYYMMDDHHMMSS` | `0.1.0.dev20260215045901` | `develop` | `pip install mosaicstack-telemetry --pre` |
+
+Dev versions use a UTC timestamp suffix following [PEP 440](https://peps.python.org/pep-0440/#developmental-releases). This convention is shared across Mosaic Stack SDKs:
+
+| SDK | Dev Version Format | Example |
+|-----|-------------------|---------|
+| Python (this SDK) | `X.Y.Z.devYYYYMMDDHHMMSS` | `0.1.0.dev20260215045901` |
+| JavaScript | `X.Y.Z-dev.YYYYMMDDHHmmss` | `0.1.0-dev.20260215045901` |
+
+By default, `pip install` resolves only stable releases. To install the latest dev build:
+
+```bash
+pip install mosaicstack-telemetry --pre --index-url https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
+```
+
+To pin to a specific dev version:
+
+```bash
+pip install mosaicstack-telemetry==0.1.0.dev20260215045901 --index-url https://git.mosaicstack.dev/api/packages/mosaic/pypi/simple/
+```
+
+---
+
 ## API Compatibility
 
 | SDK Version | Telemetry API | Event Schema | Notes |