From c0adf9e74d8a9c4c1d530f3b449bf8bc61c9d6e1 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sun, 4 Oct 2026 17:34:58 +0000
Subject: [PATCH] docs(python): make the PyPI description a short readable
 introduction

The README PyPI renders as the opensysml project description was the full
developer document, with paragraphs that ran for forty lines. Keep the
install, quickstart and documentation links, and replace the dense
service-resolution section with a short ordered list and a pointer to the
service guide.

Co-Authored-By: jason.han <hanhuijun@gmail.com>
---
 .../unreleased/python-readme-pypi.changed.md  |  1 +
 client/python/README.md                       | 47 +++++++++++--------
 2 files changed, 28 insertions(+), 20 deletions(-)
 create mode 100644 changes/unreleased/python-readme-pypi.changed.md

diff --git a/changes/unreleased/python-readme-pypi.changed.md b/changes/unreleased/python-readme-pypi.changed.md
new file mode 100644
index 0000000000..8305a3c4fd
--- /dev/null
+++ b/changes/unreleased/python-readme-pypi.changed.md
@@ -0,0 +1 @@
+- **The `opensysml` PyPI page reads as a short introduction.** The Python package's README, which PyPI renders as the project description, is the install command, a quickstart, a short account of how the service is found, and links to the guides; the walls of implementation detail that 0.9.1 published move to the [service guide](https://opensysml.org/clients/python/service/) and the API reference.
diff --git a/client/python/README.md b/client/python/README.md
index ab8e4a63c7..3ab7ca0252 100644
--- a/client/python/README.md
+++ b/client/python/README.md
@@ -45,26 +45,33 @@ print(model.eval("mass", subject="Demo::sedan"))
 1800.0
 ```
 
-## Service resolution
-
-On its first connection, the client starts a `sysml-grpc` service if none was
-configured. It checks `$OPENSYSML_BINARY`, the shared cache, downloads the
-release it was built against, then checks `$PATH`. Release downloads are
-verified against the digest pinned in the package when one is available. A
-release of `opensysml` pins the five `sysml-grpc-*` binaries of its own release,
-stamped into its `release-digests.json` from the built binaries before the wheel
-is built, so installing a release and connecting needs no environment variable
-and no `sigstore` at run time. For another release, or one newer than the
-package's table, the client verifies the release's signed checksum manifest
-with `sigstore` and uses its digest; if that package is missing the download is
-refused, never taken unverified, and the error names the package and its
-install (`python -m pip install 'sigstore>=4.5.0,<5'`). A manifest that
-disagrees with a package pin is an integrity failure. Without a package pin or
-a digest from a verifiable signed manifest, the download is refused unless
-`OPENSYSML_ALLOW_UNPINNED_DOWNLOAD` opts into trusting a same-origin checksum.
-See the [service guide](https://opensysml.org/clients/python/service/) for
-cache ownership, offline behavior, trust configuration and external service
-setup.
+## The service
+
+The client talks to a `sysml-grpc` service. You do not have to install or
+start one: the first connection starts a private service for the current
+interpreter and stops it when the interpreter exits.
+
+To find the service binary, the client checks, in order:
+
+1. `$OPENSYSML_BINARY`, if set.
+2. The shared cache at `~/.opensysml/bin/sysml-grpc`.
+3. A download of the OpenSysML release this package was built against.
+4. A `sysml-grpc` on `$PATH`.
+
+A downloaded binary is verified against a SHA-256 digest shipped inside the
+package, so a normal `pip install opensysml` followed by `opensysml.connect()`
+needs no environment variables and no extra setup. Downloading another release
+is also verified, through its signed checksum manifest; an unverifiable download
+is refused rather than trusted.
+
+To use a service you run yourself, pass its address:
+
+```python
+model = opensysml.connect("localhost:50051").load("model.sysml")
+```
+
+The [service guide](https://opensysml.org/clients/python/service/) covers the
+cache, offline use, trust configuration and connecting to an external service.
 
 ## Documentation