docs: pre-PyPI README refresh for release-frozen long_descriptions

INSTALL.md

@@ -14,8 +14,23 @@
 
 ## Install
 
-**Not yet published to PyPI** -- `pip install honua-sdk` will not resolve
-until the first public release lands. Until then, install from a clone:
+The canonical install path is PyPI:
+
+```bash
+# Core data client (REST/HTTP, sync + async)
+pip install honua-sdk
+
+# With extras: gRPC, GeoPandas vector interop, raster interop
+pip install "honua-sdk[grpc,geopandas,raster]"
+
+# Admin / control-plane client (installs honua-sdk alongside it)
+pip install honua-admin
+```
+
+If those commands do not resolve yet — the first public release is staged on
+the release automation (release-please + PyPI Trusted Publishing) but may not
+have landed — install from a clone instead; this path always works and is
+also the development path:
 
 ```bash
 git clone https://github.com/honua-io/honua-sdk-python.git
@@ -40,16 +55,16 @@ pip install ./packages/honua-sdk ./packages/honua-admin
 pip install "./packages/honua-sdk[grpc,geopandas,raster]" ./packages/honua-admin
 ```
 
-Or straight from GitHub without cloning:
+Or straight from GitHub without cloning, pinned to a release tag (replace
+with the newest `python-sdk-v*` tag):
 
 ```bash
 pip install "honua-sdk[geopandas] @ git+https://github.com/honua-io/honua-sdk-python.git@python-sdk-v0.1.9#subdirectory=packages/honua-sdk"
 ```
 
 The repo-root `pyproject.toml` is intentionally **not** installable (it
 holds shared tool config only) -- install the per-package directories,
-not `.`. Once the packages are published, the commands above collapse to
-`pip install honua-sdk[...]` / `pip install honua-admin`.
+not `.`.
 
 ## Quick Start
 
@@ -60,9 +75,9 @@ with HonuaClient(base_url="https://your-honua-server.com") as client:
     # Query features through the shared Source/Query/Result API
     source = client.source(
         SourceDescriptor(
-            id="test_service",
+            id="parcels",
             protocol="geoservices-feature-service",
-            locator=SourceLocator(service_id="test_service", layer_id=0),
+            locator=SourceLocator(service_id="parcels", layer_id=0),
         )
     )
     result = source.query(
@@ -83,7 +98,7 @@ import grpc
 
 from honua_sdk.grpc import HonuaGrpcClient, QueryFeaturesRequest
 
-request = QueryFeaturesRequest(service_id="test_service", layer_id=0)
+request = QueryFeaturesRequest(service_id="parcels", layer_id=0)
 
 # Production: TLS via channel credentials
 with HonuaGrpcClient(
@@ -154,9 +169,9 @@ from honua_sdk import HonuaClient, Query, SourceDescriptor, SourceLocator
 with HonuaClient(base_url="https://your-honua-server.com") as client:
     source = client.source(
         SourceDescriptor(
-            id="test_service",
+            id="parcels",
             protocol="geoservices-feature-service",
-            locator=SourceLocator(service_id="test_service", layer_id=0),
+            locator=SourceLocator(service_id="parcels", layer_id=0),
         )
     )
     result = source.query(Query(where="status = 'active'", out_fields=["*"]))

README.md

@@ -3,6 +3,7 @@
 [![CI](https://github.com/honua-io/honua-sdk-python/actions/workflows/ci.yml/badge.svg?branch=trunk)](https://github.com/honua-io/honua-sdk-python/actions/workflows/ci.yml)
 [![Conformance](https://github.com/honua-io/honua-sdk-python/actions/workflows/conformance.yml/badge.svg?branch=trunk)](https://github.com/honua-io/honua-sdk-python/actions/workflows/conformance.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/honua-io/honua-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/honua-io/honua-sdk-python)
+[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://honua-io.github.io/honua-sdk-python/latest/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
 Python client libraries for [Honua](https://honua.io), the cloud-native
@@ -31,19 +32,27 @@ re-exports it.
 
 ## Status
 
-Alpha (`0.x`): `honua-sdk` 0.1.9, `honua-admin` 0.1.6. APIs may change before
-1.0; breaking changes to the public API are gated by a
-[compatibility snapshot](docs/compatibility.md).
+Alpha (`0.x`). APIs may change before 1.0; breaking changes to the public API
+are gated by a [compatibility snapshot](docs/compatibility.md) and a
+per-capability [SDK coverage snapshot](docs/sdk-coverage.md).
 
-**Not yet published to PyPI** — install from source (below). Release
-automation is in place (release-please + a tag-triggered publish workflow
-using PyPI Trusted Publishing), so `pip install honua-sdk` becomes the install
-path once the first publish lands.
+Releases are automated (release-please + a tag-triggered publish workflow
+using PyPI Trusted Publishing) and ship to PyPI as `honua-sdk` and
+`honua-admin`. If `pip install honua-sdk` does not resolve yet — the first
+public release is staged but may not have landed — install from source
+(below); the from-source path always works.
 
 ## Install
 
-Requires Python 3.11+ (CI tests 3.11, 3.12, 3.13). Until the packages are on
-PyPI, install from a clone:
+Requires Python 3.11+ (CI tests 3.11, 3.12, 3.13). From PyPI:
+
+```bash
+pip install honua-sdk                             # data-plane client
+pip install "honua-sdk[grpc,geopandas,raster]"    # + optional extras
+pip install honua-admin                           # control-plane (admin) client
+```
+
+From source (always works, and the path for development):
 
 ```bash
 git clone https://github.com/honua-io/honua-sdk-python.git
@@ -60,7 +69,8 @@ pip install "./packages/honua-sdk[grpc,geopandas,raster]"
 pip install ./packages/honua-sdk ./packages/honua-admin
 ```
 
-Or straight from GitHub without cloning:
+Or straight from GitHub without cloning, pinned to a release tag (replace
+with the newest `python-sdk-v*` tag):
 
 ```bash
 pip install "honua-sdk[geopandas] @ git+https://github.com/honua-io/honua-sdk-python.git@python-sdk-v0.1.9#subdirectory=packages/honua-sdk"
@@ -105,7 +115,7 @@ with HonuaClient("https://your-honua-server.com") as client:
     for feature in result.features[:3]:
         print(feature.id, feature.properties)
 
-    # Requires: pip install "./packages/honua-sdk[geopandas]"
+    # Requires the [geopandas] extra
     gdf = result.to_geodataframe()  # GeoDataFrame with geometry column + CRS set
     print(gdf.head(), gdf.crs)
 ```
@@ -192,27 +202,32 @@ with HonuaAdminClient("https://your-honua-server.com", api_key="honua-api-key")
 | | |
 |---|---|
 | Typed, canonical query surface | `Source` / `Query` / `Result` with normalized `QueryFeature` across FeatureServer, OGC Features, STAC, OData |
-| Protocol clients | GeoServices (Feature/Map/Image/Geocode/Geometry servers), OGC API Features, STAC, OData, WFS, WMS, WMTS — see [protocol parity](docs/protocol-parity.md) |
+| Protocol clients | GeoServices (Feature/Map/Image/Geocode/Geometry/Scene/Elevation servers), OGC API Features/Maps/Tiles/Coverages/Processes/Records, STAC, OData, WFS, WMS, WMTS, geoprocessing + workflow wrappers — see [protocol parity](docs/protocol-parity.md) |
 | GIS interop | `Result.to_geodataframe()`, `features_to_geodataframe` (Esri JSON aware), raster results via `rasterio`/`rioxarray` (`[raster]` extra) |
 | gRPC streaming | `honua_sdk.grpc.HonuaGrpcClient` / `HonuaGrpcAsyncClient` for unary + streaming feature queries (`[grpc]` extra) |
 | Sync + async | `HonuaClient` / `AsyncHonuaClient` in lockstep (sync clients generated from the async source of truth) |
 | Automatic retry | 429/502/503 with exponential backoff and `Retry-After` support; configurable via `max_retries`, `retry_methods` |
 | Typed errors | `HonuaAuthError`, `HonuaRateLimitError`, `HonuaHttpError`, `HonuaTimeoutError`, `HonuaTransportError` — see [common errors](docs/quickstart.md#common-errors) |
-| CLI | `honua` (services / layers / style apply / sanitized `doctor` diagnostics) and `honua-migrate` (offline ArcPy script scan / translate / `.pyt` classify) |
-| Quality gates | mypy `strict` workspace-wide, 94% coverage gate, public-API [compatibility snapshot](docs/compatibility.md), live-server [conformance lane](.github/workflows/conformance.yml) against shared [geospatial-grpc](https://github.com/honua-io/geospatial-grpc) fixtures |
+| CLI | `honua` (services / layers / style apply / sanitized `doctor` diagnostics) and `honua-migrate` (offline ArcPy script scan / translate / run, plus `.pyt` / `.atbx` toolbox and GP-service classification) |
+| Quality gates | mypy `strict` workspace-wide, 94% coverage gate, public-API [compatibility snapshot](docs/compatibility.md), per-capability [SDK coverage snapshot](docs/sdk-coverage.md), live-server [conformance lane](.github/workflows/conformance.yml) against shared [geospatial-grpc](https://github.com/honua-io/geospatial-grpc) fixtures |
 
 ## Documentation
 
-Repo docs live under [docs/](docs/README.md) (MkDocs sources; browsable on
-GitHub). Platform-level docs are at
+The rendered docs site lives at
+[honua-io.github.io/honua-sdk-python](https://honua-io.github.io/honua-sdk-python/latest/)
+(versioned MkDocs build of [docs/](docs/README.md)). Platform-level docs are
+at [honua.io](https://honua.io) and
 [honua.gitbook.io/honuaio](https://honua.gitbook.io/honuaio/).
 
 - [5-Minute Quickstart](docs/quickstart.md) — query, GeoDataFrame, plot, common errors
 - [Core Client](docs/core-client.md) — typed service, FeatureServer, applyEdits, pagination, error handling
 - [Protocol Examples](docs/protocol-examples.md) — OGC, STAC, WFS, WMS, WMTS, OData, geocoding, gRPC with response shapes
 - [Authentication](docs/auth.md) — refreshable bearer tokens, storage, rotation, failure modes
+- [Pagination](docs/pagination.md) and [retries & timeouts](docs/retries-and-timeouts.md)
+- [Sanitized diagnostic bundles](docs/diagnostic-bundles.md) — the `honua doctor` bundle format
 - [Geospatial ETL demo](examples/geospatial_etl/README.md) — script-first ETL flow with notebook companion
 - [Compatibility](docs/compatibility.md) — supported server matrix and public-API snapshot gate
+- [SDK coverage](docs/sdk-coverage.md) — per-capability coverage snapshot gate
 - [Troubleshooting](docs/troubleshooting.md) — base URL, auth, staging smoke env vars, cleanup
 
 ## Related Honua repos
@@ -223,7 +238,7 @@ GitHub). Platform-level docs are at
 | [honua-sdk-js](https://github.com/honua-io/honua-sdk-js) | JavaScript/TypeScript SDKs + MCP server |
 | [honua-sdk-dotnet](https://github.com/honua-io/honua-sdk-dotnet) | .NET SDKs |
 | [honua-console](https://github.com/honua-io/honua-console) | Unified web console (Studio, Catalog, Operate, Share) |
-| [honua-qgis-plugin](https://github.com/honua-io/honua-qgis-plugin) | QGIS plugin |
+| honua-qgis-plugin | QGIS plugin (private preview; repo not yet public) |
 | [geospatial-grpc](https://github.com/honua-io/geospatial-grpc) | Vendor-neutral gRPC protocol standard; source of this repo's conformance fixtures |
 
 ## Development

packages/honua-admin/README.md

@@ -1,36 +1,60 @@
 # honua-admin
 
-Admin / control-plane client for [Honua Server](https://github.com/honua-io) --
-manage services, connections, layers, styles, metadata resources, and
-manifests. Sync (`HonuaAdminClient`) and async (`AsyncHonuaAdminClient`)
-clients included.
-
-See the [monorepo README](https://github.com/honua-io/honua-sdk-python) for
-the full documentation index and release notes.
-
-## Highlights
-
-- Typed compatibility check (`check_compatibility()`) against the server's
-  `/api/v1/admin/capabilities` contract before issuing control-plane calls.
-- Capability flag accessor for feature toggles such as `manifest_apply`,
-  `manifest_dry_run`, and `metadata_resources`.
-- Service/layer/style/connection/metadata-resource CRUD helpers backed by typed
-  request and response dataclasses.
-- Manifest export/apply/dry-run/prune helpers for declarative server state.
-- Reuses `honua-sdk`'s retry transport, auth providers, and `HonuaHttpError`
-  envelopes for a single error-handling surface.
+Admin / control-plane client for
+[Honua Server](https://github.com/honua-io/honua-server), the multi-protocol
+geospatial server behind [Honua](https://honua.io) -- inspect and configure
+services, connections, layers, styles, and metadata resources from Python,
+and manage server state declaratively through manifests. Sync
+(`HonuaAdminClient`) and async (`AsyncHonuaAdminClient`) clients included.
+
+> **Status: Alpha (`0.x`).** APIs may change before 1.0. Breaking changes to
+> the public API are gated by a
+> [compatibility snapshot](https://github.com/honua-io/honua-sdk-python/blob/trunk/docs/compatibility.md),
+> and the client checks server compatibility at runtime via
+> `check_compatibility()`.
+
+## What it does
+
+- **Compatibility-first**: `check_compatibility()` and
+  `get_capability_flags()` read the server's `/api/v1/admin/capabilities`
+  contract, so callers can gate control-plane calls on what the connected
+  server actually supports (`manifest_apply`, `manifest_dry_run`,
+  `metadata_resources`, ...).
+- **Services**: `list_services()`, `get_service_settings()`,
+  `update_protocols()`, `update_mapserver_settings()`.
+- **Layers and data**: `list_layers()`, `publish_layer()`,
+  `set_layer_enabled()` / `set_service_layers_enabled()`, and
+  `discover_tables()` for source-database table discovery.
+- **Connections**: typed CRUD plus `test_connection()` /
+  `test_draft_connection()`, `validate_encryption()`, and
+  `rotate_encryption_key()`.
+- **Styles**: OGC Styles API (`list_styles()`, `get_stylesheet()`,
+  `update_style()`) and per-layer styles (`get_layer_style()`,
+  `update_layer_style()`).
+- **Metadata resources**: typed CRUD over the server's metadata catalog.
+- **Manifests as declarative state**: `get_manifest()` exports the server's
+  metadata state; `apply_manifest()` applies a manifest with dry-run and
+  prune options and idempotency-key support.
+- **ArcGIS migration tooling**: `scan_migration_source()` drives the
+  server-side migration inventory scanner
+  (`POST /api/v1/admin/import/scan`), and the offline
+  `scan_arcpy_script()` / `scan_arcpy_source()` helpers inventory ArcPy
+  scripts without a server or an `arcpy` install.
+- Reuses `honua-sdk`'s retry transport, auth providers, and
+  `HonuaHttpError` envelopes, so data-plane and control-plane code share one
+  error-handling surface.
 
 ## Install
 
 ```bash
 pip install honua-admin
 ```
 
-Installs `honua-sdk` automatically (shared HTTP, auth, and error utilities).
-Requires Python 3.11+.
+Installs a compatible `honua-sdk` automatically (shared HTTP, auth, and
+error utilities). Requires Python 3.11+.
 
-The server compatibility baseline and release gate policy are documented in
-the monorepo
+The supported server baseline and release gate policy are documented in the
+monorepo
 [compatibility guide](https://github.com/honua-io/honua-sdk-python/blob/trunk/docs/compatibility.md).
 
 ## Minimal Example
@@ -72,15 +96,25 @@ async with AsyncHonuaAdminClient(
 ```
 
 The async client mirrors the sync method surface (CRUD helpers, manifest
-operations, capability checks) and shares the same retry transport, auth
-providers, and `HonuaHttpError` envelopes.
+operations, migration scans, capability checks) and shares the same retry
+transport, auth providers, and `HonuaHttpError` envelopes.
 
 ## Documentation
 
+Rendered docs site:
+[honua-io.github.io/honua-sdk-python](https://honua-io.github.io/honua-sdk-python/latest/).
+Platform docs: [honua.io](https://honua.io) and
+[honua.gitbook.io/honuaio](https://honua.gitbook.io/honuaio/).
+
 - [Compatibility policy](https://github.com/honua-io/honua-sdk-python/blob/trunk/docs/compatibility.md)
 - [Authentication](https://github.com/honua-io/honua-sdk-python/blob/trunk/docs/auth.md)
 - [Monorepo README](https://github.com/honua-io/honua-sdk-python) -- install matrix and package overview
 
+Related: [honua-sdk](https://github.com/honua-io/honua-sdk-python/tree/trunk/packages/honua-sdk)
+(the data-plane client this package builds on),
+[honua-sdk-js](https://github.com/honua-io/honua-sdk-js) (JS/TS SDKs + MCP server),
+[honua-sdk-dotnet](https://github.com/honua-io/honua-sdk-dotnet) (.NET SDKs).
+
 ## License
 
 Apache-2.0

packages/honua-admin/pyproject.toml

@@ -29,7 +29,8 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/honua-io"
+Homepage = "https://honua.io"
+Documentation = "https://honua-io.github.io/honua-sdk-python/latest/"
 Repository = "https://github.com/honua-io/honua-sdk-python"
 Issues = "https://github.com/honua-io/honua-sdk-python/issues"