dominus-sdk-python 9.0.2__tar.gz → 9.0.4__tar.gz

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.2
+Version: 9.0.4
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-08-04-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.2`
+- Current package version: `9.0.4`
 
 ## Install
 
@@ -67,13 +67,12 @@ for operators and advanced use; this path is the stable teaching surface.
 Set both values before the Python process imports the SDK singleton:
 
 ```bash
-export DOMINUS_TOKEN="your-psk-token"
+export DOMINUS_USER_TOKEN="your-user-token"
 export DOMINUS_PROJECT="your-project-slug"
 ```
 
 ```python
 import asyncio
-import base64
 
 from dominus import dominus
 
@@ -83,22 +82,6 @@ async def main() -> None:
         workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
     )
 
-    await dominus.artifacts.store_v2(
-        group="your-group",
-        owner="your-project-slug",
-        environment="production",
-        kind="blob",
-        artifact_key="hello",
-        data=base64.b64encode(b"hello dominus").decode("ascii"),
-    )
-    artifact = await dominus.artifacts.retrieve_v2(
-        group="your-group",
-        owner="your-project-slug",
-        environment="production",
-        kind="blob",
-        artifact_key="hello",
-    )
-
     stash_result = await dominus.stash.upsert(
         kind="config",
         scope={"env": "production"},

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/README.md

@@ -15,7 +15,7 @@ cleanup audit is `docs/janitor/2026-08-04-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.2`
+- Current package version: `9.0.4`
 
 ## Install
 
@@ -34,13 +34,12 @@ for operators and advanced use; this path is the stable teaching surface.
 Set both values before the Python process imports the SDK singleton:
 
 ```bash
-export DOMINUS_TOKEN="your-psk-token"
+export DOMINUS_USER_TOKEN="your-user-token"
 export DOMINUS_PROJECT="your-project-slug"
 ```
 
 ```python
 import asyncio
-import base64
 
 from dominus import dominus
 
@@ -50,22 +49,6 @@ async def main() -> None:
         workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
     )
 
-    await dominus.artifacts.store_v2(
-        group="your-group",
-        owner="your-project-slug",
-        environment="production",
-        kind="blob",
-        artifact_key="hello",
-        data=base64.b64encode(b"hello dominus").decode("ascii"),
-    )
-    artifact = await dominus.artifacts.retrieve_v2(
-        group="your-group",
-        owner="your-project-slug",
-        environment="production",
-        kind="blob",
-        artifact_key="hello",
-    )
-
     stash_result = await dominus.stash.upsert(
         kind="config",
         scope={"env": "production"},

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/dominus/__init__.py

@@ -178,7 +178,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "9.0.2"
+__version__ = "9.0.4"
 __all__ = [
     # Main SDK instance
     "dominus",

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/dominus/errors.py

@@ -4,6 +4,45 @@ Dominus SDK Error Classes
 Custom exceptions for the Dominus SDK with structured error information.
 """
 from typing import Any, Dict, Optional
+from uuid import uuid4
+
+
+CANONICAL_ERROR_KINDS = (
+    "unauthorized",
+    "forbidden",
+    "not_found",
+    "validation_failed",
+    "conflict",
+    "rate_limited",
+    "upstream_unavailable",
+    "internal",
+    "timeout",
+    "canceled",
+    "unsupported_version",
+)
+
+RECOVERY_ACTIONS = ("retry", "reauth", "escalate", "fix_config")
+
+
+def recovery_action_for_kind(kind: str, retryable: Optional[bool] = None) -> str:
+    if kind == "unauthorized":
+        return "reauth"
+    if kind in {"rate_limited", "timeout"}:
+        return "retry"
+    if kind == "upstream_unavailable":
+        return "retry" if retryable is not False else "escalate"
+    if kind == "internal":
+        return "escalate"
+    if kind in {
+        "validation_failed",
+        "unsupported_version",
+        "not_found",
+        "forbidden",
+        "conflict",
+        "canceled",
+    }:
+        return "fix_config"
+    return "escalate"
 
 
 def _first_string(*values: Any) -> Optional[str]:
@@ -59,6 +98,38 @@ def _normalize_kernel_details(
     return normalized
 
 
+def _kind_from_details(status_code: Optional[int], details: Dict[str, Any]) -> str:
+    explicit = _first_string(details.get("kind"))
+    if explicit in CANONICAL_ERROR_KINDS:
+        return explicit
+    code = (_first_string(details.get("code")) or "").lower()
+    if "unsupported_version" in code:
+        return "unsupported_version"
+    if "timeout" in code or status_code in {408, 504}:
+        return "timeout"
+    if "cancel" in code or status_code == 499:
+        return "canceled"
+    if status_code == 401:
+        return "unauthorized"
+    if status_code == 403:
+        return "forbidden"
+    if status_code == 404:
+        return "not_found"
+    if status_code in {400, 422}:
+        return "validation_failed"
+    if status_code == 409:
+        return "conflict"
+    if status_code == 429:
+        return "rate_limited"
+    if status_code and status_code >= 500:
+        return "upstream_unavailable"
+    return "internal"
+
+
+def _default_retryable(kind: str) -> bool:
+    return kind in {"rate_limited", "upstream_unavailable", "timeout"}
+
+
 class DominusError(Exception):
     """
     Base exception for all Dominus SDK errors.
@@ -70,17 +141,21 @@ class DominusError(Exception):
         message: Human-readable error message
         status_code: HTTP status code (if applicable)
         code: Stable machine-readable error code
+        kind: Canonical error kind from the closed-sum taxonomy (errors.spec.json)
         category: Error category from the kernel contract
         details: Additional error details from backend
         endpoint: The endpoint that was called (if applicable)
     """
 
+    kind: str = "internal"
+
     def __init__(
         self,
         message: str,
         status_code: Optional[int] = None,
         details: Optional[Dict[str, Any]] = None,
-        endpoint: Optional[str] = None
+        endpoint: Optional[str] = None,
+        kind: Optional[str] = None,
     ):
         self.message = message
         self.status_code = status_code
@@ -91,6 +166,11 @@ class DominusError(Exception):
         self.trace_id = _first_string(self.details.get("trace_id"), self.details.get("traceId"))
         self.request_id = _first_string(self.details.get("request_id"), self.details.get("requestId"))
         self.retryable = _first_bool(self.details.get("retryable"))
+        self.kind = kind or _kind_from_details(status_code, self.details)
+        self.correlation_id = _first_string(self.details.get("correlation_id"), self.details.get("correlationId"))
+        self.cause = self.details.get("cause")
+        self.recovery_action = recovery_action_for_kind(self.kind, self.retryable)
+        self.details.setdefault("recovery_action", self.recovery_action)
         super().__init__(self.message)
 
     def __str__(self) -> str:
@@ -107,6 +187,7 @@ class DominusError(Exception):
         return (
             f"DominusError(message={self.message!r}, "
             f"status_code={self.status_code}, "
+            f"kind={self.kind!r}, "
             f"code={self.code!r}, "
             f"category={self.category!r}, "
             f"details={self.details!r}, "
@@ -114,21 +195,40 @@ class DominusError(Exception):
         )
 
     def to_dict(self) -> Dict[str, Any]:
+        request_id = self.request_id or str(uuid4())
+        self.request_id = request_id
+        self.details.setdefault("request_id", request_id)
+        http_status = self.status_code or 500
+        retryable = self.retryable if self.retryable is not None else _default_retryable(self.kind)
         return {
             "message": self.message,
             "status_code": self.status_code,
             "code": self.code,
+            "kind": self.kind,
             "category": self.category,
             "details": self.details,
             "endpoint": self.endpoint,
             "trace_id": self.trace_id,
-            "request_id": self.request_id,
-            "retryable": self.retryable,
+            "request_id": request_id,
+            "correlation_id": self.correlation_id,
+            "retryable": retryable,
+            "recovery_action": self.recovery_action,
+            "http_status": http_status,
+            "envelope_version": "1",
+            **({"cause": self.cause} if self.cause is not None else {}),
         }
 
 
-class AuthenticationError(DominusError):
+# ---------------------------------------------------------------------------
+# Per-kind canonical subclasses (Seams fork 6, ADR 0010).
+# Retired kind codes: dominus-cli/docs/deprecation-table.json (M-1).
+# One derived class per canonical `kind` from errors.spec.json.
+# Existing class names are preserved as aliases (v1); deprecated in v2.
+# ---------------------------------------------------------------------------
+
+class UnauthorizedError(DominusError):
     """Raised when authentication fails (invalid token, expired JWT, etc.)."""
+    kind = "unauthorized"
 
     def __init__(
         self,
@@ -137,11 +237,12 @@ class AuthenticationError(DominusError):
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="unauthorized")
 
 
-class AuthorizationError(DominusError):
+class ForbiddenError(DominusError):
     """Raised when authorization fails (insufficient permissions)."""
+    kind = "forbidden"
 
     def __init__(
         self,
@@ -150,11 +251,12 @@ class AuthorizationError(DominusError):
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="forbidden")
 
 
 class NotFoundError(DominusError):
     """Raised when a requested resource is not found."""
+    kind = "not_found"
 
     def __init__(
         self,
@@ -163,11 +265,12 @@ class NotFoundError(DominusError):
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="not_found")
 
 
-class ValidationError(DominusError):
+class ValidationFailedError(DominusError):
     """Raised when request validation fails."""
+    kind = "validation_failed"
 
     def __init__(
         self,
@@ -176,11 +279,12 @@ class ValidationError(DominusError):
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="validation_failed")
 
 
 class ConflictError(DominusError):
     """Raised when there's a conflict (duplicate key, version mismatch, etc.)."""
+    kind = "conflict"
 
     def __init__(
         self,
@@ -189,87 +293,134 @@ class ConflictError(DominusError):
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="conflict")
 
 
-class ServiceError(DominusError):
-    """Raised when a backend service error occurs."""
+class RateLimitedError(DominusError):
+    """Raised when a request is rate-limited (429)."""
+    kind = "rate_limited"
 
     def __init__(
         self,
-        message: str = "Service error",
-        status_code: int = 500,
+        message: str = "Rate limit exceeded",
+        status_code: int = 429,
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="rate_limited")
 
 
-class StashBookmarkArtifactNotFound(NotFoundError):
-    """Raised when a stash artifact bookmark target cannot be found."""
-
-
-class StashBookmarkInvalidVersionRef(ValidationError):
-    """Raised when a stash artifact bookmark version_ref is invalid."""
-
-
-class StashBookmarkDuplicateName(ConflictError):
-    """Raised when a stash artifact bookmark name is already in use."""
-
-
-class StashBookmarkUpstreamRejected(ServiceError):
-    """Raised when the artifact backend rejects a stash bookmark operation."""
-
-
-class StashWatchInvalidWebhookUrl(ValidationError):
-    """Raised when a stash artifact watcher webhook_url is invalid."""
+class UpstreamUnavailableError(DominusError):
+    """Raised when a backend service is unavailable (5xx)."""
+    kind = "upstream_unavailable"
 
+    def __init__(
+        self,
+        message: str = "Service unavailable",
+        status_code: int = 500,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint, kind="upstream_unavailable")
 
-class StashWatchUpstreamRejected(ServiceError):
-    """Raised when the artifact backend rejects a stash watch operation."""
 
+class InternalError(DominusError):
+    """Raised for unexpected internal errors."""
+    kind = "internal"
 
-class StashWatchNotFound(NotFoundError):
-    """Raised when a stash artifact watcher cannot be found."""
+    def __init__(
+        self,
+        message: str = "Internal error",
+        status_code: int = 500,
+        details: Optional[Dict[str, Any]] = None,
+        endpoint: Optional[str] = None
+    ):
+        super().__init__(message, status_code, details, endpoint, kind="internal")
 
 
-class ConnectionError(DominusError):
-    """Raised when connection to the backend fails."""
+class TimeoutError(DominusError):
+    """Raised when a request times out."""
+    kind = "timeout"
 
     def __init__(
         self,
-        message: str = "Connection failed",
+        message: str = "Request timed out",
         status_code: Optional[int] = None,
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="timeout")
 
 
-class TimeoutError(DominusError):
-    """Raised when a request times out."""
+class CanceledError(DominusError):
+    """Raised when an operation is canceled."""
+    kind = "canceled"
 
     def __init__(
         self,
-        message: str = "Request timed out",
+        message: str = "Operation canceled",
         status_code: Optional[int] = None,
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="canceled")
 
 
-class SecureTableError(DominusError):
-    """Raised when accessing a secure table without providing a reason."""
+class UnsupportedVersionError(DominusError):
+    """Raised when an unsupported API or schema version is requested."""
+    kind = "unsupported_version"
 
     def __init__(
         self,
-        message: str = "Access to secure table requires 'reason' parameter",
-        status_code: int = 403,
+        message: str = "Unsupported version",
+        status_code: int = 400,
         details: Optional[Dict[str, Any]] = None,
         endpoint: Optional[str] = None
     ):
-        super().__init__(message, status_code, details, endpoint)
+        super().__init__(message, status_code, details, endpoint, kind="unsupported_version")
+
+
+# ---------------------------------------------------------------------------
+# v1 aliases — existing public class names preserved.
+# Every existing name maps to exactly one canonical per-kind subclass.
+# Deprecation warnings fire in v2; removal in v3 (Seams fork 6, ADR 0010).
+# ---------------------------------------------------------------------------
+
+AuthenticationError = UnauthorizedError
+AuthorizationError = ForbiddenError
+ValidationError = ValidationFailedError
+ServiceError = UpstreamUnavailableError
+ConnectionError = UpstreamUnavailableError
+SecureTableError = ForbiddenError
+
+
+# Stash subclass aliases — map to the canonical per-kind base.
+class StashBookmarkArtifactNotFound(NotFoundError):
+    """Raised when a stash artifact bookmark target cannot be found."""
+
+
+class StashBookmarkInvalidVersionRef(ValidationFailedError):
+    """Raised when a stash artifact bookmark version_ref is invalid."""
+
+
+class StashBookmarkDuplicateName(ConflictError):
+    """Raised when a stash artifact bookmark name is already in use."""
+
+
+class StashBookmarkUpstreamRejected(UpstreamUnavailableError):
+    """Raised when the artifact backend rejects a stash bookmark operation."""
+
+
+class StashWatchInvalidWebhookUrl(ValidationFailedError):
+    """Raised when a stash artifact watcher webhook_url is invalid."""
+
+
+class StashWatchUpstreamRejected(UpstreamUnavailableError):
+    """Raised when the artifact backend rejects a stash watch operation."""
+
+
+class StashWatchNotFound(NotFoundError):
+    """Raised when a stash artifact watcher cannot be found."""
 
 
 STASH_ERROR_CLASSES = {
@@ -303,16 +454,34 @@ def raise_for_status(
     """
     code = _first_string((details or {}).get("code"))
     error_classes = {
-        400: ValidationError,
-        401: AuthenticationError,
-        403: AuthorizationError,
+        400: ValidationFailedError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
         404: NotFoundError,
         409: ConflictError,
-        500: ServiceError,
-        502: ServiceError,
-        503: ServiceError,
+        429: RateLimitedError,
+        500: UpstreamUnavailableError,
+        502: UpstreamUnavailableError,
+        503: UpstreamUnavailableError,
         504: TimeoutError,
     }
 
-    error_class = STASH_ERROR_CLASSES.get(code) or error_classes.get(status_code, DominusError)
+    kind_classes = {
+        kind: error_class for kind, error_class in (
+            ("unauthorized", UnauthorizedError),
+            ("forbidden", ForbiddenError),
+            ("not_found", NotFoundError),
+            ("validation_failed", ValidationFailedError),
+            ("conflict", ConflictError),
+            ("rate_limited", RateLimitedError),
+            ("upstream_unavailable", UpstreamUnavailableError),
+            ("internal", InternalError),
+            ("timeout", TimeoutError),
+            ("canceled", CanceledError),
+            ("unsupported_version", UnsupportedVersionError),
+        )
+    }
+
+    kind = _first_string((details or {}).get("kind"))
+    error_class = STASH_ERROR_CLASSES.get(code) or kind_classes.get(kind) or error_classes.get(status_code, DominusError)
     raise error_class(message, status_code, details, endpoint)

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/dominus/helpers/auth.py

@@ -19,5 +19,5 @@ def _resolve_token() -> Optional[str]:
     Returns:
         Token string or None if not set
     """
-    return os.getenv("DOMINUS_TOKEN")
+    return os.getenv("DOMINUS_USER_TOKEN") or os.getenv("DOMINUS_TOKEN")
 

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 9.0.2
+Version: 9.0.4
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License-Expression: LicenseRef-Proprietary
@@ -48,7 +48,7 @@ cleanup audit is `docs/janitor/2026-08-04-sdk-python-cleanup-audit.md`.
 - Gateway-scoped client mode for MCP and other user-JWT sessions
 - Transport compatibility for wrapped `{success,data}` responses and unwrapped Warden/control-plane success objects
 - Local helpers for JWT verification, trace propagation, retries, and console capture
-- Current package version: `9.0.2`
+- Current package version: `9.0.4`
 
 ## Install
 
@@ -67,13 +67,12 @@ for operators and advanced use; this path is the stable teaching surface.
 Set both values before the Python process imports the SDK singleton:
 
 ```bash
-export DOMINUS_TOKEN="your-psk-token"
+export DOMINUS_USER_TOKEN="your-user-token"
 export DOMINUS_PROJECT="your-project-slug"
 ```
 
 ```python
 import asyncio
-import base64
 
 from dominus import dominus
 
@@ -83,22 +82,6 @@ async def main() -> None:
         workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
     )
 
-    await dominus.artifacts.store_v2(
-        group="your-group",
-        owner="your-project-slug",
-        environment="production",
-        kind="blob",
-        artifact_key="hello",
-        data=base64.b64encode(b"hello dominus").decode("ascii"),
-    )
-    artifact = await dominus.artifacts.retrieve_v2(
-        group="your-group",
-        owner="your-project-slug",
-        environment="production",
-        kind="blob",
-        artifact_key="hello",
-    )
-
     stash_result = await dominus.stash.upsert(
         kind="config",
         scope={"env": "production"},

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ tests/test_auth.py
 tests/test_authority_public_vocabulary.py
 tests/test_browser_namespace.py
 tests/test_control_plane_namespaces.py
+tests/test_error_recovery_action.py
 tests/test_errors.py
 tests/test_flat_commands.py
 tests/test_health.py

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "9.0.2"
+version = "9.0.4"
 description = "Python SDK for the Dominus gateway-first platform"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

dominus_sdk_python-9.0.4/tests/test_error_recovery_action.py

@@ -0,0 +1,31 @@
+import pytest
+
+from dominus.errors import CANONICAL_ERROR_KINDS, DominusError, raise_for_status, recovery_action_for_kind
+
+
+@pytest.mark.parametrize("kind", CANONICAL_ERROR_KINDS)
+def test_recovery_action_for_kind_is_closed_sum(kind: str) -> None:
+    retryable = False if kind == "upstream_unavailable" else None
+    action = recovery_action_for_kind(kind, retryable)
+    assert action in {"retry", "reauth", "escalate", "fix_config"}
+
+
+def test_dominus_error_recovery_action_accessor() -> None:
+    error = DominusError(
+        "Auth failed",
+        status_code=401,
+        details={"code": "kernel.auth.token_invalid", "kind": "unauthorized", "request_id": "req-auth"},
+    )
+    assert error.recovery_action == "reauth"
+    assert error.to_dict()["recovery_action"] == "reauth"
+    assert error.details["recovery_action"] == "reauth"
+
+
+def test_raise_for_status_surfaces_recovery_action() -> None:
+    with pytest.raises(DominusError) as exc:
+        raise_for_status(
+            404,
+            "Missing",
+            {"code": "kernel.resource.resource_not_found", "kind": "not_found"},
+        )
+    assert exc.value.recovery_action == "fix_config"

{dominus_sdk_python-9.0.2 → dominus_sdk_python-9.0.4}/tests/test_readme_quickstart_catalog.py

@@ -15,8 +15,6 @@ README = ROOT / "README.md"
 SDK_PYTHON_CATALOG = frozenset(
     {
         "workflow.ensure",
-        "artifacts.store_v2",
-        "artifacts.retrieve_v2",
         "stash.upsert",
         "stash.get",
         "authority.get_run_timeline",
@@ -24,7 +22,7 @@ SDK_PYTHON_CATALOG = frozenset(
     }
 )
 
-FORBIDDEN = re.compile(r"summit|carebridge|PCM47474562|report-cycle", re.IGNORECASE)
+FORBIDDEN = re.compile(r"summit|carebridge|PCM47474562|report-cycle|artifact", re.IGNORECASE)
 
 
 def _quick_start_section(readme: str) -> str:
@@ -48,11 +46,11 @@ def test_quick_start_scope_precedes_import_and_methods_match_catalog() -> None:
     python_index, body = _fenced(section, "python")
 
     assert shell_index < python_index
-    assert 'export DOMINUS_TOKEN="your-psk-token"' in shell
+    assert 'export DOMINUS_USER_TOKEN="your-user-token"' in shell
     assert 'export DOMINUS_PROJECT="your-project-slug"' in shell
     assert "os.environ" not in body
     assert "from dominus import dominus" in body
-    assert not FORBIDDEN.search(body), "Quick Start still has CareBridge-shaped nouns"
+    assert not FORBIDDEN.search(body), "Quick Start still has forbidden catalog nouns"
 
     found = set(re.findall(r"\bdominus\.([a-z0-9_]+)\.([a-z0-9_]+)\b", body))
     identifiers = {f"{namespace}.{method}" for namespace, method in found}
@@ -64,9 +62,12 @@ def test_quick_start_executes_in_fresh_process_with_live_transport_shapes() -> N
         r'''
         import asyncio
         import base64
+        import json
         import sys
         from pathlib import Path
 
+        import httpx
+
         readme = Path(sys.argv[1]).read_text(encoding="utf-8")
         section = readme[readme.index("## Quick Start"):]
         marker = "```python\n"
@@ -74,48 +75,65 @@ def test_quick_start_executes_in_fresh_process_with_live_transport_shapes() -> N
         body = section[start:section.index("```", start)]
 
         from dominus import dominus
+        import dominus.helpers.core as core
 
         asyncio.run(dominus._ensure_ready())
         calls = []
 
-        async def fake_request(**kwargs):
-            calls.append(kwargs)
-            endpoint = kwargs["endpoint"]
-            if endpoint == "/api/authority/runs/ensure":
-                return {"run_id": "run-1"}
-            if endpoint == "/svc/stash/items/upsert":
-                return {"item": {"id": "stash-1"}, "scope_origin": "own"}
-            if endpoint == "/svc/stash/items/get":
-                return {"item": {"id": "stash-1"}}
-            return {}
-
-        dominus._request = fake_request
+        async def fake_jwt(*_args, **_kwargs):
+            return "header.payload.signature"
+
+        core._ensure_valid_jwt = fake_jwt
+
+        def handle(request):
+            body = json.loads(base64.b64decode(request.content)) if request.content else {}
+            calls.append(
+                {
+                    "endpoint": request.url.path,
+                    "body": body,
+                    "headers": dict(request.headers),
+                }
+            )
+            if request.url.path == "/svc/authority/runs/ensure":
+                payload = {"run_id": "run-1"}
+            elif request.url.path == "/svc/stash/items/upsert":
+                payload = {"item": {"id": "stash-1"}, "scope_origin": "own"}
+            elif request.url.path == "/svc/stash/items/get":
+                payload = {"item": {"id": "stash-1"}}
+            else:
+                payload = {}
+            return httpx.Response(200, json=payload)
+
+        transport = httpx.MockTransport(handle)
+        real_async_client = httpx.AsyncClient
+
+        def mock_async_client(*args, **kwargs):
+            kwargs["transport"] = transport
+            return real_async_client(*args, **kwargs)
+
+        httpx.AsyncClient = mock_async_client
         exec(compile(body, "README.md#quick-start", "exec"), {"__name__": "__main__"})
 
         endpoints = [call["endpoint"] for call in calls]
         assert endpoints == [
-            "/api/authority/runs/ensure",
-            "/api/artifact/v2/store",
-            "/api/artifact/v2/retrieve",
+            "/svc/authority/runs/ensure",
             "/svc/stash/items/upsert",
             "/svc/stash/items/get",
-            "/api/authority/runs/run-1/timeline",
-            "/api/authority/runs/run-1/verdict",
+            "/svc/authority/runs/run-1/timeline",
+            "/svc/authority/runs/run-1/verdict",
         ], endpoints
         assert calls[0]["body"]["workflow_recipe_ref"] == "recipe://workflow-recipe-v1/hello@v1"
-        assert calls[1]["body"]["data"] == base64.b64encode(b"hello dominus").decode("ascii")
-        assert base64.b64decode(calls[1]["body"]["data"], validate=True) == b"hello dominus"
-        assert calls[3]["body"] == {
+        assert calls[1]["body"] == {
             "kind": "config",
             "scope": {"env": "production"},
             "value": {"greeting": "hello"},
             "item_key": "hello",
         }
-        assert calls[4]["body"] == {"id": "stash-1"}
+        assert calls[2]["body"] == {"id": "stash-1"}
         '''
     )
     env = os.environ.copy()
-    env["DOMINUS_TOKEN"] = "a" * 64
+    env["DOMINUS_USER_TOKEN"] = "a" * 64
     env["DOMINUS_PROJECT"] = "your-project-slug"
     result = subprocess.run(
         [sys.executable, "-c", child, str(README)],