anycodes · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026 · Nov 12, 2026
diff --git a/.agents/README.md b/.agents/README.md
@@ -275,3 +275,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
 - [Community QR replacement](notes/proposed/process/2026-11-10-refresh-community-qr.md) · [verification](evidence/verify/2026-11-10-refresh-community-qr.md).
 
 - [SDK simplification mainline reconciliation](evidence/verify/2026-11-10-simplification-main-merge.md).
+
+- [Python documentation consumers of the unified CLI](notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md) · [verification](evidence/verify/2026-11-12-ecosystem-guidance-sync.md).
diff --git a/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md b/.agents/evidence/verify/2026-11-12-ecosystem-guidance-sync.md
@@ -0,0 +1,59 @@
+# Verification: ecosystem guidance synchronization
+
+Date: 2026-11-12
+Result: PARTIAL
+Baseline: cf3ff7dd14193b63e4fc31cb4a98627c748c5af2
+
+## Scope and review
+
+Update current indexes, fixture guidance, lifecycle examples, authoring ownership and HTTP MCP deployment instructions. The generated HTTP service uses create_mcp_app in a Sandbox with explicit backend runtime credentials and saved application authentication. Correct template-index network-error source-acquisition guidance without changing fetching, caching or SDK execution.
+
+Command spellings and options were compared with the current parser and built help. Replacing historical result text, adding aliases, modifying runtime algorithms, upgrading template dependencies and recreating cloud resources were excluded after examining whether they were necessary for this task.
+
+## Results
+
+Local checks are recorded below. No cloud resources were created. Existing runtime receipts were preserved; modified source identity does not inherit a new qualification.
+
+## Delivery limitations
+
+The root dotenv's configured GitHub credential returned HTTP401, no alternate process credential or configured Git credential helper/gh session was available, and private Registry/Website fetches could not authenticate. Public producer main revisions were fetched and checked. Private consumers are based on the latest locally recovered task branches, not claimed current remote main. Finish local commits and reproducible bundles; push, PR, remote CI, review and merge remain blocked until authentication is restored. No new package, image or live website release is claimed.
+
+## Local verification
+
+- Remote template-index offline behavior: 35 pytest tests passed, including cache/network-error paths; source-acquisition suggestion follows the current CLI.
+- Repository health: 106 passes, one warning, zero failures.
+- Lychee 0.24.2 offline with fragments: all 496 tracked Markdown inputs pass.
+- Changed source is only an error-guidance string and docstrings; SDK resource execution, dependency pins and runtime behavior were preserved.
+
+The secret hook initially rejected an environment-variable reference in an MCP
+example as a generic quoted secret assignment. The example now uses explicit
+YOUR_* placeholders. No secret value was present and the hook was not changed
+or bypassed.
+
+A second scan removed global-option-prefixed template launch examples from
+both example indexes and the current template-system descriptions. Conditional
+acceptance uses the supported `--opt region=...` Provider override. Historical
+SDK quickstart run output remains explicitly labeled as such. No SDK method or
+configuration resolver was changed.
+
+Final permission-guide review removed the obsolete claim that CI output authorizes key preparation. Existing explicit SDK confirmation remains required; no key was created or renewed during this task.
+
+## Authentication and delivery follow-up
+
+The initial API Bearer request returned HTTP401, but the credential was not
+invalid. Git push/fetch and the API's Basic authentication succeeded with the
+same existing credential; no credential was changed or created. Public
+producer source branches can now be pushed. Private Registry/Website main was
+fetched successfully, and the prior coordinating PRs were confirmed merged.
+This supersedes the initial delivery-authentication limitation above.
+
+## Remote fixture-boundary regression
+
+The first remote client matrix found two documentation guard failures: the
+existing source-flow check still required retired search/install commands,
+and the rewritten Chinese fixture title omitted its explicit English fixture
+marker. Updated the existing assertions to list/init and restored the bilingual
+marker, preserving the fixture boundary rather than weakening it. The failures
+were reproduced locally (2 failed, 35 passed, one skipped) and in the full
+remote suite (2 failed, 2,450 passed on Python3.12). The corrected focused suite
+passed (37 passed, one skipped); full remote matrix results remain separate.
diff --git a/.agents/notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md b/.agents/notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md
@@ -0,0 +1,35 @@
+# Decision: Python documentation consumers of the unified CLI
+
+Status: proposed
+
+## Problem
+
+Unified command changes had landed, but some current examples, contributor text and cross-repository consumers still advertised retired entry points. The user requested complete implementation of the affected ecosystem synchronization.
+
+## Decision
+
+Update current indexes, fixture guidance, lifecycle examples, authoring ownership and HTTP MCP deployment instructions. The generated HTTP service uses create_mcp_app in a Sandbox with explicit backend runtime credentials and saved application authentication. Correct template-index network-error source-acquisition guidance without changing fetching, caching or SDK execution.
+
+## API Design
+
+No execution API or resource lifecycle change. Command examples follow the current CLI contract.
+
+## Alternatives considered
+
+Blind text replacement was rejected: historical runs and version-pinned cases must remain truthful. Rebuilding every template or repeating cloud matrices for documentation would not validate these text changes. Generated consumers must be refreshed from their actual source rather than hand-patched.
+
+## Dependencies
+
+Current CLI contract: https://github.com/Alibaba-Agent-Sandbox/agent-sandbox/pull/247. Template producer: https://github.com/Alibaba-Agent-Sandbox/awesome-templates/pull/305. Registry and website consume the reviewed source commits after local validation.
+
+## Test Strategy
+
+Run owner document/link/record checks and relevant actual command or catalog checks. Verify generated consumer snapshots through their normal generators and local site builds. Record missing prerequisites and remote authentication failures separately.
+
+## Acceptance criteria
+
+Current user instructions resolve to supported commands; every catalog template is checked; historical commands have an explicit version/research boundary. Bilingual pages and generated consumers agree. No secrets, acceptance results or release claims are fabricated.
+
+## Evidence
+
+[Verification](../../../evidence/verify/2026-11-12-ecosystem-guidance-sync.md).
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -180,9 +180,9 @@ Read the owning repository's [contributor guide](https://github.com/Alibaba-Agen
 
 Use the CLI (`abx`, from the `agent-sandbox` repository) to search the remote index:
 ```bash
-abx template search python      # search by tag or keyword
-abx template search ai-agent    # find AI agent templates
-abx template search browser     # find browser automation templates
+abx template list python      # search by tag or keyword
+abx template list ai-agent    # find AI agent templates
+abx template list browser     # find browser automation templates
 ```
 
 ## Commit Message Convention

diff --git a/AGENTS.md b/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. 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.
+**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 deploy <reference> --name <name>`; advanced image preparation uses `abx template build/publish`. 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):
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Documentation
+
+- Synchronize CLI-dependent SDK documentation, HTTP MCP template deployment and source-acquisition error guidance. / 同步 SDK 文档中的 CLI 用法、HTTP MCP 模板部署与源码获取错误指引。
+
 ### Changed
 
 - Align current English and Chinese CLI guides with template authoring, named deployment lifecycle and Provider operations; preserve the SDK’s independent clients and instance methods.

diff --git a/client-sdk/src/agent_sandbox/providers/installer.py b/client-sdk/src/agent_sandbox/providers/installer.py
@@ -109,7 +109,7 @@ def expand_catalog_ref(
 ) -> tuple[str, str | None, str | None]:
     """Turn ``owner/repo//subdir[@ref]`` into a GitHub URL plus subdir and ref.
 
-    Same grammar as ``abx template install``: ``//`` is the directory inside the
+    Same grammar as ``abx template init --from``: ``//`` is the directory inside the
     repository, ``@`` after that is the git ref. A full git URL, an scp-style
     ``git@host:path``, or a local path is returned unchanged. ``--ref`` and
     ``--subdir`` still work; giving both forms with different values is an error.

diff --git a/client-sdk/src/agent_sandbox/utils/template_index.py b/client-sdk/src/agent_sandbox/utils/template_index.py
@@ -2,8 +2,8 @@
 
 The official and community template catalog lives in a **single source of
 truth** repository: ``alibaba-agent-sandbox/awesome-templates``.  Its root index file
-(``awesome-templates.yaml``) is what ``abx template search`` queries and what
-``abx template install <name>`` resolves bare template names against.
+(``awesome-templates.yaml``) is what ``abx template list`` queries and what
+``abx template init DIRECTORY --from <name>`` resolves bare template names against.
 
 Design notes
 ------------
@@ -460,8 +460,8 @@ async def fetch_index(
     suggestion = (
         "Check your network connection, or point at a mirror with "
         f"--index-url / {INDEX_URL_ENV}. For GitHub rate limits, authenticate "
-        "with 'abx config set github_token'. As a last resort install directly "
-        "with 'abx template install owner/repo//subdir[@ref]'."
+        "with 'abx config set github_token'. As a last resort acquire source directly "
+        "with 'abx template init ./project --from owner/repo//subdir[@ref]'."
     )
 
     try:

diff --git a/client-sdk/tests/test_templates/test_template_catalog.py b/client-sdk/tests/test_templates/test_template_catalog.py
@@ -218,10 +218,10 @@ def test_index_readme_links_the_source_of_truth(self, catalog_readme: Path) -> N
             f"({SOURCE_OF_TRUTH_URL})"
         )
 
-    def test_index_readme_documents_remote_install_flow(self, catalog_readme: Path) -> None:
+    def test_index_readme_documents_remote_source_flow(self, catalog_readme: Path) -> None:
         readme = catalog_readme.read_text(encoding="utf-8")
-        assert "abx template search" in readme
-        assert "abx template install" in readme
+        assert "abx template list" in readme
+        assert "abx template init" in readme
         assert "ABX_TEMPLATE_INDEX_URL" in readme, (
             "README must document the index override for private mirrors"
         )

diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md
@@ -8,7 +8,7 @@
 
 ## Project Overview
 
-**Agent Sandbox** (`agent-sandbox-client` on PyPI) is a Python SDK for the Alibaba Cloud FC Agent Sandbox service. It is the runtime client: create, use and kill sandboxes. Source templates normally start with `abx template launch`; Python consumes the returned sandbox. Advanced image preparation uses `abx template build` and `abx template deploy`. Method names are E2B-shaped to ease migration; the standard public API follows the pinned Alibaba E2B contract (see [Migrate from E2B](guide/migrate-from-e2b.md)).
+**Agent Sandbox** (`agent-sandbox-client` on PyPI) is a Python SDK for the Alibaba Cloud FC Agent Sandbox service. It is the runtime client: create, use and kill sandboxes. Source templates normally start with `abx deploy`; Python consumes the returned sandbox. Advanced image preparation uses `abx template build` and `abx deploy`. Method names are E2B-shaped to ease migration; the standard public API follows the pinned Alibaba E2B contract (see [Migrate from E2B](guide/migrate-from-e2b.md)).
 
 This repository holds the Python SDK as two lock-step PyPI distributions — `agent-sandbox-client` (`client-sdk/`, import `agent_sandbox`) and `agent-sandbox-server` (`server-sdk/`, import `agent_sandbox.server`, the container-side runtime). The `abx` CLI is a Node.js/TypeScript project in the `cli` repository, which holds the CLI's own design and guide documents (see [Related: the abx CLI](#related-the-abx-cli)).
 
@@ -126,8 +126,8 @@ Chinese copies of these pages live under `docs/zh/`. `repository-layout.md` is E
 | SDK core (Sandbox, files, commands, code) | **Implemented** | |
 | MCP Server (STDIO) | **Implemented** | 7 P0 tools |
 | MCP Server (Streamable HTTP) | **Implemented** | `mcp_http.py` |
-| FC deployment artifact application | **Implemented** | `agent_sandbox.agent.mcp_http:asgi_app`; the artifact is generated by `abx mcp deploy` in the CLI. See [mcp-server.md](design/mcp-server.md#7-fc-deployment) |
-| Template startup and image preparation | **In the CLI** | Start sources with `abx template launch` and consume with the SDK; advanced preparation uses `abx template build` and `abx template deploy` |
+| Deployable HTTP MCP application | **Implemented** | `create_mcp_app`; the source is generated by `abx template init --template mcp` in the CLI. See [mcp-server.md](design/mcp-server.md#7-deployable-http-mcp) |
+| Template startup and image preparation | **In the CLI** | Start sources with `abx deploy` and consume with the SDK; advanced preparation uses `abx template build` and `abx deploy` |
 | One environment variable per configuration key (SDK) | **Implemented** | See [Configuration](reference/configuration.md); CLI spec in `cli/docs/design/providers-and-credentials-cli.md` |
 | Provider plugins (SDK, `python -m agent_sandbox.providers`) | **Implemented** | See [Providers](guide/providers.md). The CLI loads installed `node`, `exec` and `rest` plugins (`abx provider`, `abx --provider`) |
 | Persistent sandbox | **Future** | Requires underlying platform support |

diff --git a/docs/en/README.md b/docs/en/README.md
@@ -60,7 +60,7 @@ The installer fetches the catalog index at `https://registry.agent-sandbox.cn/pr
 | [File and command controls](guide/file-and-command-controls.md) | Limit paths and commands |
 | [Agents API](guide/agents-api.md) | Codex and Qwen Code HTTP sessions inside the sandbox |
 | [Hosted agents](guide/hosted-agents.md) | How those routes refuse and what they return |
-| [Build and deploy](guide/build-and-deploy.md) | `abx template build` and `abx template deploy` |
+| [Build and deploy](guide/build-and-deploy.md) | `abx template build` and `abx deploy` |
 
 How a change counts as tested: [Testing and the Definition of Done](guide/testing-e2e.md).
 

diff --git a/docs/en/design/base-image-and-server-sdk.md b/docs/en/design/base-image-and-server-sdk.md
@@ -5,7 +5,7 @@
 > Product requirement: *all template builds should be based on the Alibaba Cloud Agent Sandbox
 > (FC Agent Sandbox) base image.*
 >
-> **Update.** The Python client no longer builds images: `Image`, `DockerBuilder`, `Sandbox.deploy` and `agent_sandbox.api.base_image` were removed. The base-image contract in section 3, the lint and the Dockerfile scaffold are owned by the `abx` CLI (`abx template scaffold|build|deploy`). Sections 4, 5, 7 and 8 describe what remains in this repository.
+> **Update.** The Python client no longer builds images: `Image`, `DockerBuilder`, `Sandbox.deploy` and `agent_sandbox.api.base_image` were removed. The base-image contract in section 3, the lint and the Dockerfile scaffold are owned by the `abx` CLI (`abx template init/build` and `abx deploy`). Sections 4, 5, 7 and 8 describe what remains in this repository.
 
 ## 1. What the base image is (evidence)
 
@@ -91,7 +91,7 @@ Documented in `server-api.md` and enforced by the CLI's template lint:
 
 ## 5. CLI-side changes (recorded in `cli-followups.md`)
 
-Node scaffold `abx template scaffold` (FROM official base, scaffold per section 3); deploy path
+Node scaffold `abx template init` (FROM official base, scaffold per section 3); deploy path
 (wheel injection, `envd_inject` auto-choice, `start_cmd`/`ready_cmd`);
 `template.yaml` `server:` compile; AI template-guide prompt (must start FROM the official base,
 never override ENTRYPOINT, use `agent-sandbox-server serve`).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -275,3 +275,5 @@ Builtin transport: [direct HTTP](notes/implemented/architecture/2026-10-18-nativ
		- [Community QR replacement](notes/proposed/process/2026-11-10-refresh-community-qr.md) · [verification](evidence/verify/2026-11-10-refresh-community-qr.md).

		- [SDK simplification mainline reconciliation](evidence/verify/2026-11-10-simplification-main-merge.md).

		- [Python documentation consumers of the unified CLI](notes/proposed/process/2026-11-12-ecosystem-guidance-sync.md) · [verification](evidence/verify/2026-11-12-ecosystem-guidance-sync.md).