feat(add): scaffold runtime docs instead of code in add runtime

README.md

@@ -57,22 +57,35 @@ agentcore create --name MyAgent --template agent-python-strands
 ```
 
 `agentcore create --template` scaffolds the template with its default model provider (Amazon
-Bedrock for the model-backed templates). To use another provider, add the runtime with
-`agentcore add runtime --template <template>` instead: templates that take a model provider
-(`agent-python-strands` and its `-container` variant, `a2a-python-strands`, `agui-python-strands`,
-`agent-typescript-strands`) accept `--model-provider` (`bedrock`, `anthropic`, `open_ai`,
-`openai_compatible`, `gemini`, `lite_llm`; `openai` and `litellm` are accepted too; LiteLLM is
-Python-only), `--model-id`, and `--api-key file://<path>` there; the API key is kept in
+Bedrock for the model-backed templates). To use another provider, run `agentcore create` with no
+flags: for templates that take a model provider (`agent-python-strands` and its `-container`
+variant, `a2a-python-strands`, `agui-python-strands`, `agent-typescript-strands`) the wizard asks
+for the provider (Amazon Bedrock, Anthropic, OpenAI, an OpenAI-compatible endpoint, Gemini, or
+LiteLLM, which is Python-only), the model id, and an API-key file. The API key is kept in
 `agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy.
-`openai_compatible` is the OpenAI client pointed at any OpenAI-compatible endpoint (DeepSeek, Qwen,
-a self-hosted vLLM, …): it requires `--api-base <url>` and `--model-id <model>`, since nothing is
-known about the endpoint until you name it, while `open_ai` always calls api.openai.com and takes
-neither. A self-hosted endpoint that ignores authentication still needs an `--api-key` file; any
-placeholder value works.
-
-Run `agentcore create` with no flags for a guided setup; for those templates the wizard asks the
-same provider, model id, and API-key-file questions. Either way, run it outside any existing
-project.
+
+To bring your own code into a project instead, add a runtime for it:
+
+```bash
+agentcore add runtime --name search --language python   # or --language typescript
+```
+
+`add runtime` doesn't generate code. It creates `app/search/` with a `README.md` and an
+`AGENTS.md` describing what the code has to provide for the chosen `--protocol` (`HTTP` by
+default, or `MCP`, `A2A`, `AGUI`), and registers the runtime in `agentcore.json` with starting
+values (a CodeZip build on the latest Python or Node.js, entrypoint `main.py` or `main.js`). If
+`app/search/` already exists, your files are left alone and only the missing docs are added.
+
+`agentcore dev`, `agentcore build`, and `agentcore deploy` then update `agentcore.json` from the
+code and print what changed. Adding a `Dockerfile` to the folder switches the runtime to a
+container build. `requires-python` in `pyproject.toml` or `engines.node` in `package.json`
+constrains the runtime version: it changes only when the range excludes the current one, and then
+to the highest version the range allows. The Python entrypoint comes from `[tool.agentcore]
+entrypoint` in `pyproject.toml`; TypeScript is always bundled from `main.ts` (a `package.json`
+`"main"` of `main.ts` or `main.js` agrees with that, and any other value is ignored with a
+warning). Where the code doesn't say, the value in `agentcore.json` is kept.
+
+Run `agentcore create` outside any existing project.
 
 ## Projects
 

docs/china-regions.md

@@ -3,23 +3,22 @@
 `cn-north-1` and `cn-northwest-1` are supported, with three differences:
 
 - **Templates:** Amazon Bedrock, Anthropic, OpenAI, and Gemini are not accessible from China
-  regions, so templates wired to those providers (and `--type import`, which reads from Amazon
-  Bedrock) are rejected when a deployment target is in a China region. Bring your own agent
+  regions, so templates wired to those providers (and `agentcore add runtime --agent-id`, which
+  imports from Amazon Bedrock) are rejected when a deployment target is in a China region. Bring your own agent
   implementation instead: scaffold with `agent-python-minimal` or `mcp-python-fastmcp` and add
-  your own model connectivity, or pick one of the two routes to a model that is reachable from
-  China (as `agentcore add runtime --template <template>` flags or in the `agentcore create`
-  wizard; `agentcore create --template` always scaffolds the template's Bedrock default):
-  `--model-provider litellm --model-id <model>` on a Python strands template
+  your own model connectivity (or add a runtime for your own code with `agentcore add runtime`),
+  or pick one of the two routes to a model that is reachable from China in the
+  `agentcore create` wizard (`agentcore create --template` always scaffolds the template's
+  Bedrock default): LiteLLM with a model id on a Python strands template
   (`agent-python-strands`, `a2a-python-strands`, `agui-python-strands`) with a
   [LiteLLM model](https://docs.litellm.ai/docs/providers) — no default model id is applied
   there, and the `bedrock/` LiteLLM prefix (which routes to Amazon Bedrock) is rejected — or
-  `--model-provider openai_compatible --api-base <url> --model-id <model>` on any strands template
+  an OpenAI-compatible endpoint with a base URL and model id on any strands template
   including `agent-typescript-strands`, pointing the OpenAI client at an OpenAI-compatible
   endpoint such as `https://api.deepseek.com/v1` (`open_ai` itself is rejected there like the
   other providers, since it calls api.openai.com). The scaffolded runtime records `modelProvider`
-  and, for LiteLLM, `modelId` in `agentcore.json` so deploys can re-check this. The
-  `agentcore create` and `agentcore add runtime` wizards ask the same question for these
-  templates: in a China region the model step starts on LiteLLM (Python) or openai-compatible
+  and, for LiteLLM, `modelId` in `agentcore.json` so deploys can re-check this. In a China
+  region the `agentcore create` wizard's model step starts on LiteLLM (Python) or openai-compatible
   (TypeScript), with no model id prefilled, marks the other providers as not accessible, and
   applies the same restrictions when the form is submitted.
 - The restrictions are enforced wherever the region is known: at `agentcore create` when the
@@ -28,10 +27,10 @@
   target yet and the resolved region is a China region — and at `agentcore deploy` — deploying
   to a China target fails when a runtime was scaffolded with an inaccessible model provider
   (recorded as the runtime's `modelProvider` in `agentcore.json`; delete that field if you have
-  replaced the model wiring in code). The `agentcore add runtime` wizard's model step reads the
-  same answer, so with a China deployment target it starts on a China-capable provider and marks
-  the blocked ones even when the shell's region is commercial. Harness projects are not available
-  in China regions.
+  replaced the model wiring in code). A runtime added with `agentcore add runtime` has no
+  recorded `modelProvider`, so deploys only note that its model connectivity cannot be verified;
+  make sure your code calls a model reachable from China. Harness projects are not available in
+  China regions.
 - **Resource families:** only Runtimes, Gateways (without connector-backed Targets: the curated
   `web-search` and `bedrock-knowledge-bases` connectors are refused there), and credentials are
   available in China