docs: synchronize current usage and engineering records

.agents/README.md

@@ -1,5 +1,18 @@
 # `.agents/` — engineering record of the python-sdk repository
 
+## Current delivery — 2026-10-24
+
+- Published client/server pair: **0.3.1a5**, with [immutable public artifacts, fresh installation and retained propagation failure](evidence/verify/2026-10-24-python-a5-public-release.md). This is an alpha release; host installation does not update in-image runtimes.
+- Standard `Sandbox`/`AsyncSandbox` and `code_interpreter` clients retain their migration contract. Asynchronous `ProviderSandbox` owns provider/server extensions; [SDK usage](../docs/en/guide/sdk-usage.md) now keeps process execution, interpreter calls, application HTTP and resource cleanup separate.
+- Python consumes installed Node providers through the CLI engine; exec/rest providers run directly. [Provider guidance](../docs/en/guide/providers.md) owns the language boundary and content-based Git catalog updates.
+- [Managed workflow acceptance](evidence/verify/2026-10-24-managed-native-workflows.md) and [proxy application authentication](evidence/verify/2026-10-24-application-proxy-token.md) record their exact operations. Unified interpreter support is not implied by shell execution on an interpreter image.
+- The [92-case matrix](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/78c30fbbd186cb59c3a0f0abd9fdf85b10c84b35/.agents/evidence/verify/2026-10-24-public-template-matrix.md) used public client/server host installation 0.3.1a5 and CLI 0.4.16. Dockerfile runtime pins remained their own inputs; real-model, PTY and desktop claims remain outside that matrix.
+
+[Documentation synchronization decision](notes/implemented/process/2026-10-24-current-docs-and-records.md) · [verification and acceptance reconciliation](evidence/verify/2026-10-24-current-docs-and-records.md).
+
+Earlier entries below are a decision history. A remaining proposal is not a current product guarantee; read the linked acceptance scope before treating its full criteria as complete.
+
+
 - [Native process OS user](notes/implemented/feature/2026-10-24-native-process-user.md) · [verification](evidence/verify/2026-10-24-native-process-user.md)
 
 Maintainer and AI-agent facing records of **why** the code looks the way it does. Nothing here is imported or
@@ -110,7 +123,7 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 
 - [Current compatibility-removal documentation verification](evidence/verify/2026-10-22-remove-legacy-docs.md).
 
-- [Explicit template workflows](notes/proposed/architecture/2026-10-23-template-workflow-contract.md) · [canonical vectors](evidence/verify/2026-10-23-workflow-foundation.md) · [provider operations](evidence/verify/2026-10-23-provider-workflow-operations.md) · [independent second-round review](evidence/verify/2026-10-23-workflow-round2-independent.md).
+- [Explicit template workflows](notes/implemented/architecture/2026-10-23-template-workflow-contract.md) · [canonical vectors](evidence/verify/2026-10-23-workflow-foundation.md) · [provider operations](evidence/verify/2026-10-23-provider-workflow-operations.md) · [independent second-round review](evidence/verify/2026-10-23-workflow-round2-independent.md).
 - [Workflow runtime implementation and review](evidence/verify/2026-10-23-workflow-runtime-review.md).
 - [Workflow migration real-cloud acceptance](evidence/verify/2026-10-23-workflow-real-cloud.md).
 - [Workflow CI follow-up](evidence/verify/2026-10-23-workflow-ci-followup.md).
@@ -124,7 +137,7 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 - [Complete OpenSandbox workflow acceptance](evidence/verify/2026-10-23-workflow-opensandbox-acceptance.md).
 - [Provider error reference anchors](evidence/verify/2026-10-23-workflow-provider-error-anchors.md).
 
-- [Python alpha release](notes/proposed/process/2026-10-24-python-alpha-release.md) · [verification](evidence/verify/2026-10-24-python-alpha-release.md)
+- [Python alpha release](notes/implemented/process/2026-10-24-python-alpha-release.md) · [verification](evidence/verify/2026-10-24-python-alpha-release.md)
 
 - [Python alpha real-component acceptance](evidence/verify/2026-10-24-python-alpha-cloud.md).
 

.agents/evidence/verify/2026-10-24-current-docs-and-records.md

@@ -0,0 +1,31 @@
+# Verification: current documentation and engineering records
+
+- Date: 2026-10-24
+- Result: PASS for local documentation checks; latest-head remote CI and review remain merge gates.
+- Baseline: `04e8a716aa341ca2c15c48bc0bc94c3adf8d5848`.
+- Scope: current Markdown documentation, lifecycle moves and owner index; no runtime or package change.
+
+## Accepted note reconciliation
+
+The GitHub API returned an actual merged timestamp and merge SHA for each linked PR:
+- `2026-10-24-python-alpha-release`: [merged PR #91](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/91).
+- `2026-10-23-template-workflow-contract`: [merged PR #89](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/89).
+
+This updates the notes' lifecycle, not the historical observations in their evidence. Subsequent source preparation, release and runtime acceptance is linked from the current `.agents/README.md` entry. Older proposals outside this scope retain their original state where their full acceptance criteria have not been re-established.
+
+## Validation
+
+- PASS: `bash scripts/check-repo-health.sh`: 106 passes, one existing recommendation warning, zero failures; `make hygiene`; `git diff --check`.
+- PASS: all 292 relative links in changed/new Markdown resolved locally; 12 Python blocks in the modified README/client/session pages parsed with `ast.parse`.
+- PASS: a fresh environment installed public `agent-sandbox-client==0.3.1a5` and its matching server. Public imports and current ProviderSandbox method names were checked. The actual `LocalSessionStore` saved, loaded, listed and deleted a temporary record; temporary storage was removed.
+- Independent review caught an incorrect draft inference that Python named sessions had been removed along with the CLI command. That draft was discarded: the final guide preserves the SDK feature, corrects the real `SessionManager` import and `list_sessions()` method, and distinguishes local metadata from remote snapshots and confirmed cleanup.
+- The full process/file/server guide is retained. Only the obsolete installation claim, default-code-capability promise and unsupported Express interpreter example were replaced; the README uses explicit process execution and cleanup.
+
+No new cloud resources or task credentials were created. Existing real-component receipts are references, not reruns under this documentation revision. The normal remote CI matrix remains mandatory; no runtime or publication workflow is weakened for this documentation change.
+
+## Packaged skill follow-up
+
+Independent review found the two current skills still instructed pre-release source-only installation, and their sample manifest/feature table contradicted the delivered workflow contract. Both now install public alpha 0.3.1a5, preserve standard versus Provider credentials, use an explicitly borrowed application binding, retain valid feature IDs and declare exact consumer operations. The SDK skill's source template uses spec 4 and aligns generation 2, readiness, port and runtime token input with the owning template skeleton; no unsupported host-kit interpreter is invented. Skill references were scanned for the same obsolete installation claims.
+
+- PASS: the actual public-a5 `parse_manifest` accepts the complete REST example; `SandboxTemplate.model_validate` accepts the skill's source template. All skill Python blocks parse with `ast.parse`.
+- Skill changes are instructions only. No image build, new cloud run, first Node package release or new Python package publication is claimed.

.agents/notes/proposed/architecture/2026-10-23-template-workflow-contract.md → .agents/notes/implemented/architecture/2026-10-23-template-workflow-contract.md

@@ -1,6 +1,6 @@
 # Decision: Explicit template workflows and operation contracts
 
-Status: proposed
+Status: implemented
 
 ## Problem
 Template application services, provider interpreter APIs and consuming clients were conflated. A code feature could incorrectly block an otherwise executable application, while shell fallback could conceal a missing interpreter.
@@ -36,3 +36,7 @@ Python and CLI pass the same vectors. Package copies match canonical bytes. Curr
 
 - [Native startup acknowledgment correction](../../../evidence/verify/2026-10-23-native-startup-acknowledgment.md).
 - [Complete OpenSandbox application workflow](../../../evidence/verify/2026-10-23-workflow-opensandbox-acceptance.md).
+
+## Implementation
+
+Delivered in [PR #89](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/89); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations.

.agents/notes/implemented/process/2026-10-24-current-docs-and-records.md

@@ -0,0 +1,26 @@
+# Decision: Synchronize current documentation and accepted records
+Status: implemented
+
+## Problem
+Current user guides and engineering entry points still contain stale installation, usage or pending-status descriptions after recent delivery.
+
+## Decision
+Update only this owner's current guides and index the actual release, implementation and verification boundaries. Reconcile dated notes with verified merged PRs. Preserve merged evidence verbatim and keep source/provider/consumer versions explicit.
+
+## API Design
+N/A — documentation only; no runtime API, package version or publication changes.
+
+## Alternatives considered
+Do not copy a whole cross-repository report or rewrite historical failures into passes. Do not infer broad platform support from an unrelated passing test.
+
+## Dependencies
+The already-merged owner PRs and dated receipts linked in this repository's engineering index. Related repositories own their own documentation and records.
+
+## Test Strategy
+Run document/record/link checks and the normal remote CI gates. Check examples against the current public API and existing real-component evidence. No cloud rerun is needed for this documentation-only synchronization.
+
+## Acceptance criteria
+Current English/Chinese instructions agree with implemented entry points; accepted notes match their state directory; local links resolve; old evidence is unchanged; required latest-head CI and independent review pass before merge.
+
+## Evidence
+[Verification](../../../evidence/verify/2026-10-24-current-docs-and-records.md).

.agents/notes/proposed/process/2026-10-24-python-alpha-release.md → .agents/notes/implemented/process/2026-10-24-python-alpha-release.md

@@ -1,6 +1,6 @@
 # Decision: Publish an explicitly verified Python alpha pair
 
-Status: proposed
+Status: implemented
 
 ## Problem
 
@@ -41,3 +41,7 @@ Run full client/server tests, lint/type/format, lockstep checks, actual Python-t
 ## Evidence
 
 See [verification](../../../evidence/verify/2026-10-24-python-alpha-release.md). Remote CI, PR review and publication status are recorded on the linked owner Issue and PR; local build alone is not a published release.
+
+## Implementation
+
+Delivered in [PR #91](https://github.com/Alibaba-Agent-Sandbox/python-sdk/pull/91); actual merged state was checked on 2026-10-24. Later acceptance and current limitations are indexed in the [current synchronization record](../../../evidence/verify/2026-10-24-current-docs-and-records.md). Earlier verification files remain unchanged and retain their original pending or failed observations.

.github/CONTRIBUTING.md

@@ -174,23 +174,7 @@ logged or committed. The full rule, the evidence-file and ADR templates are in
 
 Sandbox templates — content, the machine-readable index (`awesome-templates.yaml`), releases and CI — live in the dedicated repository **[alibaba-agent-sandbox/awesome-templates](https://github.com/alibaba-agent-sandbox/awesome-templates)**. It is the single source of truth for official & community templates; this repository no longer bundles a template collection (it keeps only a minimal `python-hello` offline fixture for tests).
 
-### Contributing a Template
-
-1. **Read** the catalog repository's [CONTRIBUTING.md](https://github.com/alibaba-agent-sandbox/awesome-templates/blob/main/CONTRIBUTING.md) — it defines the template anatomy, capability-group rules, and local dev workflow.
-2. **Open a PR** against [alibaba-agent-sandbox/awesome-templates](https://github.com/alibaba-agent-sandbox/awesome-templates) that adds your template folder and updates `awesome-templates.yaml` (plus the README template table) in the same PR.
-3. **Required index fields**: `name`, `description`, `repo`, `tags`, `author`, `status` (optional: `path` for subdirectory templates, `ref` to pin a version).
-4. **Status values**:
-   - `official` — maintained by the alibaba-agent-sandbox team (do not use for community PRs)
-   - `community` — community-contributed and maintained
-   - `experimental` — early-stage or proof-of-concept
-5. **Ensure** your repo contains a valid `template.yaml` at the specified path. The catalog CI validates every folder and the index offline.
-
-### Template Repository Requirements
-
-Your template repository should include:
-- A `template.yaml` declaring specification 4, `provides`, explicit `workflows` and `default_workflow`
-- A `Dockerfile` and a `README.md` with usage instructions
-- Example code or scripts that demonstrate the template's purpose
+Read the owning repository's [contributor guide](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/CONTRIBUTING.md) and [template specification](https://github.com/Alibaba-Agent-Sandbox/awesome-templates/blob/main/template-spec.md) before submitting there. Those files own the current manifest, catalog fields and required validation. Maintenance labels do not certify runtime behavior. Do not duplicate their schema or a template-status checklist in this SDK repository.
 
 ### Searching Templates
 

CHANGELOG.md

@@ -8,6 +8,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Documentation synchronization
+
+- Correct current SDK examples, reconnect semantics, packaged skills and installation guidance; index accepted release/workflow records without rewriting historical verification. / 修正当前 SDK 示例、重连语义、配套技能与安装说明，索引已交付发布和工作流记录，保留历史验证。
+
+
 ### Documentation
 
 - Simplify the bilingual Provider guide to actual entry points, correct installation verification guarantees and link complete authoring manifests. / 将中英文 Provider 指南收敛到实际调用入口，修正安装验证承诺，并引用完整的编写示例。

README.md

@@ -48,10 +48,9 @@ Provider management operations are available through `agent_sandbox.providers.co
 ## Client SDK
 
 - **Sync and async standard clients** — `Sandbox.create()` and `AsyncSandbox.create()`, shell execution, code interpretation, file I/O, port forwarding, and WebSocket streaming.
-- **Three execution primitives** — `sandbox.commands.run()` (bare shell), `sandbox.run_code()` (code interpreter), `sandbox.run("name", **kwargs)` (a command the Server SDK registered).
+- **Explicit execution entry points** — process execution, the standard interpreter client, and template application commands have separate runtime requirements (see Execution API below).
 - **MCP server** — expose sandbox operations as MCP tools for LLM agents.
 - **Declarative decorator** — `@sandbox` turns a plain function into a remote sandbox execution with automatic serialisation.
-- **Session persistence** — save and restore sandbox state across runs.
 - **Standard sync/async clients** — `agent_sandbox` exports the standard Sandbox and AsyncSandbox; see [Migrate from E2B](docs/en/guide/migrate-from-e2b.md).
 
 ## Server SDK
@@ -91,57 +90,37 @@ finally:
 
 ## Provider and server extensions
 
-
-Set `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN` before creating a sandbox. This snippet uses `python-base` because that image registers `hello`. `Sandbox.create()` with no template uses `base`.
+Set `ABX_SANDBOX_API_KEY`, `ABX_SANDBOX_BASE_URL` and `ABX_SANDBOX_DOMAIN`, then create a native instance and execute a process with `ProviderSandbox`:
 
 ```python
 import asyncio
-from agent_sandbox import ProviderSandbox as Sandbox
+from agent_sandbox import ProviderSandbox
 
 async def main():
-    async with await Sandbox.create(template="python-base") as sandbox:
-
-        # 1. Bare shell — sandbox.commands.run(cmd)
-        proc = await sandbox.commands.run("echo 'Hello from sandbox!'")
-        print(proc.stdout)          # Hello from sandbox!
-        print(proc.exit_code)       # 0
-
-        # 2. Code interpreter — sandbox.run_code(code)
-        result = await sandbox.run_code("print(2 ** 10)")
-        print(result.text)          # 1024
-
-        # 3. Named command — sandbox.run(name, **kwargs)
-        #    POST /commands/hello on the in-sandbox SandboxServer
-        greeting = await sandbox.run("hello", name="Alice")
-        print(greeting)             # the registered function's return value
-
-        # 4. File operations
-        await sandbox.files.write("/tmp/data.txt", "content")
-        content = await sandbox.files.read("/tmp/data.txt")
-
-        # 5. Port access
-        url = sandbox.network.get_url(3000)
+    sandbox = await ProviderSandbox.create(template="base", provider="alicloud-express")
+    try:
+        result = await sandbox.commands.run("python3 -c 'print(2 ** 10)'")
+        print(result.stdout)  # 1024
+    finally:
+        try:
+            await sandbox.kill()
+        finally:
+            await sandbox.close()
 
 asyncio.run(main())
 ```
 
-## Execution API
-
-Three execution methods, each for a distinct use case:
+This `python3` invocation is a process, not a persistent interpreter. Interpreter operations absent from a provider return `E8004`; the standard `code_interpreter.Sandbox` above is a separate entry point. `close()` releases client connections; `kill()` deletes the instance.
 
-| Method | Purpose | Returns |
-|--------|---------|---------|
-| `sandbox.commands.run(cmd)` | Execute a bare shell command (raw exec) | `ProcessResult` — `.stdout`, `.stderr`, `.exit_code` |
-| `sandbox.run_code(code)` | Execute code via the code interpreter | `CodeResult` — `.text`, `.stdout`, `.stderr` |
-| `sandbox.run(name, **kw)` | Call a command registered in the sandbox server | the registered function's JSON return value |
+## Execution API
 
-**Named commands** have one mechanism: server-side registered commands. A command is registered with
-`@sandbox.register` (or `CommandRegistry`) inside the template, and `sandbox.run("name", **kwargs)` sends
-`POST /commands/name` to the in-sandbox SandboxServer. An unknown name raises `CommandNotFoundError`;
-`await sandbox.list_commands()` lists what the server has registered. See
-[Declarative Usage](docs/en/guide/declarative-usage.md).
+| Entry point | Purpose | Requirement |
+|---|---|---|
+| `ProviderSandbox.commands.run()` | Execute a process and read stdout, stderr and exit code | Provider implements process operations |
+| Standard `code_interpreter.Sandbox.run_code()` | Execute interpreter code | A matching native runtime such as `code-interpreter-v1` |
+| `ProviderSandbox.application_client()` | Call application commands registered by a template HTTP service | Start the template service and supply the correct port and application token |
 
-> **Environment variables:** envd uses direct exec — shell features (`$VAR`, pipes, redirects) require `sh -c '...'`. Use `printenv VAR` to read a variable. See the [Environment Variables guide (EN)](docs/en/guide/environment-variables.md) | [环境变量指南 (中文)](docs/zh/guide/environment-variables.md) for details.
+Named application commands are registered by the in-sandbox server. Follow [template workflows](docs/en/guide/template-workflows.md) to create or connect to that application, preserving provider gateway headers, URL prefixes and query parameters; do not assume `base` registers `hello`. See [Providers](docs/en/guide/providers.md) for cross-language plugin execution.
 
 ## Templates