docs: use public a2 and current SDK contracts throughout maintained guides

.agents/README.md

@@ -168,4 +168,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 
 - [Command execution deadline](notes/proposed/feature/2026-10-25-command-execution-deadline.md) · [verification](evidence/verify/2026-10-25-command-execution-deadline.md)
 
+- [Current public SDK documentation](notes/proposed/process/2026-10-25-public-sdk-documentation.md) · [verification](evidence/verify/2026-10-25-public-sdk-documentation.md)
 - [Bounded public PyPI readback](notes/proposed/process/2026-10-25-pypi-public-readback.md) · [verification](evidence/verify/2026-10-25-pypi-public-readback.md)

.agents/evidence/verify/2026-10-25-public-sdk-documentation-benchmark.json

@@ -0,0 +1,11 @@
+{
+  "source": "client-sdk/benchmarks/bench_create.py",
+  "source_sha256": "2927f443f4ac89c57e5f2961f267a96d7cf66b94c326c44953faa0248c6e5637",
+  "public_client_server": "0.4.0a2",
+  "source_path_injection": false,
+  "actual_source_public_kwargs_sentinel_binding": true,
+  "owned_created": 3,
+  "independent_get_info_typed404": 3,
+  "result": "PASS",
+  "seconds": 4.47
+}

.agents/evidence/verify/2026-10-25-public-sdk-documentation-cloud.json

@@ -0,0 +1,35 @@
+{
+  "public_packages": "0.4.0a2",
+  "cases": [
+    {
+      "guide": "docs/en/guide/getting-started.md",
+      "sha256": "3b4dee410a0d373cb1841111e3693b77045ef8718172356706aed1c1f5405ab2",
+      "status": "PASS",
+      "operations": [
+        "create",
+        "command",
+        "file write/read",
+        "download",
+        "upload",
+        "kill on context exit",
+        "independent typed absence"
+      ],
+      "owned_cleanup": "PASS"
+    },
+    {
+      "guide": "docs/zh/guide/getting-started.md",
+      "sha256": "ce3b8b9dd36b6131f29f4186c1076b2cdc6d68caa6f28e97d1fbd98e8a8b2c6d",
+      "status": "PASS",
+      "operations": [
+        "create",
+        "command",
+        "file write/read",
+        "download",
+        "upload",
+        "kill on context exit",
+        "independent typed absence"
+      ],
+      "owned_cleanup": "PASS"
+    }
+  ]
+}

.agents/evidence/verify/2026-10-25-public-sdk-documentation-index.json

@@ -0,0 +1,7 @@
+{
+  "package": "agent-sandbox-server==0.4.0a2",
+  "configured_index": "https://example.invalid/simple",
+  "explicit_index": "https://pypi.org/simple",
+  "download": "PASS",
+  "original_public_wheel_sha256_equal": true
+}

.agents/evidence/verify/2026-10-25-public-sdk-documentation-migration.json

@@ -0,0 +1,36 @@
+{
+  "source": "examples/compat-demos/e2b_import_migration.py",
+  "source_sha256": "73850fb33989c4b412ce5399f2303df1ca642ad5d15fe6cbd8088e7ef0819415",
+  "source_commit": "c8f5d48dc015b6bdcb65455285c651edf8c1eafd",
+  "installed_packages": {
+    "agent-sandbox-client": "0.4.0a2",
+    "agent-sandbox-server": "0.4.0a2"
+  },
+  "credential_names": [
+    "ABX_SANDBOX_API_KEY",
+    "ABX_SANDBOX_BASE_URL",
+    "ABX_SANDBOX_DOMAIN"
+  ],
+  "E2B_environment_set": false,
+  "result": "PASS",
+  "seconds": 4.27,
+  "checks": [
+    "standard sync create",
+    "file write/read",
+    "shell exit/output",
+    "persistent interpreter 41 to 42",
+    "owned context kill",
+    "independent get_info typed404"
+  ],
+  "audit": {
+    "created": 1,
+    "cleanup": [
+      {
+        "absent_before_cleanup": true,
+        "absent_after_cleanup": true
+      }
+    ],
+    "example_exit": 0
+  },
+  "owned_cleanup": "PASS"
+}

.agents/evidence/verify/2026-10-25-public-sdk-documentation.md

@@ -0,0 +1,138 @@
+# Verification: current public SDK documentation
+
+- Date: 2026-10-25
+- Tested base: dab0e3194e3f790fab28307d9fd126b8239bcbd7 plus scoped documentation changes.
+- Package under test: official PyPI agent-sandbox-client/server 0.4.0a2.
+- Environment: Linux, fresh Python 3.13.13 venv, Express account configured via
+  canonical environment variables; values and resource IDs are not recorded.
+- Result: PASS for documentation-specific execution below; broader example suite
+  remains PARTIAL because the browser cold installation failed.
+
+## From-page real execution
+
+- Install: fresh venv, official-index exact `agent-sandbox-client==0.4.0a2`, pip
+  check, public sync/async/provider/server imports all PASS. Both distribution
+  versions are exactly 0.4.0a2. Source import injection was not used.
+- Extract the first Python fence from each actual `getting-started.md` page,
+  save it as a script outside the checkout and run with the fresh environment.
+  Both complete scripts PASS: create base, command output/exit status, file
+  write/read, download, upload, content equality and context-manager kill.
+- Independently call `ProviderSandbox.get_info_by_id` for each created ID:
+  typed `SandboxNotFoundError` PASS. No owned sandboxes remain.
+- [Machine-readable source hashes and results](2026-10-25-public-sdk-documentation-cloud.json).
+
+## Public signature and local HTTP execution
+
+- Inspect published `sandbox` and `create_mcp_app` signatures: sandbox_api_key,
+  sandbox_base_url and sandbox_domain present; api_key/api_url/domain absent.
+- Confirm native `ProviderSandbox.create_sync` remains callable; retain it.
+- Install exact `agent-sandbox-client[mcp]==0.4.0a2` from official PyPI, as the
+  HTTP guide requires. Construct its documented create_mcp_app with the corrected
+  sandbox_api_key argument: real ASGI `/health` 200 and unauthenticated `/mcp` 401 PASS.
+- Construct a decorator with all three canonical configuration arguments: PASS.
+  This only validates configuration, not another remote function execution.
+
+## Independent broader public example rerun
+
+The maintainer's new public-a2 rerun executed all fourteen cloud examples: thirteen
+PASS; browser example FAIL while installing Chromium and dependencies on base
+under its 300-second command deadline (406.73 seconds total including preceding pip).
+Every owned sandbox was independently confirmed absent with typed 404. The real
+Qwen-generated sorting example passed. Local protocol fixtures are not real agent
+executions. These observations do not certify a new template image or the entire
+template matrix. The failure is retained, and browser setup/default-template policy
+is pending user choice. This documentation change does not close
+[Issue 111](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/111).
+
+## Published deadline verification
+
+The independent public-a2 check observed typed CommandTimeout for silent output
+(1.353 seconds) and continuous output (1.159 seconds). Each exact observed owned
+PID was absent from process.list afterwards, a subsequent command worked, and
+the owned sandbox was independently absent with typed 404. This closes the runtime
+deadline acceptance scope of [Issue 113](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/113),
+separately from the unfinished browser scope in Issue 111.
+
+## Unverified comparison claims removed
+
+Replace the comparison page's unsupported startup-time, GPU, lifetime, competitor
+infrastructure/pricing and stale tool-count assertions with actual project entry
+contracts and prerequisites. Keep standard interpreter, base command/file and
+launched application examples distinct. No competitor capability claim or new
+benchmark is introduced. Main README and contributor entry points recommend
+unified launch; image build/deploy remain advanced preparation steps.
+
+## Example README correction
+
+The EN/ZH core API overview previously put interpreter and hello named-command
+calls inside a base ProviderSandbox context. Split this confirmed misleading
+example into base shell execution, the actual standard interpreter entry, and
+a separately launched python-hello application bound with application_client(token).
+No runtime helper or fallback is added. Correct the example table, decorator
+template ID, writable file path and canonical configuration wording together.
+
+## Repository skills
+
+The current SDK/provider SKILL.md files now use published a2 instead of claiming
+a1 is awaiting publication. Their installation/Dockerfile pins and shared ABX
+configuration agree with the user guides. Original public client/server wheels
+and sdists contain neither skill file, so this Git documentation fix does not
+replace or require rebuilding the immutable published a2 artifacts.
+
+## Static checks and limits
+
+- PASS: repository health 106 PASS / 1 warning / 0 failures; hygiene PASS.
+- PASS: scan maintained docs/READMEs for retired Git-archive install pins and old
+  decorator/MCP keywords. Historical explicitly retired provider-engine design and
+  merged evidence remain history; actual third-party api_key/domain options remain.
+- Follow-up review: canonical ABX configuration is supported by all project
+  entries, including standard sync/async/interpreter; it is not ProviderSandbox-only.
+  Corrected this wording in the installation, beginner, migration and example guides.
+  Standard public api_key parameters and real third-party E2B configuration remain valid.
+  The import-migration example changes only its configuration docstring, not code.
+- Documentation-only change: no product runtime or test implementation changed.
+  Full package CI remains enforced by the PR; unrelated cloud matrix is not rerun
+  merely for prose. CLI source preparation and new application images are being
+  separately verified by their owning repositories; no new success claim is made here.
+
+## Final official-index and benchmark follow-up
+
+A real template build found the Alibaba base-image pip mirror still listing only
+a1. All maintained first-party public install instructions now explicitly select
+`https://pypi.org/simple`, including skill Dockerfiles and package READMEs. No
+source fallback or retry is added. A real pip download with an intentionally
+different configured index succeeded through the explicit official index and
+matched the original public a2 server wheel digest.
+
+The maintained release guide now states actual published a2 facts and requires a
+new reviewed lockstep tag for a future release, rather than calling a1 unreleased.
+
+The creation benchmark used obsolete TransportConfig api_key/api_url/domain
+arguments. Actual public a2 construction silently ignored all three sentinel
+values. The benchmark now uses the explicit public ProviderSandbox entry and
+canonical parameters with the normally installed package. It creates three fixed
+samples, deletes and closes each owned sandbox before the next iteration,
+propagates cleanup failures, prints no IDs, and reports only this run's samples.
+No product runtime configuration behavior is changed.
+
+- PASS: 3 benchmark regressions cover a failing second create, a failing kill
+  with close still executed, and exactly three successful owned lifecycles.
+- PASS: execute the actual benchmark with public a2: three creates, three
+  independent get_info_by_id typed NotFound results, no leaked resources.
+- PASS: rerun the updated import-migration script from its documented path using
+  only ABX configuration, no E2B environment or source injection: files, shell,
+  persistent interpreter 41-to-42, owned kill and independent typed absence.
+- PASS: full client suite 2264 passed / 27 skipped; lint, typecheck, format checks.
+- PARTIAL: full local server suite 873 passed / 1 skipped / 2 raw-loopback
+  failures: missing-key WebSocket expected400/actual501 and chunked framing
+  expected400/actual502. The earlier original-tag official CI passed; this PR's
+  latest-head official matrix remains required, not inferred from that earlier run.
+- PASS: repository health106 / warning1 / failure0, hygiene and diff checks.
+
+New receipts preserve the separate executed sources:
+[benchmark](2026-10-25-public-sdk-documentation-benchmark.json),
+[migration](2026-10-25-public-sdk-documentation-migration.json),
+[official index](2026-10-25-public-sdk-documentation-index.json).
+The broader old example results remain unchanged; the browser case in Issue111
+still has its own unresolved acceptance scope. Docker fixture repair/build
+acceptance is tracked separately and is not claimed by this PR.

.agents/notes/proposed/process/2026-10-25-public-sdk-documentation.md

@@ -0,0 +1,62 @@
+# Decision: Use current public SDK contracts in maintained guides
+Status: proposed
+
+## Problem
+
+Maintained guides still installed a retired Git archive or older alpha packages,
+published decorator/MCP keyword names absent from current signatures, mixed MCP
+credentials with the standard E2B entry, and described the removed local Python
+gRPC engine. The Express quickstart bypassed the current template launcher. The maintained
+creation benchmark silently ignored old configuration names and could skip
+cleanup after a later failure.
+
+## Decision
+
+Use public paired 0.4.0a2 installations, canonical sandbox_* configuration and
+explicit root ProviderSandbox imports for provider-extension examples. Preserve
+valid native synchronous wrappers and genuine third-party provider options.
+Use the official PyPI index explicitly for public installs. The maintained
+benchmark uses the installed public ProviderSandbox API, exactly three samples
+and explicit per-sandbox cleanup; it adds no product runtime or compatibility API.
+Use the single template launcher for application startup, with application tokens
+separate from platform credentials. Keep standard-client migration documentation
+separate and preserve historical design/evidence files that are labeled retired.
+
+## API Design
+
+No new API, alias, compatibility path or version is introduced. Correct the
+maintained guides to match the actual published decorator and MCP signatures.
+The beginner tutorial uses base command/file operations; it does not claim an
+unimplemented Express ProviderSandbox interpreter operation.
+
+## Alternatives considered
+
+Keeping old examples with fallback aliases conflicts with the requested cleanup.
+Replacing every api_key or domain occurrence would corrupt valid external SDK and
+provider-option contracts. Rewriting historical engineering receipts would destroy
+the distinction between previously tested and current behavior.
+
+## Dependencies
+
+Official PyPI paired packages and the separately maintained CLI template launcher.
+
+## Test Strategy
+
+Execute complete English and Chinese beginner scripts extracted from the actual
+pages using fresh public packages, assert command/file transfer behavior and
+independently verify owned sandbox absence. Inspect actual public signatures and
+run the documented MCP HTTP app health/auth locally. Run document, link, health
+and hygiene checks. Record the broader public example rerun separately and honestly.
+
+## Acceptance criteria
+
+- Maintained installations and first-party examples use current public contracts.
+- Both beginner scripts pass with real Express resources and no leaked sandboxes.
+- MCP/decorator parameters match public a2; HTTP app health/auth work locally.
+- The independent browser cold-install failure remains recorded, not hidden or
+  treated as a passing example; Issue 111 remains open until its full criteria pass.
+
+## Evidence
+
+- [Verification](../../../evidence/verify/2026-10-25-public-sdk-documentation.md)
+- [Example cleanup Issue 111](https://github.com/Alibaba-Agent-Sandbox/python-sdk/issues/111)

AGENTS.md

@@ -5,7 +5,7 @@
 
 ## Project Overview
 
-**Agent Sandbox** (distribution name `agent-sandbox-client`, import `agent_sandbox`) provides standard synchronous/asynchronous Express clients and the explicit asynchronous `ProviderSandbox` for provider/server extensions. Standard entries follow the pinned Alibaba-supported E2B contract; conditional capabilities still depend on the actual account/function. Templates are built and deployed with `abx template build|deploy`; read `docs/en/guide/migrate-from-e2b.md` before changing either surface.
+**Agent Sandbox** (distribution name `agent-sandbox-client`, import `agent_sandbox`) provides standard synchronous/asynchronous Express clients and the explicit asynchronous `ProviderSandbox` for provider/server extensions. Standard entries follow the pinned Alibaba-supported E2B contract; conditional capabilities still depend on the actual account/function. Launch templates with `abx template launch <reference>`; advanced image preparation uses `abx template build|deploy`. Read `docs/en/guide/migrate-from-e2b.md` before changing either surface.
 
 This repository (`python-sdk`) holds the **Python SDK only**, split into two distributions that share the `agent_sandbox` namespace and are **versioned in lockstep** (same version number):
 

CHANGELOG.md

@@ -10,6 +10,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Fixed
 
+- Use the installed public provider API in the creation benchmark, clean each owned sandbox before continuing, propagate cleanup failures, and remove unsupported performance targets. / 创建基准改用已安装公开 Provider API，逐轮清理自有沙箱，透传清理错误并删除无依据性能目标。
+
+- Align maintained bilingual SDK guides with public 0.4.0a2, canonical decorator/MCP arguments, current ProviderSandbox imports and unified template launch. Remove stale source-install recipes and retired Python-engine instructions. / 将维护中的双语 SDK 指南统一为公开 0.4.0a2、规范装饰器/MCP 参数、ProviderSandbox 公开导入及统一模板启动；删除旧源码安装方案和已退役 Python 引擎说明。
 - Bound public PyPI metadata and fresh-install propagation retries while keeping artifact digest mismatches and dependency/import failures fatal. / 为公开 PyPI 元数据及全新安装增加有限传播重试，保持产物哈希、依赖与导入检查失败即中止。
 
 ### Fixed

README.md

@@ -14,7 +14,8 @@
 
 **Agent Sandbox** is a Python SDK for sandboxes. The default provider is Alibaba Cloud Express (`alicloud-express`, Function Compute). OpenSandbox, the container edition, CubeSandbox, and E2B are catalog `node` plugins in `awesome-providers` (`provider.mjs`). Install one with `abx provider install alibaba-agent-sandbox/awesome-providers//<id> --allow-unpinned --yes` (or `python -m agent_sandbox.providers install registry:<id> --yes`). After that, both `abx --provider <id>` and `ProviderSandbox.create(provider="<id>")` use it. The Python SDK reaches a `node` provider through the local engine (`abx provider engine serve`; `abx` on `PATH` or `ABX_BIN`). The CLI loads Express plus installed `node`, `exec` and `rest` plugins. It is the
 standard sync/async runtime and Template client. Project provider/server template launches use
-`abx template build|deploy` from the CLI. The SDK uses E2B-shaped method names so that E2B code
+`abx template launch <reference>` from the CLI; advanced image preparation uses
+`abx template build|deploy`. The SDK uses E2B-shaped method names so that E2B code
 ports with few changes; the standard API follows Alibaba-supported E2B behavior (see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md)).
 
 This repository (`python-sdk`) contains the **Python SDK**, packaged as two lock-step distributions. The `abx` command-line tool is a separate Node.js project that lives in the
@@ -58,14 +59,14 @@ Provider management operations are available through `agent_sandbox.providers.co
 - **In-image HTTP service** — `commands.py` imports `agent_sandbox.server` and calls `start(9000)`.
 - **Registered commands** — `@command` functions become routes the Client SDK calls with `sandbox.run`.
 - **Agents API** — Codex and Qwen Code HTTP sessions inside the sandbox. Install a CLI when you call it. Guide: [Agents API](docs/en/guide/agents-api.md).
-- **Templates** — the image and `template.yaml` are built and deployed with `abx template build|deploy`.
+- **Templates** — start the complete template with `abx template launch <reference>`; use `template build` / `template deploy` for advanced image preparation.
 
 ## Installation
 
 Use Python 3.10 or newer in a virtual environment. The client installs its matching server dependency automatically. See the [installation guide](docs/en/guide/install-python.md) for a pinned version, optional extras and development setup.
 
 ```bash
-python -m pip install --upgrade --pre agent-sandbox-client
+python -m pip install --index-url https://pypi.org/simple --upgrade --pre agent-sandbox-client
 python -m pip check
 ```