docs: record the deliberate differences, and pin the parity row exactly

MissingSchema is a ValueError, so the row that exists to record released
parity could not tell the two apart; it asserts the exact class now.

The README and a release-notes draft carry the differences a caller can
observe, including the console script this branch removed.

Author: chandrasekharan-zipstack

README.md

@@ -161,6 +161,26 @@ types the target lacks (listed in the end-of-run report).
 - Run the source and target on the same (or a newer-target) Unstract build.
 - Use `unstract-client >= 1.4.0`, the first release that ships the clone command.
 
+## Behaviour that differs from earlier releases
+
+Deliberate, and listed here so a difference is not rediscovered as a bug:
+
+- **The status poll is resolved under the deployment URL's own path prefix.**
+  Earlier releases concatenated the base URL and the endpoint the service
+  returned, which never reached a deployment served under an ingress or reverse
+  proxy path. Where no prefix can be derived from the deployment URL, the
+  endpoint the service returned is used as it came.
+- **An absolute `status_check_api_endpoint` now resolves.** Concatenation
+  produced `https://hosthttps://host/...`, which reached nothing at all; it is
+  joined instead.
+- **Query parameters this client sets win a collision** with the ones on the
+  returned endpoint. Everything else on that endpoint is forwarded unchanged.
+- **A malformed `api_url` raises this client's own exception classes** —
+  `APIDeploymentsClientException` for a URL with no host, `MissingSchema` for one
+  with no scheme — where earlier releases raised `InvalidSchema` for both. Code
+  catching `requests.exceptions.RequestException` around client construction no
+  longer catches the first of those.
+
 ## Questions and Feedback
 
 On Slack, [join great conversations](https://join-slack.unstract.com/) around LLMs, their ecosystem and leveraging them to automate the previously unautomatable!

RELEASE_NOTES.md

@@ -0,0 +1,41 @@
+# Release notes — draft
+
+Content for the next release. Not published yet.
+
+## Breaking
+
+**The `unstract` console script is gone.** Installing this package no longer
+puts an `unstract` command on your PATH.
+
+- The clone command is still here: run it as `python -m unstract.clone`, with
+  the same options it has always taken.
+- The name now belongs to the `unstract-cli` package, whose `unstract clone`
+  wraps this same code.
+
+An environment that holds both an older release of this package and the new CLI
+gives the name to whichever was installed last, so check what answers before
+reporting a missing command:
+
+```bash
+command -v unstract && unstract --version
+```
+
+## Behaviour that differs from earlier releases
+
+Deliberate; each is described in the README under *Behaviour that differs from
+earlier releases*:
+
+- The status poll resolves under the deployment URL's own path prefix, and falls
+  back to the endpoint the service returned where no prefix can be derived.
+- An absolute `status_check_api_endpoint` resolves instead of being concatenated
+  into an unreachable URL.
+- Query parameters this client sets win a collision with the returned
+  endpoint's; everything else on that endpoint is forwarded.
+- A malformed `api_url` raises this client's own exception classes rather than
+  `InvalidSchema`.
+
+## Under the hood
+
+The HTTP layer is generated from the service's OpenAPI spec and runs on `httpx`.
+Transport failures are still raised as their `requests` equivalents, so code
+catching `ConnectionError`, `Timeout` and the rest keeps working.

tests/test_compat.py

@@ -172,9 +172,12 @@ def test_a_malformed_deployment_url_raises_the_class_this_client_chose(
     caller wrapping construction in ``except RequestException`` no longer catches
     the first, which is the part that has to be visible.
     """
-    with pytest.raises(expected):
+    with pytest.raises(expected) as caught:
         client = _client(api_url=api_url)
         client.check_execution_status(STATUS_ENDPOINT)
+    # MissingSchema is itself a ValueError, so the parity row can only tell the
+    # two apart by the exact class.
+    assert type(caught.value) is expected
 
 
 def _httpx_request_errors():