qcoder 0.5.0a2__tar.gz → 0.5.0a3__tar.gz

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+
+## 0.5.0a3
+
+- Add public hosted Preview client commands: `qcoder pro preview status` and `qcoder pro preview demo`.
+- Support env-based hosted Preview configuration with `QCODER_PREVIEW_BASE_URL` / `QCODER_PREVIEW_TOKEN`, with `QCODER_PRO_API_URL` / `QCODER_PRO_TOKEN` compatibility fallbacks.
+- Keep hosted Preview output bounded and token-safe: no token persistence, no Authorization header printing, and safe handling for 200/401/403/network failures.
+- Preserve public package boundary: no confidential Pro implementation, account service, protected service, uploads, QPU/provider execution, payment, hosted MCP, or Pro V0.0 launch claim is included in this package.
+
 All notable changes to this project will be documented in this file.
 
 The format is based on common practice for pre-1.0 semantic versioning: **`MAJOR.MINOR.PATCH`** with **`aN`** for alpha prereleases.

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a2
+Version: 0.5.0a3
 Summary: Quantum circuit analysis and structured feature extraction tools.
 Author-email: Quantum Ready Solutions <support@qcoder.ai>
 Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
@@ -46,11 +46,13 @@ Free `qcoder` commands run offline and do not call hosted services, upload telem
 
 Public `qcoder` ships **Free local commands** plus a **Pro bootstrap/client contract**. It is **not** the sellable hosted Pro product.
 
-- **Free commands** (`analyze`, `batch`, `context`, `review`) run offline. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
+For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a2`**. It is not Pro V0.0 and not a sellable launched Pro product.
+
+- **Free commands** (`analyze`, `batch`, `context`, `review`) are Apache-2.0, local-first/offline, and useful without Pro. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
 - **`qcoder pro` bootstrap** (`signup`, `login`, `install`, `status`, `validate`) stores local token/config only. It does not upload circuits, run confidential analysis, or generate Pro cards locally.
 - **`qcoder pro workflow --dry-run-manifest`** writes a local JSON contract (`qcoder.pro_preview.workflow_manifest.v0`) and performs **no network calls**. This is the default path for most users.
 - **`qcoder pro workflow --submit`** posts a **sanitized manifest only** to an **explicitly configured** `--service-url` (or `QCODER_PRO_API_URL`). Use it only when QRS has given you a service URL and token. The default `https://qcoder.ai/preview` URL is **not** accepted for submit.
-- There is **no generally available production hosted Pro service**, account/token issuance, or artifact upload in this public-main surface. Production hosted service, Cloud Run/GCS, and confidential analysis are separate/future.
+- There is **no generally available production hosted Pro service**, account/token issuance, artifact/source upload, telemetry/training ingest, confidential local analyzer/cards, QPU/provider execution, or launched Pro V0.0 behavior in this public-main surface.
 - **No confidential Pro analysis or cards** are bundled in this package. Token-gating is **access control only**, not a secrecy boundary.
 
 ## Quick start
@@ -91,6 +93,27 @@ Use **`--dry-run-manifest`** unless QRS has given you a non-default service URL
 qcoder pro workflow --qasm path/to/circuit.qasm --submit --service-url <url-qrs-provided>
 ```
 
+**Support-safe checklist for Pro Preview pilots**
+
+Safe to share with QRS support:
+
+- `qcoder --version`
+- command name
+- HTTP status or CLI error code
+- `job_id`, if produced
+- redacted output
+- manifest schema/version
+
+Do not share:
+
+- bearer tokens
+- secrets
+- source code
+- repository archives
+- notebooks
+- private prompts or chat transcripts
+- raw QASM/source artifacts through unsupported paths
+
 Architecture notes: [`docs/architecture.md`](docs/architecture.md).
 
 ## Optional extras

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/README.md

@@ -16,11 +16,13 @@ Free `qcoder` commands run offline and do not call hosted services, upload telem
 
 Public `qcoder` ships **Free local commands** plus a **Pro bootstrap/client contract**. It is **not** the sellable hosted Pro product.
 
-- **Free commands** (`analyze`, `batch`, `context`, `review`) run offline. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
+For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a2`**. It is not Pro V0.0 and not a sellable launched Pro product.
+
+- **Free commands** (`analyze`, `batch`, `context`, `review`) are Apache-2.0, local-first/offline, and useful without Pro. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
 - **`qcoder pro` bootstrap** (`signup`, `login`, `install`, `status`, `validate`) stores local token/config only. It does not upload circuits, run confidential analysis, or generate Pro cards locally.
 - **`qcoder pro workflow --dry-run-manifest`** writes a local JSON contract (`qcoder.pro_preview.workflow_manifest.v0`) and performs **no network calls**. This is the default path for most users.
 - **`qcoder pro workflow --submit`** posts a **sanitized manifest only** to an **explicitly configured** `--service-url` (or `QCODER_PRO_API_URL`). Use it only when QRS has given you a service URL and token. The default `https://qcoder.ai/preview` URL is **not** accepted for submit.
-- There is **no generally available production hosted Pro service**, account/token issuance, or artifact upload in this public-main surface. Production hosted service, Cloud Run/GCS, and confidential analysis are separate/future.
+- There is **no generally available production hosted Pro service**, account/token issuance, artifact/source upload, telemetry/training ingest, confidential local analyzer/cards, QPU/provider execution, or launched Pro V0.0 behavior in this public-main surface.
 - **No confidential Pro analysis or cards** are bundled in this package. Token-gating is **access control only**, not a secrecy boundary.
 
 ## Quick start
@@ -61,6 +63,27 @@ Use **`--dry-run-manifest`** unless QRS has given you a non-default service URL
 qcoder pro workflow --qasm path/to/circuit.qasm --submit --service-url <url-qrs-provided>
 ```
 
+**Support-safe checklist for Pro Preview pilots**
+
+Safe to share with QRS support:
+
+- `qcoder --version`
+- command name
+- HTTP status or CLI error code
+- `job_id`, if produced
+- redacted output
+- manifest schema/version
+
+Do not share:
+
+- bearer tokens
+- secrets
+- source code
+- repository archives
+- notebooks
+- private prompts or chat transcripts
+- raw QASM/source artifacts through unsupported paths
+
 Architecture notes: [`docs/architecture.md`](docs/architecture.md).
 
 ## Optional extras

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qcoder"
-version = "0.5.0a2"
+version = "0.5.0a3"
 description = "Quantum circuit analysis and structured feature extraction tools."
 readme = "README.md"
 requires-python = ">=3.11"

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/src/qcoder/__init__.py

@@ -1,3 +1,3 @@
 __all__ = []
-__version__ = "0.5.0a2"
+__version__ = "0.5.0a3"
 file = __file__

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/src/qcoder/cli.py

@@ -17,6 +17,12 @@ from qcoder.pro_preview.config import (
     store_local_bootstrap_config,
 )
 from qcoder.pro_preview.client import ProServiceClient, ProServiceClientError
+from qcoder.pro_preview.client import (
+    PreviewClientNetworkError,
+    call_builtin_review_demo,
+    resolve_preview_client_config,
+    summarize_demo_payload,
+)
 from qcoder.pro_preview.errors import ProPreviewManifestError
 from qcoder.pro_preview.manifest import (
     build_workflow_manifest,
@@ -28,6 +34,12 @@ from qcoder.tools.batch import analyze_qasm_dir_to_jsonl
 PREVIEW_SIGNUP_URL = "https://qcoder.ai/preview"
 
 
+def _is_non_default_service_url(value: str | None) -> bool:
+    if not value:
+        return False
+    return value.strip() != DEFAULT_PRO_API_URL
+
+
 def _build_pro_bootstrap_payload(status: str) -> dict[str, object]:
     token = resolve_token()
     api_url = resolve_api_url()
@@ -242,6 +254,48 @@ def _cmd_review(argv: list[str]) -> int:
     return 0
 
 
+def _run_pro_preview_demo_check(*, base_url_override: str | None) -> int:
+    try:
+        config = resolve_preview_client_config(base_url_override=base_url_override)
+    except ValueError as exc:
+        print(f"qcoder pro preview: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        response = call_builtin_review_demo(config)
+    except PreviewClientNetworkError:
+        print(
+            "qCoder Pro Preview demo: FAIL (network). Base URL may be unreachable.",
+            file=sys.stderr,
+        )
+        print(f"  base_url: {config.base_url}", file=sys.stderr)
+        return 2
+
+    if response.status_code == 200:
+        print("qCoder Pro Preview demo: PASS (HTTP 200).")
+        print(f"  base_url: {config.base_url}")
+        for line in summarize_demo_payload(response.payload):
+            print(f"  {line}")
+        return 0
+    if response.status_code == 401:
+        print(
+            "qCoder Pro Preview demo: FAIL (HTTP 401). Token is missing, invalid, or revoked.",
+            file=sys.stderr,
+        )
+        return 1
+    if response.status_code == 403:
+        print(
+            "qCoder Pro Preview demo: FAIL (HTTP 403). Private/outer service access may be blocking access.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"qCoder Pro Preview demo: FAIL (HTTP {response.status_code}).", file=sys.stderr)
+    for line in summarize_demo_payload(response.payload):
+        print(f"  {line}", file=sys.stderr)
+    return 2
+
+
 def _cmd_pro(argv: list[str]) -> int:
     p = argparse.ArgumentParser(
         prog="qcoder pro",
@@ -265,16 +319,24 @@ def _cmd_pro(argv: list[str]) -> int:
     p_status.set_defaults(pro_command="status")
 
     p_login = sub.add_parser("login", help="Store Preview token locally (no remote validation in this slice).")
-    p_login.add_argument("--token", required=True, help="Preview token for local entitlement/config bootstrap.")
+    p_login.add_argument(
+        "--token",
+        required=True,
+        help="QRS-provided Preview token for local config. Treat as private credential.",
+    )
     p_login.add_argument("--api-url", required=False, help="Optional service URL override for local config.")
     p_login.set_defaults(pro_command="login")
 
-    p_install = sub.add_parser("install", help="Configure local Pro bootstrap token (no code download in this slice).")
-    p_install.add_argument("--token", required=True, help="Preview token for local bootstrap config.")
+    p_install = sub.add_parser("install", help="Configure local Pro Preview token (no code download in this slice).")
+    p_install.add_argument(
+        "--token",
+        required=True,
+        help="QRS-provided Preview token for local config. Treat as private credential.",
+    )
     p_install.add_argument("--api-url", required=False, help="Optional service URL override for local config.")
     p_install.set_defaults(pro_command="install")
 
-    p_validate = sub.add_parser("validate", help="Validate local Pro bootstrap config and public boundary posture.")
+    p_validate = sub.add_parser("validate", help="Validate local Pro Preview config and public package boundaries.")
     p_validate.set_defaults(pro_command="validate")
 
     p_workflow = sub.add_parser(
@@ -307,6 +369,31 @@ def _cmd_pro(argv: list[str]) -> int:
     )
     p_workflow.set_defaults(pro_command="workflow")
 
+    p_preview = sub.add_parser("preview", help="Hosted Preview demo connectivity checks.")
+    p_preview_sub = p_preview.add_subparsers(dest="pro_preview_command")
+
+    p_preview_status = p_preview_sub.add_parser(
+        "status",
+        help="Call hosted Preview demo endpoint and print safe connectivity summary.",
+    )
+    p_preview_status.add_argument(
+        "--base-url",
+        default=None,
+        help="Override hosted Preview base URL (default env: QCODER_PREVIEW_BASE_URL or QCODER_PRO_API_URL).",
+    )
+    p_preview_status.set_defaults(pro_command="preview-status")
+
+    p_preview_demo = p_preview_sub.add_parser(
+        "demo",
+        help="Alias of preview status check; calls /v0/demo/builtin-review.",
+    )
+    p_preview_demo.add_argument(
+        "--base-url",
+        default=None,
+        help="Override hosted Preview base URL (default env: QCODER_PREVIEW_BASE_URL or QCODER_PRO_API_URL).",
+    )
+    p_preview_demo.set_defaults(pro_command="preview-demo")
+
     args, unknown = p.parse_known_args(argv)
     cmd = args.pro_command
     json_output = args.json or ("--json" in unknown)
@@ -335,16 +422,20 @@ def _cmd_pro(argv: list[str]) -> int:
 
     if cmd == "status":
         payload = _build_pro_bootstrap_payload(status="configured" if resolve_token().present else "not_configured")
+        submit_ready = bool(payload["token_present"]) and _is_non_default_service_url(resolve_api_url().value)
         if json_output:
             print(json.dumps(payload, indent=2, sort_keys=True))
         else:
             print(f"qCoder Pro status: {payload['status']}.")
             print("  mode: service-backed bootstrap shell")
             print(f"  token: {'present' if payload['token_present'] else 'not set'} ({payload['token_source']})")
-            print(
-                f"  api_url: {'configured' if payload['api_url_configured'] else 'not set'} "
-                f"({payload['api_url_source']})"
-            )
+            if payload["api_url_source"] == "default":
+                print("  submit-ready service URL: not set (default Preview URL is informational)")
+            else:
+                print("  submit-ready service URL: configured")
+            print(f"  service URL source: {payload['api_url_source']}")
+            print(f"  pilot submit readiness: {'ready' if submit_ready else 'not ready'}")
+            print("  submit requirement: QRS-provided token + non-default service URL")
             print("  service validation: not available in this slice")
             print("  local cards/analysis: disabled in public package")
             print(f"  signup: {PREVIEW_SIGNUP_URL}")
@@ -362,10 +453,11 @@ def _cmd_pro(argv: list[str]) -> int:
         if json_output:
             print(json.dumps(payload, indent=2, sort_keys=True))
         else:
-            print("Configured qCoder Pro Preview/V0 local bootstrap.")
+            print("Configured qCoder Pro Preview local token settings.")
             print(f"  operation: {cmd}")
             print(f"  config: {config_path}")
             print("  token: stored locally (not displayed)")
+            print("  token hygiene: do not paste tokens into tickets, screenshots, or chat")
             print("  service validation: not performed in this slice")
             print("  upload: none performed")
             print("  local package: non-confidential bootstrap plumbing only")
@@ -381,6 +473,7 @@ def _cmd_pro(argv: list[str]) -> int:
         except ProPreviewConfigError:
             local_config_valid = False
         pro_v0_py_exists = any((Path(__file__).resolve().parent / "pro_v0").glob("*.py"))
+        submit_ready = token.present and _is_non_default_service_url(api_url.value)
         payload = {
             "schema_id": "qcoder.pro_preview_validate.v0",
             "status": "ok" if local_config_valid else "config_error",
@@ -403,12 +496,22 @@ def _cmd_pro(argv: list[str]) -> int:
             print("qCoder Pro validate")
             print(f"  status: {payload['status']}")
             print(f"  token: {'present' if token.present else 'not set'} ({token.source})")
-            print(f"  api_url: {'configured' if api_url.present else 'not set'} ({api_url.source})")
-            print(f"  pro_v0 local module present: {pro_v0_py_exists}")
+            if api_url.source == "default":
+                print("  submit-ready service URL: not set (default Preview URL is informational)")
+            else:
+                print("  submit-ready service URL: configured")
+            print(f"  service URL source: {api_url.source}")
+            print(f"  public package boundary checks: {'ok' if payload['public_boundary_ok'] else 'needs attention'}")
+            print(f"  pilot submit readiness: {'ready' if submit_ready else 'not ready'}")
+            print("  submit requirement: QRS-provided token + non-default service URL")
             print("  service validation: not available in this slice")
             print("  local cards/confidential analysis: absent")
+            print("  artifact/source upload: not performed in this command path")
         return 0 if payload["status"] == "ok" else 2
 
+    if cmd in {"preview-status", "preview-demo"}:
+        return _run_pro_preview_demo_check(base_url_override=args.base_url)
+
     if cmd == "workflow":
         if args.dry_run_manifest:
             try:
@@ -466,7 +569,8 @@ def _cmd_pro(argv: list[str]) -> int:
             if not token.present:
                 print(
                     "qcoder pro workflow: --submit requires a configured token.\n"
-                    "Run `qcoder pro login --token <token>` or set QCODER_PRO_TOKEN.",
+                    "Run `qcoder pro login --token <token>` or set QCODER_PRO_TOKEN.\n"
+                    "Do not share your token in tickets, screenshots, or chat.",
                     file=sys.stderr,
                 )
                 return 2
@@ -483,7 +587,8 @@ def _cmd_pro(argv: list[str]) -> int:
                 print(
                     "qcoder pro workflow: No production hosted Pro service is configured for "
                     "this release. Service submit URL is not configured; use --service-url or "
-                    "QCODER_PRO_API_URL only if QRS provided one.",
+                    "QCODER_PRO_API_URL only if QRS provided one.\n"
+                    "For support, share only redacted output and error/status codes.",
                     file=sys.stderr,
                 )
                 return 2

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/src/qcoder/pro_preview/__init__.py

@@ -1,4 +1,4 @@
-"""Public-safe Pro Preview/V0 bootstrap plumbing (non-confidential only)."""
+"""Public-safe Pro Preview client surface helpers (non-confidential only)."""
 
 from qcoder.pro_preview.config import (
     ProPreviewConfigError,
@@ -7,7 +7,16 @@ from qcoder.pro_preview.config import (
     resolve_token,
     store_local_bootstrap_config,
 )
-from qcoder.pro_preview.client import ProServiceClient, ProServiceClientError
+from qcoder.pro_preview.client import (
+    PreviewClientConfig,
+    PreviewClientNetworkError,
+    PreviewClientResponse,
+    ProServiceClient,
+    ProServiceClientError,
+    call_builtin_review_demo,
+    resolve_preview_client_config,
+    summarize_demo_payload,
+)
 from qcoder.pro_preview.errors import ProPreviewManifestError
 from qcoder.pro_preview.manifest import (
     WORKFLOW_MANIFEST_SCHEMA_ID,
@@ -17,16 +26,22 @@ from qcoder.pro_preview.manifest import (
 )
 
 __all__ = [
+    "PreviewClientConfig",
+    "PreviewClientNetworkError",
+    "PreviewClientResponse",
     "ProPreviewConfigError",
+    "ProPreviewManifestError",
     "ProServiceClient",
     "ProServiceClientError",
-    "ProPreviewManifestError",
     "WORKFLOW_MANIFEST_SCHEMA_ID",
     "build_workflow_manifest",
+    "call_builtin_review_demo",
     "load_local_config",
     "resolve_api_url",
+    "resolve_preview_client_config",
     "resolve_token",
     "sanitize_manifest_for_submit",
     "store_local_bootstrap_config",
+    "summarize_demo_payload",
     "write_workflow_manifest",
 ]

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/src/qcoder/pro_preview/client.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+import os
 import json
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Mapping
 from urllib.error import HTTPError, URLError
 from urllib.parse import urljoin
 from urllib.request import Request, urlopen
@@ -120,3 +121,97 @@ def _parse_http_error(exc: HTTPError) -> ServiceErrorDetail:
     else:
         safe_message = f"service returned HTTP {status_code}"
     return ServiceErrorDetail(status_code=status_code, error_code=error_code, message=safe_message)
+
+PREVIEW_BASE_URL_ENV = "QCODER_PREVIEW_BASE_URL"
+PREVIEW_TOKEN_ENV = "QCODER_PREVIEW_TOKEN"
+PRO_API_URL_ENV = "QCODER_PRO_API_URL"
+PRO_TOKEN_ENV = "QCODER_PRO_TOKEN"
+BUILTIN_REVIEW_PATH = "/v0/demo/builtin-review"
+
+
+@dataclass(frozen=True)
+class PreviewClientConfig:
+    base_url: str
+    token: str
+
+
+@dataclass(frozen=True)
+class PreviewClientResponse:
+    status_code: int
+    payload: dict[str, Any] | None
+
+
+class PreviewClientNetworkError(RuntimeError):
+    """Raised when hosted Preview cannot be reached."""
+
+
+def resolve_preview_client_config(
+    *, base_url_override: str | None = None, env_map: Mapping[str, str] | None = None
+) -> PreviewClientConfig:
+    env = os.environ if env_map is None else env_map
+    base_url = _normalize_base_url(
+        base_url_override
+        if base_url_override is not None
+        else str(env.get(PREVIEW_BASE_URL_ENV) or env.get(PRO_API_URL_ENV) or "")
+    )
+    token = str(env.get(PREVIEW_TOKEN_ENV) or env.get(PRO_TOKEN_ENV) or "").strip()
+    if not token:
+        raise ValueError("missing hosted Preview token; set QCODER_PREVIEW_TOKEN or QCODER_PRO_TOKEN")
+    return PreviewClientConfig(base_url=base_url, token=token)
+
+
+def call_builtin_review_demo(
+    config: PreviewClientConfig, *, timeout_s: float = 10.0
+) -> PreviewClientResponse:
+    """Call the hosted Preview builtin-review demo endpoint.
+
+    HTTP 401/403 are valid service responses and must not be treated as
+    network failures.  HTTPError is a subclass of URLError, so keep this
+    handler before the URLError handler.
+    """
+    request = Request(
+        _join_service_url(config.base_url, BUILTIN_REVIEW_PATH),
+        headers={"Authorization": f"Bearer {config.token}"},
+        method="GET",
+    )
+    try:
+        with urlopen(request, timeout=timeout_s) as response:
+            body = response.read().decode("utf-8", errors="replace")
+            status_code = int(getattr(response, "status", 200))
+            return PreviewClientResponse(status_code=status_code, payload=_safe_json_decode(body))
+    except HTTPError as err:
+        body = err.read().decode("utf-8", errors="replace")
+        return PreviewClientResponse(status_code=int(err.code), payload=_safe_json_decode(body))
+    except URLError as exc:
+        raise PreviewClientNetworkError(str(exc)) from exc
+
+def summarize_demo_payload(payload: dict[str, Any] | None) -> list[str]:
+    if not payload:
+        return []
+    lines: list[str] = []
+    for key in ("service", "mode", "status", "demo_level"):
+        value = payload.get(key)
+        if isinstance(value, (str, int, float, bool)):
+            lines.append(f"  {key}: {value}")
+    samples = payload.get("samples")
+    if isinstance(samples, list):
+        lines.append(f"  samples: {len(samples)}")
+    return lines
+
+
+def _normalize_base_url(raw_base_url: str) -> str:
+    base_url = raw_base_url.strip().rstrip("/")
+    if not base_url:
+        raise ValueError(
+            "missing hosted Preview base URL; set QCODER_PREVIEW_BASE_URL or "
+            "QCODER_PRO_API_URL, or pass --base-url"
+        )
+    return base_url
+
+
+def _safe_json_decode(raw: str) -> dict[str, Any] | None:
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return payload if isinstance(payload, dict) else None

{qcoder-0.5.0a2 → qcoder-0.5.0a3}/src/qcoder.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qcoder
-Version: 0.5.0a2
+Version: 0.5.0a3
 Summary: Quantum circuit analysis and structured feature extraction tools.
 Author-email: Quantum Ready Solutions <support@qcoder.ai>
 Maintainer-email: Quantum Ready Solutions <support@qcoder.ai>
@@ -46,11 +46,13 @@ Free `qcoder` commands run offline and do not call hosted services, upload telem
 
 Public `qcoder` ships **Free local commands** plus a **Pro bootstrap/client contract**. It is **not** the sellable hosted Pro product.
 
-- **Free commands** (`analyze`, `batch`, `context`, `review`) run offline. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
+For a public, pilot-safe walkthrough, see the [Pro Preview pilot walkthrough](https://qcoder.ai/manual/pro-preview-pilot-walkthrough/). The current public PyPI alpha client surface for Pro Preview is **`qcoder==0.5.0a2`**. It is not Pro V0.0 and not a sellable launched Pro product.
+
+- **Free commands** (`analyze`, `batch`, `context`, `review`) are Apache-2.0, local-first/offline, and useful without Pro. They do not upload data, call a qCoder hosted service, or run QPU/simulator jobs.
 - **`qcoder pro` bootstrap** (`signup`, `login`, `install`, `status`, `validate`) stores local token/config only. It does not upload circuits, run confidential analysis, or generate Pro cards locally.
 - **`qcoder pro workflow --dry-run-manifest`** writes a local JSON contract (`qcoder.pro_preview.workflow_manifest.v0`) and performs **no network calls**. This is the default path for most users.
 - **`qcoder pro workflow --submit`** posts a **sanitized manifest only** to an **explicitly configured** `--service-url` (or `QCODER_PRO_API_URL`). Use it only when QRS has given you a service URL and token. The default `https://qcoder.ai/preview` URL is **not** accepted for submit.
-- There is **no generally available production hosted Pro service**, account/token issuance, or artifact upload in this public-main surface. Production hosted service, Cloud Run/GCS, and confidential analysis are separate/future.
+- There is **no generally available production hosted Pro service**, account/token issuance, artifact/source upload, telemetry/training ingest, confidential local analyzer/cards, QPU/provider execution, or launched Pro V0.0 behavior in this public-main surface.
 - **No confidential Pro analysis or cards** are bundled in this package. Token-gating is **access control only**, not a secrecy boundary.
 
 ## Quick start
@@ -91,6 +93,27 @@ Use **`--dry-run-manifest`** unless QRS has given you a non-default service URL
 qcoder pro workflow --qasm path/to/circuit.qasm --submit --service-url <url-qrs-provided>
 ```
 
+**Support-safe checklist for Pro Preview pilots**
+
+Safe to share with QRS support:
+
+- `qcoder --version`
+- command name
+- HTTP status or CLI error code
+- `job_id`, if produced
+- redacted output
+- manifest schema/version
+
+Do not share:
+
+- bearer tokens
+- secrets
+- source code
+- repository archives
+- notebooks
+- private prompts or chat transcripts
+- raw QASM/source artifacts through unsupported paths
+
 Architecture notes: [`docs/architecture.md`](docs/architecture.md).
 
 ## Optional extras