From 447a3a29cf8d2bf6bb09d38afa221c8a33b44586 Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Thu, 15 Oct 2026 22:36:59 +0000
Subject: [PATCH 1/5] feat(add)!: scaffold runtime docs instead of code in add
 runtime

`agentcore add runtime --type create` no longer generates agent code. It
creates app/<name>/ with a README.md and AGENTS.md describing exactly what
the user's code needs (entry file, runtime contract per protocol, manifest,
container flow), never overwriting existing files, and writes a complete
runtime entry with starting values.

dev, build and deploy now keep agentcore.json in sync with the code before
running: a Dockerfile switches the runtime to Container, requires-python /
engines.node constrain runtimeVersion (an allowed current value is kept),
and the entrypoint comes from [tool.agentcore] / package.json "main".
Changes are printed and written back; prechecks fail early with a pointer
to the runtime's README.

BREAKING CHANGE: `add runtime` drops --template, --model-provider,
--model-id, --api-key and --api-base, and adds --language (required for
--type create) and --protocol. Use `create --template` for starter code.
---
 README.md                                     |  43 +-
 command.md                                    |   9 +-
 docs/china-regions.md                         |  23 +-
 e2eTest/project/templates.test.ts             | 316 ++++----
 .../bedrock-managed-agents/README.md          |   2 -
 .../templates/runtime-docs/python/AGENTS.md   |  85 ++
 .../templates/runtime-docs/python/README.md   | 369 +++++++++
 .../runtime-docs/typescript/AGENTS.md         |  77 ++
 .../runtime-docs/typescript/README.md         | 304 +++++++
 src/core/project/manager.export.test.ts       |   5 +
 src/core/project/manager.test.ts              | 499 ++++++++++++
 src/core/project/manager.tsx                  | 203 ++++-
 src/core/project/migrate/journal.ts           |   4 +-
 src/core/project/runtimeBuild.test.ts         | 561 +++++++++++++
 src/core/project/runtimeBuild.ts              | 605 ++++++++++++++
 src/core/project/templates/fsTree.test.ts     |  17 +-
 src/core/project/templates/fsTree.ts          |  26 +-
 src/core/project/templates/runtime.test.ts    | 257 ++++++
 src/core/project/templates/runtimeDocs.ts     | 126 +++
 src/handlers/project/RuntimeModelField.tsx    |  10 +-
 .../project/add/runtime/index.test.ts         | 744 ++++--------------
 src/handlers/project/add/runtime/index.ts     | 184 +++--
 .../add/runtime/runtime.screen.test.tsx       | 295 ++-----
 src/handlers/project/add/runtime/screen.tsx   | 186 ++---
 src/handlers/project/add/runtime/types.ts     |  18 +
 src/handlers/project/bma.ts                   |   5 -
 src/handlers/project/create/index.ts          |   7 +-
 src/handlers/project/dev/index.test.ts        | 163 +++-
 src/handlers/project/dev/index.ts             |  73 +-
 src/handlers/project/project.test.ts          |   2 +-
 src/handlers/project/types.ts                 |  35 +-
 31 files changed, 3955 insertions(+), 1298 deletions(-)
 create mode 100644 src/assets/templates/runtime-docs/python/AGENTS.md
 create mode 100644 src/assets/templates/runtime-docs/python/README.md
 create mode 100644 src/assets/templates/runtime-docs/typescript/AGENTS.md
 create mode 100644 src/assets/templates/runtime-docs/typescript/README.md
 create mode 100644 src/core/project/runtimeBuild.test.ts
 create mode 100644 src/core/project/runtimeBuild.ts
 create mode 100644 src/core/project/templates/runtime.test.ts
 create mode 100644 src/core/project/templates/runtimeDocs.ts

diff --git a/README.md b/README.md
index 893362b685..dc67645cc0 100644
--- a/README.md
+++ b/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
 
diff --git a/command.md b/command.md
index 01fbd71911..174d99d677 100644
--- a/command.md
+++ b/command.md
@@ -531,12 +531,9 @@ add a Runtime to the current project
 **Options**
 
 - `--name <name>`: the name of the Runtime (required)
-- `--type <type>`: create generates new agent code (the default); import translates a Bedrock Agent version
-- `--template <template>`: template for the Runtime code (default: agent-python-minimal); available templates listed below
-- `--model-provider <model-provider>`: model provider for supported templates: bedrock, anthropic, open\_ai (or openai), openai\_compatible, gemini, or lite\_llm (or litellm)
-- `--model-id <model-id>`: model id for the scaffolded Runtime code, overriding the provider's default (required with openai\_compatible, and with litellm in China regions)
-- `--api-key <api-key>`: API key for non-Bedrock providers on supported templates; '-' for stdin, 'file://path' for file
-- `--api-base <api-base>`: base URL of the endpoint for --model-provider openai\_compatible (required with it, not accepted with other providers)
+- `--type <type>`: create sets up app/&lt;name&gt;/ with docs for the code you write (the default); import translates a Bedrock Agent version into runtime code
+- `--language <language>`: language you will write the Runtime in: python or typescript (required with --type create)
+- `--protocol <protocol>`: protocol the Runtime serves: HTTP (default), MCP, A2A, or AGUI
 - `--description <description>`: an optional description of the Runtime
 - `--tags <tags...>`: tags as key=value (repeatable) or JSON object
 - `--environment-variables <environment-variables>`: environment variables (JSON object of key/value strings)
diff --git a/docs/china-regions.md b/docs/china-regions.md
index 9400099d7d..531850a295 100644
--- a/docs/china-regions.md
+++ b/docs/china-regions.md
@@ -6,20 +6,19 @@
   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
   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
diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts
index 80262b7167..4b3da2d3ce 100644
--- a/e2eTest/project/templates.test.ts
+++ b/e2eTest/project/templates.test.ts
@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { describe, expect, test } from "vitest";
 import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -144,194 +144,170 @@ const A2aResponseSchema = z.object({
   error: z.undefined().optional(),
 });
 
+/** The runtime `agentcore create --template` scaffolds (DEFAULT_CREATE_RUNTIME_NAME). */
+const CREATED_RUNTIME_NAME = "agent";
+
+// Each template gets its own project from `agentcore create --template`, the
+// command that scaffolds template code (`add runtime` only writes docs). The
+// projects are independent, so the templates run concurrently; each one's
+// steps run in order inside its test.
 describe(
-  "add, dev, deploy, invoke for runtime templates",
-  { sequential: true, tags: [TAGS.RUNTIME, TAGS.CANARY] },
+  "create, dev, deploy, invoke for runtime templates",
+  { tags: [TAGS.RUNTIME, TAGS.CANARY] },
   () => {
     const cli = new CliRunner();
-    const projectName = `${E2E_PREFIX}${Date.now().toString(36)}`;
-    let projectDir: string;
-
-    beforeAll(async () => {
-      const projectRoot = await mkdtemp(join(tmpdir(), "agentcore-e2e-"));
-      const created = parseResult(
-        ProjectCreatedSchema,
-        await cli.run(
-          ["create", "--name", projectName, "--template", "empty", "--skip-git", "--json"],
-          projectRoot,
-        ),
-      );
-      projectDir = created.project.path;
-    }, TIMEOUT_MS.PROJECT_CREATE);
 
-    test.each(RUNTIME_TEMPLATES)(
-      "$name can be added to a project",
-      { timeout: TIMEOUT_MS.PROJECT_CREATE },
-      async (runtime) => {
-        const added = parseResult(
-          OperationSchema,
-          await cli.run(
-            ["add", "runtime", "--name", runtime.name, "--template", runtime.template, "--json"],
-            projectDir,
-          ),
-        );
-        expect(added.operation).toBe("add");
+    test.concurrent.each(RUNTIME_TEMPLATES)(
+      "$name",
+      {
+        timeout:
+          TIMEOUT_MS.PROJECT_CREATE +
+          TIMEOUT_MS.PROJECT_DEV +
+          2 * TIMEOUT_MS.PROJECT_INVOKE +
+          2 * TIMEOUT_MS.PROJECT_DEPLOY +
+          TIMEOUT_MS.PROJECT_REMOVE,
       },
-    );
-
-    describe("local invocation", { sequential: true }, () => {
-      const runtimePorts = new Map<string, number>();
-      let dev: ReturnType<CliRunner["start"]> | undefined;
-      let pendingOutput = "";
-      let devOutput = "";
-
-      /** Given dev-process output, records the ports announced by running runtimes. */
-      const captureDevOutput = (chunk: Buffer) => {
-        const text = chunk.toString();
-        devOutput += text;
-        pendingOutput += text;
-        const lines = pendingOutput.split(/\r?\n/);
-        pendingOutput = lines.pop() ?? "";
-
-        // parse the out for the ports each agent is running on
-        for (const line of lines) {
-          const match = line.match(/Agent '([^']+)' is running on port (\d+)\./);
-          if (match?.[1] && match[2]) runtimePorts.set(match[1], Number(match[2]));
-        }
-      };
-
-      beforeAll(() => {
-        dev = cli.start(["dev", "--mode", "headless"], projectDir);
-        dev.stdout?.on("data", captureDevOutput);
-        dev.stderr?.on("data", captureDevOutput);
-        dev.stdout?.resume();
-        dev.stderr?.resume();
-      }, TIMEOUT_MS.PROJECT_DEV);
-
-      afterAll(async () => {
-        if (!dev || dev.exitCode !== null) return;
-        dev.kill("SIGTERM");
-        await new Promise<void>((resolve) => dev?.once("close", resolve));
-      });
-
-      test.each(RUNTIME_TEMPLATES)(
-        "$name runs locally",
-        { concurrent: true, timeout: TIMEOUT_MS.PROJECT_INVOKE },
-        async (runtime) => {
-          const sessionId = getSessionId(`${runtime.name}`);
-
-          // The server may take a bit to get ready, so we retry on a timeout.
-          const response = await retry(async () => {
-            if (!dev) {
-              throw new Error(`agentcore dev did not start. \nstdout/stderr = ${devOutput}`);
-            }
-            if (dev.exitCode !== null) {
-              throw new Error(
-                `agentcore dev exited with code ${dev.exitCode ?? "unknown"}.  \nstdout/stderr = ${devOutput}`,
-              );
-            }
-
-            const port = runtimePorts.get(runtime.name);
-            if (!port) {
-              throw new Error(
-                `Runtime '${runtime.name}' is not ready. \nstdout/stderr = ${devOutput}`,
-              );
-            }
+      async (runtime) => {
+        const projectDir = await createTemplateProject(cli, runtime);
+        try {
+          await invokeLocally(cli, runtime, projectDir);
 
-            return parseResult(
-              LocalRuntimeInvokeResponseSchema,
-              await cli.run(
-                [
-                  "invoke",
-                  "--runtime",
-                  runtime.name,
-                  "--local",
-                  "--port",
-                  String(port),
-                  "--session-id",
-                  sessionId,
-                  "--payload",
-                  JSON.stringify(runtime.payload),
-                  "--json",
-                  ...(runtime.invokeFlags ?? []),
-                ],
-                projectDir,
-              ),
-            );
-          }, TIMEOUT_MS.PROJECT_INVOKE * 0.9);
+          const deployment = parseResult(
+            DeployResponseSchema,
+            await cli.run(["deploy", "--yes", "--json"], projectDir),
+          );
+          expect(deployment.message).toContain("Deployed project");
 
+          const response = parseResult(
+            RuntimeInvokeResponseSchema,
+            await cli.run(
+              [
+                "invoke",
+                "--runtime",
+                CREATED_RUNTIME_NAME,
+                "--session-id",
+                getSessionId(runtime.name),
+                "--payload",
+                JSON.stringify(runtime.payload),
+                "--json",
+                ...(runtime.invokeFlags ?? []),
+              ],
+              projectDir,
+            ),
+          );
           expect(response.complete).toBe(true);
           if (runtime.protocol === "MCP" || runtime.protocol === "A2A") {
             assertProtocolResponse(runtime, response.body);
           }
-        },
-      );
-    });
-
-    test("deploys all runtimes", { timeout: TIMEOUT_MS.PROJECT_DEPLOY }, async () => {
-      const deployment = parseResult(
-        DeployResponseSchema,
-        await cli.run(["deploy", "--yes", "--json"], projectDir),
-      );
-      expect(deployment.message).toContain("Deployed project");
-    });
 
-    test.each(RUNTIME_TEMPLATES)(
-      "$name can be invoked after deployed",
-      { concurrent: true, timeout: TIMEOUT_MS.PROJECT_INVOKE },
-      async (runtime) => {
-        const sessionId = getSessionId(runtime.name);
-        const response = parseResult(
-          RuntimeInvokeResponseSchema,
-          await cli.run(
-            [
-              "invoke",
-              "--runtime",
-              runtime.name,
-              "--session-id",
-              sessionId,
-              "--payload",
-              JSON.stringify(runtime.payload),
-              "--json",
-              ...(runtime.invokeFlags ?? []),
-            ],
-            projectDir,
-          ),
-        );
-
-        expect(response.complete).toBe(true);
-        if (runtime.protocol === "MCP" || runtime.protocol === "A2A") {
-          assertProtocolResponse(runtime, response.body);
+          const removed = parseResult(
+            OperationSchema,
+            await cli.run(
+              ["remove", "runtime", "--name", CREATED_RUNTIME_NAME, "--json"],
+              projectDir,
+            ),
+          );
+          expect(removed.operation).toBe("remove");
+        } finally {
+          // Tear the stack down even when a step above failed.
+          await cli.run(["remove", "all", "--yes", "--json"], projectDir);
+          parseResult(JsonObjectSchema, await cli.run(["deploy", "--yes", "--json"], projectDir));
         }
       },
     );
+  },
+);
 
-    test.each(RUNTIME_TEMPLATES)(
-      "$name can be removed from the project",
-      { timeout: TIMEOUT_MS.PROJECT_REMOVE },
-      async (runtime) => {
-        const removed = parseResult(
-          OperationSchema,
-          await cli.run(["remove", "runtime", "--name", runtime.name, "--json"], projectDir),
-        );
-        expect(removed.operation).toBe("remove");
-      },
-    );
+/** Given a template test case, creates a project scaffolded from it and returns its path. */
+async function createTemplateProject(
+  cli: CliRunner,
+  runtime: RuntimeTemplateTestCase,
+): Promise<string> {
+  const parent = await mkdtemp(join(tmpdir(), "agentcore-e2e-"));
+  // A per-template suffix keeps concurrent projects (and their stacks) apart;
+  // project names are alphanumeric, so it is the template's index.
+  const projectName = `${E2E_PREFIX}${Date.now().toString(36)}t${RUNTIME_TEMPLATES.indexOf(runtime)}`;
+  const created = parseResult(
+    ProjectCreatedSchema,
+    await cli.run(
+      ["create", "--name", projectName, "--template", runtime.template, "--skip-git", "--json"],
+      parent,
+    ),
+  );
+  return created.project.path;
+}
 
-    test(
-      "deploys the empty project",
-      { timeout: TIMEOUT_MS.PROJECT_REMOVE + TIMEOUT_MS.PROJECT_DEPLOY },
-      async () => {
-        parseResult(
-          JsonObjectSchema,
-          await cli.run(["remove", "all", "--yes", "--json"], projectDir),
+/** Given a template test case, runs `agentcore dev` and invokes the runtime locally. */
+async function invokeLocally(
+  cli: CliRunner,
+  runtime: RuntimeTemplateTestCase,
+  projectDir: string,
+): Promise<void> {
+  let port: number | undefined;
+  let pendingOutput = "";
+  let devOutput = "";
+  /** Given dev-process output, records the port the runtime announces. */
+  const captureDevOutput = (chunk: Buffer) => {
+    const text = chunk.toString();
+    devOutput += text;
+    pendingOutput += text;
+    const lines = pendingOutput.split(/\r?\n/);
+    pendingOutput = lines.pop() ?? "";
+    for (const line of lines) {
+      const match = line.match(/Agent '([^']+)' is running on port (\d+)\./);
+      if (match?.[1] === CREATED_RUNTIME_NAME && match[2]) port = Number(match[2]);
+    }
+  };
+
+  const dev = cli.start(["dev", "--mode", "headless"], projectDir);
+  dev.stdout?.on("data", captureDevOutput);
+  dev.stderr?.on("data", captureDevOutput);
+  dev.stdout?.resume();
+  dev.stderr?.resume();
+  try {
+    // The server may take a bit to get ready, so we retry on a timeout.
+    const response = await retry(async () => {
+      if (dev.exitCode !== null) {
+        throw new Error(
+          `agentcore dev exited with code ${dev.exitCode ?? "unknown"}.  \nstdout/stderr = ${devOutput}`,
         );
+      }
+      if (!port) {
+        throw new Error(`Runtime '${runtime.name}' is not ready. \nstdout/stderr = ${devOutput}`);
+      }
+      return parseResult(
+        LocalRuntimeInvokeResponseSchema,
+        await cli.run(
+          [
+            "invoke",
+            "--runtime",
+            CREATED_RUNTIME_NAME,
+            "--local",
+            "--port",
+            String(port),
+            "--session-id",
+            getSessionId(runtime.name),
+            "--payload",
+            JSON.stringify(runtime.payload),
+            "--json",
+            ...(runtime.invokeFlags ?? []),
+          ],
+          projectDir,
+        ),
+      );
+    }, TIMEOUT_MS.PROJECT_INVOKE * 0.9);
 
-        parseResult(JsonObjectSchema, await cli.run(["deploy", "--yes", "--json"], projectDir));
-      },
-    );
-  },
-);
+    expect(response.complete).toBe(true);
+    if (runtime.protocol === "MCP" || runtime.protocol === "A2A") {
+      assertProtocolResponse(runtime, response.body);
+    }
+  } finally {
+    if (dev.exitCode === null) {
+      dev.kill("SIGTERM");
+      await new Promise<void>((resolve) => dev.once("close", resolve));
+    }
+  }
+}
 
 /** Given a runtime and response body, validates the protocol response and request identifier. */
 function assertProtocolResponse(runtime: RuntimeTemplateTestCase, body: string): void {
diff --git a/src/assets/templates/bedrock-managed-agents/README.md b/src/assets/templates/bedrock-managed-agents/README.md
index 2222de3c18..3b64a7eed2 100644
--- a/src/assets/templates/bedrock-managed-agents/README.md
+++ b/src/assets/templates/bedrock-managed-agents/README.md
@@ -38,8 +38,6 @@ image build downloads Codex and Python from the internet, so a build in VPC mode
   capacity provider.
 
 To customize these settings after creation, edit the Runtime entry in `agentcore/agentcore.json`.
-When adding this environment to an existing project, `agentcore add runtime` also accepts
-`--lifecycle-configuration` and `--filesystem-configurations`.
 
 If the Runtime has an `executionRoleArn`, AgentCore CDK cannot attach `bma-acr-policy.json` to that imported role.
 Grant the role `bedrock-mantle:RegisterEnvironment` and `bedrock-mantle:ConnectEnvironment` before deploying.
diff --git a/src/assets/templates/runtime-docs/python/AGENTS.md b/src/assets/templates/runtime-docs/python/AGENTS.md
new file mode 100644
index 0000000000..ad8d7cd644
--- /dev/null
+++ b/src/assets/templates/runtime-docs/python/AGENTS.md
@@ -0,0 +1,85 @@
+# Instructions for coding agents: runtime `{{name}}`
+
+You are writing the code for an AgentCore runtime. The AgentCore CLI deploys
+this folder. Follow these rules exactly, or `agentcore dev` and
+`agentcore deploy` will fail. `README.md` in this folder explains each rule
+in more detail.
+
+## Must
+
+- Put the entrypoint in `main.py` at the root of this folder. To use another
+  file, name it in `pyproject.toml` under `[tool.agentcore]` as
+  `entrypoint = "server.py"` (optionally `"server.py:app"`); the CLI copies it
+  into `agentcore/agentcore.json` on `agentcore dev`, `build`, and `deploy`.
+- Implement the runtime contract with the AgentCore SDK for Python
+  (`bedrock-agentcore`, https://github.com/aws/bedrock-agentcore-sdk-python);
+  examples: https://github.com/awslabs/amazon-bedrock-agentcore-samples.
+{{#if (eq protocol "HTTP")}}
+- Serve the AgentCore HTTP contract on `0.0.0.0` port 8080: `POST /invocations`
+  (JSON in; JSON or `text/event-stream` out) and `GET /ping` (returns
+  `{"status": "Healthy"}` or `{"status": "HealthyBusy"}`). Use
+  `BedrockAgentCoreApp` from `bedrock_agentcore.runtime` with an
+  `@app.entrypoint` function; it implements both.
+- Keep a module-level `app` and end `main.py` with
+  `if __name__ == "__main__": app.run()`.
+{{/if}}
+{{#if (eq protocol "MCP")}}
+- Serve MCP over streamable HTTP on `0.0.0.0` port 8000 at `POST /mcp`, for
+  example with `FastMCP("{{name}}", host="0.0.0.0", stateless_http=True)` and
+  `mcp.run(transport="streamable-http")` under `if __name__ == "__main__":`.
+- Accept the platform-provided `Mcp-Session-Id` header. Stay stateless unless
+  the user needs elicitation or sampling with MCP protocol version 2025-11-25
+  or earlier, which requires stateful mode.
+- Add `mcp` to the dependencies. Do not hardcode a port other than 8000;
+  `agentcore dev` sets `FASTMCP_PORT`.
+{{/if}}
+{{#if (eq protocol "A2A")}}
+- Serve A2A on `0.0.0.0` port 9000: JSON-RPC 2.0 at `POST /` (for example
+  `message/send`), the agent card at `GET /.well-known/agent-card.json`, and
+  `GET /ping`. Use `serve_a2a(executor)` from `bedrock_agentcore.runtime`
+  under `if __name__ == "__main__":`; it implements all three.
+- Add `bedrock-agentcore[a2a] ~= 1.24.0` and `a2a-sdk` to the dependencies.
+{{/if}}
+{{#if (eq protocol "AGUI")}}
+- Serve AG-UI on `0.0.0.0` port 8080: `POST /invocations` takes a
+  `RunAgentInput` and streams AG-UI events as server-sent events, and
+  `GET /ping` returns `{"status": "Healthy"}` or `{"status": "HealthyBusy"}`.
+- Read the port from the `PORT` environment variable (default 8080) and start
+  the server under `if __name__ == "__main__":`.
+{{/if}}
+- Declare every dependency in `[project].dependencies` in `pyproject.toml`.
+  Do not use `requirements.txt`.
+- Include `bedrock-agentcore` and `aws-opentelemetry-distro` in the
+  dependencies.
+- Set `requires-python` to a range that includes at least one of
+  {{versions.python}}. It constrains `runtimeVersion` in `agentcore.json`:
+  the CLI keeps the current version while the range allows it, and only
+  replaces it (with the highest allowed) when the range excludes it.
+- Only use packages that publish `aarch64` manylinux wheels (glibc ≤ 2.34).
+- Read resource IDs from environment variables (`MEMORY_<NAME>_ID`,
+  `AGENTCORE_GATEWAY_<NAME>_URL`, `CREDENTIAL_<NAME>_NAME`, ...) and handle
+  them being missing.
+- Use the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header (or
+  `context.session_id`) to tell conversations apart. Custom headers only
+  arrive if they are named `X-Amzn-Bedrock-AgentCore-Runtime-Custom-*` and
+  listed in `requestHeaderAllowlist`.
+
+## Must not
+
+- Do not hardcode secrets or put `.env` files in this folder. Use
+  `agentcore add credential` and `@requires_api_key`.
+- Do not edit `agentcore/agentcore.json` unless the user asks. Set the build
+  settings in the code instead (`Dockerfile`, `requires-python`,
+  `[tool.agentcore] entrypoint`); the CLI updates `agentcore.json` from them.
+- Do not add a `Dockerfile` unless the user wants a container build.
+  Adding one switches this runtime to container mode.
+{{#if (or (eq protocol "HTTP") (eq protocol "A2A") (eq protocol "AGUI"))}}
+- If you implement `/ping` yourself, do not set `time_of_last_update` to the
+  current time on every ping; only change it when the status changes.
+{{/if}}
+
+## Check your work
+
+- Run `uv sync`, then `agentcore dev`, and invoke it locally.
+- Run `agentcore deploy` when the user is ready.
+- Contract reference: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-{{contractPage}}-protocol-contract.html
diff --git a/src/assets/templates/runtime-docs/python/README.md b/src/assets/templates/runtime-docs/python/README.md
new file mode 100644
index 0000000000..00d31ae30a
--- /dev/null
+++ b/src/assets/templates/runtime-docs/python/README.md
@@ -0,0 +1,369 @@
+# {{name}}
+
+This folder is the code for the `{{name}}` runtime. The AgentCore CLI created it
+with `agentcore add runtime`. It doesn't contain any code yet. This README
+explains what your code needs so that `agentcore dev` and `agentcore deploy`
+work.
+
+Using a coding agent? Point it at `AGENTS.md` in this folder. It has the same
+requirements, written as instructions.
+
+## What goes in this folder
+
+```
+app/{{name}}/
+├── main.py           # your entrypoint (required; see [tool.agentcore] to rename)
+├── pyproject.toml    # your dependencies (required)
+├── Dockerfile        # optional: only if you want a container build
+└── ...               # any other modules your code imports
+```
+
+The entrypoint is `main.py` at the root of this folder unless you name another
+file in `pyproject.toml` (see "How `agentcore.json` follows your code"). Other
+modules can live anywhere inside it and be imported normally.
+
+## Direct code deploy or container?
+
+The CLI decides when you run `dev`, `build`, or `deploy`:
+
+- **No `Dockerfile` in this folder:** direct code deploy (CodeZip). The CLI
+  installs your dependencies with uv, zips them with your code, and AgentCore
+  runs `main.py` on its managed Python runtime. This is the simpler option
+  and the one we recommend unless you need system packages or full control
+  of the image.
+- **A `Dockerfile` in this folder:** container deploy. The CLI builds your
+  image and AgentCore runs it. See "Container builds" below.
+
+## How `agentcore.json` follows your code
+
+`agentcore add runtime` registered this runtime with starting values: a
+direct code (CodeZip) build on Python {{versions.latestPython}} with entrypoint `main.py`. Each
+time you run `agentcore dev`, `agentcore build`, or `agentcore deploy`, the
+CLI reads your code, updates the runtime in `agentcore/agentcore.json`, and
+prints anything it changed:
+
+- **Build type:** adding a file named exactly `Dockerfile` to this folder
+  switches the runtime to a container build, and the CLI says so. It never
+  switches back on its own: to return to a direct code deploy, delete the
+  Dockerfile and set `"build": "CodeZip"` in `agentcore.json`.
+- **Python version** (CodeZip only): kept as long as `requires-python` in
+  `pyproject.toml` allows it (see below).
+- **Entrypoint:** from `[tool.agentcore]` in `pyproject.toml`, if you want a
+  file other than `main.py`, or an app object other than `app`. The CLI reads
+  exactly this form, a `[tool.agentcore]` table with `entrypoint = "..."` on
+  one line:
+
+  ```toml
+  [tool.agentcore]
+  entrypoint = "main.py"   # or "server.py:app"
+  ```
+
+Where your code doesn't say (no `[tool.agentcore]`), the value already in
+`agentcore.json` is kept.
+
+## The runtime contract
+
+AgentCore sends requests to a server your code runs. The easiest way to get
+it right is the AgentCore SDK for Python, `bedrock-agentcore`
+(https://github.com/aws/bedrock-agentcore-sdk-python), which implements the
+contract for you. For complete agents built on it, see the samples at
+https://github.com/awslabs/amazon-bedrock-agentcore-samples.
+
+{{#if (eq protocol "HTTP")}}
+For HTTP, the server listens on port **8080**, takes each invocation's JSON
+payload on `POST /invocations` (returning JSON or a `text/event-stream`
+stream), and answers health checks on `GET /ping` with
+`{"status": "Healthy"}` (or `"HealthyBusy"` to keep a busy session alive).
+
+```python
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+
+app = BedrockAgentCoreApp()
+
+
+@app.entrypoint
+def invoke(payload, context):
+    prompt = payload.get("prompt", "")
+    # your agent logic here
+    return {"message": f"You said: {prompt}"}
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Keep the module-level `app` (`agentcore dev` serves it with uvicorn and
+reloads it when you save) and the `app.run()` at the end (deployed, AgentCore
+runs `main.py` directly, so it must start the server itself).
+`context.session_id` identifies the conversation.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-http-protocol-contract.html
+{{/if}}
+{{#if (eq protocol "MCP")}}
+For MCP, the server listens on port **8000** and serves `POST /mcp` with the
+streamable HTTP transport. Stateless mode (`stateless_http=True`) is the
+default, and the server must accept the platform-provided `Mcp-Session-Id`
+header. Stateful mode also works. It is required for elicitation and sampling
+with MCP protocol version 2025-11-25 and earlier; from 2026-07-28 those use
+multi-round-trip requests, which work in stateless mode.
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("{{name}}", host="0.0.0.0", stateless_http=True)
+
+
+@mcp.tool()
+def add_numbers(a: int, b: int) -> int:
+    """Add two numbers together"""
+    return a + b
+
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")
+```
+
+Add `mcp` to your dependencies. `agentcore dev` sets `FASTMCP_PORT`, so
+don't hardcode a different port.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp-protocol-contract.html
+{{/if}}
+{{#if (eq protocol "A2A")}}
+For A2A, the server listens on port **9000**, takes JSON-RPC 2.0 messages
+(such as `message/send`) on `POST /`, publishes its agent card at
+`GET /.well-known/agent-card.json`, and answers `GET /ping`. `serve_a2a`
+from the SDK does all three:
+
+```python
+from bedrock_agentcore.runtime import serve_a2a
+
+# executor: any a2a-sdk AgentExecutor, e.g. StrandsA2AExecutor
+if __name__ == "__main__":
+    serve_a2a(executor)
+```
+
+Add `bedrock-agentcore[a2a] ~= 1.24.0` (the version line with `serve_a2a`) and
+`a2a-sdk` to your dependencies, as in the `pyproject.toml` example below.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a-protocol-contract.html
+{{/if}}
+{{#if (eq protocol "AGUI")}}
+For AG-UI, the server listens on port **8080**, takes an AG-UI
+`RunAgentInput` on `POST /invocations` and streams AG-UI events back as
+server-sent events, and answers health checks on `GET /ping`. Read the port
+from `PORT` so `agentcore dev` can move it:
+
+```python
+import os
+import uvicorn
+from fastapi import FastAPI
+
+app = FastAPI()
+# mount your AG-UI endpoint at /invocations and a health check at /ping
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))
+```
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui-protocol-contract.html
+{{/if}}
+
+Every protocol also shares these:
+
+- AgentCore runs your code on **ARM64** Linux and expects it to listen on
+  `0.0.0.0`.
+- Each request carries an `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`
+  header. Requests with the same session ID go to the same session (the same
+  microVM), so you can keep per-conversation state in memory.
+- Custom request headers only reach your code if they are named
+  `X-Amzn-Bedrock-AgentCore-Runtime-Custom-*` and listed in
+  `--request-header-allowlist` (`requestHeaderAllowlist` in `agentcore.json`).
+- If you write your own `/ping`, don't set the optional `time_of_last_update`
+  to the current time on every ping. Change it only when the status changes,
+  or idle sessions never time out and can use up your session quota.
+
+## Dependencies: `pyproject.toml`
+
+Declare dependencies in `[project].dependencies`. That's the only place the
+CLI reads them from. For direct code deploy, `requirements.txt` and
+`uv.lock` are ignored.
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{name}}"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+{{#if (eq protocol "A2A")}}
+    "bedrock-agentcore[a2a] ~= 1.24.0",
+    "a2a-sdk[all] ~= 0.3.26",
+{{else}}
+    "bedrock-agentcore >= 1.18.1, < 2.0.0",
+{{/if}}
+    "aws-opentelemetry-distro ~= 0.21.0",
+    # your framework and libraries, e.g. "strands-agents >= 1.15.0, < 2.0.0"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+```
+
+Two dependencies are required:
+
+- **`bedrock-agentcore`** provides the runtime server for HTTP and A2A.
+- **`aws-opentelemetry-distro`** is needed because AgentCore starts your code
+  with `opentelemetry-instrument`. Without it, the runtime won't start.
+  You'll also get traces and logs in CloudWatch.
+
+You need [uv](https://docs.astral.sh/uv/) installed. `agentcore dev` runs
+your code with `uv run`, and `agentcore deploy` uses uv to install your
+dependencies. Run `uv sync` once after editing `pyproject.toml` to get a
+local `.venv`.
+
+### How the Python version is chosen
+
+The Python version is `runtimeVersion` in `agentcore/agentcore.json`. A new
+runtime starts on the latest one AgentCore supports (Python
+{{versions.latestPython}}; supported versions are {{versions.python}}).
+
+`requires-python` is a constraint, not a choice. The CLI changes
+`runtimeVersion` only when `requires-python` excludes the current version;
+it then picks the **highest** supported version that `requires-python`
+allows, writes it, and prints the change. For example, with the current
+version Python {{versions.latestPython}}:
+
+- `>=3.12` allows it, so nothing changes.
+- `>=3.10,<3.13` excludes it, so the runtime moves to Python 3.12.
+- `==3.11.*` excludes it, so the runtime moves to Python 3.11.
+
+Nothing moves a runtime to a newer Python on its own, not even a newer CLI.
+To move to a newer version, edit `runtimeVersion` (for example
+`"PYTHON_3_13"`) or tighten `requires-python` so it excludes the old one.
+
+### Things that break direct code deploys
+
+- **Packages without ARM64 Linux wheels.** AgentCore runs on ARM64 Linux,
+  and the CLI only installs prebuilt wheels (`aarch64-manylinux`, glibc 2.34
+  or older). Packages that only publish source distributions fail to
+  install. If you need one, use a container build.
+- **Size.** The zip, meaning your code plus installed dependencies, must be
+  under 250 MiB.
+- **Secrets.** Everything in this folder is uploaded, including `.env`
+  files. Only `.git`, `.venv`, `__pycache__`, `.pytest_cache`,
+  `node_modules` and `.DS_Store` are left out. Put local secrets in
+  `agentcore/.env.local` instead. Put deployed secrets in a credential (see
+  below).
+
+## Using other resources
+
+Resources you add to the project are passed to your runtime as environment
+variables named after the resource:
+
+- Memory (`agentcore add memory`): `MEMORY_<NAME>_ID` and `MEMORY_<NAME>_ARN`,
+  where `<NAME>` is the memory name in upper case.
+- Gateway (`agentcore add gateway`): `AGENTCORE_GATEWAY_<NAME>_URL`,
+  `AGENTCORE_GATEWAY_<NAME>_ARN` and `AGENTCORE_GATEWAY_<NAME>_AUTH_TYPE`, where
+  `<NAME>` is the gateway name in upper case with every character other than
+  letters and digits turned into `_`.
+- Credential (`agentcore add credential`): `CREDENTIAL_<NAME>_NAME`, the
+  provider name (not the secret), where `<NAME>` is the credential name in
+  upper case with `.` and `-` turned into `_`.
+
+For example, a memory named `{{memoryExample.name}}` shows up as
+`{{memoryExample.env}}`, a gateway named `{{gatewayExample.name}}` as
+`{{gatewayExample.env}}`, and a credential named `{{credentialExample.name}}` as
+`{{credentialExample.env}}`. Read these with
+`os.environ.get(...)` and handle them being missing, so your code still runs before the resource
+exists.
+
+**API keys** (for example for a non-Bedrock model provider): add them with
+`agentcore add credential`. The secret is never put in an environment
+variable. Fetch it at runtime through AgentCore Identity with the
+`@requires_api_key(provider_name=...)` decorator from `bedrock_agentcore`,
+using the provider name from `CREDENTIAL_<NAME>_NAME`.
+
+Your own variables go in `--environment-variables` (deployed) or
+`agentcore/.env.local` (local only, gitignored).
+
+## Run it locally
+
+```bash
+agentcore dev
+```
+
+`dev` sets a few variables for you:
+
+- `PORT`: the port to listen on.
+- `LOCAL_DEV=1`: use this if your code should behave differently locally,
+  for example reading an API key from `.env.local` instead of AgentCore
+  Identity.
+- `AWS_REGION`.
+
+It also starts a local OpenTelemetry collector, so you can see traces while
+you develop.
+
+## Deploy and invoke
+
+```bash
+agentcore deploy
+agentcore invoke --runtime {{name}} --payload '{"prompt": "Hello"}'
+```
+
+## Container builds
+
+Add a `Dockerfile` to this folder and the CLI switches to a container build.
+Nothing else needs to change in `agentcore.json`.
+
+Requirements for the image:
+
+- **ARM64.** Images are built natively on ARM64 in AWS CodeBuild, so your
+  base image has to support `linux/arm64`. Most official images do.
+- **Port.** Listen on `0.0.0.0` on port {{port}} and `EXPOSE` it.
+- **Non-root user.** Recommended: run as a non-root user (for example
+  uid 1000).
+- **Observability.** Start your app with `opentelemetry-instrument` to get
+  traces and logs in CloudWatch.
+- **Lockfile.** If you install with `uv sync --frozen`, commit `uv.lock`.
+  Run `uv lock` to create it.
+
+A starting point:
+
+```dockerfile
+FROM public.ecr.aws/docker/library/python:3.12-slim-trixie
+
+RUN pip install --no-cache-dir uv
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+ENV UV_SYSTEM_PYTHON=1 UV_COMPILE_BYTECODE=1 PYTHONUNBUFFERED=1 \
+    UV_DEFAULT_INDEX=${UV_DEFAULT_INDEX} UV_INDEX=${UV_INDEX} \
+    PATH="/app/.venv/bin:$PATH"
+
+WORKDIR /app
+RUN useradd -m -u 1000 bedrock_agentcore
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+COPY --chown=bedrock_agentcore:bedrock_agentcore . .
+RUN uv sync --frozen --no-dev
+
+USER bedrock_agentcore
+EXPOSE {{port}}
+CMD ["opentelemetry-instrument", "python", "-m", "main"]
+```
+
+Notes:
+
+- **Build context.** The build context is this folder. Add a
+  `.dockerignore` to keep things out of it. `.env` files are always left
+  out.
+- **Build arguments.** To pass build arguments, such as a private package
+  index for `UV_DEFAULT_INDEX`, set `customDockerBuildArgs` on this runtime
+  in `agentcore.json`.
+- **Local engine.** `agentcore dev` builds and runs the image locally with
+  Docker, Podman or Finch, so you need one of them installed.
+- **Python version.** For container builds, the Python version is whatever
+  your base image provides. `requires-python` isn't used.
diff --git a/src/assets/templates/runtime-docs/typescript/AGENTS.md b/src/assets/templates/runtime-docs/typescript/AGENTS.md
new file mode 100644
index 0000000000..7f4ba09053
--- /dev/null
+++ b/src/assets/templates/runtime-docs/typescript/AGENTS.md
@@ -0,0 +1,77 @@
+# Instructions for coding agents: runtime `{{name}}`
+
+You are writing the code for an AgentCore runtime. The AgentCore CLI deploys
+this folder. Follow these rules exactly, or `agentcore dev` and
+`agentcore deploy` will fail. `README.md` in this folder explains each rule
+in more detail.
+
+## Must
+
+- Put the entrypoint in `main.ts` at the root of this folder. The CLI bundles
+  it into `main.js`, which `agentcore.json` records as the entrypoint. A
+  `"main"` in `package.json` other than `"main.ts"` is ignored.
+- Implement the runtime contract with the AgentCore SDK for TypeScript
+  (`bedrock-agentcore`, https://github.com/aws/bedrock-agentcore-sdk-typescript);
+  examples: https://github.com/awslabs/amazon-bedrock-agentcore-samples.
+{{#if (eq protocol "HTTP")}}
+- Serve the AgentCore HTTP contract on `0.0.0.0` port 8080: `POST /invocations`
+  (JSON in; JSON or `text/event-stream` out) and `GET /ping` (returns
+  `{"status": "Healthy"}` or `{"status": "HealthyBusy"}`). Use
+  `BedrockAgentCoreApp` from `bedrock-agentcore/runtime`; it implements both.
+- Start the server with `app.run({ port: parseInt(process.env.PORT ?? '8080') })`.
+{{/if}}
+{{#if (eq protocol "MCP")}}
+- Serve MCP over streamable HTTP on `0.0.0.0` port 8000 at `POST /mcp`.
+- Accept the platform-provided `Mcp-Session-Id` header. Stay stateless unless
+  the user needs elicitation or sampling with MCP protocol version 2025-11-25
+  or earlier, which requires stateful mode.
+- Read the port from the `PORT` environment variable (default 8000).
+{{/if}}
+{{#if (eq protocol "A2A")}}
+- Serve A2A on `0.0.0.0` port 9000: JSON-RPC 2.0 at `POST /` (for example
+  `message/send`), the agent card at `GET /.well-known/agent-card.json`, and
+  `GET /ping` returning `{"status": "Healthy"}`.
+- Read the port from the `PORT` environment variable (default 9000).
+{{/if}}
+{{#if (eq protocol "AGUI")}}
+- Serve AG-UI on `0.0.0.0` port 8080: `POST /invocations` takes a
+  `RunAgentInput` and streams AG-UI events as server-sent events, and
+  `GET /ping` returns `{"status": "Healthy"}` or `{"status": "HealthyBusy"}`.
+- Read the port from the `PORT` environment variable (default 8080).
+{{/if}}
+- Declare every dependency in `package.json`, including `bedrock-agentcore`
+  and `tsx` (used by `agentcore dev`).
+- Set `engines.node` to a range that includes at least one of
+  {{versions.node}}. It constrains `runtimeVersion` in `agentcore.json`: the
+  CLI keeps the current version while the range allows it, and only replaces
+  it (with the highest allowed) when the range excludes it.
+- Run `npm install` so `node_modules` exists; deploy bundles from it.
+- Read resource IDs from environment variables (`MEMORY_<NAME>_ID`,
+  `AGENTCORE_GATEWAY_<NAME>_URL`, `CREDENTIAL_<NAME>_NAME`, ...) and handle
+  them being missing.
+- Use the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header to tell
+  conversations apart. Custom headers only arrive if they are named
+  `X-Amzn-Bedrock-AgentCore-Runtime-Custom-*` and listed in
+  `requestHeaderAllowlist`.
+
+## Must not
+
+- Do not use top-level `await` in `main.ts` or anything it imports; the
+  bundle is CommonJS.
+- Do not hardcode secrets or put `.env` files in this folder. Use
+  `agentcore add credential` and `withApiKey`.
+- Do not edit `agentcore/agentcore.json` unless the user asks. Set the build
+  settings in the code instead (`Dockerfile`, `engines.node`); the CLI updates
+  `agentcore.json` from them.
+- Do not add a `Dockerfile` unless the user wants a container build.
+  Adding one switches this runtime to container mode.
+{{#if (or (eq protocol "HTTP") (eq protocol "A2A") (eq protocol "AGUI"))}}
+- If you implement `/ping` yourself, do not set `time_of_last_update` to the
+  current time on every ping; only change it when the status changes.
+{{/if}}
+
+## Check your work
+
+- Run `npm install`, then `agentcore dev`, and invoke it locally.
+- Run `agentcore deploy` when the user is ready.
+- Contract reference: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-{{contractPage}}-protocol-contract.html
diff --git a/src/assets/templates/runtime-docs/typescript/README.md b/src/assets/templates/runtime-docs/typescript/README.md
new file mode 100644
index 0000000000..6cb6a93a07
--- /dev/null
+++ b/src/assets/templates/runtime-docs/typescript/README.md
@@ -0,0 +1,304 @@
+# {{name}}
+
+This folder is the code for the `{{name}}` runtime. The AgentCore CLI created it
+with `agentcore add runtime`. It doesn't contain any code yet. This README
+explains what your code needs so that `agentcore dev` and `agentcore deploy`
+work.
+
+Using a coding agent? Point it at `AGENTS.md` in this folder. It has the same
+requirements, written as instructions.
+
+## What goes in this folder
+
+```
+app/{{name}}/
+├── main.ts           # your entrypoint (required, this exact name)
+├── package.json      # your dependencies (required)
+├── tsconfig.json     # recommended, for your editor and type checking
+├── node_modules/     # run `npm install`; deploy bundles from it
+├── Dockerfile        # optional: only if you want a container build
+└── ...               # any other modules main.ts imports
+```
+
+`main.ts` must sit at the root of this folder. The CLI always bundles from
+`app/{{name}}/main.ts`, whatever else is in the folder. `agentcore.json` records
+the bundled output, `main.js`, as the entrypoint.
+
+## Direct code deploy or container?
+
+The CLI decides when you run `dev`, `build`, or `deploy`:
+
+- **No `Dockerfile` in this folder:** direct code deploy (CodeZip). The CLI
+  bundles `main.ts` and everything it imports into a single `main.js` with
+  esbuild, and AgentCore runs it on its managed Node.js runtime. This is the
+  simpler option and the one we recommend.
+- **A `Dockerfile` in this folder:** container deploy. The CLI builds your
+  image and AgentCore runs it. See "Container builds" below.
+
+## How `agentcore.json` follows your code
+
+`agentcore add runtime` registered this runtime with starting values: a
+direct code (CodeZip) build on Node.js {{versions.latestNode}} with entrypoint `main.js` (the
+bundle the CLI builds from `main.ts`). Each time you run `agentcore dev`,
+`agentcore build`, or `agentcore deploy`, the CLI reads your code, updates
+the runtime in `agentcore/agentcore.json`, and prints anything it changed:
+
+- **Build type:** adding a file named exactly `Dockerfile` to this folder
+  switches the runtime to a container build, and the CLI says so. It never
+  switches back on its own: to return to a direct code deploy, delete the
+  Dockerfile and set `"build": "CodeZip"` in `agentcore.json`.
+- **Node.js version** (CodeZip only): kept as long as `engines.node` in
+  `package.json` allows it (see below).
+- **Entrypoint** (CodeZip only): AgentCore currently bundles `main.ts` at the
+  root of this folder, stored as `main.js`. A `"main"` of `"main.ts"` or
+  `"main.js"` in `package.json` agrees with that; any other `"main"` is
+  ignored with a warning.
+
+## The runtime contract
+
+AgentCore sends requests to a server your code runs. The easiest way to get
+it right is the AgentCore SDK for TypeScript, `bedrock-agentcore`
+(https://github.com/aws/bedrock-agentcore-sdk-typescript), which implements
+the contract for you. For complete agents, see the samples at
+https://github.com/awslabs/amazon-bedrock-agentcore-samples.
+
+{{#if (eq protocol "HTTP")}}
+For HTTP, the server listens on port **8080**, takes each invocation's JSON
+payload on `POST /invocations` (returning JSON or a `text/event-stream`
+stream), and answers health checks on `GET /ping` with
+`{"status": "Healthy"}` (or `"HealthyBusy"` to keep a busy session alive).
+
+```ts
+import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
+import { z } from 'zod';
+
+const app = new BedrockAgentCoreApp({
+  invocationHandler: {
+    requestSchema: z.object({ prompt: z.string().default('') }),
+    async *process(payload, context) {
+      // your agent logic here; yield chunks to stream
+      yield { data: `You said: ${payload.prompt}` };
+    },
+  },
+});
+
+app.run({ port: parseInt(process.env.PORT ?? '8080') });
+```
+
+Read the port from `PORT`, so `agentcore dev` can move it if 8080 is busy.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-http-protocol-contract.html
+{{/if}}
+{{#if (eq protocol "MCP")}}
+For MCP, the server listens on port **8000** (read it from `PORT` in local
+dev) and serves `POST /mcp` with the streamable HTTP transport. Stateless mode
+is the default, and the server must accept the platform-provided
+`Mcp-Session-Id` header. Stateful mode also works. It is required for
+elicitation and sampling with MCP protocol version 2025-11-25 and earlier;
+from 2026-07-28 those use multi-round-trip requests, which work in stateless
+mode.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-mcp-protocol-contract.html
+{{/if}}
+{{#if (eq protocol "A2A")}}
+For A2A, the server listens on port **9000** (read it from `PORT` in local
+dev), takes JSON-RPC 2.0 messages (such as `message/send`) on `POST /`,
+publishes its agent card at `GET /.well-known/agent-card.json`, and answers
+health checks on `GET /ping`.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a-protocol-contract.html
+{{/if}}
+{{#if (eq protocol "AGUI")}}
+For AG-UI, the server listens on port **8080** (read it from `PORT` in local
+dev), takes an AG-UI `RunAgentInput` on `POST /invocations` and streams AG-UI
+events back as server-sent events, and answers health checks on `GET /ping`.
+
+Full contract: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui-protocol-contract.html
+{{/if}}
+
+Every protocol also shares these:
+
+- AgentCore runs your code on **ARM64** Linux and expects it to listen on
+  `0.0.0.0`.
+- Each request carries an `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`
+  header. Requests with the same session ID go to the same session (the same
+  microVM), so you can keep per-conversation state in memory.
+- Custom request headers only reach your code if they are named
+  `X-Amzn-Bedrock-AgentCore-Runtime-Custom-*` and listed in
+  `--request-header-allowlist` (`requestHeaderAllowlist` in `agentcore.json`).
+- If you write your own `/ping`, don't set the optional `time_of_last_update`
+  to the current time on every ping. Change it only when the status changes,
+  or idle sessions never time out and can use up your session quota.
+
+## Dependencies: `package.json`
+
+```json
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "main.ts",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "dev": "tsx watch main.ts"
+  },
+  "dependencies": {
+    "bedrock-agentcore": "~0.3.0",
+    "zod": "~4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "~22.0.0",
+    "tsx": "~4.19.0",
+    "typescript": "~5.6.0"
+  }
+}
+```
+
+- **`bedrock-agentcore`** provides the runtime server.
+- **`tsx`** is what `agentcore dev` uses to run `main.ts` with reload on save.
+- **Run `npm install` before you deploy.** The bundle is built from your
+  local `node_modules`, and deploy fails if it's missing. `agentcore dev`
+  runs `npm install` for you the first time.
+
+### How your code is bundled
+
+You don't need a build step. At deploy, esbuild bundles `main.ts` and every
+import into one minified `main.js`. Only that file and a few packages the
+SDK loads dynamically are uploaded. Your `node_modules` folder itself isn't.
+
+Some consequences:
+
+- **ESM source is fine.** Write normal `import`s, as in the example. The
+  bundle is CommonJS, and esbuild converts your code.
+- **No top-level `await` in `main.ts` or its imports.** CommonJS can't
+  express it, so the bundle fails. Do async setup inside your handler, or in
+  an async function you call from it.
+- **`tsconfig.json` isn't read by the bundler.** Keep one for your editor
+  and for `tsc --noEmit` type checking. `"module": "NodeNext"` with `.js`
+  suffixes on relative imports works well.
+- **Size.** The zip must be under 250 MiB.
+- **Secrets.** Don't keep secrets in this folder. Use `agentcore/.env.local`
+  for local secrets and a credential for deployed ones (see below).
+
+### How the Node.js version is chosen
+
+The Node.js version is `runtimeVersion` in `agentcore/agentcore.json`, and
+the bundle targets it. A new runtime starts on the latest one AgentCore
+supports (Node.js {{versions.latestNode}}; supported versions are {{versions.node}}).
+
+`engines.node` is a constraint, not a choice. The CLI changes
+`runtimeVersion` only when `engines.node` excludes the current version; it
+then picks the **highest** supported version that `engines.node` allows,
+writes it, and prints the change. For example, with the current version
+Node.js {{versions.latestNode}}:
+
+- `>=20` allows it, so nothing changes.
+- `^20` excludes it, so the runtime moves to Node.js 20.
+
+Nothing moves a runtime to a newer Node.js on its own, not even a newer CLI.
+To move to a newer version, edit `runtimeVersion` (for example `"NODE_22"`)
+or tighten `engines.node` so it excludes the old one.
+
+## Using other resources
+
+Resources you add to the project are passed to your runtime as environment
+variables named after the resource:
+
+- Memory (`agentcore add memory`): `MEMORY_<NAME>_ID` and `MEMORY_<NAME>_ARN`,
+  where `<NAME>` is the memory name in upper case.
+- Gateway (`agentcore add gateway`): `AGENTCORE_GATEWAY_<NAME>_URL`,
+  `AGENTCORE_GATEWAY_<NAME>_ARN` and `AGENTCORE_GATEWAY_<NAME>_AUTH_TYPE`, where
+  `<NAME>` is the gateway name in upper case with every character other than
+  letters and digits turned into `_`.
+- Credential (`agentcore add credential`): `CREDENTIAL_<NAME>_NAME`, the
+  provider name (not the secret), where `<NAME>` is the credential name in
+  upper case with `.` and `-` turned into `_`.
+
+For example, a memory named `{{memoryExample.name}}` shows up as
+`{{memoryExample.env}}`, a gateway named `{{gatewayExample.name}}` as
+`{{gatewayExample.env}}`, and a credential named `{{credentialExample.name}}` as
+`{{credentialExample.env}}`.
+
+Read these from `process.env` and handle them being missing, so your code
+still runs before the resource exists.
+
+**API keys** (for example for a non-Bedrock model provider): add them with
+`agentcore add credential`. The secret is never put in an environment
+variable. Fetch it at runtime through AgentCore Identity with `withApiKey`
+from `bedrock-agentcore`, using the provider name from
+`CREDENTIAL_<NAME>_NAME`.
+
+Your own variables go in `--environment-variables` (deployed) or
+`agentcore/.env.local` (local only, gitignored).
+
+## Run it locally
+
+```bash
+agentcore dev
+```
+
+`dev` runs `tsx watch main.ts` and sets:
+
+- `PORT`: the port to listen on.
+- `LOCAL_DEV=1`: for local-only behavior, such as reading an API key from
+  `.env.local`.
+- `AWS_REGION`.
+
+## Deploy and invoke
+
+```bash
+agentcore deploy
+agentcore invoke --runtime {{name}} --payload '{"prompt": "Hello"}'
+```
+
+## Observability
+
+AgentCore doesn't auto-instrument Node.js runtimes the way it does Python.
+To send traces, set up OpenTelemetry in your code.
+
+## Container builds
+
+Add a `Dockerfile` to this folder and the CLI switches to a container build.
+Nothing else needs to change in `agentcore.json`.
+
+Requirements for the image:
+
+- **ARM64.** Images are built natively on ARM64 in AWS CodeBuild, so your
+  base image has to support `linux/arm64`.
+- **Port.** Listen on `0.0.0.0` on port {{port}} and `EXPOSE` it.
+- **Non-root user.** Recommended: run as a non-root user.
+- **Lockfile.** If you install with `npm ci`, commit `package-lock.json`.
+
+A starting point:
+
+```dockerfile
+FROM public.ecr.aws/docker/library/node:22-slim
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npx esbuild main.ts --bundle --platform=node --target=node22 --outfile=dist/main.js \
+    && npm prune --omit=dev
+
+USER node
+EXPOSE {{port}}
+CMD ["node", "dist/main.js"]
+```
+
+Notes:
+
+- **No CLI bundling.** With a container build, the CLI doesn't bundle your
+  code. The Dockerfile decides how it's built and started, and the
+  Node.js version comes from your base image.
+- **Build context.** The build context is this folder. Add a
+  `.dockerignore` (at least `node_modules`). `.env` files are always left
+  out.
+- **Build arguments.** Set `customDockerBuildArgs` on this runtime in
+  `agentcore.json` to pass build arguments.
+- **Local engine.** `agentcore dev` builds and runs the image locally with
+  Docker, Podman or Finch.
diff --git a/src/core/project/manager.export.test.ts b/src/core/project/manager.export.test.ts
index 9c2e70cef3..1aa8cd5050 100644
--- a/src/core/project/manager.export.test.ts
+++ b/src/core/project/manager.export.test.ts
@@ -6,6 +6,7 @@ import { tmpdir } from "node:os";
 import z from "zod";
 import { parse, stringify } from "yaml";
 import { FsProjectManager } from "./manager";
+import { prepareRuntimes } from "./runtimeBuild";
 import { FsReadWriteJson, type ReadWriteJson } from "../../io";
 import { createSilentLogger, TestIdentityClient } from "../../testing";
 import { resolveRuntimeTemplateShortcut } from "../../handlers/project/shortcuts";
@@ -338,6 +339,10 @@ describe("FsProjectManager.exportHarness rendered tree", () => {
     expect(runtime.build).toBe("CodeZip");
     expect(runtime.runtimeVersion).toBe("PYTHON_3_14");
     expect(runtime.dockerfile).toBeUndefined();
+    // dev/build/deploy re-derive build settings from the code; an export already agrees.
+    const prepared = prepareRuntimes(project.rootPath, spec.runtimes, "dev");
+    expect(prepared.changed).toEqual([]);
+    expect(prepared.messages).toEqual([]);
   });
 
   test("exports a containerUri harness as CodeZip and reports the dropped image", async () => {
diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts
index d635ab500f..f26a43468f 100644
--- a/src/core/project/manager.test.ts
+++ b/src/core/project/manager.test.ts
@@ -2690,3 +2690,502 @@ describe("migratedFrom", () => {
     expect(written.migratedFrom).toBe("v1");
   });
 });
+
+describe("docs-only runtimes", () => {
+  const recordingBackend = () => {
+    const builds: Project[] = [];
+    const backend: ProjectBackend = {
+      async *build(project) {
+        builds.push(project);
+        yield { type: "step", message: "Building" };
+      },
+      async *deploy() {
+        yield { type: "step", message: "Deploying" };
+        return { outputs: {} };
+      },
+      async resolveDeployedResources() {
+        return [];
+      },
+      async resolveProjectResources() {
+        return [];
+      },
+    };
+    return { backend, builds };
+  };
+
+  async function emptyProject(subject: FsProjectManager): Promise<Project> {
+    await inTempDirectory();
+    const { project } = await runCreate(subject, {
+      name: "example",
+      skipInstall: true,
+      skipGit: true,
+    });
+    return project;
+  }
+
+  const docsRuntime = (overrides: Record<string, unknown> = {}): AddResourceInput => ({
+    resourceType: "runtime",
+    resourceConfig: { name: "search", language: "Python", protocol: "HTTP", ...overrides },
+  });
+
+  async function addFails(subject: FsProjectManager, project: Project, input: AddResourceInput) {
+    // networkMode VPC without networkConfig passes the add input but fails the
+    // spec commit, which is what triggers the rollback.
+    await expect(runAdd(subject, project, input)).rejects.toThrow(
+      "networkConfig is required when networkMode is VPC",
+    );
+  }
+
+  test("writes only docs and a complete spec entry with starting values, installing nothing", async () => {
+    const { manager: subject, commands, checkedTools } = manager();
+    const project = await emptyProject(subject);
+    commands.length = 0;
+    checkedTools.length = 0;
+
+    const updated = await runAdd(subject, project, docsRuntime({ protocol: "A2A" }));
+
+    expect(updated.spec.runtimes).toEqual([
+      {
+        name: "search",
+        codeLocation: "app/search" as never,
+        build: "CodeZip",
+        runtimeVersion: "PYTHON_3_14",
+        entrypoint: "main.py",
+        protocol: "A2A",
+      },
+    ]);
+    expect((await readdir(join(project.rootPath, "app", "search"))).sort()).toEqual([
+      "AGENTS.md",
+      "README.md",
+    ]);
+    expect(commands).toEqual([]);
+    expect(checkedTools).toEqual([]);
+  });
+
+  test("a failed commit removes the folder it created", async () => {
+    const { manager: subject } = manager();
+    const project = await emptyProject(subject);
+
+    await addFails(subject, project, docsRuntime({ networkMode: "VPC" }));
+
+    expect(existsSync(join(project.rootPath, "app", "search"))).toBe(false);
+  });
+
+  test("a failed commit never deletes a folder or files that were already there", async () => {
+    const { manager: subject } = manager();
+    const project = await emptyProject(subject);
+    const appDir = join(project.rootPath, "app", "search");
+    await mkdir(join(appDir, "lib"), { recursive: true });
+    await writeFile(join(appDir, "main.py"), "print('mine')\n");
+    await writeFile(join(appDir, "README.md"), "# mine\n");
+    await writeFile(join(appDir, "lib", "tools.py"), "");
+
+    await addFails(subject, project, docsRuntime({ networkMode: "VPC" }));
+
+    // Only the docs this add wrote are gone; the user's README was never replaced.
+    expect((await readdir(appDir, { recursive: true })).sort()).toEqual([
+      "README.md",
+      "lib",
+      join("lib", "tools.py"),
+      "main.py",
+    ]);
+    expect(await readFile(join(appDir, "README.md"), "utf-8")).toBe("# mine\n");
+  });
+
+  test("a failed commit leaves an existing user README.md and its folder untouched", async () => {
+    const { manager: subject } = manager();
+    const project = await emptyProject(subject);
+    const appDir = join(project.rootPath, "app", "search");
+    await mkdir(appDir, { recursive: true });
+    await writeFile(join(appDir, "README.md"), "# my agent\n");
+
+    await addFails(subject, project, docsRuntime({ networkMode: "VPC" }));
+
+    expect(await readdir(appDir)).toEqual(["README.md"]);
+    expect(await readFile(join(appDir, "README.md"), "utf-8")).toBe("# my agent\n");
+  });
+
+  test("a docs write that fails partway removes only what it wrote", async () => {
+    const failing = new FsProjectManager({
+      logger: createSilentLogger(),
+      identity: new TestIdentityClient(),
+      enableTransactionSearch: async () => {},
+      source: {
+        list: async (dir) => [`${dir}/AGENTS.md`, `${dir}/README.md`],
+        read: async (path) => {
+          if (path.endsWith("README.md")) throw new Error("disk full");
+          return "doc\n";
+        },
+      },
+    });
+    const project = await emptyProject(manager().manager);
+
+    await expect(runAdd(failing, project, docsRuntime())).rejects.toThrow("disk full");
+    expect(existsSync(join(project.rootPath, "app", "search"))).toBe(false);
+
+    const appDir = join(project.rootPath, "app", "search");
+    await mkdir(appDir, { recursive: true });
+    await writeFile(join(appDir, "main.py"), "");
+    await expect(runAdd(failing, project, docsRuntime())).rejects.toThrow("disk full");
+    expect(await readdir(appDir)).toEqual(["main.py"]);
+  });
+
+  test.each<[string, (spec: Record<string, unknown[]>) => void, string]>([
+    [
+      "a harness",
+      (spec) => (spec.harnesses ??= []).push({ name: "assistant", path: "app/search" }),
+      "harness 'assistant'",
+    ],
+    [
+      "another runtime",
+      (spec) =>
+        (spec.runtimes ??= []).push({
+          name: "other",
+          build: "CodeZip",
+          runtimeVersion: "PYTHON_3_14",
+          entrypoint: "main.py",
+          codeLocation: "app/search/",
+          protocol: "HTTP",
+        }),
+      "runtime 'other'",
+    ],
+    [
+      "a code-based evaluator",
+      (spec) =>
+        (spec.evaluators ??= []).push({
+          name: "grader",
+          level: "SESSION",
+          config: { codeBased: { managed: { codeLocation: "./app/search" } } },
+        }),
+      "evaluator 'grader'",
+    ],
+    [
+      "a harness nested inside it",
+      (spec) => (spec.harnesses ??= []).push({ name: "inner", path: "app/search/sub" }),
+      "harness 'inner'",
+    ],
+    [
+      "a runtime whose folder contains it",
+      (spec) =>
+        (spec.runtimes ??= []).push({
+          name: "everything",
+          build: "CodeZip",
+          runtimeVersion: "PYTHON_3_14",
+          entrypoint: "main.py",
+          codeLocation: "app",
+          protocol: "HTTP",
+        }),
+      "runtime 'everything'",
+    ],
+  ])("refuses a folder that overlaps %s", async (_label, own, owner) => {
+    const { manager: subject } = manager();
+    const created = await emptyProject(subject);
+    const specPath = join(created.rootPath, "agentcore", "agentcore.json");
+    const spec = JSON.parse(await readFile(specPath, "utf-8"));
+    own(spec);
+    await writeFile(specPath, JSON.stringify(spec));
+    const project = (await subject.resolve({ filePath: created.rootPath }))!;
+
+    await expect(runAdd(subject, project, docsRuntime())).rejects.toThrow(
+      new InputValidationError(
+        `cannot add runtime 'search': 'app/search' overlaps the files of ${owner}. ` +
+          "Choose a different --name.",
+      ),
+    );
+    expect(existsSync(join(created.rootPath, "app", "search", "AGENTS.md"))).toBe(false);
+  });
+
+  test("a sibling folder with a shared prefix is not an overlap", async () => {
+    const { manager: subject } = manager();
+    const created = await emptyProject(subject);
+    const specPath = join(created.rootPath, "agentcore", "agentcore.json");
+    const spec = JSON.parse(await readFile(specPath, "utf-8"));
+    spec.harnesses = [{ name: "searcher", path: "app/searcher" }];
+    await writeFile(specPath, JSON.stringify(spec));
+    const project = (await subject.resolve({ filePath: created.rootPath }))!;
+    await expect(runAdd(subject, project, docsRuntime())).resolves.toBeDefined();
+  });
+
+  test("an import into an existing folder that fails partway removes only what it wrote", async () => {
+    const { manager: subject } = manager();
+    const project = await emptyProject(subject);
+    const appDir = join(project.rootPath, "app", "agent");
+    await mkdir(appDir, { recursive: true });
+    // The translated plan writes main.py first, then collides with the user's pyproject.toml.
+    await writeFile(join(appDir, "pyproject.toml"), "# mine\n");
+
+    await expect(
+      runAdd(subject, project, {
+        resourceType: "runtime",
+        resourceConfig: {
+          name: "agent",
+          scaffoldRuntimeInput: { ...AGENT_PYTHON, runtimeName: "agent" },
+          importBedrockAgent: {
+            framework: "strands",
+            sourceAgentId: "A1B2C3D4E5",
+            sourceAgentAliasId: "TSTALIASID",
+            sourceAgentVersion: "1",
+            files: { "main.py": "print('translated')\n", "pyproject.toml": "[project]\n" },
+            notes: [],
+          },
+        },
+      }),
+    ).rejects.toThrow("File already exists");
+    expect(await readdir(appDir)).toEqual(["pyproject.toml"]);
+    expect(await readFile(join(appDir, "pyproject.toml"), "utf-8")).toBe("# mine\n");
+  });
+
+  test("a scaffold that fails to commit never deletes a folder that was already there", async () => {
+    const { manager: subject } = manager();
+    const project = await emptyProject(subject);
+    const appDir = join(project.rootPath, "app", "agent");
+    await mkdir(appDir, { recursive: true });
+    await writeFile(join(appDir, "notes.txt"), "keep me\n");
+
+    await addFails(subject, project, {
+      resourceType: "runtime",
+      resourceConfig: {
+        name: "agent",
+        networkMode: "VPC",
+        scaffoldRuntimeInput: { ...AGENT_PYTHON, runtimeName: "agent" },
+      },
+    });
+
+    expect(await readFile(join(appDir, "notes.txt"), "utf-8")).toBe("keep me\n");
+  });
+
+  test("build writes what the code changed to agentcore.json, then hands off to the backend", async () => {
+    const { backend, builds } = recordingBackend();
+    const subject = new FsProjectManager({
+      logger: createSilentLogger(),
+      identity: new TestIdentityClient(),
+      enableTransactionSearch: async () => {},
+      backends: { CDK: backend },
+    });
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+    const specPath = join(project.rootPath, "agentcore", "agentcore.json");
+    // A field the schema does not know about must survive the write.
+    const raw = JSON.parse(await readFile(specPath, "utf-8"));
+    raw.runtimes[0].x_note = "kept";
+    await writeFile(specPath, JSON.stringify(raw, null, 2));
+    const appDir = join(project.rootPath, "app", "search");
+    await writeFile(join(appDir, "main.py"), "");
+    await writeFile(
+      join(appDir, "pyproject.toml"),
+      '[project]\nrequires-python = ">=3.10,<3.13"\n\n[tool.agentcore]\nentrypoint = "main.py:app"\n',
+    );
+
+    const events = [];
+    for await (const event of subject.build(project)) events.push(event);
+
+    expect(events).toEqual([
+      {
+        type: "step",
+        message:
+          'search: runtimeVersion PYTHON_3_14 -> PYTHON_3_12 (requires-python ">=3.10,<3.13" in ' +
+          "app/search/pyproject.toml)",
+      },
+      {
+        type: "step",
+        message:
+          "search: entrypoint main.py -> main.py:app ([tool.agentcore] entrypoint in " +
+          "app/search/pyproject.toml)",
+      },
+      { type: "step", message: "Building" },
+    ]);
+    // The backend synthesizes from the updated spec, which is what is on disk.
+    expect(builds[0]?.spec.runtimes[0]).toMatchObject({
+      runtimeVersion: "PYTHON_3_12",
+      entrypoint: "main.py:app",
+    });
+    const onDisk = JSON.parse(await readFile(specPath, "utf-8"));
+    expect(onDisk.runtimes[0]).toEqual({
+      name: "search",
+      codeLocation: "app/search",
+      build: "CodeZip",
+      runtimeVersion: "PYTHON_3_12",
+      entrypoint: "main.py:app",
+      protocol: "HTTP",
+      x_note: "kept",
+    });
+
+    // A second build finds nothing to change and writes nothing.
+    const before = await readFile(specPath, "utf-8");
+    const again = [];
+    for await (const event of subject.build((await subject.resolve({ filePath: appDir }))!)) {
+      again.push(event);
+    }
+    expect(again).toEqual([{ type: "step", message: "Building" }]);
+    expect(await readFile(specPath, "utf-8")).toBe(before);
+  });
+
+  test("deploy switches to a Container build when a Dockerfile appears, before synth", async () => {
+    const deployed: Project[] = [];
+    const { backend } = recordingBackend();
+    backend.deploy = async function* (configured) {
+      deployed.push(configured);
+      yield { type: "step", message: "Deploying" };
+      return { outputs: {} };
+    };
+    const subject = new FsProjectManager({
+      logger: createSilentLogger(),
+      identity: new TestIdentityClient(),
+      enableTransactionSearch: async () => {},
+      backends: { CDK: backend },
+      resolveAccount: async () => "111122223333",
+    });
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+    await writeFile(join(project.rootPath, "app", "search", "Dockerfile"), "FROM scratch\n");
+
+    const events = [];
+    for await (const event of subject.deploy(project, {
+      target: "default",
+      region: "us-east-1",
+      confirmTeardown: async () => false,
+      transactionSearch: false,
+    })) {
+      events.push(event);
+    }
+
+    expect(
+      events.filter((event) => event.type === "step" && event.message.startsWith("search:")),
+    ).toEqual([
+      {
+        type: "step",
+        message: expect.stringContaining(
+          "search: build CodeZip -> Container (Dockerfile in app/search). It now builds",
+        ),
+      },
+      {
+        type: "step",
+        message: "search: dockerfile (unset) -> Dockerfile (Dockerfile in app/search)",
+      },
+      {
+        type: "step",
+        message: "search: runtimeVersion PYTHON_3_14 -> (removed) (Container build)",
+      },
+    ]);
+    expect(deployed[0]?.spec.runtimes[0]).toMatchObject({ build: "Container" });
+    const onDisk = JSON.parse(
+      await readFile(join(project.rootPath, "agentcore", "agentcore.json"), "utf-8"),
+    ).runtimes[0];
+    expect(onDisk).toMatchObject({ build: "Container", dockerfile: "Dockerfile" });
+    expect(onDisk.runtimeVersion).toBeUndefined();
+  });
+
+  test("write-back changes only the patched field, keeping unknown runtime keys and key order", async () => {
+    const { manager: subject } = manager();
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+    const specPath = join(project.rootPath, "agentcore", "agentcore.json");
+    const raw = JSON.parse(await readFile(specPath, "utf-8"));
+    // The top level is strict, so its unusual key order is what must survive there.
+    const { name, ...rest } = raw;
+    const edited = { ...rest, name };
+    edited.runtimes[0] = { x_first: 1, ...raw.runtimes[0], x_last: "kept" };
+    await writeFile(specPath, JSON.stringify(edited, null, 2));
+    const appDir = join(project.rootPath, "app", "search");
+    await writeFile(join(appDir, "main.py"), "");
+    await writeFile(join(appDir, "pyproject.toml"), '[project]\nrequires-python = "<3.13"\n');
+
+    const resolved = (await subject.resolve({ filePath: appDir }))!;
+    const result = await subject.syncRuntimeBuilds(resolved, { purpose: "dev" });
+
+    expect(result.written).toBe(true);
+    const expected = structuredClone(edited);
+    expected.runtimes[0].runtimeVersion = "PYTHON_3_12";
+    expect(await readFile(specPath, "utf-8")).toBe(JSON.stringify(expected, null, 2));
+  });
+
+  test("a v0 project is never rewritten", async () => {
+    const { manager: subject } = manager();
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+    await writeFile(join(project.rootPath, "app", "search", "Dockerfile"), "FROM scratch\n");
+    const specPath = join(project.rootPath, "agentcore", "agentcore.json");
+    const before = await readFile(specPath, "utf-8");
+
+    const result = await subject.syncRuntimeBuilds(
+      { ...project, legacy: { format: "v0", v0Spec: {} as never } },
+      { purpose: "deploy" },
+    );
+
+    expect(result).toMatchObject({ messages: [], written: false });
+    expect(await readFile(specPath, "utf-8")).toBe(before);
+  });
+
+  test("a requires-python-free manifest keeps a version pinned in agentcore.json", async () => {
+    const { backend } = recordingBackend();
+    const subject = new FsProjectManager({
+      logger: createSilentLogger(),
+      identity: new TestIdentityClient(),
+      enableTransactionSearch: async () => {},
+      backends: { CDK: backend },
+    });
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+    const specPath = join(project.rootPath, "agentcore", "agentcore.json");
+    const raw = JSON.parse(await readFile(specPath, "utf-8"));
+    raw.runtimes[0].runtimeVersion = "PYTHON_3_11";
+    await writeFile(specPath, JSON.stringify(raw, null, 2));
+    const appDir = join(project.rootPath, "app", "search");
+    await writeFile(join(appDir, "main.py"), "");
+    await writeFile(join(appDir, "pyproject.toml"), '[project]\nname = "search"\n');
+
+    const resolved = (await subject.resolve({ filePath: appDir }))!;
+    for await (const _event of subject.build(resolved));
+
+    expect(JSON.parse(await readFile(specPath, "utf-8")).runtimes[0].runtimeVersion).toBe(
+      "PYTHON_3_11",
+    );
+  });
+
+  test("build and deploy fail before the backend when the runtime has no code yet", async () => {
+    const { backend, builds } = recordingBackend();
+    const subject = new FsProjectManager({
+      logger: createSilentLogger(),
+      identity: new TestIdentityClient(),
+      enableTransactionSearch: async () => {},
+      backends: { CDK: backend },
+      resolveAccount: async () => "111122223333",
+    });
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+
+    const message =
+      'runtime "search": no pyproject.toml in app/search/. See app/search/README.md.\n' +
+      'runtime "search": no main.py in app/search/. See app/search/README.md.';
+    await expect(subject.build(project).next()).rejects.toThrow(new ProjectStateError(message));
+    const deploy = async () => {
+      for await (const _event of subject.deploy(project, {
+        target: "default",
+        region: "us-east-1",
+        confirmTeardown: async () => false,
+        transactionSearch: false,
+      }));
+    };
+    await expect(deploy()).rejects.toThrow(new ProjectStateError(message));
+    expect(builds).toEqual([]);
+  });
+
+  test("deploy to a target that does not exist leaves agentcore.json alone", async () => {
+    const { backend } = recordingBackend();
+    const subject = new FsProjectManager({
+      logger: createSilentLogger(),
+      identity: new TestIdentityClient(),
+      enableTransactionSearch: async () => {},
+      backends: { CDK: backend },
+    });
+    const project = await runAdd(subject, await emptyProject(subject), docsRuntime());
+    await writeFile(join(project.rootPath, "app", "search", "Dockerfile"), "FROM scratch\n");
+    const specPath = join(project.rootPath, "agentcore", "agentcore.json");
+    const before = await readFile(specPath, "utf-8");
+
+    const deploy = async () => {
+      for await (const _event of subject.deploy(project, {
+        target: "typo",
+        region: "us-east-1",
+        confirmTeardown: async () => false,
+        transactionSearch: false,
+      }));
+    };
+    await expect(deploy()).rejects.toThrow("No deployment targets are configured");
+    expect(await readFile(specPath, "utf-8")).toBe(before);
+  });
+});
diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx
index f9c329a485..13e5ae7fd1 100644
--- a/src/core/project/manager.tsx
+++ b/src/core/project/manager.tsx
@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import semver from "semver";
 import type {
   AddResourceOptions,
@@ -23,6 +23,8 @@ import type {
   ProjectManager,
   ProjectEvent,
   ProjectResource,
+  SyncRuntimeBuildsInput,
+  SyncRuntimeBuildsResult,
   RemoveResourceInput,
   RemoveResourceResult,
   RemoveResourcesResult,
@@ -98,7 +100,11 @@ import {
   type AwsDeploymentTarget,
 } from "../../projectSchemas/aws-targets";
 import { V0AwsDeploymentTargetsSchema } from "../../projectSchemas/v0";
-import type { RuntimeResourceConfig } from "../../handlers/project/add/runtime/types";
+import {
+  isRuntimeDocsConfig,
+  type RuntimeResourceConfig,
+} from "../../handlers/project/add/runtime/types";
+import { buildDocsRuntimeSpec, runtimeDocsTree } from "./templates/runtimeDocs";
 import type { TemplateRenderer } from "./templates/types";
 import { HandlebarsTemplateRenderer } from "./templates/renderer";
 import type { CreateCloudFormationClient } from "../types";
@@ -109,6 +115,7 @@ import { projectFormat, type ProjectFormat } from "./legacy/detect";
 import { loadLegacyProject } from "./legacy/load";
 import { assertV1Project } from "./legacy/writeGate";
 import { assertNoPendingMigration } from "./migrate/journal";
+import { prepareRuntimes } from "./runtimeBuild";
 
 const TARGETS_EXAMPLE = '[{ "name": "default", "account": "111122223333", "region": "us-east-1" }]';
 
@@ -674,7 +681,8 @@ export class FsProjectManager implements ProjectManager {
             : cnUnsupportedResourceMessage(input.resourceType),
         );
       }
-      if (input.resourceType === "runtime") {
+      // A docs-only runtime has no scaffolded code to gate; its code is the user's.
+      if (input.resourceType === "runtime" && !isRuntimeDocsConfig(input.resourceConfig)) {
         const scaffold = input.resourceConfig.scaffoldRuntimeInput;
         if (scaffold.framework === "bma") {
           throw new RegionUnsupportedFeatureError(BMA_CN_MESSAGE);
@@ -748,7 +756,8 @@ export class FsProjectManager implements ProjectManager {
 
         yield { type: "step", message: `Scaffolding harness in project` };
         const outputPath = join(project.rootPath, "app", harnessName);
-        scaffoldedPaths.push(outputPath);
+        // Rollback removes only what this add created, never a folder the user already had.
+        if (!existsSync(outputPath)) scaffoldedPaths.push(outputPath);
 
         const resolver = getHarnessTemplateResolver({
           assetSource: this.assetSource,
@@ -771,15 +780,63 @@ export class FsProjectManager implements ProjectManager {
         break;
       }
       case "runtime": {
+        const outputPath = join(project.rootPath, "app", input.resourceConfig.name);
+        // The folder may hold the user's own code, but never another resource's.
+        const owner = appFolderOwner(projectSpec, project.rootPath, outputPath);
+        if (owner !== undefined) {
+          throw new InputValidationError(
+            `cannot add runtime '${input.resourceConfig.name}': 'app/${input.resourceConfig.name}' ` +
+              `overlaps the files of ${owner}. Choose a different --name.`,
+          );
+        }
+        // Rollback removes only what this add created, never a folder the user already had.
+        const folderExisted = existsSync(outputPath);
+        if (isRuntimeDocsConfig(input.resourceConfig)) {
+          const relativeFolder = `app/${input.resourceConfig.name}`;
+          yield { type: "step", message: `Writing runtime docs to '${relativeFolder}'` };
+          const tree = await runtimeDocsTree(
+            { assetSource: this.assetSource, templateRenderer: this.templateRenderer },
+            input.resourceConfig,
+          );
+          // Tracked as each file is written, so a write that fails partway is
+          // cleaned up too (only what this add created).
+          const written: string[] = [];
+          if (!folderExisted) scaffoldedPaths.push(outputPath);
+          try {
+            await tree.write(dirname(outputPath), { skipExisting: true, written });
+          } catch (err) {
+            await this.discardStaged(folderExisted ? written : [outputPath]);
+            throw err;
+          }
+          if (folderExisted) scaffoldedPaths.push(...written);
+          for (const child of tree.children) {
+            if (!written.includes(join(outputPath, child.name))) {
+              yield {
+                type: "step",
+                message: `'${relativeFolder}/${child.name}' already exists; left unchanged`,
+              };
+            }
+          }
+          projectSpec.runtimes.push(buildDocsRuntimeSpec(input.resourceConfig));
+          break;
+        }
+
         await this.checkRuntimeDependency(input.resourceConfig.scaffoldRuntimeInput);
         yield { type: "step", message: "Scaffolding runtime in project" };
-        const outputPath = join(project.rootPath, "app", input.resourceConfig.name);
-        scaffoldedPaths.push(outputPath);
+        if (!folderExisted) scaffoldedPaths.push(outputPath);
 
+        // Tracked as each file is written, so a failed write into an existing
+        // folder removes only what it wrote, and a new folder goes entirely.
+        const scaffoldWritten: string[] = [];
         const { spec, envEntries } = await this.scaffoldRuntimeResources(
           outputPath,
           input.resourceConfig,
-        );
+          scaffoldWritten,
+        ).catch(async (err: unknown) => {
+          await this.discardStaged(folderExisted ? scaffoldWritten : [outputPath]);
+          throw err;
+        });
+        if (folderExisted) scaffoldedPaths.push(...scaffoldWritten);
         if (spec.runtimes) projectSpec.runtimes.push(...spec.runtimes);
         if (spec.memories) projectSpec.memories.push(...spec.memories);
         if (spec.credentials) projectSpec.credentials.push(...spec.credentials);
@@ -942,14 +999,7 @@ export class FsProjectManager implements ProjectManager {
         `could not commit the spec update to ${agentCoreSpecPath}; attempting best-effort cleanup of staged changes`,
       );
       await Promise.all([
-        ...scaffoldedPaths.map((p) =>
-          rm(p, { recursive: true, force: true }).catch((e) => {
-            const error = AgentCoreCLIError.fromError(e);
-            this.logger
-              .child({ errorName: error.name, errorMessage: error.message })
-              .warn(`failed to clean up ${p}`);
-          }),
-        ),
+        this.discardStaged(scaffoldedPaths),
         envFile?.rollback().catch((e) => {
           const error = AgentCoreCLIError.fromError(e);
           this.logger
@@ -966,6 +1016,20 @@ export class FsProjectManager implements ProjectManager {
     };
   }
 
+  /** Best-effort removal of paths an add created; failures are logged, not thrown. */
+  private async discardStaged(paths: string[]): Promise<void> {
+    await Promise.all(
+      paths.map((p) =>
+        rm(p, { recursive: true, force: true }).catch((e) => {
+          const error = AgentCoreCLIError.fromError(e);
+          this.logger
+            .child({ errorName: error.name, errorMessage: error.message })
+            .warn(`failed to clean up ${p}`);
+        }),
+      ),
+    );
+  }
+
   private getProjectSpecPath(project: Project): string {
     return projectSpecPath(project.rootPath);
   }
@@ -1398,7 +1462,11 @@ export class FsProjectManager implements ProjectManager {
     };
   }
 
-  private async scaffoldRuntimeResources(outputPath: string, input: RuntimeResourceConfig) {
+  private async scaffoldRuntimeResources(
+    outputPath: string,
+    input: RuntimeResourceConfig,
+    written: string[] = [],
+  ) {
     const resolver = getRuntimeTemplateResolver(
       { assetSource: this.assetSource, templateRenderer: this.templateRenderer },
       input,
@@ -1407,13 +1475,62 @@ export class FsProjectManager implements ProjectManager {
       throw new InputValidationError(`unable to find template that matches given parameters`);
 
     const result = await resolver.resolve(input);
-    await result.tree.write(dirname(outputPath));
+    await result.tree.write(dirname(outputPath), { written });
     return { spec: result.spec, envEntries: result.envEntries ?? [] };
   }
 
   public async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
     assertV1Project(project, "build");
-    yield* this.backendFor(project).build(project);
+    // Half-written project files from an interrupted `agentcore migrate` must not
+    // be synced or synthesized; build has no target, so only that state stops it.
+    await assertNoPendingMigration(project.rootPath);
+    const synced = await this.syncRuntimeBuilds(project, { purpose: "deploy" });
+    for (const message of synced.messages) yield { type: "step", message };
+    yield* this.backendFor(project).build(synced.project);
+  }
+
+  public async syncRuntimeBuilds(
+    project: Project,
+    input: SyncRuntimeBuildsInput,
+  ): Promise<SyncRuntimeBuildsResult> {
+    // A v0 project's agentcore.json has the v0 shape and is never rewritten here.
+    if (project.legacy) return { project, messages: [], written: false };
+    const runtimes = input.runtimeNames
+      ? project.spec.runtimes.filter((runtime) => input.runtimeNames!.includes(runtime.name))
+      : project.spec.runtimes;
+    const prepared = prepareRuntimes(project.rootPath, runtimes, input.purpose);
+    if (prepared.changed.length === 0) {
+      return { project, messages: prepared.messages, written: false };
+    }
+
+    // Patch the raw file rather than re-serializing the parsed spec, so fields
+    // the schema does not know about, and the order of every key, survive.
+    const specPath = this.getProjectSpecPath(project);
+    const raw = await this.json.read(specPath, z.record(z.string(), z.unknown()));
+    const rawRuntimes = Array.isArray(raw.runtimes) ? [...(raw.runtimes as unknown[])] : [];
+    for (const { runtime, changes } of prepared.changed) {
+      const index = rawRuntimes.findIndex(
+        (entry) => (entry as { name?: unknown } | null)?.name === runtime.name,
+      );
+      if (index < 0) continue;
+      const entry: Record<string, unknown> = { ...(rawRuntimes[index] as object) };
+      for (const { field, to } of changes) {
+        if (to === undefined) delete entry[field];
+        else entry[field] = to;
+      }
+      rawRuntimes[index] = entry;
+    }
+    const updated = { ...raw, runtimes: rawRuntimes };
+    const parsed = ProjectSpecSchema.safeParse(updated);
+    if (!parsed.success) {
+      throw new ProjectStateError(z.prettifyError(parsed.error), { cause: parsed.error });
+    }
+    await this.json.write(specPath, updated);
+    return {
+      project: { ...project, spec: parsed.data },
+      messages: prepared.messages,
+      written: true,
+    };
   }
 
   // Resolves the named target from aws-targets.json before handing off, so the
@@ -1466,6 +1583,12 @@ export class FsProjectManager implements ProjectManager {
       );
     }
 
+    // Synth reads agentcore.json, so it is brought up to date with the code
+    // first; only once the target is known, so a bad --target rewrites nothing.
+    const synced = await this.syncRuntimeBuilds(project, { purpose: "deploy" });
+    for (const message of synced.messages) yield { type: "step", message };
+    project = synced.project;
+
     // China (aws-cn) targets cannot run runtimes whose scaffolded code is
     // wired to Bedrock/Anthropic/OpenAI/Gemini (unreachable there), nor
     // harnesses (not part of the China launch). Runtimes without a persisted
@@ -1858,6 +1981,50 @@ function toProjectSpecKey(resourceType: ProjectResource) {
   }
 }
 
+/**
+ * The resource whose files live in `folder` (a runtime's codeLocation, a
+ * harness's path, or a managed code-based evaluator's codeLocation), if any.
+ */
+function appFolderOwner(
+  spec: z.infer<typeof ProjectSpecSchema>,
+  rootPath: string,
+  folder: string,
+): string | undefined {
+  const owners: [string, string | undefined][] = [
+    ...spec.runtimes.map((runtime): [string, string] => [
+      `runtime '${runtime.name}'`,
+      runtime.codeLocation,
+    ]),
+    ...spec.harnesses.map((harness): [string, string] => [
+      `harness '${harness.name}'`,
+      harness.path,
+    ]),
+    ...spec.evaluators.map((evaluator): [string, string | undefined] => [
+      `evaluator '${evaluator.name}'`,
+      evaluator.config.codeBased?.managed?.codeLocation,
+    ]),
+  ];
+  // The same folder, one inside the other, or one containing the other (a
+  // codeLocation of `app`) all mean the two resources would share files.
+  const overlaps = (location: string) => {
+    const owned = resolve(rootPath, location);
+    const target = resolve(folder);
+    return owned === target || isInside(owned, target) || isInside(target, owned);
+  };
+  return owners.find(([, location]) => location !== undefined && overlaps(location))?.[0];
+}
+
+/** Whether `path` is strictly inside `dir`. */
+function isInside(path: string, dir: string): boolean {
+  const relativePath = relative(dir, path);
+  return (
+    relativePath !== "" &&
+    relativePath !== ".." &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath)
+  );
+}
+
 /** The strands-agents requirement from the rendered pyproject.toml, for EXPORT_NOTES.md. */
 async function readStrandsVersion(agentDir: string): Promise<string> {
   try {
diff --git a/src/core/project/migrate/journal.ts b/src/core/project/migrate/journal.ts
index cb83b00363..deb56f83b4 100644
--- a/src/core/project/migrate/journal.ts
+++ b/src/core/project/migrate/journal.ts
@@ -92,7 +92,7 @@ export async function removeMigrationState(rootPath: string): Promise<void> {
  * resources. A migration stopped while writing the project files blocks every
  * target, since the files are part v0 and part v1. Other targets deploy as usual.
  */
-export async function assertNoPendingMigration(rootPath: string, target: string): Promise<void> {
+export async function assertNoPendingMigration(rootPath: string, target?: string): Promise<void> {
   let state: MigrationState | undefined;
   try {
     state = await readMigrationState(rootPath);
@@ -112,6 +112,8 @@ export async function assertNoPendingMigration(rootPath: string, target: string)
       { meta: { reason: "migration-interrupted" } },
     );
   }
+  // Without a target (build), only half-written project files stop the command.
+  if (target === undefined) return;
   const pending = state.targets.find((entry) => entry.name === target);
   if (!pending) return;
   throw new ProjectStateError(
diff --git a/src/core/project/runtimeBuild.test.ts b/src/core/project/runtimeBuild.test.ts
new file mode 100644
index 0000000000..e672eda782
--- /dev/null
+++ b/src/core/project/runtimeBuild.test.ts
@@ -0,0 +1,561 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { ProjectStateError } from "../../errors";
+import type { ProjectRuntime } from "../../projectSchemas/runtime";
+import { describeChange, prepareRuntimes, readTomlString, syncRuntimeBuild } from "./runtimeBuild";
+
+const roots: string[] = [];
+afterEach(() => Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true }))));
+
+/** A project root holding the given files (path -> content; a trailing `/` makes a directory). */
+async function project(files: Record<string, string>): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "runtime-build-"));
+  roots.push(root);
+  await mkdir(join(root, "app", "search"), { recursive: true });
+  for (const [path, content] of Object.entries(files)) {
+    if (path.endsWith("/")) {
+      await mkdir(join(root, path), { recursive: true });
+      continue;
+    }
+    await mkdir(dirname(join(root, path)), { recursive: true });
+    await writeFile(join(root, path), content);
+  }
+  return root;
+}
+
+/** The entry `add runtime --language python` writes, with overrides. */
+function runtime(overrides: Partial<ProjectRuntime> = {}): ProjectRuntime {
+  return {
+    name: "search",
+    codeLocation: "app/search" as ProjectRuntime["codeLocation"],
+    build: "CodeZip",
+    runtimeVersion: "PYTHON_3_14",
+    entrypoint: "main.py",
+    protocol: "HTTP",
+    ...overrides,
+  };
+}
+
+const nodeRuntime = (overrides: Partial<ProjectRuntime> = {}) =>
+  runtime({ runtimeVersion: "NODE_22", entrypoint: "main.js", ...overrides });
+
+const pyproject = (requiresPython: string, extra = "") =>
+  `[project]\nname = "search"\nrequires-python = "${requiresPython}"\n${extra}`;
+
+const packageJson = (fields: Record<string, unknown>) =>
+  JSON.stringify({ name: "search", ...fields });
+
+describe("runtimeVersion from requires-python", () => {
+  test.each([
+    [">=3.12", "PYTHON_3_14"],
+    [">=3.10,<3.13", "PYTHON_3_12"],
+    ["==3.11.*", "PYTHON_3_11"],
+    ["~=3.11", "PYTHON_3_14"],
+    ["~=3.11.2", "PYTHON_3_11"],
+    [">=3.12.4", "PYTHON_3_14"],
+    ["<3.12", "PYTHON_3_11"],
+    [">3.13", "PYTHON_3_14"],
+    [">= 3.10, < 3.13", "PYTHON_3_12"],
+    ["!=3.14.*", "PYTHON_3_13"],
+    ["==3.12", "PYTHON_3_12"],
+    ["<=3.10", "PYTHON_3_10"],
+    [">=v3.12", "PYTHON_3_14"],
+  ])("%s resolves to %s", async (specifier, expected) => {
+    const root = await project({ "app/search/pyproject.toml": pyproject(specifier) });
+    const sync = syncRuntimeBuild(runtime(), root);
+    expect(sync.runtime.runtimeVersion).toBe(expected as never);
+    expect(sync.changes).toEqual(
+      expected === "PYTHON_3_14"
+        ? []
+        : [
+            {
+              field: "runtimeVersion",
+              from: "PYTHON_3_14",
+              to: expected,
+              reason: `requires-python "${specifier}" in app/search/pyproject.toml`,
+            },
+          ],
+    );
+  });
+
+  test("a version in agentcore.json that requires-python allows is kept", async () => {
+    const root = await project({ "app/search/pyproject.toml": pyproject(">=3.10") });
+    const sync = syncRuntimeBuild(runtime({ runtimeVersion: "PYTHON_3_12" }), root);
+    expect(sync.runtime.runtimeVersion).toBe("PYTHON_3_12");
+    expect(sync.changes).toEqual([]);
+  });
+
+  test("a version requires-python excludes is replaced with the highest it allows", async () => {
+    const root = await project({ "app/search/pyproject.toml": pyproject("<3.12") });
+    expect(syncRuntimeBuild(runtime({ runtimeVersion: "PYTHON_3_13" }), root).changes).toEqual([
+      {
+        field: "runtimeVersion",
+        from: "PYTHON_3_13",
+        to: "PYTHON_3_11",
+        reason: 'requires-python "<3.12" in app/search/pyproject.toml',
+      },
+    ]);
+  });
+
+  test.each(['[project]\nname = "search"\n', pyproject("")])(
+    "with no requires-python, the agentcore.json version is kept (the way to pin)",
+    async (manifest) => {
+      const root = await project({ "app/search/pyproject.toml": manifest });
+      const sync = syncRuntimeBuild(runtime({ runtimeVersion: "PYTHON_3_11" }), root);
+      expect(sync.runtime.runtimeVersion).toBe("PYTHON_3_11");
+      expect(sync.changes).toEqual([]);
+      expect(sync.warnings).toEqual([]);
+    },
+  );
+
+  test("with neither, the latest version is used with a warning", async () => {
+    const root = await project({});
+    const sync = syncRuntimeBuild(runtime({ runtimeVersion: undefined }), root);
+    expect(sync.runtime.runtimeVersion).toBe("PYTHON_3_14");
+    expect(sync.warnings).toEqual([
+      'runtime "search": no requires-python in pyproject.toml; using Python 3.14. ' +
+        "Set requires-python (or runtimeVersion in agentcore.json) to pin a version.",
+    ]);
+  });
+
+  test(">=3.15 matches no supported version", async () => {
+    const root = await project({ "app/search/pyproject.toml": pyproject(">=3.15") });
+    expect(() => syncRuntimeBuild(runtime(), root)).toThrow(
+      new ProjectStateError(
+        'runtime "search": requires-python ">=3.15" in app/search/pyproject.toml matches no ' +
+          "supported Python version (supported: 3.10, 3.11, 3.12, 3.13, 3.14).",
+      ),
+    );
+  });
+
+  test.each(["3.12", ">=3.12.*", "~=3", ">=three", "===3.12.0", ">=3.12rc1"])(
+    "%s is unparseable",
+    async (specifier) => {
+      const root = await project({ "app/search/pyproject.toml": pyproject(specifier) });
+      expect(() => syncRuntimeBuild(runtime(), root)).toThrow(
+        `cannot parse requires-python "${specifier}" in app/search/pyproject.toml`,
+      );
+    },
+  );
+
+  test("an unquoted value is an error", async () => {
+    const root = await project({
+      "app/search/pyproject.toml": "[project]\nrequires-python = >=3.12\n",
+    });
+    expect(() => syncRuntimeBuild(runtime(), root)).toThrow(
+      "cannot parse requires-python >=3.12 in app/search/pyproject.toml",
+    );
+  });
+
+  test("the manifest is found in a parent folder, up to the project root", async () => {
+    const root = await project({ "pyproject.toml": pyproject("<3.13") });
+    const sync = syncRuntimeBuild(runtime(), root);
+    expect(sync.runtime.runtimeVersion).toBe("PYTHON_3_12");
+    expect(sync.changes[0]?.reason).toBe('requires-python "<3.13" in pyproject.toml');
+  });
+
+  test.each([
+    ['requires-python = ">=3.12"', ">=3.12"],
+    ["requires-python = '>=3.11'", ">=3.11"],
+    ['  requires-python="==3.13.*"   # pinned', "==3.13.*"],
+    ['"requires-python" = ">=3.10"', ">=3.10"],
+  ])("reads %s", (line, expected) => {
+    expect(readTomlString(`[project]\n${line}\n`, "project", "requires-python")?.value).toBe(
+      expected,
+    );
+  });
+
+  test("reads a key only from its own table", () => {
+    const text =
+      '[tool.other]\nrequires-python = ">=3.10"\n\n[project]\nname = "x"\n\n[tool.uv]\n' +
+      'requires-python = ">=3.11"\n';
+    expect(readTomlString(text, "project", "requires-python")).toBeUndefined();
+    expect(
+      readTomlString(`[project]\nrequires-python = [">=3"]\n`, "project", "requires-python"),
+    ).toEqual({ raw: '[">=3"]' });
+  });
+});
+
+describe("runtimeVersion from engines.node", () => {
+  test.each([
+    [">=20", "NODE_22"],
+    ["^20", "NODE_20"],
+    ["18 || 20", "NODE_20"],
+    ["20.x", "NODE_20"],
+    ["~18.17", "NODE_18"],
+  ])("%s resolves to %s", async (range, expected) => {
+    const root = await project({
+      "app/search/package.json": packageJson({ engines: { node: range } }),
+    });
+    expect(syncRuntimeBuild(nodeRuntime(), root).runtime.runtimeVersion).toBe(expected as never);
+  });
+
+  test("a version engines.node allows is kept; one it excludes is replaced", async () => {
+    const root = await project({
+      "app/search/package.json": packageJson({ engines: { node: ">=18" } }),
+    });
+    expect(syncRuntimeBuild(nodeRuntime({ runtimeVersion: "NODE_20" }), root).changes).toEqual([]);
+    const narrowed = await project({
+      "app/search/package.json": packageJson({ engines: { node: "^22" } }),
+    });
+    expect(
+      syncRuntimeBuild(nodeRuntime({ runtimeVersion: "NODE_20" }), narrowed).runtime.runtimeVersion,
+    ).toBe("NODE_22");
+  });
+
+  test(">=24 matches no supported version", async () => {
+    const root = await project({
+      "app/search/package.json": packageJson({ engines: { node: ">=24" } }),
+    });
+    expect(() => syncRuntimeBuild(nodeRuntime(), root)).toThrow(
+      'engines.node ">=24" in app/search/package.json matches no supported Node.js version ' +
+        "(supported: 18, 20, 22).",
+    );
+  });
+
+  test.each(["node twenty", "^20.0.0-beta.1"])("%s is unparseable", async (range) => {
+    const root = await project({
+      "app/search/package.json": packageJson({ engines: { node: range } }),
+    });
+    expect(() => syncRuntimeBuild(nodeRuntime(), root)).toThrow(
+      `cannot parse engines.node "${range}" in app/search/package.json`,
+    );
+  });
+
+  test("a non-string engines.node or invalid package.json is an error", async () => {
+    const numeric = await project({
+      "app/search/package.json": packageJson({ engines: { node: 20 } }),
+    });
+    expect(() => syncRuntimeBuild(nodeRuntime(), numeric)).toThrow(
+      "cannot parse engines.node 20 in app/search/package.json",
+    );
+    const broken = await project({ "app/search/package.json": "{" });
+    expect(() => syncRuntimeBuild(nodeRuntime(), broken)).toThrow(
+      "cannot parse app/search/package.json as JSON",
+    );
+  });
+
+  test.each([{}, { engines: { node: "" } }])(
+    "with no engines.node the agentcore.json version is kept",
+    async (fields) => {
+      const root = await project({ "app/search/package.json": packageJson(fields) });
+      const sync = syncRuntimeBuild(nodeRuntime({ runtimeVersion: "NODE_18" }), root);
+      expect(sync.runtime.runtimeVersion).toBe("NODE_18");
+      expect(sync.changes).toEqual([]);
+    },
+  );
+});
+
+describe("build", () => {
+  test("a Dockerfile switches to a Container build and drops runtimeVersion", async () => {
+    const root = await project({ "app/search/Dockerfile": "FROM scratch\n" });
+    const sync = syncRuntimeBuild(runtime(), root);
+    expect(sync.runtime).toMatchObject({ build: "Container", dockerfile: "Dockerfile" });
+    expect(sync.runtime.runtimeVersion).toBeUndefined();
+    expect(sync.changes).toEqual([
+      { field: "build", from: "CodeZip", to: "Container", reason: "Dockerfile in app/search" },
+      { field: "dockerfile", to: "Dockerfile", reason: "Dockerfile in app/search" },
+      { field: "runtimeVersion", from: "PYTHON_3_14", reason: "Container build" },
+    ]);
+    expect(describeChange("search", sync.changes[0]!)).toBe(
+      "search: build CodeZip -> Container (Dockerfile in app/search). It now builds and " +
+        "deploys as a container image from that Dockerfile; to go back, delete the Dockerfile " +
+        'and set "build": "CodeZip" in agentcore.json.',
+    );
+  });
+
+  test("a migrated Container runtime drops its runtimeVersion once, then stays put", async () => {
+    const root = await project({ "app/search/Dockerfile": "FROM scratch\n" });
+    const migrated = runtime({ build: "Container", dockerfile: "Dockerfile" });
+    const first = syncRuntimeBuild(migrated, root);
+    expect(first.changes).toEqual([
+      { field: "runtimeVersion", from: "PYTHON_3_14", reason: "Container build" },
+    ]);
+    expect(syncRuntimeBuild(first.runtime, root).changes).toEqual([]);
+  });
+
+  test("a Container runtime whose Dockerfile is missing fails instead of switching", async () => {
+    const root = await project({
+      "app/search/main.py": "",
+      "app/search/pyproject.toml": pyproject(">=3.10,<3.14"),
+    });
+    const container = runtime({
+      build: "Container",
+      dockerfile: "Dockerfile",
+      runtimeVersion: undefined,
+    });
+    expect(syncRuntimeBuild(container, root).changes).toEqual([]);
+    expect(() => prepareRuntimes(root, [container], "deploy")).toThrow(
+      new ProjectStateError(
+        'runtime "search": no Dockerfile in app/search/, and agentcore.json says this is a ' +
+          'Container build. Add the Dockerfile, or set "build": "CodeZip" in agentcore.json to ' +
+          "deploy the code directly. See app/search/README.md.",
+      ),
+    );
+  });
+
+  test("only a file named exactly Dockerfile counts", async () => {
+    const root = await project({
+      "app/search/dockerfile": "FROM scratch\n",
+      "app/search/Dockerfile.dev": "FROM scratch\n",
+    });
+    expect(syncRuntimeBuild(runtime(), root).changes).toEqual([]);
+  });
+
+  test("a symlinked Dockerfile counts", async () => {
+    const root = await project({ "app/search/docker/Dockerfile.real": "FROM scratch\n" });
+    await symlink(join("docker", "Dockerfile.real"), join(root, "app", "search", "Dockerfile"));
+    expect(syncRuntimeBuild(runtime(), root).runtime.build).toBe("Container");
+  });
+
+  test("the Dockerfile is looked up in buildContextPath when set", async () => {
+    const root = await project({ "app/Dockerfile": "FROM scratch\n" });
+    const sync = syncRuntimeBuild(
+      runtime({ build: "Container", buildContextPath: "app" as never, runtimeVersion: undefined }),
+      root,
+    );
+    expect(sync.runtime).toMatchObject({ build: "Container", dockerfile: "Dockerfile" });
+  });
+
+  test("a custom dockerfile path keeps the build Container", async () => {
+    const root = await project({ "app/search/docker/Prod.Dockerfile": "FROM scratch\n" });
+    const custom = runtime({
+      build: "Container",
+      dockerfile: "docker/Prod.Dockerfile",
+      runtimeVersion: undefined,
+    });
+    expect(syncRuntimeBuild(custom, root).changes).toEqual([]);
+  });
+
+  test("a Container build with buildContextPath and no Dockerfile names the folder", async () => {
+    const root = await project({});
+    const container = runtime({
+      build: "Container",
+      buildContextPath: "app" as never,
+      runtimeVersion: undefined,
+    });
+    expect(() => prepareRuntimes(root, [container], "deploy")).toThrow(
+      'runtime "search": no Dockerfile in app/, and agentcore.json says this is a Container build.',
+    );
+  });
+});
+
+describe("entrypoint", () => {
+  test("[tool.agentcore] entrypoint in pyproject.toml wins", async () => {
+    const root = await project({
+      "app/search/pyproject.toml": pyproject(
+        ">=3.12",
+        '\n[tool.agentcore]\nentrypoint = "agent.py:app"\n',
+      ),
+    });
+    const sync = syncRuntimeBuild(runtime(), root);
+    expect(sync.runtime.entrypoint).toBe("agent.py:app");
+    expect(sync.changes).toEqual([
+      {
+        field: "entrypoint",
+        from: "main.py",
+        to: "agent.py:app",
+        reason: "[tool.agentcore] entrypoint in app/search/pyproject.toml",
+      },
+    ]);
+  });
+
+  test("without [tool.agentcore] the agentcore.json entrypoint is kept", async () => {
+    const root = await project({ "app/search/pyproject.toml": pyproject(">=3.12") });
+    expect(syncRuntimeBuild(runtime({ entrypoint: "server.py" }), root).runtime.entrypoint).toBe(
+      "server.py",
+    );
+  });
+
+  test("a non-Python [tool.agentcore] entrypoint is an error", async () => {
+    const root = await project({
+      "app/search/pyproject.toml": '[tool.agentcore]\nentrypoint = "main.ts"\n',
+    });
+    expect(() => syncRuntimeBuild(runtime(), root)).toThrow(
+      '[tool.agentcore] entrypoint "main.ts" in app/search/pyproject.toml is not a Python file path',
+    );
+  });
+
+  test.each(["main.ts", "./main.ts", "main.js", "./main.js"])(
+    'package.json "main" %s is stored as main.js',
+    async (main) => {
+      const root = await project({ "app/search/package.json": packageJson({ main }) });
+      const sync = syncRuntimeBuild(nodeRuntime({ entrypoint: "main.ts" }), root);
+      expect(sync.runtime.entrypoint).toBe("main.js");
+    },
+  );
+
+  test.each(["src/index.ts", "dist/main.js", "index.js"])(
+    'package.json "main" %s is ignored with a warning on a CodeZip build',
+    async (main) => {
+      const root = await project({ "app/search/package.json": packageJson({ main }) });
+      const sync = syncRuntimeBuild(nodeRuntime(), root);
+      expect(sync.runtime.entrypoint).toBe("main.js");
+      expect(sync.changes).toEqual([]);
+      expect(sync.warnings).toEqual([
+        `runtime "search": package.json "main" is "${main}"; AgentCore currently bundles main.ts ` +
+          'at the root of app/search, so "main" is ignored.',
+      ]);
+    },
+  );
+
+  test('package.json "main" is not read for a Container build', async () => {
+    const root = await project({
+      "app/search/Dockerfile": "FROM node:22\n",
+      "app/search/package.json": packageJson({ main: "dist/main.js" }),
+    });
+    const container = nodeRuntime({
+      build: "Container",
+      dockerfile: "Dockerfile",
+      runtimeVersion: undefined,
+      entrypoint: "dist/main.js",
+    });
+    const sync = syncRuntimeBuild(container, root);
+    expect(sync.changes).toEqual([]);
+    expect(sync.warnings).toEqual([]);
+  });
+
+  test.each([
+    '[tool]\nagentcore.entrypoint = "server.py"\n',
+    'tool.agentcore.entrypoint = "server.py"\n',
+    '[tool]\nagentcore = { entrypoint = "server.py" }\n',
+  ])("warns about an agentcore entrypoint form it does not read: %p", async (toml) => {
+    const root = await project({ "app/search/pyproject.toml": toml });
+    const sync = syncRuntimeBuild(runtime(), root);
+    expect(sync.runtime.entrypoint).toBe("main.py");
+    expect(sync.warnings).toEqual([
+      'runtime "search": app/search/pyproject.toml sets the agentcore entrypoint in a form the ' +
+        "CLI does not read; it is ignored. Use a [tool.agentcore] table with " +
+        'entrypoint = "main.py" on one line.',
+    ]);
+  });
+});
+
+describe("prepareRuntimes", () => {
+  test("runtimes that already match their code are left alone, with no output", async () => {
+    const root = await project({
+      "app/search/pyproject.toml": pyproject(">=3.12"),
+      "app/search/main.py": "",
+    });
+    expect(prepareRuntimes(root, [runtime()], "deploy")).toEqual({
+      runtimes: [runtime()],
+      changed: [],
+      messages: [],
+    });
+  });
+
+  test("a changed runtime is reported field by field", async () => {
+    const root = await project({
+      "app/search/pyproject.toml": pyproject(">=3.10,<3.13"),
+      "app/search/main.py": "",
+    });
+    const prepared = prepareRuntimes(root, [runtime()], "deploy");
+    expect(prepared.changed).toHaveLength(1);
+    expect(prepared.messages).toEqual([
+      'search: runtimeVersion PYTHON_3_14 -> PYTHON_3_12 (requires-python ">=3.10,<3.13" in ' +
+        "app/search/pyproject.toml)",
+    ]);
+  });
+
+  test.each<[string, Record<string, string>, Partial<ProjectRuntime>, string[]]>([
+    [
+      "Python without a manifest or entrypoint",
+      {},
+      {},
+      ["no pyproject.toml in app/search/.", "no main.py in app/search/."],
+    ],
+    [
+      "Python with a package.json instead",
+      { "app/search/package.json": "{}", "app/search/main.py": "" },
+      {},
+      ["this runtime is Python (entrypoint main.py) but app/search/ has a package.json"],
+    ],
+    [
+      "TypeScript without package.json, main.ts, or node_modules",
+      {},
+      { runtimeVersion: "NODE_22", entrypoint: "main.js" },
+      [
+        "no package.json in app/search/.",
+        "no main.ts in app/search/.",
+        "no node_modules in app/search/; run `npm install` there.",
+      ],
+    ],
+    [
+      "TypeScript with a pyproject.toml instead",
+      { "app/search/pyproject.toml": "", "app/search/main.ts": "", "app/search/node_modules/": "" },
+      { runtimeVersion: "NODE_22", entrypoint: "main.js" },
+      ["this runtime is TypeScript (entrypoint main.js) but app/search/ has a pyproject.toml"],
+    ],
+    [
+      "a custom dockerfile that is missing",
+      {},
+      { build: "Container", dockerfile: "docker/Prod.Dockerfile", runtimeVersion: undefined },
+      ["no Dockerfile at app/search/docker/Prod.Dockerfile, and agentcore.json says"],
+    ],
+    [
+      "a Container build in VPC mode without vpcId",
+      { "app/search/Dockerfile": "" },
+      {
+        networkMode: "VPC",
+        networkConfig: {
+          subnets: ["subnet-0123456789abcdef0"],
+          securityGroups: ["sg-0123456789abcdef0"],
+        },
+      },
+      ["networkConfig.vpcId is required for Container builds in VPC mode"],
+    ],
+    [
+      "a missing code folder",
+      {},
+      { codeLocation: "app/missing" as never },
+      ["app/missing/ does not exist."],
+    ],
+    [
+      "an unsupported requires-python",
+      { "app/search/pyproject.toml": pyproject(">=3.15"), "app/search/main.py": "" },
+      {},
+      ['requires-python ">=3.15" in app/search/pyproject.toml matches no supported Python version'],
+    ],
+  ])("fails early for %s", async (_label, files, overrides, expected) => {
+    const root = await project(files);
+    let error: unknown;
+    try {
+      prepareRuntimes(root, [runtime(overrides)], "deploy");
+    } catch (caught) {
+      error = caught;
+    }
+    expect(error).toBeInstanceOf(ProjectStateError);
+    const lines = (error as Error).message.split("\n");
+    expect(lines).toHaveLength(expected.length);
+    expected.forEach((fragment, i) => {
+      expect(lines[i]).toStartWith('runtime "search":');
+      expect(lines[i]).toContain(fragment);
+      expect(lines[i]).toEndWith(`See ${overrides.codeLocation ?? "app/search"}/README.md.`);
+    });
+  });
+
+  test("deploy requires main.ts even when a main.js exists; dev runs the JavaScript", async () => {
+    const root = await project({
+      "app/search/package.json": packageJson({ engines: { node: "^20" } }),
+      "app/search/main.js": "",
+      "app/search/node_modules/": "",
+    });
+    expect(() => prepareRuntimes(root, [nodeRuntime()], "deploy")).toThrow(
+      "no main.ts in app/search/.",
+    );
+    expect(prepareRuntimes(root, [nodeRuntime()], "dev").runtimes[0]?.runtimeVersion).toBe(
+      "NODE_20",
+    );
+  });
+
+  test("dev does not require node_modules, which it installs itself", async () => {
+    const root = await project({
+      "app/search/package.json": packageJson({}),
+      "app/search/main.ts": "",
+    });
+    expect(prepareRuntimes(root, [nodeRuntime()], "dev").changed).toEqual([]);
+    expect(() => prepareRuntimes(root, [nodeRuntime()], "deploy")).toThrow("no node_modules");
+  });
+});
diff --git a/src/core/project/runtimeBuild.ts b/src/core/project/runtimeBuild.ts
new file mode 100644
index 0000000000..a0526114b2
--- /dev/null
+++ b/src/core/project/runtimeBuild.ts
@@ -0,0 +1,605 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import semver from "semver";
+import { ProjectStateError } from "../../errors";
+import {
+  NodeRuntimeSchema,
+  PythonRuntimeSchema,
+  type RuntimeVersion,
+} from "../../projectSchemas/constants";
+import { EntrypointSchema, type ProjectRuntime } from "../../projectSchemas/runtime";
+
+/**
+ * Re-derives a runtime's build settings (`build`, `dockerfile`, `runtimeVersion`,
+ * `entrypoint`) from its code folder before dev, build, and deploy. The code wins
+ * where it states a value (a Dockerfile, requires-python / engines.node,
+ * `[tool.agentcore] entrypoint` / package.json `main`); otherwise the value in
+ * agentcore.json is kept, which is how a user pins one. The caller writes any
+ * changes back to agentcore.json, so synth always sees a complete runtime.
+ */
+
+export const DOCKERFILE_NAME = "Dockerfile";
+
+type Language = "Python" | "Node";
+
+type SyncedField = "build" | "dockerfile" | "runtimeVersion" | "entrypoint";
+
+/** One field the code folder changed, and why. `to` undefined means the field is removed. */
+export interface RuntimeChange {
+  field: SyncedField;
+  from?: string;
+  to?: string;
+  reason: string;
+}
+
+export interface RuntimeSync {
+  runtime: ProjectRuntime;
+  changes: RuntimeChange[];
+  warnings: string[];
+}
+
+/** `search: runtimeVersion PYTHON_3_14 -> PYTHON_3_12 (requires-python ">=3.10,<3.13" in app/search/pyproject.toml)` */
+export function describeChange(name: string, change: RuntimeChange): string {
+  const line =
+    `${name}: ${change.field} ${change.from ?? "(unset)"} -> ${change.to ?? "(removed)"} ` +
+    `(${change.reason})`;
+  // Switching to a container changes how the runtime builds and deploys, so say so.
+  return change.field === "build" && change.to === "Container"
+    ? `${line}. It now builds and deploys as a container image from that Dockerfile; to go ` +
+        `back, delete the Dockerfile and set "build": "CodeZip" in agentcore.json.`
+    : line;
+}
+
+/** Re-derives a runtime's build settings. Throws a {@link ProjectStateError} when they cannot be. */
+export function syncRuntimeBuild(runtime: ProjectRuntime, projectRoot: string): RuntimeSync {
+  const next: ProjectRuntime = { ...runtime };
+  const reasons: Partial<Record<SyncedField, string>> = {};
+  const warnings: string[] = [];
+  const context = contextDir(runtime, projectRoot);
+  const contextLabel = displayPath(projectRoot, context);
+
+  // build: a CodeZip runtime becomes Container when a Dockerfile appears in its
+  // build context. A Container runtime never flips back on its own: a missing
+  // Dockerfile is a precheck error, so deleting one by accident cannot silently
+  // change how the runtime deploys.
+  if (runtime.build === "CodeZip" && hasDockerfile(context)) {
+    next.build = "Container";
+    next.dockerfile = DOCKERFILE_NAME;
+    reasons.build = reasons.dockerfile = `${DOCKERFILE_NAME} in ${contextLabel}`;
+  } else if (runtime.build === "Container" && runtime.dockerfile === undefined) {
+    next.dockerfile = DOCKERFILE_NAME;
+    reasons.dockerfile = "default";
+  }
+
+  // entrypoint, from the manifest for the runtime's language. package.json
+  // `main` only names the CodeZip bundle; a Container image decides its own.
+  const language = entrypointLanguage(runtime);
+  const entrypoint =
+    language === "Python"
+      ? pythonEntrypoint(runtime, projectRoot, warnings)
+      : next.build === "CodeZip"
+        ? nodeEntrypoint(runtime, projectRoot, warnings)
+        : undefined;
+  if (entrypoint !== undefined) {
+    next.entrypoint = entrypoint.value;
+    reasons.entrypoint = entrypoint.reason;
+  }
+
+  // runtimeVersion: CodeZip only; a Container image picks its own.
+  if (next.build === "Container") {
+    delete next.runtimeVersion;
+    reasons.runtimeVersion = "Container build";
+  } else {
+    // requires-python / engines.node is a constraint, not a choice: a version in
+    // agentcore.json that satisfies it is kept, so neither a loose range nor a
+    // newer CLI with newer runtimes moves a runtime on its own. Only a version
+    // the constraint excludes (or none at all) is replaced, with the highest match.
+    const allowed =
+      language === "Python"
+        ? allowedPythonVersions(runtime, projectRoot)
+        : allowedNodeVersions(runtime, projectRoot);
+    if (allowed !== undefined) {
+      if (next.runtimeVersion === undefined || !allowed.versions.includes(next.runtimeVersion)) {
+        next.runtimeVersion = allowed.versions[0]!;
+        reasons.runtimeVersion = allowed.source;
+      }
+    } else if (next.runtimeVersion === undefined) {
+      const latest = language === "Python" ? LATEST_PYTHON : LATEST_NODE;
+      next.runtimeVersion = latest;
+      reasons.runtimeVersion = "default";
+      warnings.push(
+        language === "Python"
+          ? `runtime "${runtime.name}": no requires-python in pyproject.toml; using ${versionLabel(latest)}. ` +
+              `Set requires-python (or runtimeVersion in agentcore.json) to pin a version.`
+          : `runtime "${runtime.name}": no engines.node in package.json; using ${versionLabel(latest)}. ` +
+              `Set engines.node (or runtimeVersion in agentcore.json) to pin a version.`,
+      );
+    }
+  }
+
+  const changes = (["build", "dockerfile", "runtimeVersion", "entrypoint"] as const)
+    .filter((field) => runtime[field] !== next[field])
+    .map((field) => ({
+      field,
+      from: runtime[field],
+      to: next[field],
+      reason: reasons[field] ?? "agentcore.json",
+    }));
+  return { runtime: next, changes, warnings };
+}
+
+/**
+ * Whether `dir` holds a regular file named exactly `Dockerfile`. Listing the
+ * directory keeps the match case-sensitive on case-insensitive file systems
+ * (macOS, Windows), as the L3 constructs do; statSync follows a symlink.
+ */
+function hasDockerfile(dir: string): boolean {
+  try {
+    return readdirSync(dir).includes(DOCKERFILE_NAME) && isFile(join(dir, DOCKERFILE_NAME));
+  } catch {
+    return false;
+  }
+}
+
+function entrypointLanguage(runtime: ProjectRuntime): Language {
+  const [file = ""] = runtime.entrypoint.split(":");
+  if (file.endsWith(".py")) return "Python";
+  if (file.endsWith(".ts") || file.endsWith(".js")) return "Node";
+  throw new ProjectStateError(
+    `runtime "${runtime.name}": cannot tell the language of entrypoint "${runtime.entrypoint}". ` +
+      `Use a .py, .ts, or .js entrypoint.`,
+  );
+}
+
+/** `[tool.agentcore] entrypoint` from pyproject.toml, when set. */
+function pythonEntrypoint(
+  runtime: ProjectRuntime,
+  projectRoot: string,
+  warnings: string[],
+): { value: string; reason: string } | undefined {
+  const manifest = findManifest("pyproject.toml", runtime, projectRoot);
+  if (manifest === undefined) return undefined;
+  const text = readFileSync(manifest, "utf-8");
+  const file = displayPath(projectRoot, manifest);
+  const read = readTomlString(text, "tool.agentcore", "entrypoint");
+  if (read === undefined) {
+    // Only the `[tool.agentcore]` table form is read; say so rather than ignore
+    // `tool.agentcore.entrypoint = ...` or `agentcore = { entrypoint = ... }`.
+    if (/^\s*(?:tool\s*\.\s*)?agentcore\s*(?:\.\s*entrypoint\s*=|=\s*\{)/m.test(text)) {
+      warnings.push(
+        `runtime "${runtime.name}": ${file} sets the agentcore entrypoint in a form the CLI ` +
+          `does not read; it is ignored. Use a [tool.agentcore] table with ` +
+          `entrypoint = "main.py" on one line.`,
+      );
+    }
+    return undefined;
+  }
+  if (read.value === "") return undefined;
+  const value = read.value;
+  if (
+    value === undefined ||
+    !EntrypointSchema.safeParse(value).success ||
+    !/\.py(:|$)/.test(value)
+  ) {
+    throw new ProjectStateError(
+      `runtime "${runtime.name}": [tool.agentcore] entrypoint ${read.raw} in ${file} is not a ` +
+        `Python file path relative to the runtime folder (for example "main.py" or "main.py:app").`,
+    );
+  }
+  return { value, reason: `[tool.agentcore] entrypoint in ${file}` };
+}
+
+/**
+ * package.json `main`, when set. The L3 Node packager always bundles main.ts at
+ * the root of the folder, so only main.ts / main.js are accepted, stored as the
+ * bundle's name, main.js.
+ */
+function nodeEntrypoint(
+  runtime: ProjectRuntime,
+  projectRoot: string,
+  warnings: string[],
+): { value: string; reason: string } | undefined {
+  const manifest = readPackageJson(runtime, projectRoot);
+  const main = manifest?.json.main;
+  if (main === undefined) return undefined;
+  const normalized = typeof main === "string" ? main.replace(/^\.\//, "") : undefined;
+  if (normalized !== "main.ts" && normalized !== "main.js") {
+    // Many packages set "main" for other reasons (a library build, a start
+    // script), so it is ignored with a warning rather than refused.
+    warnings.push(
+      `runtime "${runtime.name}": package.json "main" is ${JSON.stringify(main)}; AgentCore ` +
+        `currently bundles main.ts at the root of ` +
+        `${displayPath(projectRoot, resolve(projectRoot, runtime.codeLocation))}, so "main" is ignored.`,
+    );
+    return undefined;
+  }
+  return { value: "main.js", reason: `"main" in ${manifest!.file}` };
+}
+
+function readPackageJson(
+  runtime: ProjectRuntime,
+  projectRoot: string,
+): { file: string; json: { main?: unknown; engines?: { node?: unknown } } } | undefined {
+  const manifest = findManifest("package.json", runtime, projectRoot);
+  if (manifest === undefined) return undefined;
+  const file = displayPath(projectRoot, manifest);
+  try {
+    const json: unknown = JSON.parse(readFileSync(manifest, "utf-8"));
+    return { file, json: json !== null && typeof json === "object" ? json : {} };
+  } catch (error) {
+    throw new ProjectStateError(`runtime "${runtime.name}": cannot parse ${file} as JSON.`, {
+      cause: error,
+    });
+  }
+}
+
+type AllowedVersions = {
+  /** Supported versions the constraint allows, highest first; never empty. */
+  versions: RuntimeVersion[];
+  /** The constraint and the manifest it is in. */
+  source: string;
+};
+
+const PYTHON_VERSIONS = PythonRuntimeSchema.options.map((option) => ({
+  option,
+  minor: Number(option.split("_")[2]),
+}));
+const NODE_VERSIONS = NodeRuntimeSchema.options.map((option) => ({
+  option,
+  major: Number(option.split("_")[1]),
+}));
+export const LATEST_PYTHON = PYTHON_VERSIONS[PYTHON_VERSIONS.length - 1]!.option;
+export const LATEST_NODE = NODE_VERSIONS[NODE_VERSIONS.length - 1]!.option;
+
+/** The highest supported Python matching requires-python, or undefined when it is not set. */
+function allowedPythonVersions(
+  runtime: ProjectRuntime,
+  projectRoot: string,
+): AllowedVersions | undefined {
+  const manifest = findManifest("pyproject.toml", runtime, projectRoot);
+  if (manifest === undefined) return undefined;
+  const requiresPython = readTomlString(
+    readFileSync(manifest, "utf-8"),
+    "project",
+    "requires-python",
+  );
+  // An empty value says nothing, so it counts as missing.
+  if (requiresPython === undefined || requiresPython.value === "") return undefined;
+
+  const file = displayPath(projectRoot, manifest);
+  const value = requiresPython.value;
+  const clauses = value === undefined ? undefined : parseSpecifierSet(value);
+  if (value === undefined || clauses === undefined) {
+    throw new ProjectStateError(
+      `runtime "${runtime.name}": cannot parse requires-python ${requiresPython.raw} in ${file}. ` +
+        `Use a PEP 440 specifier such as ">=3.12", or set runtimeVersion in agentcore.json.`,
+    );
+  }
+  const versions = [...PYTHON_VERSIONS]
+    .reverse()
+    .filter(({ minor }) => pythonMinorSatisfies(3, minor, clauses))
+    .map(({ option }) => option);
+  if (versions.length === 0) {
+    throw new ProjectStateError(
+      `runtime "${runtime.name}": requires-python "${value}" in ${file} matches no supported ` +
+        `Python version (supported: ${PYTHON_VERSIONS.map(({ minor }) => `3.${minor}`).join(", ")}).`,
+    );
+  }
+  return { versions, source: `requires-python "${value}" in ${file}` };
+}
+
+/** The supported Node.js majors engines.node allows, or undefined when it is not set. */
+function allowedNodeVersions(
+  runtime: ProjectRuntime,
+  projectRoot: string,
+): AllowedVersions | undefined {
+  const manifest = readPackageJson(runtime, projectRoot);
+  const engines = manifest?.json.engines?.node;
+  // An empty value says nothing, so it counts as missing.
+  if (engines === undefined || (typeof engines === "string" && engines.trim() === "")) {
+    return undefined;
+  }
+
+  const file = manifest!.file;
+  const range = typeof engines === "string" ? semver.validRange(engines) : null;
+  if (range === null || hasPrerelease(engines as string)) {
+    throw new ProjectStateError(
+      `runtime "${runtime.name}": cannot parse engines.node ${JSON.stringify(engines)} in ${file}. ` +
+        `Use a semver range such as ">=20", or set runtimeVersion in agentcore.json.`,
+    );
+  }
+  const versions = [...NODE_VERSIONS]
+    .reverse()
+    .filter(({ major }) => semver.intersects(range, `>=${major}.0.0 <${major + 1}.0.0`))
+    .map(({ option }) => option);
+  if (versions.length === 0) {
+    throw new ProjectStateError(
+      `runtime "${runtime.name}": engines.node "${engines}" in ${file} matches no supported ` +
+        `Node.js version (supported: ${NODE_VERSIONS.map(({ major }) => major).join(", ")}).`,
+    );
+  }
+  return { versions, source: `engines.node "${engines}" in ${file}` };
+}
+
+/**
+ * Whether a range as written names a prerelease version (`^20.0.0-beta.1`), which
+ * the L3 treats as unparseable. Checked on the written text: semver's normalized
+ * ranges add `-0` prerelease bounds of their own (`^20` -> `<21.0.0-0`).
+ */
+function hasPrerelease(range: string): boolean {
+  return /\d+\.\d+\.\d+-[0-9A-Za-z]/.test(range);
+}
+
+/** `PYTHON_3_14` -> `Python 3.14`, `NODE_22` -> `Node.js 22`. */
+export function versionLabel(version: RuntimeVersion): string {
+  const [kind, ...parts] = version.split("_");
+  return kind === "PYTHON" ? `Python ${parts.join(".")}` : `Node.js ${parts.join(".")}`;
+}
+
+/**
+ * Finds a manifest the way the packagers do: in the code folder, then each
+ * parent up to (and including) the project root.
+ */
+export function findManifest(
+  fileName: string,
+  runtime: ProjectRuntime,
+  projectRoot: string,
+): string | undefined {
+  const root = resolve(projectRoot);
+  let current = resolve(root, runtime.codeLocation);
+  for (;;) {
+    const candidate = join(current, fileName);
+    if (isFile(candidate)) return candidate;
+    if (current === root || !isWithin(root, current)) return undefined;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+/** The directory a Dockerfile is looked up in: buildContextPath, else codeLocation. */
+export function contextDir(runtime: ProjectRuntime, projectRoot: string): string {
+  return resolve(projectRoot, runtime.buildContextPath ?? runtime.codeLocation);
+}
+
+/** A project-relative, forward-slash path for messages. */
+export function displayPath(projectRoot: string, path: string): string {
+  const relativePath = relative(resolve(projectRoot), path);
+  return (relativePath === "" ? "." : relativePath).split(sep).join("/");
+}
+
+function isWithin(root: string, path: string): boolean {
+  const relativePath = relative(root, path);
+  return !(
+    relativePath === ".." ||
+    relativePath.startsWith(`..${sep}`) ||
+    isAbsolute(relativePath)
+  );
+}
+
+export function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads a single-line string `key` from a TOML `[table]` with a line-based parse
+ * (no TOML dependency); the key may be quoted. Returns undefined when the key
+ * is absent, and no `value` (only the raw text) when it is not a string.
+ */
+export function readTomlString(
+  text: string,
+  table: string,
+  key: string,
+): { value?: string; raw: string } | undefined {
+  let inTable = false;
+  // Keys here are plain identifiers ("requires-python", "entrypoint"), so no escaping.
+  const keyPattern = new RegExp(`^\\s*(?:${key}|"${key}"|'${key}')\\s*=\\s*(.*?)\\s*$`);
+  for (const line of text.split(/\r?\n/)) {
+    const header = /^\s*(\[\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(line);
+    if (header) {
+      inTable = header[1] === "[" && header[2]?.replace(/\s*\.\s*/g, ".") === table;
+      continue;
+    }
+    if (!inTable) continue;
+    const field = keyPattern.exec(line);
+    if (!field) continue;
+    const rest = field[1]!;
+    const value = /^(["'])(.*?)\1\s*(?:#.*)?$/.exec(rest);
+    return value ? { value: value[2]!.trim(), raw: `"${value[2]}"` } : { raw: rest };
+  }
+  return undefined;
+}
+
+type Clause = { operator: string; release: number[]; wildcard: boolean };
+
+/** Parses a PEP 440 specifier set (comma = AND). Returns undefined when any clause is invalid. */
+export function parseSpecifierSet(value: string): Clause[] | undefined {
+  const clauses: Clause[] = [];
+  for (const part of value.split(",")) {
+    const clause = /^\s*(~=|==|!=|<=|>=|<|>)\s*[vV]?(\d+(?:\.\d+)*)(\.\*)?\s*$/.exec(part);
+    if (!clause) return undefined;
+    const [, operator = "", version = "", wildcard] = clause;
+    if (wildcard && operator !== "==" && operator !== "!=") return undefined;
+    const release = version.split(".").map(Number);
+    if (operator === "~=" && release.length < 2) return undefined;
+    clauses.push({ operator, release, wildcard: wildcard !== undefined });
+  }
+  return clauses;
+}
+
+/** Whether some patch release major.minor.p (p in 0..99) satisfies every clause. */
+function pythonMinorSatisfies(major: number, minor: number, clauses: Clause[]): boolean {
+  for (let patch = 0; patch <= 99; patch++) {
+    const candidate = [major, minor, patch];
+    if (clauses.every((clause) => clauseMatches(candidate, clause))) return true;
+  }
+  return false;
+}
+
+function clauseMatches(candidate: number[], { operator, release, wildcard }: Clause): boolean {
+  const order = compareReleases(candidate, release);
+  switch (operator) {
+    case "==":
+      return wildcard ? hasPrefix(candidate, release) : order === 0;
+    case "!=":
+      return wildcard ? !hasPrefix(candidate, release) : order !== 0;
+    case ">=":
+      return order >= 0;
+    case "<=":
+      return order <= 0;
+    case ">":
+      return order > 0;
+    case "<":
+      return order < 0;
+    case "~=":
+      return order >= 0 && hasPrefix(candidate, release.slice(0, -1));
+    default:
+      return false;
+  }
+}
+
+function compareReleases(a: number[], b: number[]): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const difference = (a[i] ?? 0) - (b[i] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+function hasPrefix(candidate: number[], prefix: number[]): boolean {
+  return prefix.every((segment, i) => (candidate[i] ?? 0) === segment);
+}
+
+export interface PreparedRuntimes {
+  /** Every runtime, re-derived from its code folder. */
+  runtimes: ProjectRuntime[];
+  /** The runtimes whose settings changed, to write back to agentcore.json. */
+  changed: RuntimeSync[];
+  /** A line per changed field, then any warnings. */
+  messages: string[];
+}
+
+/**
+ * Checks and re-derives the runtimes `dev` or `deploy` is about to run. Every
+ * problem across them is reported in one error, each pointing at the runtime's
+ * README.
+ */
+export function prepareRuntimes(
+  projectRoot: string,
+  runtimes: ProjectRuntime[],
+  purpose: "dev" | "deploy",
+): PreparedRuntimes {
+  const prepared: ProjectRuntime[] = [];
+  const changed: RuntimeSync[] = [];
+  const messages: string[] = [];
+  const problems: string[] = [];
+  for (const runtime of runtimes) {
+    const readme = `${displayPath(projectRoot, resolve(projectRoot, runtime.codeLocation))}/README.md`;
+    const pointAtReadme = (found: string[]) =>
+      problems.push(...found.map((problem) => `${problem.replace(/\.?$/, ".")} See ${readme}.`));
+    const folder = resolve(projectRoot, runtime.codeLocation);
+    if (!isDirectory(folder)) {
+      pointAtReadme([
+        `runtime "${runtime.name}": ${displayPath(projectRoot, folder)}/ does not exist.`,
+      ]);
+      continue;
+    }
+    let sync: RuntimeSync;
+    try {
+      sync = syncRuntimeBuild(runtime, projectRoot);
+    } catch (error) {
+      if (!(error instanceof ProjectStateError)) throw error;
+      pointAtReadme([error.message]);
+      continue;
+    }
+    const found = runtimeProblems(sync.runtime, projectRoot, purpose);
+    if (found.length > 0) {
+      pointAtReadme(found);
+      continue;
+    }
+    prepared.push(sync.runtime);
+    if (sync.changes.length > 0) changed.push(sync);
+    messages.push(...sync.changes.map((change) => describeChange(runtime.name, change)));
+    messages.push(...sync.warnings);
+  }
+  if (problems.length > 0) throw new ProjectStateError(problems.join("\n"));
+  return { runtimes: prepared, changed, messages };
+}
+
+/** What a re-derived runtime's folder is missing for its build. */
+function runtimeProblems(
+  runtime: ProjectRuntime,
+  projectRoot: string,
+  purpose: "dev" | "deploy",
+): string[] {
+  const prefix = `runtime "${runtime.name}":`;
+  const folder = resolve(projectRoot, runtime.codeLocation);
+  const folderLabel = `${displayPath(projectRoot, folder)}/`;
+  const problems: string[] = [];
+  if (runtime.build === "Container") {
+    const context = contextDir(runtime, projectRoot);
+    const dockerfile = runtime.dockerfile ?? DOCKERFILE_NAME;
+    if (!isFile(join(context, dockerfile))) {
+      const missing =
+        dockerfile === DOCKERFILE_NAME
+          ? `no Dockerfile in ${displayPath(projectRoot, context)}/`
+          : `no Dockerfile at ${displayPath(projectRoot, join(context, dockerfile))}`;
+      problems.push(
+        `${prefix} ${missing}, and agentcore.json says this is a Container build. Add the ` +
+          `Dockerfile, or set "build": "CodeZip" in agentcore.json to deploy the code directly.`,
+      );
+    }
+    if (runtime.networkMode === "VPC" && !runtime.networkConfig?.vpcId) {
+      problems.push(
+        `${prefix} networkConfig.vpcId is required for Container builds in VPC mode ` +
+          `(CodeBuild cannot infer the VPC from subnets).`,
+      );
+    }
+    return problems;
+  }
+
+  const [entrypoint = ""] = runtime.entrypoint.split(":");
+  const has = (file: string) => isFile(join(folder, file));
+  if (entrypoint.endsWith(".py")) {
+    if (findManifest("pyproject.toml", runtime, projectRoot) === undefined) {
+      problems.push(
+        has("package.json")
+          ? `${prefix} this runtime is Python (entrypoint ${entrypoint}) but ${folderLabel} has a ` +
+              `package.json and no pyproject.toml.`
+          : `${prefix} no pyproject.toml in ${folderLabel}.`,
+      );
+    }
+    if (!has(entrypoint)) problems.push(`${prefix} no ${entrypoint} in ${folderLabel}.`);
+  } else {
+    if (findManifest("package.json", runtime, projectRoot) === undefined) {
+      problems.push(
+        has("pyproject.toml")
+          ? `${prefix} this runtime is TypeScript (entrypoint ${entrypoint}) but ${folderLabel} has ` +
+              `a pyproject.toml and no package.json.`
+          : `${prefix} no package.json in ${folderLabel}.`,
+      );
+    }
+    // The deploy packager always bundles from main.ts (the spec records the bundle,
+    // main.js); dev also runs a plain JavaScript entrypoint.
+    if (!has("main.ts") && (purpose === "deploy" || !has(entrypoint))) {
+      problems.push(`${prefix} no main.ts in ${folderLabel}.`);
+    }
+    // `dev` installs missing Node dependencies itself; deploy bundles from them.
+    if (purpose === "deploy" && !isDirectory(join(folder, "node_modules"))) {
+      problems.push(`${prefix} no node_modules in ${folderLabel}; run \`npm install\` there.`);
+    }
+  }
+  return problems;
+}
diff --git a/src/core/project/templates/fsTree.test.ts b/src/core/project/templates/fsTree.test.ts
index c06f3db1f4..9b640f4a05 100644
--- a/src/core/project/templates/fsTree.test.ts
+++ b/src/core/project/templates/fsTree.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { ProjectStateError } from "../../../errors/errors";
@@ -54,6 +54,21 @@ describe("FsTreeNode.write", () => {
 
     await expect(tree.write(directory)).rejects.toBeInstanceOf(ProjectStateError);
   });
+
+  test("with skipExisting, leaves existing files alone and reports only what it wrote", async () => {
+    const directory = await inTempDirectory();
+    await writeFile(join(directory, "README.md"), "mine\n");
+    const tree = FsTreeNode.createDirectory(".", [
+      FsTreeNode.createFile("README.md", async () => "generated\n"),
+      FsTreeNode.createFile("AGENTS.md", async () => "generated\n"),
+    ]);
+
+    const written = await tree.write(directory, { skipExisting: true });
+
+    expect(written).toEqual([join(directory, "AGENTS.md")]);
+    expect(await readFile(join(directory, "README.md"), "utf8")).toBe("mine\n");
+    expect(await readFile(join(directory, "AGENTS.md"), "utf8")).toBe("generated\n");
+  });
 });
 
 describe("FsTreeNode.fromAssetSource", () => {
diff --git a/src/core/project/templates/fsTree.ts b/src/core/project/templates/fsTree.ts
index 73650fcfd9..f1c5e7cbed 100644
--- a/src/core/project/templates/fsTree.ts
+++ b/src/core/project/templates/fsTree.ts
@@ -34,7 +34,18 @@ export class FsTreeNode {
     return true;
   }
 
-  async write(dest: string): Promise<void> {
+  /**
+   * Writes the tree under `dest`, returning the paths of the files it wrote. An
+   * existing file is an error, unless `skipExisting` is set: then it is left
+   * untouched and not reported as written. `written`, when given, is filled as
+   * each file is written, so a caller still knows what was created if a later
+   * write fails.
+   */
+  async write(
+    dest: string,
+    options: { skipExisting?: boolean; written?: string[] } = {},
+  ): Promise<string[]> {
+    const written = options.written ?? [];
     await this.walk(async (node, path) => {
       if (node.isDir) {
         await mkdir(path, { recursive: true });
@@ -42,12 +53,23 @@ export class FsTreeNode {
       }
 
       if (existsSync(path)) {
+        if (options.skipExisting) return true;
         throw new ProjectStateError(`File already exists: ${path}`);
       }
 
-      await writeFile(path, await node.bytes!());
+      try {
+        // "wx" refuses to clobber a file created after the check above.
+        await writeFile(path, await node.bytes!(), { flag: "wx" });
+      } catch (error) {
+        if (options.skipExisting && (error as NodeJS.ErrnoException).code === "EEXIST") {
+          return true;
+        }
+        throw error;
+      }
+      written.push(path);
       return true;
     }, dest);
+    return written;
   }
 
   static createFile(name: string, bytes: () => Promise<string>): FsTreeNode {
diff --git a/src/core/project/templates/runtime.test.ts b/src/core/project/templates/runtime.test.ts
new file mode 100644
index 0000000000..3540c9324f
--- /dev/null
+++ b/src/core/project/templates/runtime.test.ts
@@ -0,0 +1,257 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { initProject, TestCoreClient } from "../../../testing";
+import { toAddRuntimeInput, type RuntimeInput } from "../../../handlers/project/add/runtime";
+import {
+  RUNTIME_TEMPLATE_SHORTCUT_NAMES,
+  resolveRuntimeTemplateShortcut,
+  type RuntimeTemplateShortcutName,
+} from "../../../handlers/project/shortcuts";
+import { prepareRuntimes } from "../runtimeBuild";
+import { importScaffoldRuntimeInput } from "../../../handlers/project/importBedrockAgent";
+import type { ModelProvider } from "../../../handlers/project/types";
+import { credentialEnvVarName } from "../../../projectSchemas/credential";
+import { readEnvFile } from "../../../io/envFile";
+
+// Runtime templates are scaffolded by `agentcore create --template` (and its
+// wizard, which adds model overrides) and by `add runtime --type import`. These
+// tests drive the shared addResource path directly with each template.
+
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(() => Promise.all(cleanups.splice(0).map((cleanup) => cleanup())));
+
+async function addTemplate(
+  name: string,
+  template: RuntimeTemplateShortcutName,
+  options: {
+    model?: { modelProvider?: ModelProvider; modelId?: string; apiKey?: string; apiBase?: string };
+    infra?: Partial<RuntimeInput>;
+  } = {},
+) {
+  const { projectRoot, cleanup } = await initProject();
+  cleanups.push(cleanup);
+  const core = new TestCoreClient();
+  const project = (await core.projectManager.resolve({ filePath: projectRoot }))!;
+  const generator = core.projectManager.addResource(
+    project,
+    toAddRuntimeInput({
+      name,
+      envVars: [],
+      ...options.infra,
+      scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(template, {
+        runtimeName: name,
+        ...options.model,
+      }),
+    } as RuntimeInput),
+  );
+  for (let step = await generator.next(); !step.done; step = await generator.next());
+  const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
+  const runtime = spec.runtimes.find((candidate: { name: string }) => candidate.name === name);
+  return { projectRoot, core, spec, runtime, appDir: join(projectRoot, "app", name) };
+}
+
+const mounts = {
+  networkMode: "VPC",
+  networkConfig: {
+    subnets: ["subnet-0123456789abcdef0"],
+    securityGroups: ["sg-0123456789abcdef0"],
+  },
+  filesystemConfigurations: [
+    { sessionStorage: { mountPath: "/mnt/session" } },
+    {
+      efsAccessPoint: {
+        accessPointArn:
+          "arn:aws:elasticfilesystem:us-east-1:123456789012:access-point/fsap-0123456789abcdef0",
+        mountPath: "/mnt/efs",
+      },
+    },
+    {
+      s3FilesAccessPoint: {
+        accessPointArn:
+          "arn:aws:s3files:us-east-1:123456789012:file-system/fs-0123456789abcdef01/access-point/fsap-0123456789abcdef1",
+        mountPath: "/mnt/s3",
+      },
+    },
+  ],
+} as const;
+
+describe("runtime templates", () => {
+  test.each<[RuntimeTemplateShortcutName, Record<string, unknown>, Partial<RuntimeInput>]>([
+    ["agent-python-minimal", { build: "CodeZip", runtimeVersion: "PYTHON_3_14" }, {}],
+    ["agent-python-strands", { build: "CodeZip", protocol: "HTTP" }, {}],
+    ["agent-python-strands-container", { build: "Container", dockerfile: "Dockerfile" }, {}],
+    ["mcp-python-fastmcp", { build: "CodeZip", protocol: "MCP" }, {}],
+    ["a2a-python-strands", { build: "CodeZip", protocol: "A2A" }, {}],
+    ["agui-python-strands", { build: "CodeZip", protocol: "AGUI" }, {}],
+    ["agent-python-strands", { networkMode: "VPC" }, mounts as Partial<RuntimeInput>],
+    ["mcp-python-fastmcp", { protocol: "MCP" }, mounts as Partial<RuntimeInput>],
+    ["a2a-python-strands", { protocol: "A2A" }, mounts as Partial<RuntimeInput>],
+  ])("%s scaffolds code and its spec entry", async (template, expected, infra) => {
+    const { runtime, appDir } = await addTemplate("my_agent", template, { infra });
+    expect(runtime).toMatchObject({ entrypoint: "main.py", ...expected });
+    expect(await Bun.file(join(appDir, "main.py")).exists()).toBe(true);
+    const isContainer = template.endsWith("-container");
+    expect(runtime.runtimeVersion).toBe(isContainer ? undefined : "PYTHON_3_14");
+    expect(await Bun.file(join(appDir, "Dockerfile")).exists()).toBe(isContainer);
+    expect(await Bun.file(join(appDir, ".dockerignore")).exists()).toBe(isContainer);
+  });
+
+  test("Bedrock Managed Agents keeps infrastructure overrides and its required policy", async () => {
+    const { runtime, appDir, core } = await addTemplate("my_bma", "environment-python-bma", {
+      infra: {
+        lifecycleConfiguration: { idleRuntimeSessionTimeout: 300, maxLifetime: 3600 },
+        additionalPolicies: ["custom-policy.json"],
+        tags: { team: "agents" },
+      },
+    });
+    expect(runtime).toMatchObject({
+      build: "Container",
+      bedrockManagedAgents: true,
+      entrypoint: "lifecycle/server.py",
+      dockerfile: "Dockerfile",
+      protocol: "HTTP",
+      lifecycleConfiguration: { idleRuntimeSessionTimeout: 300, maxLifetime: 3600 },
+      additionalPolicies: ["bma-acr-policy.json", "custom-policy.json"],
+      tags: { "agentcore:template": "BedrockManagedAgents", team: "agents" },
+    });
+    // Local Python dependency setup is deferred to the container.
+    expect(core.projectCommands).toEqual([]);
+    expect(await Bun.file(join(appDir, "pyproject.toml")).exists()).toBe(true);
+  });
+
+  test.each<[RuntimeTemplateShortcutName, string[]]>([
+    ["agent-python-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
+    ["a2a-python-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
+    ["agent-typescript-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
+    ["agent-python-minimal", []],
+    ["agent-python-langchain", []],
+    ["agent-typescript-vercel", []],
+    ["mcp-python-fastmcp", []],
+    ["agui-python-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
+    ["environment-python-bma", []],
+  ])("%s ships with its pre-configured memory", async (template, expectedStrategies) => {
+    const { spec } = await addTemplate("my_agent", template);
+    const memory = (spec.memories ?? []).find(
+      (candidate: { name: string }) => candidate.name === "my_agentMemory",
+    );
+    if (expectedStrategies.length === 0) {
+      expect(memory).toBeUndefined();
+      return;
+    }
+    expect(memory).toMatchObject({ name: "my_agentMemory", eventExpiryDuration: 30 });
+    expect(memory.strategies.map(({ type }: { type: string }) => type)).toEqual(expectedStrategies);
+  });
+
+  test.each<[RuntimeTemplateShortcutName, string]>([
+    ["agent-typescript-strands", "main.ts"],
+    ["agent-typescript-vercel", "main.ts"],
+  ])("%s scaffolds a TypeScript runtime", async (template, file) => {
+    const { runtime, appDir } = await addTemplate("my_agent", template);
+    expect(runtime).toMatchObject({
+      entrypoint: "main.js",
+      build: "CodeZip",
+      runtimeVersion: "NODE_22",
+      protocol: "HTTP",
+    });
+    expect(await Bun.file(join(appDir, file)).exists()).toBe(true);
+  });
+
+  test("escapes quotes in the model id in the scaffolded model code", async () => {
+    const { appDir } = await addTemplate("quoted", "agent-python-strands", {
+      model: { modelProvider: "LiteLLM", modelId: 'openai/we"ird' },
+    });
+    const loadPy = await Bun.file(join(appDir, "model", "load.py")).text();
+    expect(loadPy).toContain('model_id="openai/we\\"ird"');
+  });
+
+  test("OpenAICompatible renders the OpenAI client against the API base", async () => {
+    const { spec, runtime, appDir } = await addTemplate("ds_agent", "agent-python-strands", {
+      model: {
+        modelProvider: "OpenAICompatible",
+        modelId: "deepseek-chat",
+        apiKey: "sk-ds",
+        apiBase: "https://api.deepseek.com/v1",
+      },
+    });
+    expect(runtime.modelProvider).toBe("OpenAICompatible");
+    expect(spec.credentials).toContainEqual({
+      authorizerType: "ApiKeyCredentialProvider",
+      name: "ds_agentOpenAICompatibleApiKey",
+    });
+    const loadModel = await Bun.file(join(appDir, "model", "load.py")).text();
+    expect(loadModel).toContain('"base_url": "https://api.deepseek.com/v1"');
+  });
+
+  test("an API base is refused with a provider other than OpenAICompatible", () => {
+    expect(() =>
+      resolveRuntimeTemplateShortcut("agent-python-strands", {
+        modelProvider: "Gemini",
+        apiKey: "sk-g",
+        apiBase: "https://example.com/v1",
+      }),
+    ).toThrow(/only supported with the openai_compatible model provider/);
+  });
+
+  test.each<ModelProvider>(["Anthropic", "OpenAI", "Gemini"])(
+    "%s scaffolds agent-python-strands with an API-key credential",
+    async (provider) => {
+      const { projectRoot, spec } = await addTemplate("my_agent", "agent-python-strands", {
+        model: { modelProvider: provider, apiKey: "test-api-key" },
+      });
+      const credentialName = `my_agent${provider}ApiKey`;
+      expect(spec.credentials).toContainEqual({
+        authorizerType: "ApiKeyCredentialProvider",
+        name: credentialName,
+      });
+      const envPath = join(projectRoot, "agentcore", ".env.local");
+      expect(await Bun.file(envPath).text()).not.toContain("test-api-key");
+      expect((await readEnvFile(envPath))[credentialEnvVarName(credentialName)]).toBe(
+        "test-api-key",
+      );
+    },
+  );
+
+  // dev/build/deploy re-derive build settings from the code and write changes
+  // back; a freshly scaffolded template must already agree with its own code.
+  test.each([...RUNTIME_TEMPLATE_SHORTCUT_NAMES])(
+    "%s resolves to the settings it was scaffolded with",
+    async (template) => {
+      const { projectRoot, spec } = await addTemplate("my_agent", template);
+      const prepared = prepareRuntimes(projectRoot, spec.runtimes, "dev");
+      expect(prepared.changed).toEqual([]);
+      expect(prepared.messages).toEqual([]);
+    },
+  );
+
+  test("a translated Bedrock Agent import resolves to the settings it was scaffolded with", async () => {
+    const { projectRoot, cleanup } = await initProject();
+    cleanups.push(cleanup);
+    const core = new TestCoreClient();
+    const project = (await core.projectManager.resolve({ filePath: projectRoot }))!;
+    const generator = core.projectManager.addResource(
+      project,
+      toAddRuntimeInput({
+        name: "imported",
+        envVars: [],
+        scaffoldRuntimeInput: importScaffoldRuntimeInput("imported"),
+        importBedrockAgent: {
+          framework: "strands",
+          sourceAgentId: "A1B2C3D4E5",
+          sourceAgentAliasId: "TSTALIASID",
+          sourceAgentVersion: "1",
+          files: {
+            "main.py": "from strands import Agent\n",
+            "pyproject.toml": '[project]\nname = "imported"\nrequires-python = ">=3.10"\n',
+          },
+          notes: [],
+        },
+      }),
+    );
+    for (let step = await generator.next(); !step.done; step = await generator.next());
+    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
+
+    const prepared = prepareRuntimes(projectRoot, spec.runtimes, "dev");
+    expect(prepared.changed).toEqual([]);
+    expect(prepared.messages).toEqual([]);
+  });
+});
diff --git a/src/core/project/templates/runtimeDocs.ts b/src/core/project/templates/runtimeDocs.ts
new file mode 100644
index 0000000000..30e13e3ff0
--- /dev/null
+++ b/src/core/project/templates/runtimeDocs.ts
@@ -0,0 +1,126 @@
+import { FsTreeNode } from "./fsTree";
+import type { AssetSource } from "../source";
+import type { TemplateRenderer } from "./types";
+import type { RuntimeDocsConfig } from "../../../handlers/project/add/runtime/types";
+import type { ProjectRuntime } from "../../../projectSchemas/runtime";
+import {
+  NodeRuntimeSchema,
+  PythonRuntimeSchema,
+  type ProtocolMode,
+} from "../../../projectSchemas/constants";
+import { defaultMemoryName, memoryEnvVarName } from "../../../projectSchemas/memory";
+import { credentialProviderNameEnvVarName } from "../../../projectSchemas/credential";
+import { LATEST_NODE, LATEST_PYTHON } from "../runtimeBuild";
+
+/**
+ * The discovery prefix @aws/agentcore-cdk gives a project gateway:
+ * `AGENTCORE_GATEWAY_<NAME>`, the name upper-cased with every other character
+ * turned into `_` (the L3's `discoveryPrefix` / `connectionEnvToken`).
+ */
+function gatewayEnvPrefix(gatewayName: string): string {
+  return `AGENTCORE_GATEWAY_${gatewayName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+}
+
+/** The port each protocol's runtime contract listens on. */
+const PROTOCOL_PORTS: Record<ProtocolMode, number> = {
+  HTTP: 8080,
+  MCP: 8000,
+  A2A: 9000,
+  AGUI: 8080,
+};
+
+/** `PYTHON_3_14` -> `3.14`, `NODE_22` -> `22`. */
+function versionNumber(version: string): string {
+  return version.split("_").slice(1).join(".");
+}
+
+/** `["18", "20", "22"]` -> `18, 20 and 22`. */
+function listVersions(versions: string[]): string {
+  return versions.length < 2
+    ? versions.join("")
+    : `${versions.slice(0, -1).join(", ")} and ${versions.at(-1)}`;
+}
+
+/** The entrypoint agentcore.json records: TypeScript deploys the bundled main.js. */
+export function docsRuntimeEntrypoint(language: RuntimeDocsConfig["language"]): string {
+  return language === "TypeScript" ? "main.js" : "main.py";
+}
+
+/**
+ * The README.md and AGENTS.md for a runtime the user writes themselves,
+ * rendered for its language and protocol.
+ */
+export function runtimeDocsTree(
+  config: { assetSource: AssetSource; templateRenderer: TemplateRenderer },
+  input: RuntimeDocsConfig,
+): Promise<FsTreeNode> {
+  const protocol = input.protocol ?? "HTTP";
+  const context = {
+    name: input.name,
+    protocol,
+    port: PROTOCOL_PORTS[protocol],
+    entrypoint: docsRuntimeEntrypoint(input.language),
+    contractPage: protocol.toLowerCase(),
+    // Supported and starting versions, from the schema so the docs follow it.
+    versions: {
+      latestPython: versionNumber(LATEST_PYTHON),
+      latestNode: versionNumber(LATEST_NODE),
+      python: listVersions(PythonRuntimeSchema.options.map(versionNumber)),
+      node: listVersions(NodeRuntimeSchema.options.map(versionNumber)),
+    },
+    // Worked examples of the discovery variable names, rendered from the same
+    // rules the CDK app uses so the docs cannot drift from them.
+    memoryExample: {
+      name: defaultMemoryName(input.name),
+      env: memoryEnvVarName(defaultMemoryName(input.name)),
+    },
+    gatewayExample: { name: "docs-gateway", env: `${gatewayEnvPrefix("docs-gateway")}_URL` },
+    credentialExample: {
+      name: "openai-key",
+      env: credentialProviderNameEnvVarName("openai-key"),
+    },
+  };
+  return FsTreeNode.fromAssetSource(
+    { assetSource: config.assetSource },
+    {
+      assetDir: `templates/runtime-docs/${input.language === "TypeScript" ? "typescript" : "python"}`,
+    },
+    {
+      rootDirName: input.name,
+      transformContent: (raw) => config.templateRenderer.render(raw, context),
+    },
+  );
+}
+
+/**
+ * The agentcore.json entry for a docs-only runtime, with starting values: a
+ * CodeZip build on the latest runtime for the language. dev, build, and deploy
+ * update build, runtimeVersion, and entrypoint from the code once it exists.
+ */
+export function buildDocsRuntimeSpec(input: RuntimeDocsConfig): ProjectRuntime {
+  const { name, language, ...infra } = input;
+  return {
+    name,
+    codeLocation: `app/${name}` as ProjectRuntime["codeLocation"],
+    build: "CodeZip",
+    runtimeVersion: language === "TypeScript" ? LATEST_NODE : LATEST_PYTHON,
+    entrypoint: docsRuntimeEntrypoint(language),
+    protocol: infra.protocol ?? "HTTP",
+    ...(infra.description && { description: infra.description }),
+    ...(infra.executionRoleArn && { executionRoleArn: infra.executionRoleArn }),
+    ...(infra.additionalPolicies?.length && { additionalPolicies: infra.additionalPolicies }),
+    ...(infra.envVars?.length && { envVars: infra.envVars }),
+    ...(infra.networkMode && { networkMode: infra.networkMode }),
+    ...(infra.networkConfig && { networkConfig: infra.networkConfig }),
+    ...(infra.authorizerType && { authorizerType: infra.authorizerType }),
+    ...(infra.authorizerConfiguration && {
+      authorizerConfiguration: infra.authorizerConfiguration,
+    }),
+    ...(infra.requestHeaderAllowlist && { requestHeaderAllowlist: infra.requestHeaderAllowlist }),
+    ...(infra.lifecycleConfiguration && { lifecycleConfiguration: infra.lifecycleConfiguration }),
+    ...(infra.filesystemConfigurations && {
+      filesystemConfigurations: infra.filesystemConfigurations,
+    }),
+    ...(infra.tags && { tags: infra.tags }),
+  };
+}
diff --git a/src/handlers/project/RuntimeModelField.tsx b/src/handlers/project/RuntimeModelField.tsx
index 1851721e91..e36affe2bb 100644
--- a/src/handlers/project/RuntimeModelField.tsx
+++ b/src/handlers/project/RuntimeModelField.tsx
@@ -13,12 +13,10 @@ import type { ScaffoldRuntimeInput } from "./types";
 
 const theme = darkTheme;
 
-// The model step of the code-based runtime wizards: `agentcore create` with a
-// runtime template and `agentcore add runtime`. Both hand the answer to
-// resolveRuntimeTemplateShortcut as the same overrides the --model-provider,
-// --model-id, --api-key and --api-base flags supply, so the wizard scaffolds
-// exactly what the flag command would. It is only shown for templates whose
-// shortcut has supportsModelProviderOverride; the others stay Bedrock-only.
+// The model step of the `agentcore create` wizard for a runtime template. It
+// hands the answer to resolveRuntimeTemplateShortcut as model-provider, model-id,
+// API-key and API-base overrides. It is only shown for templates whose shortcut
+// has supportsModelProviderOverride; the others stay Bedrock-only.
 
 type TemplateLanguage = ScaffoldRuntimeInput["language"];
 
diff --git a/src/handlers/project/add/runtime/index.test.ts b/src/handlers/project/add/runtime/index.test.ts
index 85c951b6f8..c49a8835ac 100644
--- a/src/handlers/project/add/runtime/index.test.ts
+++ b/src/handlers/project/add/runtime/index.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { writeFile } from "node:fs/promises";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createRootHandler } from "../../../index";
 import {
@@ -11,9 +11,7 @@ import {
   testIO,
 } from "../../../../testing";
 import type { BedrockAgentImportPlan } from "../../../../core/project/bedrockAgentImport";
-import { credentialEnvVarName } from "../../../../projectSchemas/credential";
 import { InputValidationError } from "../../../../errors";
-import { readEnvFile } from "../../../../io/envFile";
 
 const cleanups: Array<() => Promise<void>> = [];
 afterEach(() => Promise.all(cleanups.splice(0).map((cleanup) => cleanup())));
@@ -58,9 +56,16 @@ function translatedImportPlan(
   };
 }
 
-describe("project add runtime", () => {
-  const template = ["--template", "agent-python-minimal"];
+async function specOf(projectRoot: string) {
+  return Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
+}
+
+async function runtimeOf(projectRoot: string, name: string) {
+  const spec = await specOf(projectRoot);
+  return spec.runtimes.find((candidate: { name: string }) => candidate.name === name);
+}
 
+describe("project add runtime", () => {
   const allInfrastructureFlags = [
     "--description",
     "Configured runtime",
@@ -88,37 +93,105 @@ describe("project add runtime", () => {
     '{"team":"ml","env":"test"}',
   ];
 
-  const expectedSpecByLabel: Record<string, Record<string, unknown>> = {
-    "strands -container template": {
-      build: "Container",
-      dockerfile: "Dockerfile",
-    },
-    "mcp-python-fastmcp template preset": {
-      build: "CodeZip",
-      protocol: "MCP",
-    },
-    "a2a-python-strands template preset": {
-      build: "CodeZip",
-      protocol: "A2A",
+  test.each<[string, string[], Record<string, unknown>, RegExp, RegExp[]]>([
+    [
+      "python (HTTP by default)",
+      ["--language", "python"],
+      { entrypoint: "main.py", protocol: "HTTP", runtimeVersion: "PYTHON_3_14" },
+      /POST \/invocations/,
+      [/runtime-mcp-/, /runtime-a2a-/, /runtime-agui-/],
+    ],
+    [
+      "python MCP",
+      ["--language", "python", "--protocol", "MCP"],
+      { entrypoint: "main.py", protocol: "MCP", runtimeVersion: "PYTHON_3_14" },
+      /port \*\*8000\*\*/,
+      [/runtime-http-/, /runtime-a2a-/, /runtime-agui-/],
+    ],
+    [
+      "typescript A2A",
+      ["--language", "typescript", "--protocol", "A2A"],
+      { entrypoint: "main.js", protocol: "A2A", runtimeVersion: "NODE_22" },
+      /agent-card\.json/,
+      [/runtime-http-/, /runtime-mcp-/, /runtime-agui-/],
+    ],
+    [
+      "typescript AGUI",
+      ["--language", "typescript", "--protocol", "AGUI"],
+      { entrypoint: "main.js", protocol: "AGUI", runtimeVersion: "NODE_22" },
+      /RunAgentInput/,
+      [/runtime-http-/, /runtime-mcp-/, /runtime-a2a-/],
+    ],
+  ])(
+    "%s writes the runtime docs and a complete spec entry with starting values",
+    async (_label, flags, expected, contract, otherContracts) => {
+      const { projectRoot, cleanup } = await initProject();
+      cleanups.push(cleanup);
+      const { core, io } = await run(["add", "runtime", "--name", "search", ...flags]);
+
+      const runtime = await runtimeOf(projectRoot, "search");
+      expect(runtime).toEqual({
+        name: "search",
+        codeLocation: "app/search",
+        build: "CodeZip",
+        ...expected,
+      });
+      // No code is scaffolded and nothing is installed.
+      expect(core.projectCommands).toEqual([]);
+      const appDir = join(projectRoot, "app", "search");
+      expect((await readdir(appDir)).sort()).toEqual(["AGENTS.md", "README.md"]);
+
+      const readme = await Bun.file(join(appDir, "README.md")).text();
+      const agents = await Bun.file(join(appDir, "AGENTS.md")).text();
+      expect(readme).toMatch(contract);
+      for (const other of otherContracts) expect(readme).not.toMatch(other);
+      expect(readme).not.toContain("{{");
+      // Discovery variables use the names the CDK app sets.
+      expect(readme).toContain("`MEMORY_SEARCHMEMORY_ID`");
+      expect(readme).toContain("`AGENTCORE_GATEWAY_DOCS_GATEWAY_URL`");
+      expect(readme).toContain("`CREDENTIAL_OPENAI_KEY_NAME`");
+      expect(readme + agents).not.toMatch(/AGENTCORE_(MEMORY|CREDENTIAL)_/);
+      expect(agents).toContain("runtime `search`");
+      expect(agents).toContain(
+        `runtime-${String(expected.protocol).toLowerCase()}-protocol-contract.html`,
+      );
+      expect(readme).toContain(expected.entrypoint === "main.py" ? "main.py" : "main.ts");
+      // Points at the SDK and explains how agentcore.json follows the code.
+      expect(readme).toContain(
+        expected.entrypoint === "main.py"
+          ? "https://github.com/aws/bedrock-agentcore-sdk-python"
+          : "https://github.com/aws/bedrock-agentcore-sdk-typescript",
+      );
+      expect(readme).toContain("## How `agentcore.json` follows your code");
+      expect(readme + agents).not.toContain("CLAUDE");
+
+      expect(io.stderr()).toContain(
+        `Added runtime "search" (${flags[1] === "python" ? "Python" : "TypeScript"}, ${expected.protocol}).`,
+      );
+      expect(io.stderr()).toContain("See app/search/README.md for what it needs.");
     },
-    "agui-python-strands template preset": {
+  );
+
+  test("infrastructure flags are written to the spec entry", async () => {
+    const { projectRoot, cleanup } = await initProject();
+    cleanups.push(cleanup);
+    await run([
+      "add",
+      "runtime",
+      "--name",
+      "configured_agent",
+      "--language",
+      "python",
+      ...allInfrastructureFlags,
+    ]);
+
+    expect(await runtimeOf(projectRoot, "configured_agent")).toEqual({
+      name: "configured_agent",
+      codeLocation: "app/configured_agent",
       build: "CodeZip",
-      protocol: "AGUI",
-    },
-    "environment-python-bma template preset": {
-      build: "Container",
-      bedrockManagedAgents: true,
-      entrypoint: "lifecycle/server.py",
-      dockerfile: "Dockerfile",
+      runtimeVersion: "PYTHON_3_14",
+      entrypoint: "main.py",
       protocol: "HTTP",
-      additionalPolicies: ["bma-acr-policy.json"],
-      lifecycleConfiguration: {
-        idleRuntimeSessionTimeout: 1800,
-        maxLifetime: 28800,
-      },
-      tags: { "agentcore:template": "BedrockManagedAgents" },
-    },
-    "all infrastructure flags": {
       description: "Configured runtime",
       executionRoleArn: "arn:aws:iam::123456789012:role/MyRole",
       additionalPolicies: ["arn:aws:iam::123456789012:policy/MyPolicy"],
@@ -142,517 +215,80 @@ describe("project add runtime", () => {
       ],
       filesystemConfigurations: [{ sessionStorage: { mountPath: "/mnt/data" } }],
       tags: { team: "ml", env: "test" },
-    },
-  };
-
-  const mounts = [
-    "--network-mode",
-    "VPC",
-    "--network-config",
-    '{"subnets":["subnet-0123456789abcdef0"],"securityGroups":["sg-0123456789abcdef0"]}',
-    "--filesystem-configurations",
-    '[{"sessionStorage":{"mountPath":"/mnt/session"}},{"efsAccessPoint":{"accessPointArn":"arn:aws:elasticfilesystem:us-east-1:123456789012:access-point/fsap-0123456789abcdef0","mountPath":"/mnt/efs"}},{"s3FilesAccessPoint":{"accessPointArn":"arn:aws:s3files:us-east-1:123456789012:file-system/fs-0123456789abcdef01/access-point/fsap-0123456789abcdef1","mountPath":"/mnt/s3"}}]',
-  ];
-
-  test.each<[string, string[]]>([
-    ["default (no template) scaffolds agent-python-minimal", ["--name", "my_agent"]],
-    ["agent-python-minimal template preset", ["--name", "my_agent", ...template]],
-    [
-      "agent-python-strands template preset",
-      ["--name", "my_agent", "--template", "agent-python-strands"],
-    ],
-    [
-      "strands -container template",
-      ["--name", "my_agent", "--template", "agent-python-strands-container"],
-    ],
-    [
-      "mcp-python-fastmcp template preset",
-      ["--name", "my_mcp", "--template", "mcp-python-fastmcp"],
-    ],
-    [
-      "a2a-python-strands template preset",
-      ["--name", "my_a2a", "--template", "a2a-python-strands"],
-    ],
-    [
-      "agui-python-strands template preset",
-      ["--name", "my_agui", "--template", "agui-python-strands"],
-    ],
-    [
-      "environment-python-bma template preset",
-      ["--name", "my_bma", "--template", "environment-python-bma"],
-    ],
-    [
-      "agent-python-strands with session, EFS, and S3 mounts",
-      ["--name", "fs_agent", "--template", "agent-python-strands", ...mounts],
-    ],
-    [
-      "mcp-python-fastmcp with session, EFS, and S3 mounts",
-      ["--name", "fs_mcp", "--template", "mcp-python-fastmcp", ...mounts],
-    ],
-    [
-      "a2a-python-strands with session, EFS, and S3 mounts",
-      ["--name", "fs_a2a", "--template", "a2a-python-strands", ...mounts],
-    ],
-    ["description", ["--name", "my_agent", ...template, "--description", "A test agent"]],
-    [
-      "role-arn",
-      ["--name", "my_agent", ...template, "--role-arn", "arn:aws:iam::123456789012:role/MyRole"],
-    ],
-    [
-      "network — VPC",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--network-mode",
-        "VPC",
-        "--network-config",
-        '{"subnets":["subnet-0123456789abcdef0"],"securityGroups":["sg-0123456789abcdef0"]}',
-      ],
-    ],
-    ["network — PUBLIC", ["--name", "my_agent", ...template, "--network-mode", "PUBLIC"]],
-    [
-      "authorizer — customJWT",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--authorizer-type",
-        "CUSTOM_JWT",
-        "--authorizer-configuration",
-        '{"customJwtAuthorizer":{"discoveryUrl":"https://idp.example.com/.well-known/openid-configuration","allowedAudience":["app"]}}',
-      ],
-    ],
-    [
-      "request-header-allowlist",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--request-header-allowlist",
-        "X-Custom-Header",
-        "Authorization",
-      ],
-    ],
-    [
-      "lifecycle-configuration",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--lifecycle-configuration",
-        '{"idleRuntimeSessionTimeout":300,"maxLifetime":3600}',
-      ],
-    ],
-    [
-      "environment-variables",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--environment-variables",
-        '{"LOG_LEVEL":"debug","APP_ENV":"staging"}',
-      ],
-    ],
-    [
-      "filesystem-configurations — sessionStorage",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--filesystem-configurations",
-        '[{"sessionStorage":{"mountPath":"/mnt/data"}}]',
-      ],
-    ],
-    ["tags", ["--name", "my_agent", ...template, "--tags", '{"team":"ml","env":"prod"}']],
-    [
-      "additional-policies",
-      [
-        "--name",
-        "my_agent",
-        ...template,
-        "--additional-policies",
-        "arn:aws:iam::123456789012:policy/MyPolicy",
-      ],
-    ],
-    [
-      "all infrastructure flags",
-      ["--name", "configured_agent", ...template, ...allInfrastructureFlags],
-    ],
-  ])("%s — accepts flags", async (label, flags) => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    await run(["add", "runtime", ...flags]);
-
-    const name = flags[flags.indexOf("--name") + 1]!;
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    const runtime = spec.runtimes.find((candidate: { name: string }) => candidate.name === name);
-    expect(runtime).toMatchObject({ entrypoint: "main.py", ...expectedSpecByLabel[label] });
-    const isBma = flags.includes("environment-python-bma");
-    expect(
-      await Bun.file(
-        join(projectRoot, "app", name, isBma ? "lifecycle/server.py" : "main.py"),
-      ).exists(),
-    ).toBe(true);
-    const isContainer = flags.some(
-      (flag) => flag.endsWith("-container") || flag === "environment-python-bma",
-    );
-    expect(runtime.runtimeVersion).toBe(isContainer ? undefined : "PYTHON_3_14");
-    expect(await Bun.file(join(projectRoot, "app", name, "Dockerfile")).exists()).toBe(isContainer);
-    expect(await Bun.file(join(projectRoot, "app", name, ".dockerignore")).exists()).toBe(
-      isContainer,
-    );
+    });
   });
 
-  test("Bedrock Managed Agents defers local Python dependency setup", async () => {
+  test("an existing folder keeps the user's files; only missing docs are added", async () => {
     const { projectRoot, cleanup } = await initProject();
     cleanups.push(cleanup);
-    const { core } = await run([
-      "add",
-      "runtime",
-      "--name",
-      "my_bma",
-      "--template",
-      "environment-python-bma",
-    ]);
-
-    expect(core.projectCommands).toEqual([]);
-    expect(await Bun.file(join(projectRoot, "app", "my_bma", "pyproject.toml")).exists()).toBe(
-      true,
-    );
+    const appDir = join(projectRoot, "app", "search");
+    await mkdir(appDir, { recursive: true });
+    await writeFile(join(appDir, "main.py"), "print('mine')\n");
+    await writeFile(join(appDir, "README.md"), "# my readme\n");
+
+    const { io } = await run(["add", "runtime", "--name", "search", "--language", "python"]);
+
+    expect(await Bun.file(join(appDir, "main.py")).text()).toBe("print('mine')\n");
+    expect(await Bun.file(join(appDir, "README.md")).text()).toBe("# my readme\n");
+    expect(await Bun.file(join(appDir, "AGENTS.md")).text()).toContain("runtime `search`");
+    expect(await Bun.file(join(appDir, "CLAUDE.md")).exists()).toBe(false);
+    expect(io.stderr()).toContain("'app/search/README.md' already exists; left unchanged");
+    expect(await runtimeOf(projectRoot, "search")).toMatchObject({ codeLocation: "app/search" });
   });
 
-  test("Bedrock Managed Agents keeps infrastructure overrides and its required policy", async () => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    await run([
-      "add",
-      "runtime",
-      "--name",
-      "my_bma",
-      "--template",
-      "environment-python-bma",
-      "--lifecycle-configuration",
-      '{"idleRuntimeSessionTimeout":300,"maxLifetime":3600}',
-      "--additional-policies",
-      "custom-policy.json",
-      "--tags",
-      '{"team":"agents"}',
-    ]);
-
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    expect(spec.runtimes).toContainEqual(
-      expect.objectContaining({
-        name: "my_bma",
-        bedrockManagedAgents: true,
-        lifecycleConfiguration: {
-          idleRuntimeSessionTimeout: 300,
-          maxLifetime: 3600,
-        },
-        additionalPolicies: ["bma-acr-policy.json", "custom-policy.json"],
-        tags: { "agentcore:template": "BedrockManagedAgents", team: "agents" },
-      }),
-    );
-  });
-
-  test("Bedrock Managed Agents warns when an existing execution role needs its permissions", async () => {
-    const { projectRoot, cleanup } = await initProject();
+  test("--json reports the added runtime", async () => {
+    const { cleanup } = await initProject();
     cleanups.push(cleanup);
-    const roleArn = "arn:aws:iam::111122223333:role/ExistingBmaRole";
-
     const { io } = await run([
       "add",
       "runtime",
       "--name",
-      "my_bma",
-      "--template",
-      "environment-python-bma",
-      "--role-arn",
-      roleArn,
+      "search",
+      "--language",
+      "typescript",
       "--json",
     ]);
-
-    expect(JSON.parse(io.stdout()).notes).toEqual([
-      expect.stringContaining("AgentCore CDK cannot attach bma-acr-policy.json"),
-    ]);
-    expect(io.stderr()).not.toContain("bma-acr-policy.json");
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    expect(spec.runtimes).toContainEqual(
-      expect.objectContaining({
-        name: "my_bma",
-        bedrockManagedAgents: true,
-        executionRoleArn: roleArn,
-        additionalPolicies: ["bma-acr-policy.json"],
-      }),
-    );
-  });
-
-  test.each<[string, string[]]>([
-    ["agent-python-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
-    ["a2a-python-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
-    ["agent-python-minimal", []],
-    ["agent-python-langchain", []],
-    ["agent-typescript-vercel", []],
-    ["mcp-python-fastmcp", []],
-    ["agui-python-strands", ["SEMANTIC", "USER_PREFERENCE", "SUMMARIZATION", "EPISODIC"]],
-    ["environment-python-bma", []],
-  ])("%s ships with its pre-configured memory", async (templateName, expectedStrategies) => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    await run(["add", "runtime", "--name", "my_agent", "--template", templateName]);
-
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    const memory = (spec.memories ?? []).find(
-      (candidate: { name: string }) => candidate.name === "my_agentMemory",
-    );
-
-    if (expectedStrategies.length === 0) {
-      expect(memory).toBeUndefined();
-      return;
-    }
-
-    expect(memory).toMatchObject({ name: "my_agentMemory", eventExpiryDuration: 30 });
-    expect(memory.strategies.map(({ type }: { type: string }) => type)).toEqual(expectedStrategies);
-  });
-
-  test("escapes quotes in --model-id in the scaffolded model code", async () => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-
-    await run([
-      "add",
-      "runtime",
-      "--name",
-      "quoted",
-      "--template",
-      "agent-python-strands",
-      "--model-provider",
-      "lite_llm",
-      "--model-id",
-      'openai/we"ird',
-    ]);
-
-    const loadPy = await Bun.file(join(projectRoot, "app", "quoted", "model", "load.py")).text();
-    expect(loadPy).toContain('model_id="openai/we\\"ird"');
-  });
-
-  test("openai_compatible renders the OpenAI client against --api-base", async () => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    const apiKeyPath = join(projectRoot, "api-key.txt");
-    await Bun.write(apiKeyPath, "sk-ds");
-
-    await run([
-      "add",
-      "runtime",
-      "--name",
-      "ds_agent",
-      "--template",
-      "agent-python-strands",
-      "--model-provider",
-      "openai_compatible",
-      "--model-id",
-      "deepseek-chat",
-      "--api-key",
-      `file://${apiKeyPath}`,
-      "--api-base",
-      "https://api.deepseek.com/v1",
-    ]);
-
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    const runtime = spec.runtimes.find(
-      (candidate: { name: string }) => candidate.name === "ds_agent",
-    );
-    expect(runtime.modelProvider).toBe("OpenAICompatible");
-    expect(runtime.modelApiBase).toBeUndefined();
-    expect(spec.credentials).toContainEqual({
-      authorizerType: "ApiKeyCredentialProvider",
-      name: "ds_agentOpenAICompatibleApiKey",
+    expect(JSON.parse(io.stdout())).toMatchObject({
+      operation: "add",
+      resource: { type: "runtime", name: "search" },
     });
-    const loadModel = await Bun.file(
-      join(projectRoot, "app", "ds_agent", "model", "load.py"),
-    ).text();
-    expect(loadModel).toContain('"base_url": "https://api.deepseek.com/v1"');
   });
 
-  test("--api-base is refused with a provider other than openai_compatible", async () => {
+  test("a China region does not restrict a runtime whose code the user writes", async () => {
     const { projectRoot, cleanup } = await initProject();
     cleanups.push(cleanup);
-    const apiKeyPath = join(projectRoot, "api-key.txt");
-    await Bun.write(apiKeyPath, "sk-g");
-    await expect(
-      run([
-        "add",
-        "runtime",
-        "--name",
-        "g_agent",
-        "--template",
-        "agent-python-strands",
-        "--model-provider",
-        "gemini",
-        "--api-key",
-        `file://${apiKeyPath}`,
-        "--api-base",
-        "https://example.com/v1",
-      ]),
-    ).rejects.toThrow(/only supported with the openai_compatible model provider/);
-  });
-
-  test("openai_compatible without --api-base or --model-id is refused", async () => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    const apiKeyPath = join(projectRoot, "api-key.txt");
-    await Bun.write(apiKeyPath, "sk-ds");
-    const base = [
+    await run([
       "add",
       "runtime",
       "--name",
-      "ds_agent",
-      "--template",
-      "agent-python-strands",
-      "--model-provider",
-      "openai_compatible",
-      "--api-key",
-      `file://${apiKeyPath}`,
-    ];
-    await expect(run([...base, "--model-id", "deepseek-chat"])).rejects.toThrow(
-      /openai_compatible requires --api-base/,
-    );
-    await expect(run([...base, "--api-base", "https://api.deepseek.com/v1"])).rejects.toThrow(
-      /openai_compatible requires --model-id/,
-    );
-  });
-
-  test("agent-typescript-strands scaffolds a TypeScript agent", async () => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    await run(["add", "runtime", "--name", "my_agent", "--template", "agent-typescript-strands"]);
-
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    const runtime = spec.runtimes.find(
-      (candidate: { name: string }) => candidate.name === "my_agent",
-    );
-    expect(runtime).toMatchObject({
-      entrypoint: "main.js",
-      build: "CodeZip",
-      runtimeVersion: "NODE_22",
-    });
-    expect(await Bun.file(join(projectRoot, "app", "my_agent", "main.ts")).exists()).toBe(true);
-
-    const memory = (spec.memories ?? []).find(
-      (candidate: { name: string }) => candidate.name === "my_agentMemory",
-    );
-    expect(memory?.strategies.map(({ type }: { type: string }) => type)).toEqual([
-      "SEMANTIC",
-      "USER_PREFERENCE",
-      "SUMMARIZATION",
-      "EPISODIC",
+      "cn_agent",
+      "--language",
+      "python",
+      "--region",
+      "cn-north-1",
     ]);
+    expect(await runtimeOf(projectRoot, "cn_agent")).toMatchObject({ entrypoint: "main.py" });
   });
 
-  test("agent-typescript-vercel scaffolds a memory-free TypeScript runtime", async () => {
-    const { projectRoot, cleanup } = await initProject();
-    cleanups.push(cleanup);
-    await run(["add", "runtime", "--name", "my_agent", "--template", "agent-typescript-vercel"]);
-
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    expect(spec.runtimes).toContainEqual(
-      expect.objectContaining({
-        name: "my_agent",
-        entrypoint: "main.js",
-        build: "CodeZip",
-        runtimeVersion: "NODE_22",
-        protocol: "HTTP",
-      }),
-    );
-    expect(spec.memories ?? []).toEqual([]);
-  });
-
-  test.each<[string, string]>([
-    ["anthropic", "Anthropic"],
-    ["OpenAI", "OpenAI"],
-    ["gemini", "Gemini"],
-  ])(
-    "scaffolds agent-python-strands for --model-provider %s with an API-key credential",
-    async (flagValue, provider) => {
-      const { projectRoot, cleanup } = await initProject();
-      cleanups.push(cleanup);
-      const apiKeyPath = join(projectRoot, "api-key.txt");
-      await Bun.write(apiKeyPath, "test-api-key");
-
-      await run([
-        "add",
-        "runtime",
-        "--name",
-        "my_agent",
-        "--template",
-        "agent-python-strands",
-        "--model-provider",
-        flagValue,
-        "--api-key",
-        `file://${apiKeyPath}`,
-      ]);
-
-      const credentialName = `my_agent${provider}ApiKey`;
-      const envVarName = credentialEnvVarName(credentialName);
-
-      const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-      expect(spec.credentials).toContainEqual({
-        authorizerType: "ApiKeyCredentialProvider",
-        name: credentialName,
-      });
-
-      const envLocal = await Bun.file(join(projectRoot, "agentcore", ".env.local")).text();
-      expect(envLocal).not.toContain("test-api-key");
-      expect((await readEnvFile(join(projectRoot, "agentcore", ".env.local")))[envVarName]).toBe(
-        "test-api-key",
-      );
-    },
-  );
-
   test.each<[string, string[], string?]>([
+    ["missing --name", ["--language", "python"], "required option '--name' not specified"],
     [
-      "missing --name",
-      ["--template", "agent-python-minimal"],
-      "required option '--name' not specified",
+      "missing --language",
+      ["--name", "my_agent"],
+      "required option '--language <language>' not specified",
     ],
     [
       "deployed name over the 48-character service limit",
-      ["--name", `r${"x".repeat(28)}`],
+      ["--name", `r${"x".repeat(28)}`, "--language", "python"],
       `Runtime deployed name 'TestProject_default_r${"x".repeat(28)}' is 49 characters. The maximum is 48.`,
     ],
     [
-      "--model-provider is not valid with the a2a-python-strands template",
-      ["--name", "my_agent", "--template", "a2a-python-strands", "--model-provider", "Anthropic"],
+      "--framework requires --type import",
+      ["--name", "my_agent", "--language", "python", "--framework", "strands"],
     ],
-    [
-      "--api-key is not valid with the agent-python-minimal template",
-      ["--name", "my_agent", "--template", "agent-python-minimal", "--api-key", "secret-key"],
-    ],
-    [
-      "--model-provider is not valid with the agent-typescript-vercel template",
-      [
-        "--name",
-        "my_agent",
-        "--template",
-        "agent-typescript-vercel",
-        "--model-provider",
-        "Anthropic",
-      ],
-    ],
-    [
-      "--model-provider is not valid with the environment-python-bma template",
-      ["--name", "my_bma", "--template", "environment-python-bma", "--model-provider", "Anthropic"],
-      "--model-provider, --model-id, --api-key, and --api-base are not valid with the environment-python-bma template",
-    ],
-    [
-      "--model-provider without a template requires agent-python-strands",
-      ["--name", "my_agent", "--model-provider", "Anthropic"],
-    ],
-    ["--framework requires --type import", ["--name", "my_agent", "--framework", "strands"]],
     [
       "invalid JSON in --network-config",
-      ["--name", "my_agent", ...template, "--network-config", "{bad}"],
+      ["--name", "my_agent", "--language", "python", "--network-config", "{bad}"],
     ],
   ])("%s", async (...[_label, flags, requiredMessage]) => {
     const { cleanup } = await initProject();
@@ -661,21 +297,20 @@ describe("project add runtime", () => {
     await expectError(promise, requiredMessage ?? /./, InputValidationError);
   });
 
-  test.each(["nonsense", "bedrock-managed-agents"])(
-    "rejects the unknown --template value %s",
-    async (template) => {
-      const { projectRoot, cleanup } = await initProject();
-      cleanups.push(cleanup);
-      await expect(
-        run(["add", "runtime", "--name", "my_agent", "--template", template]),
-      ).rejects.toThrow();
-      const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-      expect(spec.runtimes ?? []).toEqual([]);
-      expect(
-        await Bun.file(join(projectRoot, "app", "my_agent", "lifecycle", "server.py")).exists(),
-      ).toBe(false);
-    },
-  );
+  test.each([
+    ["--template", "agent-python-minimal"],
+    ["--model-provider", "anthropic"],
+    ["--language", "rust"],
+    ["--protocol", "GRPC"],
+  ])("rejects %s %s and writes nothing", async (flagName, value) => {
+    const { projectRoot, cleanup } = await initProject();
+    cleanups.push(cleanup);
+    await expect(
+      run(["add", "runtime", "--name", "my_agent", "--language", "python", flagName, value]),
+    ).rejects.toThrow();
+    expect((await specOf(projectRoot)).runtimes ?? []).toEqual([]);
+    expect(await Bun.file(join(projectRoot, "app", "my_agent", "README.md")).exists()).toBe(false);
+  });
 });
 
 describe("project add runtime --type import", () => {
@@ -828,58 +463,6 @@ describe("project add runtime --type import", () => {
     expect(core.importedBedrockAgents).toEqual([]);
   });
 
-  test("with no target yet, --region cn-north-1 drops the default memory and refuses blocked providers", async () => {
-    const { projectRoot, cleanup } = await initProject({
-      flags: ["--template", "agent-python-minimal"],
-    });
-    cleanups.push(cleanup);
-    const keyFile = join(projectRoot, "key.txt");
-    await writeFile(keyFile, "sk-test");
-
-    // Blocked provider: refused before anything is written, as it is once a China target exists.
-    await expect(
-      run([
-        "add",
-        "runtime",
-        "--name",
-        "claude",
-        "--template",
-        "agent-python-strands",
-        "--model-provider",
-        "anthropic",
-        "--api-key",
-        `file://${keyFile}`,
-        "--region",
-        "cn-north-1",
-      ]),
-    ).rejects.toThrow(/not accessible from China regions/);
-
-    // Allowed provider: added, with the template's default memory dropped and the notice shown.
-    const { io } = await run([
-      "add",
-      "runtime",
-      "--name",
-      "cn_mem",
-      "--template",
-      "agent-python-strands",
-      "--model-provider",
-      "litellm",
-      "--model-id",
-      "deepseek/deepseek-chat",
-      "--api-key",
-      `file://${keyFile}`,
-      "--region",
-      "cn-north-1",
-    ]);
-    expect(io.stderr()).toContain("AgentCore Memory is not available in China regions");
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    expect(spec.memories).toEqual([]);
-    expect(spec.runtimes.map((runtime: { name: string }) => runtime.name)).toEqual([
-      "agent",
-      "cn_mem",
-    ]);
-  });
-
   test("rejects the import when --region is a China region even without a China target", async () => {
     const { cleanup } = await initProject();
     cleanups.push(cleanup);
@@ -909,14 +492,17 @@ describe("project add runtime --type import", () => {
     );
   });
 
-  test("accepts translation flags and rejects a template", async () => {
+  test("accepts translation flags and rejects --language and --protocol", async () => {
     const { cleanup } = await initProject();
     cleanups.push(cleanup);
     const core = new TestCoreClient();
     core.bedrockAgentImportPlans["A1B2C3D4E5/TSTALIASID"] = translatedImportPlan();
     await expect(run([...importArgs, "--framework", "strands"], { core })).resolves.toBeDefined();
-    await expect(run([...importArgs, "--template", "agent-python-minimal"])).rejects.toThrow(
-      /--template cannot be combined/,
+    await expect(run([...importArgs, "--language", "python"])).rejects.toThrow(
+      /--language cannot be combined/,
+    );
+    await expect(run([...importArgs, "--protocol", "MCP"])).rejects.toThrow(
+      /--protocol cannot be combined/,
     );
   });
 });
diff --git a/src/handlers/project/add/runtime/index.ts b/src/handlers/project/add/runtime/index.ts
index d96eb99053..2f8840a018 100644
--- a/src/handlers/project/add/runtime/index.ts
+++ b/src/handlers/project/add/runtime/index.ts
@@ -6,24 +6,24 @@ import { parseJsonFlag, parseTags } from "../../../utils";
 import { InputValidationError, RegionUnsupportedFeatureError } from "../../../../errors";
 import { AgentNameSchema, type EnvVar } from "../../../../projectSchemas/runtime";
 import { RuntimeAuthorizerTypeSchema } from "../../../../projectSchemas/auth";
-import { NetworkModeSchema } from "../../../../projectSchemas/constants";
-import { SourceResolver } from "../../../../io";
 import {
-  RUNTIME_TEMPLATE_SHORTCUTS,
-  RUNTIME_TEMPLATE_SHORTCUT_NAMES,
-  formatTemplateParameterHelp,
-  getDefaultMemorySpec,
-  resolveRuntimeTemplateShortcut,
-} from "../../shortcuts";
-import { ModelProviderSchema, type AddResourceInput, type ScaffoldRuntimeInput } from "../../types";
-import { RuntimeResourceConfigSchema, type ImportBedrockAgentInput } from "./types";
+  NetworkModeSchema,
+  ProtocolModeSchema,
+  type ProtocolMode,
+} from "../../../../projectSchemas/constants";
+import { getDefaultMemorySpec } from "../../shortcuts";
+import type { AddResourceInput } from "../../types";
+import {
+  RuntimeDocsConfigSchema,
+  RuntimeResourceConfigSchema,
+  type ImportBedrockAgentInput,
+} from "./types";
 import {
   importScaffoldRuntimeInput,
   resolveImportBedrockAgentInput,
 } from "../../importBedrockAgent";
 import { RegionKey } from "../../../keys";
 import { addProjectResource, requireDeployedNameFits, addDescription } from "../shared";
-import { BMA_CUSTOM_EXECUTION_ROLE_WARNING } from "../../bma";
 
 const CONFIGURATION = "Configuration:";
 const ENVIRONMENT = "Environment:";
@@ -39,22 +39,52 @@ type JsonRuntimeField =
   | "lifecycleConfiguration"
   | "filesystemConfigurations";
 
+type WithJsonFields<T> = Omit<T, JsonRuntimeField> & Partial<Record<JsonRuntimeField, unknown>>;
+
 /** A runtime resource as an entry point assembles it, before validation. */
-export type RuntimeInput = Omit<z.input<typeof RuntimeResourceConfigSchema>, JsonRuntimeField> &
-  Partial<Record<JsonRuntimeField, unknown>>;
+export type RuntimeInput =
+  | WithJsonFields<z.input<typeof RuntimeResourceConfigSchema>>
+  | WithJsonFields<z.input<typeof RuntimeDocsConfigSchema>>;
 
 /**
  * toAddRuntimeInput is the one place a runtime is validated and wrapped for
  * {@link ProjectManager.addResource}. Both the flag handler and the wizard call
- * it, so neither can accept a runtime the other would reject.
+ * it, so neither can accept a runtime the other would reject. An input with
+ * scaffoldRuntimeInput scaffolds code (`--type import`); one with a language
+ * only gets docs.
  */
 export function toAddRuntimeInput(input: RuntimeInput): AddResourceInput {
-  const result = RuntimeResourceConfigSchema.safeParse(input);
+  const result =
+    "scaffoldRuntimeInput" in input
+      ? RuntimeResourceConfigSchema.safeParse(input)
+      : RuntimeDocsConfigSchema.safeParse(input);
   if (!result.success)
     throw new InputValidationError(z.prettifyError(result.error), { cause: result.error });
   return { resourceType: "runtime", resourceConfig: result.data };
 }
 
+/** The language a `--language` value names, as the spec and templates spell it. */
+export const RUNTIME_LANGUAGES = { python: "Python", typescript: "TypeScript" } as const;
+export type RuntimeLanguageFlag = keyof typeof RUNTIME_LANGUAGES;
+
+/** What `add runtime` prints after adding a docs-only runtime. */
+export function runtimeDocsAddedMessage(
+  name: string,
+  language: "Python" | "TypeScript",
+  protocol: ProtocolMode,
+): string {
+  const folder = `app/${name}`;
+  return [
+    `Added runtime "${name}" (${language}, ${protocol}).`,
+    "",
+    "Next:",
+    `  1. Write your agent in ${folder}/. See ${folder}/README.md for what it needs.`,
+    `     Using a coding agent? Point it at ${folder}/AGENTS.md.`,
+    "  2. Run it locally:  agentcore dev",
+    "  3. Deploy it:       agentcore deploy",
+  ].join("\n");
+}
+
 export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
   createHandler({
     name: "runtime",
@@ -63,41 +93,21 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
       flag("name", "the name of the Runtime", AgentNameSchema, { group: CONFIGURATION }),
       flag(
         "type",
-        "create generates new agent code (the default); import translates a Bedrock Agent version",
+        "create sets up app/<name>/ with docs for the code you write (the default); " +
+          "import translates a Bedrock Agent version into runtime code",
         z.enum(["create", "import"]).optional(),
         { group: CONFIGURATION },
       ),
       flag(
-        "template",
-        "template for the Runtime code (default: agent-python-minimal); available templates listed below",
-        z.enum(RUNTIME_TEMPLATE_SHORTCUT_NAMES).optional(),
-        { group: CONFIGURATION, help: formatTemplateParameterHelp() },
-      ),
-      flag(
-        "model-provider",
-        "model provider for supported templates: bedrock, anthropic, open_ai (or openai), " +
-          "openai_compatible, gemini, or lite_llm (or litellm)",
-        ModelProviderSchema.optional(),
+        "language",
+        "language you will write the Runtime in: python or typescript (required with --type create)",
+        z.enum(["python", "typescript"]).optional(),
         { group: CONFIGURATION },
       ),
       flag(
-        "model-id",
-        "model id for the scaffolded Runtime code, overriding the provider's default " +
-          "(required with openai_compatible, and with litellm in China regions)",
-        z.string().min(1).optional(),
-        { group: CONFIGURATION },
-      ),
-      flag(
-        "api-key",
-        "API key for non-Bedrock providers on supported templates; '-' for stdin, 'file://path' for file",
-        z.string().optional(),
-        { group: CONFIGURATION, sensitive: true },
-      ),
-      flag(
-        "api-base",
-        "base URL of the endpoint for --model-provider openai_compatible (required with it, " +
-          "not accepted with other providers)",
-        z.string().url().optional(),
+        "protocol",
+        "protocol the Runtime serves: HTTP (default), MCP, A2A, or AGUI",
+        ProtocolModeSchema.optional(),
         { group: CONFIGURATION },
       ),
       flag("description", "an optional description of the Runtime", z.string().optional(), {
@@ -194,49 +204,29 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
       requireDeployedNameFits("Runtime", project.name, flags.name, "_", 48, deploymentTargets);
 
       const isImport = flags["type"] === "import";
-      const isTemplate = flags["template"] !== undefined;
-      const modelFlagsPresent =
-        flags["model-provider"] !== undefined ||
-        flags["model-id"] !== undefined ||
-        flags["api-key"] !== undefined ||
-        flags["api-base"] !== undefined;
 
       if (flags.framework !== undefined && !isImport) {
         throw new InputValidationError("--framework requires --type import");
       }
-
-      if (isImport) {
-        const importIncompatibleFlags = (
-          ["model-provider", "model-id", "api-key", "api-base"] as const
-        ).filter((flagName) => flags[flagName] !== undefined);
-        if (isTemplate || importIncompatibleFlags.length > 0) {
-          const offending = isTemplate ? "template" : importIncompatibleFlags[0];
-          throw new InputValidationError(
-            `--type import translates a Bedrock Agent into Python CodeZip runtime code; ` +
-              `--${offending} cannot be combined with it`,
-          );
-        }
-      }
       if (!isImport && (flags["agent-id"] !== undefined || flags["agent-alias-id"] !== undefined)) {
         throw new InputValidationError("--agent-id and --agent-alias-id require --type import");
       }
-
-      if (!isImport && modelFlagsPresent) {
-        if (!isTemplate) {
-          throw new InputValidationError(
-            "--model-provider, --model-id, --api-key, and --api-base only apply to templates that support them",
-          );
-        }
-        if (!RUNTIME_TEMPLATE_SHORTCUTS[flags.template!].supportsModelProviderOverride) {
+      if (isImport) {
+        const offending = (["language", "protocol"] as const).find(
+          (flagName) => flags[flagName] !== undefined,
+        );
+        if (offending !== undefined) {
           throw new InputValidationError(
-            `--model-provider, --model-id, --api-key, and --api-base are not valid with the ${flags.template} template`,
+            `--type import translates a Bedrock Agent into Python HTTP runtime code; ` +
+              `--${offending} cannot be combined with it`,
           );
         }
+      } else if (flags.language === undefined) {
+        throw new InputValidationError(
+          "required option '--language <language>' not specified: pass python or typescript",
+        );
       }
 
-      const source = new SourceResolver({ stdin: config.io.stdin });
-      const apiKey = await source.resolveSecret("api-key", flags["api-key"]);
-
       const runtimeName = flags.name;
       const notes: string[] = [];
 
@@ -273,28 +263,12 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
         }
       }
 
-      const scaffoldRuntimeInput: ScaffoldRuntimeInput = isImport
-        ? importScaffoldRuntimeInput(runtimeName, getDefaultMemorySpec(runtimeName))
-        : isTemplate
-          ? resolveRuntimeTemplateShortcut(flags.template!, {
-              runtimeName: flags.name,
-              modelProvider: flags["model-provider"],
-              modelId: flags["model-id"],
-              apiKey,
-              apiBase: flags["api-base"],
-            })
-          : resolveRuntimeTemplateShortcut("agent-python-minimal", { runtimeName: flags.name });
-
-      if (scaffoldRuntimeInput.framework === "bma" && flags["role-arn"] !== undefined) {
-        notes.push(BMA_CUSTOM_EXECUTION_ROLE_WARNING);
-      }
-
       const inputEnvironmentVariables = parseJsonFlag<Record<string, string>>(
         "environment-variables",
         flags["environment-variables"],
       );
 
-      const runtimeInput = {
+      const infra = {
         name: flags.name,
         description: flags.description,
         executionRoleArn: flags["role-arn"],
@@ -317,17 +291,35 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
           flags["filesystem-configurations"],
         ),
         tags: parseTags(flags["tags"]),
-        scaffoldRuntimeInput,
-        importBedrockAgent,
       };
 
+      if (isImport) {
+        await addProjectResource(
+          ctx,
+          config,
+          project,
+          toAddRuntimeInput({
+            ...infra,
+            scaffoldRuntimeInput: importScaffoldRuntimeInput(
+              runtimeName,
+              getDefaultMemorySpec(runtimeName),
+            ),
+            importBedrockAgent,
+          }),
+          `added runtime '${flags.name}' to '${project.name}'`,
+          { notes },
+        );
+        return;
+      }
+
+      const language = RUNTIME_LANGUAGES[flags.language!];
+      const protocol = flags.protocol ?? "HTTP";
       await addProjectResource(
         ctx,
         config,
         project,
-        toAddRuntimeInput(runtimeInput),
-        `added runtime '${flags.name}' to '${project.name}'`,
-        { notes },
+        toAddRuntimeInput({ ...infra, language, protocol }),
+        runtimeDocsAddedMessage(flags.name, language, protocol),
       );
     },
   });
diff --git a/src/handlers/project/add/runtime/runtime.screen.test.tsx b/src/handlers/project/add/runtime/runtime.screen.test.tsx
index d98e32fa1a..fcbe15c711 100644
--- a/src/handlers/project/add/runtime/runtime.screen.test.tsx
+++ b/src/handlers/project/add/runtime/runtime.screen.test.tsx
@@ -1,6 +1,5 @@
 import { test, expect, describe, afterEach } from "bun:test";
 import { join } from "node:path";
-import { writeFile } from "node:fs/promises";
 import { QueryClient } from "@tanstack/react-query";
 import {
   renderScreen,
@@ -22,9 +21,6 @@ import type { AppIO } from "../../../../io";
 import { createGatewayProjectTestHarness } from "../gateway-test-support";
 import { projectQueryKey } from "../../ProjectGate";
 import type { Project } from "../../types";
-import { DEFAULT_MODEL_IDS } from "../../../../projectSchemas/runtime";
-import { readEnvFile } from "../../../../io/envFile";
-import { RegionKey } from "../../../keys";
 
 const { cleanup, inProject, projectSpec, run } =
   createGatewayProjectTestHarness("add-runtime-wizard");
@@ -32,29 +28,15 @@ const { cleanup, inProject, projectSpec, run } =
 afterEach(cleanup);
 afterEach(cleanupScreens);
 
-// selectTemplate moves the choice list onto a named template rather than
-// pressing a fixed number of arrows, so adding or reordering a template does
-// not silently point this test at a different one.
-async function selectTemplate(r: RenderScreenResult, template: string): Promise<void> {
-  for (let i = 0; i < 20; i++) {
-    // The trailing space keeps a name from matching a longer one that starts
-    // with it — agent-python-strands against agent-python-strands-container.
-    if (flatFrame(r.lastFrame).includes(`● ${template} `)) return;
+// selectChoice moves a choice list onto a named row rather than pressing a
+// fixed number of arrows, so reordering the choices does not silently point a
+// test at a different one.
+async function selectChoice(r: RenderScreenResult, label: string): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    if (flatFrame(r.lastFrame).includes(`● ${label} `)) return;
     await r.press("down");
   }
-  throw new Error(`template ${template} was never selected`);
-}
-
-// templateRows returns the choice list in the order it is drawn.
-function templateRows(frame: string): string[] {
-  return (
-    frame
-      .split("\n")
-      .map((line) => line.replace(/[│┃|]/g, " ").replace(/\s+/g, " ").trim())
-      // A radio row starts with its optional focus pointer and selection marker;
-      // the stepper's markers sit mid-line.
-      .filter((line) => /^(?:❯ )?[●○] /.test(line))
-  );
+  throw new Error(`choice ${label} was never selected`);
 }
 
 async function runtimeInSpec(projectRoot: string, name: string) {
@@ -63,7 +45,7 @@ async function runtimeInSpec(projectRoot: string, name: string) {
 }
 
 describe("project add runtime wizard", () => {
-  test("collects a name and a template, then writes the runtime", async () => {
+  test("collects a name, a language, and a protocol, then writes the runtime docs", async () => {
     const projectRoot = await inProject();
     const queryClient = new QueryClient({
       defaultOptions: { queries: { retry: false, gcTime: Infinity, staleTime: Infinity } },
@@ -74,31 +56,37 @@ describe("project add runtime wizard", () => {
     await r.write("orders_agent");
     await r.press("return");
 
-    // The default template is the one the flag path scaffolds without
-    // --template, and it is the first row, so the step opens at the top of its
-    // list rather than partway down it.
-    await waitForText(r.lastFrame, "choose a template");
-    expect(templateRows(r.lastFrame()!)[0]).toStartWith("❯ ● agent-python-minimal ");
+    // Python and HTTP are the defaults, so enter twice keeps them.
+    await waitForText(r.lastFrame, "which language will you write it in?");
+    expect(flatFrame(r.lastFrame)).toContain("● python ");
+    await r.press("return");
+    await waitForText(r.lastFrame, "which protocol will it serve?");
+    expect(flatFrame(r.lastFrame)).toContain("● HTTP ");
     await r.press("return");
 
-    // The minimal template takes no model-provider override, so no model step.
     await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
-    expect(r.lastFrame()).not.toContain("choose a model provider");
     const review = flatFrame(r.lastFrame);
     expect(review).toContain("runtime orders_agent");
-    expect(review).toContain("template agent-python-minimal");
+    expect(review).toContain("language Python");
+    expect(review).toContain("protocol HTTP");
+    expect(review).toContain("entrypoint main.py");
     await r.press("return");
 
-    await waitForText(r.lastFrame, "added runtime 'orders_agent' to 'TestProject'");
+    await waitForText(r.lastFrame, 'Added runtime "orders_agent" (Python, HTTP).');
     expect(r.lastFrame()).toContain("[enter] go back");
 
-    expect(await runtimeInSpec(projectRoot, "orders_agent")).toMatchObject({
+    expect(await runtimeInSpec(projectRoot, "orders_agent")).toEqual({
+      name: "orders_agent",
       build: "CodeZip",
+      runtimeVersion: "PYTHON_3_14",
       entrypoint: "main.py",
       codeLocation: "app/orders_agent",
-      runtimeVersion: "PYTHON_3_14",
+      protocol: "HTTP",
     });
-    expect(await Bun.file(join(projectRoot, "app", "orders_agent", "main.py")).exists()).toBe(true);
+    const appDir = join(projectRoot, "app", "orders_agent");
+    expect(await Bun.file(join(appDir, "README.md")).exists()).toBe(true);
+    expect(await Bun.file(join(appDir, "AGENTS.md")).exists()).toBe(true);
+    expect(await Bun.file(join(appDir, "main.py")).exists()).toBe(false);
     expect(
       queryClient
         .getQueryData<Project>(projectQueryKey())
@@ -112,216 +100,37 @@ describe("project add runtime wizard", () => {
     r.unmount();
   });
 
-  test("scaffolds the template the user picks", async () => {
+  test("writes the language and protocol the user picks", async () => {
     const projectRoot = await inProject();
     const r = renderScreen("/agentcore/add/runtime");
 
     await waitForText(r.lastFrame, "what should this runtime be called?");
-    await r.write("packing_agent");
-    await r.press("return");
-
-    await waitForText(r.lastFrame, "choose a template");
-    await selectTemplate(r, "agent-python-strands-container");
-    await r.press("return");
-
-    // strands takes a model-provider override, so the model step follows;
-    // Bedrock with the template's default id is preselected.
-    await waitForText(r.lastFrame, "choose a model provider");
-    expect(r.lastFrame()).toContain("● bedrock");
-    await r.press("return"); // focus model id
-    await waitForText(r.lastFrame, DEFAULT_MODEL_IDS.Bedrock);
-    await r.press("return"); // accept it
-
-    await waitForFlatText(r.lastFrame, "build Container");
-    expect(flatFrame(r.lastFrame)).toContain("model provider bedrock");
+    await r.write("tools");
     await r.press("return");
 
-    await waitForText(r.lastFrame, "added runtime 'packing_agent' to 'TestProject'");
-
-    const runtime = await runtimeInSpec(projectRoot, "packing_agent");
-    expect(runtime).toMatchObject({
-      build: "Container",
-      codeLocation: "app/packing_agent",
-      modelProvider: "Bedrock",
-    });
-    // The default model id is not an override, so it is not persisted (only
-    // LiteLLM ids are, for the China deploy gate).
-    expect(runtime.modelId).toBeUndefined();
-    // The wizard does not ask for a description; --description still sets one.
-    expect(runtime.description).toBeUndefined();
-    expect(await Bun.file(join(projectRoot, "app", "packing_agent", "Dockerfile")).exists()).toBe(
-      true,
-    );
-    r.unmount();
-  });
-
-  test("an API-key provider reads the key from its file:// source, exactly like the flags", async () => {
-    const projectRoot = await inProject();
-    const keyFile = join(projectRoot, "gemini.key");
-    await writeFile(keyFile, "AIza-test-key\n");
-    const r = renderScreen("/agentcore/add/runtime");
-
-    await waitForText(r.lastFrame, "what should this runtime be called?");
-    await r.write("keyed_agent");
+    await waitForText(r.lastFrame, "which language will you write it in?");
+    await selectChoice(r, "typescript");
     await r.press("return");
-    await waitForText(r.lastFrame, "choose a template");
-    await selectTemplate(r, "agent-python-strands");
+    await waitForText(r.lastFrame, "which protocol will it serve?");
+    await selectChoice(r, "MCP");
     await r.press("return");
 
-    await waitForText(r.lastFrame, "choose a model provider");
-    await r.press("down"); // anthropic
-    await r.press("down"); // openai
-    await r.press("down"); // openai-compatible
-    await r.press("down"); // gemini
-    await waitForText(r.lastFrame, "● gemini");
-    await r.press("return"); // model id (Gemini default)
-    await waitForText(r.lastFrame, DEFAULT_MODEL_IDS.Gemini);
-    await r.press("return"); // → API key file
-    await waitForText(r.lastFrame, "API key file");
-    await r.write(`file://${keyFile}`);
+    await waitForFlatText(r.lastFrame, "entrypoint main.js");
+    expect(flatFrame(r.lastFrame)).toContain("protocol MCP");
     await r.press("return");
+    await waitForText(r.lastFrame, 'Added runtime "tools" (TypeScript, MCP).');
 
-    await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
-    const review = flatFrame(r.lastFrame);
-    expect(review).toContain("model provider gemini");
-    // The row may wrap mid-path at the frame width (CI temp paths are long), so
-    // compare with all whitespace removed.
-    expect(review.replace(/\s/g, "")).toContain(`APIkeyfile://${keyFile}`);
-    expect(review).not.toContain("AIza-test-key");
-    await r.press("return");
-    await waitForText(r.lastFrame, "added runtime 'keyed_agent' to 'TestProject'");
-
-    // Same result as `agentcore add runtime --name keyed_agent --template
-    // agent-python-strands --model-provider gemini --api-key file://…`.
-    expect(await runtimeInSpec(projectRoot, "keyed_agent")).toMatchObject({
-      modelProvider: "Gemini",
-    });
-    const spec = await projectSpec(projectRoot);
-    expect(spec.credentials).toEqual(
-      expect.arrayContaining([
-        { authorizerType: "ApiKeyCredentialProvider", name: "keyed_agentGeminiApiKey" },
-      ]),
-    );
-    expect(
-      (await readEnvFile(join(projectRoot, "agentcore", ".env.local")))
-        .AGENTCORE_CREDENTIAL_KEYED_AGENTGEMINIAPIKEY,
-    ).toBe("AIza-test-key");
-    r.unmount();
-  });
-
-  test("the model step refuses a missing API key for a provider that needs one", async () => {
-    const projectRoot = await inProject();
-    const r = renderScreen("/agentcore/add/runtime");
-
-    await waitForText(r.lastFrame, "what should this runtime be called?");
-    await r.write("nokey_agent");
-    await r.press("return");
-    await waitForText(r.lastFrame, "choose a template");
-    await selectTemplate(r, "agent-python-strands");
-    await r.press("return");
-    await waitForText(r.lastFrame, "choose a model provider");
-    await r.press("down"); // anthropic
-    await r.press("return"); // model id
-    await r.press("return"); // → API key file
-    await waitForText(r.lastFrame, "API key file");
-    await r.press("return"); // empty
-    await waitForText(r.lastFrame, "enter the API key file for anthropic");
-    expect(r.lastFrame()).not.toContain("this runtime will be added");
-    expect(await runtimeInSpec(projectRoot, "nokey_agent")).toBeUndefined();
-    r.unmount();
-  });
-
-  test("in a China region the model step starts on LiteLLM with no default model id", async () => {
-    const projectRoot = await inProject();
-    const r = renderScreen("/agentcore/add/runtime", {
-      withContext: (ctx) => ctx.withValue(RegionKey, "cn-north-1"),
-    });
-
-    await waitForText(r.lastFrame, "what should this runtime be called?");
-    await r.write("cn_agent");
-    await r.press("return");
-    await waitForText(r.lastFrame, "choose a template");
-    await selectTemplate(r, "agent-python-strands");
-    await r.press("return");
-
-    await waitForText(r.lastFrame, "choose a model provider");
-    expect(r.lastFrame()).toContain("● litellm");
-    expect(flatFrame(r.lastFrame).match(/not accessible from China[\s│]*regions/g)).toHaveLength(4);
-    await r.press("return"); // model id, empty
-    await r.press("return");
-    await waitForText(r.lastFrame, "enter a model ID for litellm");
-    await r.write("deepseek/deepseek-chat");
-    await r.press("return"); // → optional API key file
-    await r.press("return"); // skip
-    await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
-    expect(flatFrame(r.lastFrame)).toContain("model provider litellm");
-    await r.press("return");
-    await waitForText(r.lastFrame, "added runtime 'cn_agent' to 'TestProject'");
-
-    // No deployment target exists yet, so the wizard's resolved region stands
-    // in for the China gate: the LiteLLM id is persisted and the template's
-    // default memory is dropped, exactly as after a first deploy to cn-north-1.
-    expect(await runtimeInSpec(projectRoot, "cn_agent")).toMatchObject({
-      modelProvider: "LiteLLM",
-      modelId: "deepseek/deepseek-chat",
-    });
-    const spec = await Bun.file(join(projectRoot, "agentcore", "agentcore.json")).json();
-    expect(spec.memories).toEqual([]);
-    r.unmount();
-  });
-
-  test("a China deployment target shapes the model step even when the shell's region is commercial", async () => {
-    const projectRoot = await inProject();
-    await writeFile(
-      join(projectRoot, "agentcore", "aws-targets.json"),
-      JSON.stringify([{ name: "default", account: "111122223333", region: "cn-north-1" }]),
-    );
-    // The base context resolves us-east-1; the project's target decides.
-    const r = renderScreen("/agentcore/add/runtime");
-
-    await waitForText(r.lastFrame, "what should this runtime be called?");
-    await r.write("cn_target_agent");
-    await r.press("return");
-    await waitForText(r.lastFrame, "choose a template");
-    await selectTemplate(r, "agent-python-strands");
-    await r.press("return");
-
-    await waitForText(r.lastFrame, "choose a model provider");
-    expect(r.lastFrame()).toContain("● litellm");
-    expect(r.lastFrame()).not.toContain("● bedrock");
-    expect(flatFrame(r.lastFrame).match(/not accessible from China[\s│]*regions/g)).toHaveLength(4);
-    r.unmount();
-  });
-
-  test("scaffolds the Bedrock Managed Agents environment", async () => {
-    const projectRoot = await inProject();
-    const r = renderScreen("/agentcore/add/runtime");
-
-    await waitForText(r.lastFrame, "what should this runtime be called?");
-    await r.write("bma_environment");
-    await r.press("return");
-
-    await waitForText(r.lastFrame, "choose a template");
-    await selectTemplate(r, "environment-python-bma");
-    await r.press("return");
-
-    await waitForFlatText(r.lastFrame, "build Container");
-    expect(flatFrame(r.lastFrame)).toContain("template environment-python-bma");
-    await r.press("return");
-    await waitForText(r.lastFrame, "added runtime 'bma_environment' to 'TestProject'");
-
-    expect(await runtimeInSpec(projectRoot, "bma_environment")).toMatchObject({
-      build: "Container",
-      bedrockManagedAgents: true,
-      entrypoint: "lifecycle/server.py",
-      additionalPolicies: ["bma-acr-policy.json"],
-      tags: { "agentcore:template": "BedrockManagedAgents" },
+    expect(await runtimeInSpec(projectRoot, "tools")).toEqual({
+      name: "tools",
+      build: "CodeZip",
+      runtimeVersion: "NODE_22",
+      entrypoint: "main.js",
+      codeLocation: "app/tools",
+      protocol: "MCP",
     });
-    expect(
-      await Bun.file(
-        join(projectRoot, "app", "bma_environment", "lifecycle", "server.py"),
-      ).exists(),
-    ).toBe(true);
+    const readme = await Bun.file(join(projectRoot, "app", "tools", "README.md")).text();
+    expect(readme).toContain("runtime-mcp-protocol-contract.html");
+    expect(readme).toContain("main.ts");
     r.unmount();
   });
 
@@ -333,7 +142,7 @@ describe("project add runtime wizard", () => {
     await r.press("return");
 
     await waitForText(r.lastFrame, "Name is required");
-    expect(r.lastFrame()).not.toContain("choose a template");
+    expect(r.lastFrame()).not.toContain("which language will you write it in?");
     r.unmount();
   });
 
@@ -358,7 +167,7 @@ describe("project add runtime wizard", () => {
     await r.write("a".repeat(48));
     await r.press("return");
 
-    await waitForText(r.lastFrame, "choose a template");
+    await waitForText(r.lastFrame, "which language will you write it in?");
     r.unmount();
   });
 
@@ -384,7 +193,7 @@ describe("project add runtime wizard", () => {
     // Still on the name step: the value the step would submit is the value it
     // checked, so a padded name cannot reach the project spec.
     await waitForText(r.lastFrame, "Must begin with a letter");
-    expect(r.lastFrame()).not.toContain("choose a template");
+    expect(r.lastFrame()).not.toContain("which language will you write it in?");
     expect(await runtimeInSpec(projectRoot, " orders_agent ")).toBeUndefined();
     r.unmount();
   });
@@ -393,13 +202,15 @@ describe("project add runtime wizard", () => {
     const projectRoot = await inProject();
     // The name is taken, so addResource refuses it — the realistic failure, and
     // one the user can fix without starting over.
-    await run(["add", "runtime", "--name", "orders_agent"]);
+    await run(["add", "runtime", "--name", "orders_agent", "--language", "python"]);
     const r = renderScreen("/agentcore/add/runtime");
 
     await waitForText(r.lastFrame, "what should this runtime be called?");
     await r.write("orders_agent");
     await r.press("return");
-    await waitForText(r.lastFrame, "choose a template");
+    await waitForText(r.lastFrame, "which language will you write it in?");
+    await r.press("return");
+    await waitForText(r.lastFrame, "which protocol will it serve?");
     await r.press("return");
     await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
     await r.press("return");
@@ -537,6 +348,8 @@ describe("project add runtime dispatch", () => {
       "runtime",
       "--name",
       "flag_agent",
+      "--language",
+      "python",
     ]);
 
     expect(await runtimeInSpec(projectRoot, "flag_agent")).toBeDefined();
diff --git a/src/handlers/project/add/runtime/screen.tsx b/src/handlers/project/add/runtime/screen.tsx
index 4b0a6951ca..d6fd8e129e 100644
--- a/src/handlers/project/add/runtime/screen.tsx
+++ b/src/handlers/project/add/runtime/screen.tsx
@@ -4,10 +4,10 @@ import { useNavigate } from "react-router";
 import { ProjectKey } from "../../../../router";
 import { RegionKey } from "../../../keys";
 import { AgentNameSchema } from "../../../../projectSchemas/runtime";
+import type { ProtocolMode } from "../../../../projectSchemas/constants";
 import type { ScreenProps } from "../../../types";
 import type { Project } from "../../types";
-import { LoadingFrame, ProjectGate, projectQueryKey, useProjectTargets } from "../../ProjectGate";
-import { isChinaRegion } from "../../../../core/partition";
+import { ProjectGate, projectQueryKey } from "../../ProjectGate";
 import {
   ChoiceField,
   Step,
@@ -16,82 +16,64 @@ import {
   Wizard,
   type Choice,
 } from "../../../../components/wizard";
+import { docsRuntimeEntrypoint } from "../../../../core/project/templates/runtimeDocs";
 import {
-  RUNTIME_TEMPLATE_SHORTCUTS,
-  RUNTIME_TEMPLATE_SHORTCUT_NAMES,
-  resolveRuntimeTemplateShortcut,
-  type RuntimeTemplateShortcutName,
-} from "../../shortcuts";
-import { toAddRuntimeInput, type RuntimeInput } from "./index";
-import {
-  RuntimeModelField,
-  emptyRuntimeModel,
-  resolveRuntimeModelApiKey,
-  runtimeModelSummary,
-  toRuntimeModelOverrides,
-  type RuntimeModelValues,
-} from "../../RuntimeModelField";
+  RUNTIME_LANGUAGES,
+  runtimeDocsAddedMessage,
+  toAddRuntimeInput,
+  type RuntimeInput,
+  type RuntimeLanguageFlag,
+} from "./index";
 
 const BREADCRUMB = ["agentcore", "add", "runtime"];
 const DESCRIPTION = "add a Runtime to the current project";
 const ADD_MENU = "/agentcore/add";
 
-const DEFAULT_TEMPLATE: RuntimeTemplateShortcutName = "agent-python-minimal";
-
-const TEMPLATE_CHOICES: Choice<RuntimeTemplateShortcutName>[] = [
-  DEFAULT_TEMPLATE,
-  ...RUNTIME_TEMPLATE_SHORTCUT_NAMES.filter((template) => template !== DEFAULT_TEMPLATE),
-].map((template) => ({
-  value: template,
-  label: template,
-  description: RUNTIME_TEMPLATE_SHORTCUTS[template].description,
-}));
+const LANGUAGE_CHOICES: Choice<RuntimeLanguageFlag>[] = [
+  { value: "python", label: "python", description: "main.py, dependencies in pyproject.toml (uv)" },
+  {
+    value: "typescript",
+    label: "typescript",
+    description: "main.ts, dependencies in package.json (npm)",
+  },
+];
+
+const PROTOCOL_CHOICES: Choice<ProtocolMode>[] = [
+  {
+    value: "HTTP",
+    label: "HTTP",
+    description: "an agent: POST /invocations and GET /ping on 8080",
+  },
+  { value: "MCP", label: "MCP", description: "an MCP server: POST /mcp on 8000" },
+  { value: "A2A", label: "A2A", description: "an agent-to-agent server: JSON-RPC on 9000" },
+  { value: "AGUI", label: "AGUI", description: "an AG-UI agent: event stream on 8080" },
+];
 
 interface RuntimeFormValues {
   name: string;
-  template: RuntimeTemplateShortcutName;
-  // The model step's answer; only read for templates that take a
-  // model-provider override (see templateTakesModelProvider).
-  model: RuntimeModelValues;
-}
-
-// templateTakesModelProvider says whether the chosen template accepts the
-// --model-provider/--model-id/--api-key overrides; the wizard asks the model
-// step exactly when the flag path would accept those flags.
-function templateTakesModelProvider(template: RuntimeTemplateShortcutName): boolean {
-  return RUNTIME_TEMPLATE_SHORTCUTS[template].supportsModelProviderOverride;
+  language: RuntimeLanguageFlag;
+  protocol: ProtocolMode;
 }
 
 // toRuntimeInput builds the runtime the way the flag handler does for
-// `--template <t> [--model-provider … --model-id … --api-key …]`; apiKey is
-// the model step's key, already read from its file:// source.
-export function toRuntimeInput(values: RuntimeFormValues, apiKey?: string): RuntimeInput {
-  const model = templateTakesModelProvider(values.template)
-    ? toRuntimeModelOverrides(values.model)
-    : undefined;
+// `--name <n> --language <l> --protocol <p>`.
+export function toRuntimeInput(values: RuntimeFormValues): RuntimeInput {
   return {
     name: values.name,
     envVars: [],
-    scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(values.template, {
-      runtimeName: values.name,
-      ...(model && {
-        modelProvider: model.modelProvider,
-        modelId: model.modelId,
-        apiKey,
-        apiBase: model.apiBase,
-      }),
-    }),
+    language: RUNTIME_LANGUAGES[values.language],
+    protocol: values.protocol,
   };
 }
 
 function summaryOf(values: RuntimeFormValues): Record<string, string> {
-  const template = RUNTIME_TEMPLATE_SHORTCUTS[values.template];
+  const language = RUNTIME_LANGUAGES[values.language];
   return {
     runtime: values.name,
-    template: values.template,
-    language: template.language,
-    build: template.build,
-    ...(templateTakesModelProvider(values.template) && runtimeModelSummary(values.model)),
+    language,
+    protocol: values.protocol,
+    folder: `app/${values.name}/ (README.md, AGENTS.md)`,
+    entrypoint: docsRuntimeEntrypoint(language),
   };
 }
 
@@ -106,48 +88,12 @@ export function AddRuntimeScreen({ ctx, core }: ScreenProps) {
       onBack={() => navigate(ADD_MENU)}
     >
       {(project) => (
-        <AddRuntimeLoader project={project} core={core} region={ctx.value(RegionKey)} />
+        <AddRuntimeWizard project={project} core={core} region={ctx.value(RegionKey)} />
       )}
     </ProjectGate>
   );
 }
 
-// AddRuntimeLoader resolves the region the model step should reason about.
-// The China add gate keys on the project's deployment targets first and falls
-// back to the resolved region only when there are none, so the wizard reads the
-// same answer: a China target makes the model step start on a China-capable
-// provider and mark the blocked ones even when the shell's region is
-// commercial, instead of offering Bedrock and refusing at submit.
-function AddRuntimeLoader({
-  project,
-  core,
-  region,
-}: {
-  project: Project;
-  core: ScreenProps["core"];
-  region: string | undefined;
-}) {
-  const navigate = useNavigate();
-  const targets = useProjectTargets(core, project);
-
-  if (targets.data !== undefined) {
-    const chinaTarget = targets.data.find((target) => isChinaRegion(target.region));
-    return (
-      <AddRuntimeWizard project={project} core={core} region={chinaTarget?.region ?? region} />
-    );
-  }
-
-  return (
-    <LoadingFrame
-      breadcrumb={BREADCRUMB}
-      description={DESCRIPTION}
-      query={targets}
-      loadingLabel="loading deployment targets…"
-      onBack={() => navigate(ADD_MENU)}
-    />
-  );
-}
-
 function AddRuntimeWizard({
   project,
   core,
@@ -155,16 +101,15 @@ function AddRuntimeWizard({
 }: {
   project: Project;
   core: ScreenProps["core"];
-  /** The region the model step reasons about: a China deployment target's, else the command's. */
   region: string | undefined;
 }) {
   const navigate = useNavigate();
   const queryClient = useQueryClient();
-  const [values, setValues] = useState<RuntimeFormValues>(() => ({
+  const [values, setValues] = useState<RuntimeFormValues>({
     name: "",
-    template: DEFAULT_TEMPLATE,
-    model: emptyRuntimeModel(region),
-  }));
+    language: "python",
+    protocol: "HTTP",
+  });
   const set = (update: Partial<RuntimeFormValues>) =>
     setValues((current) => ({ ...current, ...update }));
 
@@ -174,21 +119,20 @@ function AddRuntimeWizard({
       description={DESCRIPTION}
       onCancel={() => navigate(ADD_MENU)}
       onSubmit={async function* () {
-        // The API key is read here, at submit, the way the flag path reads
-        // --api-key; it throws before anything is written.
-        const apiKey = templateTakesModelProvider(values.template)
-          ? await resolveRuntimeModelApiKey(toRuntimeModelOverrides(values.model))
-          : undefined;
         const updated = yield* core.projectManager.addResource(
           project,
-          toAddRuntimeInput(toRuntimeInput(values, apiKey)),
+          toAddRuntimeInput(toRuntimeInput(values)),
           { region },
         );
         queryClient.setQueryData(projectQueryKey(), updated);
         return updated;
       }}
       runningLabel={`adding runtime ${values.name}…`}
-      successLabel={`added runtime '${values.name}' to '${project.name}'`}
+      successLabel={runtimeDocsAddedMessage(
+        values.name,
+        RUNTIME_LANGUAGES[values.language],
+        values.protocol,
+      )}
       onDone={() => navigate(ADD_MENU)}
       doneLabel="go back"
     >
@@ -205,25 +149,23 @@ function AddRuntimeWizard({
         />
       </Step>
 
-      <Step stepKey="template" prompt="choose a template">
-        <ChoiceField<RuntimeTemplateShortcutName>
-          help="the agent code scaffolded into app/"
-          choices={TEMPLATE_CHOICES}
-          value={values.template}
-          onChange={(template) => set({ template })}
+      <Step stepKey="language" prompt="which language will you write it in?">
+        <ChoiceField<RuntimeLanguageFlag>
+          help="app/<name>/ gets a README.md and AGENTS.md describing what your code needs"
+          choices={LANGUAGE_CHOICES}
+          value={values.language}
+          onChange={(language) => set({ language })}
         />
       </Step>
 
-      {templateTakesModelProvider(values.template) && (
-        <Step stepKey="model" title="model provider">
-          <RuntimeModelField
-            value={values.model}
-            onChange={(model) => set({ model })}
-            region={region}
-            language={RUNTIME_TEMPLATE_SHORTCUTS[values.template].language}
-          />
-        </Step>
-      )}
+      <Step stepKey="protocol" prompt="which protocol will it serve?">
+        <ChoiceField<ProtocolMode>
+          help="the runtime contract your server implements"
+          choices={PROTOCOL_CHOICES}
+          value={values.protocol}
+          onChange={(protocol) => set({ protocol })}
+        />
+      </Step>
 
       <Step stepKey="review" prompt="this runtime will be added to agentcore.json">
         <Summary items={summaryOf(values)} />
diff --git a/src/handlers/project/add/runtime/types.ts b/src/handlers/project/add/runtime/types.ts
index d87fb3be53..4ddafc7e61 100644
--- a/src/handlers/project/add/runtime/types.ts
+++ b/src/handlers/project/add/runtime/types.ts
@@ -29,3 +29,21 @@ export const RuntimeResourceConfigSchema = RuntimeInfraConfigSchema.extend({
   importBedrockAgent: ImportBedrockAgentInputSchema.optional(),
 });
 export type RuntimeResourceConfig = z.infer<typeof RuntimeResourceConfigSchema>;
+
+/**
+ * A runtime added without code: the CLI writes README.md and AGENTS.md for the
+ * language and protocol into app/<name>/, and the user (or their coding agent)
+ * writes the code. The spec entry starts with default build settings, which
+ * dev, build, and deploy update from the code.
+ */
+export const RuntimeDocsConfigSchema = RuntimeInfraConfigSchema.extend({
+  language: z.enum(["Python", "TypeScript"]),
+});
+export type RuntimeDocsConfig = z.infer<typeof RuntimeDocsConfigSchema>;
+
+/** Whether an added runtime only gets docs (as opposed to scaffolded code). */
+export function isRuntimeDocsConfig(
+  config: RuntimeResourceConfig | RuntimeDocsConfig,
+): config is RuntimeDocsConfig {
+  return !("scaffoldRuntimeInput" in config);
+}
diff --git a/src/handlers/project/bma.ts b/src/handlers/project/bma.ts
index c229b47018..9680f47960 100644
--- a/src/handlers/project/bma.ts
+++ b/src/handlers/project/bma.ts
@@ -15,11 +15,6 @@ export function isBmaRuntime(
   );
 }
 
-export const BMA_CUSTOM_EXECUTION_ROLE_WARNING =
-  `Warning: --role-arn uses an existing execution role, so AgentCore CDK cannot attach ` +
-  `${BMA_POLICY_FILE}. Ensure the role grants bedrock-mantle:RegisterEnvironment and ` +
-  `bedrock-mantle:ConnectEnvironment before deploying.`;
-
 export const BMA_TEMPLATE_PROFILE = {
   usesModel: false,
   dependencySetup: "deferred",
diff --git a/src/handlers/project/create/index.ts b/src/handlers/project/create/index.ts
index dfc7ee1852..3d5a989c22 100644
--- a/src/handlers/project/create/index.ts
+++ b/src/handlers/project/create/index.ts
@@ -69,7 +69,7 @@ export function emptyProjectNextSteps(name: string, china: boolean): string[] {
     ...(china
       ? []
       : [["agentcore add harness", "add a config-based agent: pick a model, prompt, and tools"]]),
-    ["agentcore add runtime", "add a code-based agent from a template"],
+    ["agentcore add runtime", "add a code-based agent you write yourself"],
     [
       "agentcore add --help",
       "see everything else you can add (memory, gateways, credentials, ...)",
@@ -152,9 +152,8 @@ export const createCreateProjectHandler = (config: CreateProjectHandlerConfig) =
           error.message === chinaModelProviderRestriction(createInput.scaffoldRuntimeInput)
         ) {
           throw new RegionUnsupportedFeatureError(
-            `${error.message} 'agentcore create' takes no model flags: create the project with ` +
-              "--template empty and pass them to 'agentcore add runtime --template <template>', " +
-              "or run 'agentcore create' interactively.",
+            `${error.message} 'agentcore create' takes no model flags: run 'agentcore create' ` +
+              "interactively to choose the model provider.",
             { cause: error },
           );
         }
diff --git a/src/handlers/project/dev/index.test.ts b/src/handlers/project/dev/index.test.ts
index 0fe7088dd8..90573e0b44 100644
--- a/src/handlers/project/dev/index.test.ts
+++ b/src/handlers/project/dev/index.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { writeMigrationState } from "../../../core/project/migrate/journal";
 import {
   InternalServerException,
@@ -19,9 +19,10 @@ import {
 import type { HttpRequestHandler, PortChecker } from "../../../io";
 import { GlobalConfigAccessorKey, ProjectKey, Router, ValueContext } from "../../../router";
 import { TestCoreClient, TestGlobalConfigAccessor, testIO } from "../../../testing";
+import { ProjectStateError } from "../../../errors";
 import { JsonRendererKey } from "../../../tui";
 import { JsonKey, RegionKey } from "../../keys";
-import type { DeployProjectInput, Project } from "../types";
+import type { DeployProjectInput, Project, ProjectManager } from "../types";
 import type { V0DeployInput } from "../../../core/project/legacy/deploy";
 import { ProjectSpecSchema } from "../../../projectSchemas/project";
 import {
@@ -41,6 +42,7 @@ function runtime(name = "orders", build: ProjectRuntime["build"] = "CodeZip"): P
     protocol: "HTTP",
     entrypoint: "main.py",
     codeLocation: `app/${name}`,
+    ...(build === "CodeZip" && { runtimeVersion: "PYTHON_3_14" }),
   } as ProjectRuntime;
 }
 
@@ -123,6 +125,11 @@ type HarnessOptions = {
   loadEnvironment?: DevProjectHandlerConfig["loadDevEnvironment"];
   /** Deploy through the real project manager instead of recording deployments. */
   realDeploy?: boolean;
+  /**
+   * Replaces the build-settings sync. By default it passes the project through,
+   * since most projects here are in-memory; `"real"` uses the project manager's.
+   */
+  syncRuntimeBuilds?: "real" | ProjectManager["syncRuntimeBuilds"];
 };
 
 function harness(options: HarnessOptions = {}) {
@@ -152,6 +159,11 @@ function harness(options: HarnessOptions = {}) {
     };
   }
   projectManager.resolveTarget = async () => undefined;
+  if (options.syncRuntimeBuilds !== "real") {
+    projectManager.syncRuntimeBuilds =
+      options.syncRuntimeBuilds ??
+      (async (configuredProject) => ({ project: configuredProject, messages: [], written: false }));
+  }
   projectManager.resolveDeployedResource = async (_project, input) => {
     resolutions.push(input);
     return {
@@ -257,6 +269,73 @@ async function inspectorStatus(subject: ReturnType<typeof harness>): Promise<{ n
   return status.agents;
 }
 
+describe("project dev build settings sync", () => {
+  async function codeProject(files: Record<string, string>) {
+    const root = await mkdtemp(join(tmpdir(), "dev-sync-"));
+    for (const [path, content] of Object.entries(files)) {
+      await mkdir(dirname(join(root, path)), { recursive: true });
+      await writeFile(join(root, path), content);
+    }
+    const configured = { ...project(runtime("search")), rootPath: root };
+    await mkdir(join(root, "agentcore"), { recursive: true });
+    await writeFile(join(root, "agentcore", "agentcore.json"), JSON.stringify(configured.spec));
+    return configured;
+  }
+
+  const specOnDisk = async (root: string) =>
+    JSON.parse(await readFile(join(root, "agentcore", "agentcore.json"), "utf-8"));
+
+  test("writes the version the code asks for to agentcore.json, prints it, and runs with it", async () => {
+    const configured = await codeProject({
+      "app/search/main.py": "",
+      "app/search/pyproject.toml": '[project]\nrequires-python = ">=3.10,<3.13"\n',
+    });
+    const subject = harness({ project: configured, syncRuntimeBuilds: "real" });
+
+    await subject.run({ agent: "search" });
+
+    expect(subject.io.stderr()).toContain(
+      'search: runtimeVersion PYTHON_3_14 -> PYTHON_3_12 (requires-python ">=3.10,<3.13" in ' +
+        "app/search/pyproject.toml)",
+    );
+    expect(subject.codeZip.inputs[0]?.runtime).toMatchObject({
+      build: "CodeZip",
+      runtimeVersion: "PYTHON_3_12",
+    });
+    expect((await specOnDisk(configured.rootPath)).runtimes[0].runtimeVersion).toBe("PYTHON_3_12");
+  });
+
+  test("a Dockerfile in the code folder switches to the container runner", async () => {
+    const configured = await codeProject({ "app/search/Dockerfile": "FROM scratch\n" });
+    const subject = harness({ project: configured, syncRuntimeBuilds: "real" });
+
+    await subject.run({ agent: "search" });
+
+    expect(subject.io.stderr()).toContain(
+      "search: build CodeZip -> Container (Dockerfile in app/search)",
+    );
+    expect(subject.container.inputs[0]?.runtime).toMatchObject({
+      build: "Container",
+      dockerfile: "Dockerfile",
+    });
+    expect(subject.codeZip.inputs).toEqual([]);
+    const written = (await specOnDisk(configured.rootPath)).runtimes[0];
+    expect(written).toMatchObject({ build: "Container", dockerfile: "Dockerfile" });
+    expect(written.runtimeVersion).toBeUndefined();
+  });
+
+  test("stops before running anything when the folder is missing what the build needs", async () => {
+    const configured = await codeProject({ "app/search/README.md": "" });
+    const subject = harness({ project: configured, syncRuntimeBuilds: "real" });
+
+    await expect(subject.run({ agent: "search" })).rejects.toThrow(
+      'runtime "search": no pyproject.toml in app/search/. See app/search/README.md.',
+    );
+    expect(subject.codeZip.inputs).toEqual([]);
+    expect(subject.collector.starts).toEqual([]);
+  });
+});
+
 describe("project dev selection and dispatch", () => {
   test("loads the environment and dispatches a translated v0 runtime", async () => {
     const configuredProject = project(runtime());
@@ -609,6 +688,84 @@ describe("project dev Inspector UI mode", () => {
     await pending.catch(() => undefined);
   });
 
+  test("a reload that no longer resolves reports why and keeps the current agents", async () => {
+    let calls = 0;
+    const subject = harness({
+      reloadedRuntimes: [runtime("orders"), runtime("payments")],
+      syncRuntimeBuilds: async (configuredProject) => {
+        if (++calls > 1) {
+          throw new ProjectStateError(
+            'runtime "payments": app/payments/ does not exist. See app/payments/README.md.',
+          );
+        }
+        return { project: configuredProject, messages: [], written: false };
+      },
+    });
+    const { pending } = await runUi(subject);
+    const before = (await inspectorStatus(subject)).map((agent) => agent.name);
+
+    subject.watchers[0]!.onChange();
+    await Bun.sleep(5);
+
+    expect(subject.io.stderr()).toContain("Could not reload agents from agentcore.json:");
+    expect(subject.io.stderr()).toContain('runtime "payments": app/payments/ does not exist.');
+    expect(subject.io.stderr()).not.toContain("Reloaded agents from agentcore.json.");
+    expect((await inspectorStatus(subject)).map((agent) => agent.name)).toEqual(before);
+
+    process.emit("SIGINT", "SIGINT");
+    await pending.catch(() => undefined);
+  });
+
+  test("any reload error is reported, not only an unresolvable runtime", async () => {
+    let calls = 0;
+    const subject = harness({
+      reloadedRuntimes: [runtime("orders")],
+      syncRuntimeBuilds: async (configuredProject) => {
+        if (++calls > 1) throw new Error("EACCES: permission denied, open agentcore.json");
+        return { project: configuredProject, messages: [], written: false };
+      },
+    });
+    const { pending } = await runUi(subject);
+
+    subject.watchers[0]!.onChange();
+    await Bun.sleep(5);
+
+    expect(subject.io.stderr()).toContain(
+      "Could not reload agents from agentcore.json:\nEACCES: permission denied",
+    );
+
+    process.emit("SIGINT", "SIGINT");
+    await pending.catch(() => undefined);
+  });
+
+  test("the reload caused by the CLI's own write-back is quiet", async () => {
+    const results = [
+      { messages: [], written: false },
+      { messages: ["orders: runtimeVersion PYTHON_3_14 -> PYTHON_3_12 (...)"], written: true },
+      { messages: [], written: false },
+    ];
+    const subject = harness({
+      reloadedRuntimes: [runtime("orders")],
+      syncRuntimeBuilds: async (configuredProject) => ({
+        project: configuredProject,
+        ...results.shift()!,
+      }),
+    });
+    const { pending } = await runUi(subject);
+
+    subject.watchers[0]!.onChange(); // the user's edit: rewritten, reported
+    await Bun.sleep(5);
+    subject.watchers[0]!.onChange(); // the CLI's own write: nothing to change
+    await Bun.sleep(5);
+
+    const reloads = subject.io.stderr().split("Reloaded agents from agentcore.json.").length - 1;
+    expect(reloads).toBe(1);
+    expect(subject.io.stderr()).toContain("orders: runtimeVersion PYTHON_3_14 -> PYTHON_3_12");
+
+    process.emit("SIGINT", "SIGINT");
+    await pending.catch(() => undefined);
+  });
+
   test("--agent narrows the supervised set", async () => {
     const container = stayingRunner([{ type: "stdout", line: "support ready" }]);
     const subject = harness({
diff --git a/src/handlers/project/dev/index.ts b/src/handlers/project/dev/index.ts
index 2b69458192..e124be3ee7 100644
--- a/src/handlers/project/dev/index.ts
+++ b/src/handlers/project/dev/index.ts
@@ -12,6 +12,7 @@ import {
   AgentCoreCLIError,
   ERROR_SOURCE,
   InputValidationError,
+  DeserializationError,
   NotImplementedError,
   ResourceNotFoundError,
   SilentCLIError,
@@ -351,7 +352,6 @@ async function runRuntimeDev({
     uiPort?: number;
   };
 }): Promise<void> {
-  const { runtimes } = input;
   await withUserCancellation(
     async (signal) => {
       const json = ctx.require(JsonKey) ? ctx.require(JsonRendererKey) : undefined;
@@ -359,7 +359,7 @@ async function runRuntimeDev({
       try {
         const project = ctx.require(ProjectKey);
         const region = ctx.require(RegionKey);
-        if (runtimes.length > 1 && input.port !== undefined) {
+        if (input.runtimes.length > 1 && input.port !== undefined) {
           throw new InputValidationError(
             "--port applies to a single runtime. Use --agent to select one.",
           );
@@ -376,6 +376,19 @@ async function runRuntimeDev({
           }
         }
 
+        // Brings agentcore.json up to date with the code (build, runtimeVersion,
+        // entrypoint), and stops before anything runs when a runtime's folder is
+        // missing what its build needs.
+        const runtimeNames = input.runtimes.map(({ name }) => name);
+        const synced = await config.projectManager.syncRuntimeBuilds(project, {
+          purpose: "dev",
+          runtimeNames,
+        });
+        for (const message of synced.messages) renderStatus({ io: config.io, message, json });
+        const runtimes = synced.project.spec.runtimes.filter(({ name }) =>
+          runtimeNames.includes(name),
+        );
+
         collector = input.traces
           ? await startRuntimeTraceCollector({ config, project, runtimes, json })
           : undefined;
@@ -455,26 +468,62 @@ async function runRuntimeDev({
             supervisor,
             traces: collector?.traces,
             assets: config.inspectorAssets,
-            project: { ...project, spec: { ...project.spec, harnesses: [] } },
+            project: { ...synced.project, spec: { ...synced.project.spec, harnesses: [] } },
             selectedAgent: input.agent,
           }),
           { port: uiPort, signal },
         );
 
+        // A reload that rewrites agentcore.json triggers one more change event
+        // for the CLI's own write; that pass finds nothing to change and stays quiet.
+        let ownWritePending = false;
         const onConfigChange = async () => {
+          let reloaded: Project | undefined;
           try {
-            const reloaded = await config.projectManager.resolve({ filePath: project.rootPath });
-            if (!reloaded) return;
-            const runtimes = reloaded.spec.runtimes.filter(supportsLocalDev);
-            supervisor.setRuntimes(
-              input.agent ? runtimes.filter((runtime) => runtime.name === input.agent) : runtimes,
-            );
-            renderStatus({ io: config.io, message: "Reloaded agents from agentcore.json.", json });
-          } catch {
+            reloaded = await config.projectManager.resolve({ filePath: project.rootPath });
+          } catch (error) {
             // A half-saved config parses on the next change event.
+            if (error instanceof DeserializationError) return;
+            renderReloadError(error);
+            return;
+          }
+          if (!reloaded) return;
+          const runtimeNames = reloaded.spec.runtimes
+            .filter(supportsLocalDev)
+            .map(({ name }) => name)
+            .filter((name) => !input.agent || name === input.agent);
+          let synced: Awaited<ReturnType<typeof config.projectManager.syncRuntimeBuilds>>;
+          try {
+            synced = await config.projectManager.syncRuntimeBuilds(reloaded, {
+              purpose: "dev",
+              runtimeNames,
+            });
+          } catch (error) {
+            // A runtime that no longer resolves keeps its previous definition; say why.
+            renderReloadError(error);
+            return;
+          }
+          for (const message of synced.messages) renderStatus({ io: config.io, message, json });
+          supervisor.setRuntimes(
+            synced.project.spec.runtimes.filter(({ name }) => runtimeNames.includes(name)),
+          );
+          const quiet = ownWritePending && !synced.written && synced.messages.length === 0;
+          ownWritePending = synced.written;
+          if (!quiet) {
+            renderStatus({ io: config.io, message: "Reloaded agents from agentcore.json.", json });
           }
         };
-        config.watchFile(projectSpecPath(project.rootPath), () => void onConfigChange(), signal);
+        const renderReloadError = (error: unknown) =>
+          renderStatus({
+            io: config.io,
+            message: `Could not reload agents from agentcore.json:\n${AgentCoreCLIError.fromError(error).message}`,
+            json,
+          });
+        config.watchFile(
+          projectSpecPath(project.rootPath),
+          () => void onConfigChange().catch(() => {}),
+          signal,
+        );
 
         const url = `http://127.0.0.1:${server.port}`;
         renderStatus({ io: config.io, message: `Agent Inspector running at ${url}`, json });
diff --git a/src/handlers/project/project.test.ts b/src/handlers/project/project.test.ts
index f98d4a4ea9..3e57fb3bb4 100644
--- a/src/handlers/project/project.test.ts
+++ b/src/handlers/project/project.test.ts
@@ -114,7 +114,7 @@ describe("project create", () => {
     expect(io.stderr()).toMatch(
       /Next steps:\n  cd MyAgent\n  agentcore add harness +add a config-based agent/,
     );
-    expect(io.stderr()).toMatch(/agentcore add runtime +add a code-based agent from a template/);
+    expect(io.stderr()).toMatch(/agentcore add runtime +add a code-based agent you write yourself/);
     expect(io.stderr()).toContain("agentcore add --help");
   });
 
diff --git a/src/handlers/project/types.ts b/src/handlers/project/types.ts
index 38e75d2009..1da64a5c91 100644
--- a/src/handlers/project/types.ts
+++ b/src/handlers/project/types.ts
@@ -7,7 +7,11 @@ import { MemorySchema } from "../../projectSchemas/memory";
 import type { EvaluatorSchema, EvaluationLevel } from "../../projectSchemas/evaluator";
 import type { ProjectSpecSchema } from "../../projectSchemas/project";
 import z from "zod";
-import type { ImportBedrockAgentInput, RuntimeResourceConfig } from "./add/runtime/types";
+import type {
+  ImportBedrockAgentInput,
+  RuntimeDocsConfig,
+  RuntimeResourceConfig,
+} from "./add/runtime/types";
 import type { OnlineEvalConfigSchema } from "../../projectSchemas/online-eval-config";
 import { AgentNameSchema, BuildTypeSchema } from "../../projectSchemas/runtime";
 import { ProtocolModeSchema, RuntimeVersionSchema } from "../../projectSchemas/constants";
@@ -353,6 +357,22 @@ export type AddResourceOptions = {
   region?: string;
 };
 
+export type SyncRuntimeBuildsInput = {
+  /** dev runs a JavaScript entrypoint and installs Node dependencies itself; deploy needs both. */
+  purpose: "dev" | "deploy";
+  /** Only these runtimes; every runtime when omitted. */
+  runtimeNames?: string[];
+};
+
+export type SyncRuntimeBuildsResult = {
+  /** The project with its runtimes as now written to agentcore.json. */
+  project: Project;
+  /** What changed, then any warnings; empty when nothing changed. */
+  messages: string[];
+  /** Whether agentcore.json was rewritten. */
+  written: boolean;
+};
+
 /** Discriminated union input for {@link ProjectManager.addResource}. */
 export type AddResourceInput =
   | {
@@ -367,7 +387,7 @@ export type AddResourceInput =
     }
   | {
       resourceType: "runtime";
-      resourceConfig: RuntimeResourceConfig;
+      resourceConfig: RuntimeResourceConfig | RuntimeDocsConfig;
     }
   | {
       resourceType: "credential";
@@ -530,6 +550,17 @@ export interface ProjectManager {
   /** Compile the project's CDK app and synthesize its CloudFormation templates. */
   build(project: Project): AsyncGenerator<ProjectEvent, void>;
 
+  /**
+   * Re-derives runtime build settings (build, dockerfile, runtimeVersion,
+   * entrypoint) from each runtime's code and writes changed fields back to
+   * agentcore.json. Throws when a runtime's folder is missing what its build
+   * needs. build and deploy run it before synth; dev before starting runtimes.
+   */
+  syncRuntimeBuilds(
+    project: Project,
+    input: SyncRuntimeBuildsInput,
+  ): Promise<SyncRuntimeBuildsResult>;
+
   /** Deploy the project to one of its configured AWS targets. */
   deploy(project: Project, input: DeployProjectInput): AsyncGenerator<ProjectEvent, DeployResult>;
 

From 4697806c3e7c7f48687dcb74013526fe613f92e7 Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Thu, 15 Oct 2026 23:10:55 +0000
Subject: [PATCH 2/5] feat(add)!: infer Bedrock Agent import from --agent-id
 and drop --type

BREAKING CHANGE: `add runtime --type` is removed; import is selected by passing --agent-id.
---
 command.md                                    |  9 ++---
 docs/china-regions.md                         |  4 +-
 src/core/project/manager.test.ts              |  2 +-
 src/core/project/manager.tsx                  |  2 +-
 src/core/project/templates/runtime.test.ts    |  2 +-
 .../project/add/runtime/index.test.ts         | 39 +++++++++++++------
 src/handlers/project/add/runtime/index.ts     | 37 ++++++++----------
 src/handlers/project/importBedrockAgent.ts    |  4 +-
 8 files changed, 57 insertions(+), 42 deletions(-)

diff --git a/command.md b/command.md
index 174d99d677..b52e172569 100644
--- a/command.md
+++ b/command.md
@@ -531,8 +531,7 @@ add a Runtime to the current project
 **Options**
 
 - `--name <name>`: the name of the Runtime (required)
-- `--type <type>`: create sets up app/&lt;name&gt;/ with docs for the code you write (the default); import translates a Bedrock Agent version into runtime code
-- `--language <language>`: language you will write the Runtime in: python or typescript (required with --type create)
+- `--language <language>`: language you will write the Runtime in: python or typescript (required unless --agent-id imports a Bedrock Agent)
 - `--protocol <protocol>`: protocol the Runtime serves: HTTP (default), MCP, A2A, or AGUI
 - `--description <description>`: an optional description of the Runtime
 - `--tags <tags...>`: tags as key=value (repeatable) or JSON object
@@ -546,9 +545,9 @@ add a Runtime to the current project
 - `--authorizer-type <authorizer-type>`: inbound authorizer type (AWS\_IAM or CUSTOM\_JWT)
 - `--authorizer-configuration <authorizer-configuration>`: inbound authorizer configuration (JSON)
 - `--request-header-allowlist <request-header-allowlist...>`: request headers to pass through to the Runtime
-- `--agent-id <agent-id>`: Bedrock Agent ID to import (requires --type import)
-- `--agent-alias-id <agent-alias-id>`: Bedrock Agent Alias ID selecting the version to import; must point at a prepared version, not DRAFT (requires --type import)
-- `--framework <framework>`: agent framework for an imported Bedrock Agent: strands or langgraph (requires --type import)
+- `--agent-id <agent-id>`: Bedrock Agent ID to import; translates that agent version into runtime code instead of writing docs
+- `--agent-alias-id <agent-alias-id>`: Bedrock Agent Alias ID selecting the version to import; must point at a prepared version, not DRAFT (requires --agent-id)
+- `--framework <framework>`: agent framework for an imported Bedrock Agent: strands or langgraph (requires --agent-id)
 
 #### `agentcore add runtime-endpoint`
 
diff --git a/docs/china-regions.md b/docs/china-regions.md
index 531850a295..cda3cea947 100644
--- a/docs/china-regions.md
+++ b/docs/china-regions.md
@@ -3,8 +3,8 @@
 `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 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
diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts
index f26a43468f..1bb30b41ae 100644
--- a/src/core/project/manager.test.ts
+++ b/src/core/project/manager.test.ts
@@ -1700,7 +1700,7 @@ describe("chinaModelProviderRestriction", () => {
       MODEL_PROVIDER_RUNTIMES_CN_MESSAGE,
     );
     expect(MODEL_PROVIDER_RUNTIMES_CN_MESSAGE).toContain("takes no --model-provider override");
-    // A scaffold without template metadata (e.g. --type import) gets the same generic text.
+    // A scaffold without template metadata (e.g. a Bedrock Agent import) gets the same generic text.
     expect(
       chinaModelProviderRestriction({ ...AGENT_PYTHON_STRANDS, templateProfile: undefined }),
     ).toBe(MODEL_PROVIDER_RUNTIMES_CN_MESSAGE);
diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx
index 13e5ae7fd1..7c0dbd836f 100644
--- a/src/core/project/manager.tsx
+++ b/src/core/project/manager.tsx
@@ -163,7 +163,7 @@ function assertCdkLibraryMatches(
 
  * Shown when a runtime template hardwired to an unreachable model provider
  * targets a China (aws-cn) region and takes no --model-provider override
- * (langchain, vercel, `--type import`). Amazon Bedrock, Anthropic, OpenAI, and
+ * (langchain, vercel, a Bedrock Agent import). Amazon Bedrock, Anthropic, OpenAI, and
  * Gemini cannot be called from China regions; LiteLLM can route to a reachable
  * provider and OpenAICompatible points the OpenAI client at a reachable endpoint.
  */
diff --git a/src/core/project/templates/runtime.test.ts b/src/core/project/templates/runtime.test.ts
index 3540c9324f..c131bbcfbf 100644
--- a/src/core/project/templates/runtime.test.ts
+++ b/src/core/project/templates/runtime.test.ts
@@ -14,7 +14,7 @@ import { credentialEnvVarName } from "../../../projectSchemas/credential";
 import { readEnvFile } from "../../../io/envFile";
 
 // Runtime templates are scaffolded by `agentcore create --template` (and its
-// wizard, which adds model overrides) and by `add runtime --type import`. These
+// wizard, which adds model overrides) and by `add runtime --agent-id` (a Bedrock Agent import). These
 // tests drive the shared addResource path directly with each template.
 
 const cleanups: Array<() => Promise<void>> = [];
diff --git a/src/handlers/project/add/runtime/index.test.ts b/src/handlers/project/add/runtime/index.test.ts
index c49a8835ac..5ca406abd4 100644
--- a/src/handlers/project/add/runtime/index.test.ts
+++ b/src/handlers/project/add/runtime/index.test.ts
@@ -283,8 +283,14 @@ describe("project add runtime", () => {
       `Runtime deployed name 'TestProject_default_r${"x".repeat(28)}' is 49 characters. The maximum is 48.`,
     ],
     [
-      "--framework requires --type import",
+      "--framework requires --agent-id",
       ["--name", "my_agent", "--language", "python", "--framework", "strands"],
+      "--framework requires --agent-id",
+    ],
+    [
+      "--agent-alias-id requires --agent-id",
+      ["--name", "my_agent", "--language", "python", "--agent-alias-id", "TSTALIASID"],
+      "--agent-alias-id requires --agent-id",
     ],
     [
       "invalid JSON in --network-config",
@@ -302,6 +308,8 @@ describe("project add runtime", () => {
     ["--model-provider", "anthropic"],
     ["--language", "rust"],
     ["--protocol", "GRPC"],
+    ["--type", "create"],
+    ["--type", "import"],
   ])("rejects %s %s and writes nothing", async (flagName, value) => {
     const { projectRoot, cleanup } = await initProject();
     cleanups.push(cleanup);
@@ -313,14 +321,12 @@ describe("project add runtime", () => {
   });
 });
 
-describe("project add runtime --type import", () => {
+describe("project add runtime --agent-id (Bedrock Agent import)", () => {
   const importArgs = [
     "add",
     "runtime",
     "--name",
     "support_proxy",
-    "--type",
-    "import",
     "--agent-id",
     "A1B2C3D4E5",
     "--agent-alias-id",
@@ -476,19 +482,27 @@ describe("project add runtime --type import", () => {
     expect(core.importedBedrockAgents).toEqual([]);
   });
 
-  test("requires --agent-id and --agent-alias-id with --type import", async () => {
+  test("--agent-id alone selects the import and still needs --agent-alias-id", async () => {
     const { cleanup } = await initProject();
     cleanups.push(cleanup);
+    const core = new TestCoreClient();
     await expect(
-      run(["add", "runtime", "--name", "p", "--type", "import", "--region", "us-east-1"]),
-    ).rejects.toThrow(/requires both --agent-id and --agent-alias-id/);
+      run(["add", "runtime", "--name", "p", "--agent-id", "A1", "--region", "us-east-1"], {
+        core,
+      }),
+    ).rejects.toThrow(
+      new InputValidationError(
+        "importing a Bedrock Agent requires both --agent-id and --agent-alias-id",
+      ),
+    );
+    expect(core.importedBedrockAgents).toEqual([]);
   });
 
-  test("rejects --agent-id without --type import", async () => {
+  test("--type is no longer an option", async () => {
     const { cleanup } = await initProject();
     cleanups.push(cleanup);
-    await expect(run(["add", "runtime", "--name", "p", "--agent-id", "A1"])).rejects.toThrow(
-      /--agent-id and --agent-alias-id require --type import/,
+    await expect(run([...importArgs, "--type", "import"])).rejects.toThrow(
+      "unknown option '--type'",
     );
   });
 
@@ -499,7 +513,10 @@ describe("project add runtime --type import", () => {
     core.bedrockAgentImportPlans["A1B2C3D4E5/TSTALIASID"] = translatedImportPlan();
     await expect(run([...importArgs, "--framework", "strands"], { core })).resolves.toBeDefined();
     await expect(run([...importArgs, "--language", "python"])).rejects.toThrow(
-      /--language cannot be combined/,
+      new InputValidationError(
+        "--agent-id imports a Bedrock Agent as Python HTTP runtime code; " +
+          "--language cannot be combined with it",
+      ),
     );
     await expect(run([...importArgs, "--protocol", "MCP"])).rejects.toThrow(
       /--protocol cannot be combined/,
diff --git a/src/handlers/project/add/runtime/index.ts b/src/handlers/project/add/runtime/index.ts
index 2f8840a018..e830eb7e8d 100644
--- a/src/handlers/project/add/runtime/index.ts
+++ b/src/handlers/project/add/runtime/index.ts
@@ -50,7 +50,7 @@ export type RuntimeInput =
  * toAddRuntimeInput is the one place a runtime is validated and wrapped for
  * {@link ProjectManager.addResource}. Both the flag handler and the wizard call
  * it, so neither can accept a runtime the other would reject. An input with
- * scaffoldRuntimeInput scaffolds code (`--type import`); one with a language
+ * scaffoldRuntimeInput scaffolds code (a Bedrock Agent import); one with a language
  * only gets docs.
  */
 export function toAddRuntimeInput(input: RuntimeInput): AddResourceInput {
@@ -91,16 +91,9 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
     description: addDescription("runtime", "add a Runtime to the current project"),
     flags: [
       flag("name", "the name of the Runtime", AgentNameSchema, { group: CONFIGURATION }),
-      flag(
-        "type",
-        "create sets up app/<name>/ with docs for the code you write (the default); " +
-          "import translates a Bedrock Agent version into runtime code",
-        z.enum(["create", "import"]).optional(),
-        { group: CONFIGURATION },
-      ),
       flag(
         "language",
-        "language you will write the Runtime in: python or typescript (required with --type create)",
+        "language you will write the Runtime in: python or typescript (required unless --agent-id imports a Bedrock Agent)",
         z.enum(["python", "typescript"]).optional(),
         { group: CONFIGURATION },
       ),
@@ -180,20 +173,21 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
       ),
       flag(
         "agent-id",
-        "Bedrock Agent ID to import (requires --type import)",
+        "Bedrock Agent ID to import; translates that agent version into runtime code " +
+          "instead of writing docs",
         z.string().optional(),
         { group: BEDROCK_AGENT_IMPORT },
       ),
       flag(
         "agent-alias-id",
         "Bedrock Agent Alias ID selecting the version to import; must point at a prepared " +
-          "version, not DRAFT (requires --type import)",
+          "version, not DRAFT (requires --agent-id)",
         z.string().optional(),
         { group: BEDROCK_AGENT_IMPORT },
       ),
       flag(
         "framework",
-        "agent framework for an imported Bedrock Agent: strands or langgraph (requires --type import)",
+        "agent framework for an imported Bedrock Agent: strands or langgraph (requires --agent-id)",
         z.enum(["strands", "langgraph"]).optional(),
         { group: BEDROCK_AGENT_IMPORT },
       ),
@@ -203,13 +197,16 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
       const deploymentTargets = await config.projectManager.listTargets(project);
       requireDeployedNameFits("Runtime", project.name, flags.name, "_", 48, deploymentTargets);
 
-      const isImport = flags["type"] === "import";
+      // Passing --agent-id is what selects a Bedrock Agent import.
+      const isImport = flags["agent-id"] !== undefined;
 
-      if (flags.framework !== undefined && !isImport) {
-        throw new InputValidationError("--framework requires --type import");
-      }
-      if (!isImport && (flags["agent-id"] !== undefined || flags["agent-alias-id"] !== undefined)) {
-        throw new InputValidationError("--agent-id and --agent-alias-id require --type import");
+      if (!isImport) {
+        const offending = (["agent-alias-id", "framework"] as const).find(
+          (flagName) => flags[flagName] !== undefined,
+        );
+        if (offending !== undefined) {
+          throw new InputValidationError(`--${offending} requires --agent-id`);
+        }
       }
       if (isImport) {
         const offending = (["language", "protocol"] as const).find(
@@ -217,7 +214,7 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
         );
         if (offending !== undefined) {
           throw new InputValidationError(
-            `--type import translates a Bedrock Agent into Python HTTP runtime code; ` +
+            `--agent-id imports a Bedrock Agent as Python HTTP runtime code; ` +
               `--${offending} cannot be combined with it`,
           );
         }
@@ -241,7 +238,7 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
           isChinaRegion(ctx.require(RegionKey))
         ) {
           throw new RegionUnsupportedFeatureError(
-            "--type import translates a Bedrock Agent, and Amazon Bedrock is not available in " +
+            "--agent-id imports a Bedrock Agent, and Amazon Bedrock is not available in " +
               "China regions (cn-north-1, cn-northwest-1).",
           );
         }
diff --git a/src/handlers/project/importBedrockAgent.ts b/src/handlers/project/importBedrockAgent.ts
index 9fdcf68703..45fcc40cd4 100644
--- a/src/handlers/project/importBedrockAgent.ts
+++ b/src/handlers/project/importBedrockAgent.ts
@@ -43,7 +43,9 @@ export async function resolveImportBedrockAgentInput(
   input: ResolveImportInput,
 ): Promise<Awaited<ReturnType<CoreBedrockAgentImporter["import"]>>> {
   if (!input.agentId || !input.agentAliasId) {
-    throw new InputValidationError("--type import requires both --agent-id and --agent-alias-id");
+    throw new InputValidationError(
+      "importing a Bedrock Agent requires both --agent-id and --agent-alias-id",
+    );
   }
 
   return input.importer.import({

From 1d5067fb06476b14a22099baa72c389cc2ab1a9f Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Fri, 16 Oct 2026 18:38:25 +0000
Subject: [PATCH 3/5] fix(runtime): spell out every edit needed to go back from
 Container to CodeZip

Switching to Container removes runtimeVersion and sets dockerfile, but the
switch message, the missing-Dockerfile precheck and the runtime READMEs said
only to set "build": "CodeZip". Following that fails schema validation
(runtimeVersion required for CodeZip, dockerfile only for Container) before
sync can run, so dev/build/deploy all stop.

The messages now name every edit: set build, remove the container-only fields
the runtime has, and add a runtimeVersion. Adds a round-trip test that follows
the instructions and checks the result loads and syncs.
---
 .../templates/runtime-docs/python/README.md   |  4 +-
 .../runtime-docs/typescript/README.md         |  4 +-
 src/core/project/runtimeBuild.test.ts         | 54 +++++++++++++++++--
 src/core/project/runtimeBuild.ts              | 30 +++++++++--
 4 files changed, 82 insertions(+), 10 deletions(-)

diff --git a/src/assets/templates/runtime-docs/python/README.md b/src/assets/templates/runtime-docs/python/README.md
index 00d31ae30a..c9dd5c0f9b 100644
--- a/src/assets/templates/runtime-docs/python/README.md
+++ b/src/assets/templates/runtime-docs/python/README.md
@@ -45,7 +45,9 @@ prints anything it changed:
 - **Build type:** adding a file named exactly `Dockerfile` to this folder
   switches the runtime to a container build, and the CLI says so. It never
   switches back on its own: to return to a direct code deploy, delete the
-  Dockerfile and set `"build": "CodeZip"` in `agentcore.json`.
+  Dockerfile, then in `agentcore.json` set `"build": "CodeZip"`, remove
+  `"dockerfile"`, and add back a `"runtimeVersion"` (the CLI removed it when
+  it switched; the schema requires it for CodeZip).
 - **Python version** (CodeZip only): kept as long as `requires-python` in
   `pyproject.toml` allows it (see below).
 - **Entrypoint:** from `[tool.agentcore]` in `pyproject.toml`, if you want a
diff --git a/src/assets/templates/runtime-docs/typescript/README.md b/src/assets/templates/runtime-docs/typescript/README.md
index 6cb6a93a07..2ddb82b0de 100644
--- a/src/assets/templates/runtime-docs/typescript/README.md
+++ b/src/assets/templates/runtime-docs/typescript/README.md
@@ -46,7 +46,9 @@ the runtime in `agentcore/agentcore.json`, and prints anything it changed:
 - **Build type:** adding a file named exactly `Dockerfile` to this folder
   switches the runtime to a container build, and the CLI says so. It never
   switches back on its own: to return to a direct code deploy, delete the
-  Dockerfile and set `"build": "CodeZip"` in `agentcore.json`.
+  Dockerfile, then in `agentcore.json` set `"build": "CodeZip"`, remove
+  `"dockerfile"`, and add back a `"runtimeVersion"` (the CLI removed it when
+  it switched; the schema requires it for CodeZip).
 - **Node.js version** (CodeZip only): kept as long as `engines.node` in
   `package.json` allows it (see below).
 - **Entrypoint** (CodeZip only): AgentCore currently bundles `main.ts` at the
diff --git a/src/core/project/runtimeBuild.test.ts b/src/core/project/runtimeBuild.test.ts
index e672eda782..517b6b2378 100644
--- a/src/core/project/runtimeBuild.test.ts
+++ b/src/core/project/runtimeBuild.test.ts
@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { ProjectStateError } from "../../errors";
-import type { ProjectRuntime } from "../../projectSchemas/runtime";
+import { ProjectRuntimeSchema, type ProjectRuntime } from "../../projectSchemas/runtime";
 import { describeChange, prepareRuntimes, readTomlString, syncRuntimeBuild } from "./runtimeBuild";
 
 const roots: string[] = [];
@@ -261,8 +261,9 @@ describe("build", () => {
     ]);
     expect(describeChange("search", sync.changes[0]!)).toBe(
       "search: build CodeZip -> Container (Dockerfile in app/search). It now builds and " +
-        "deploys as a container image from that Dockerfile; to go back, delete the Dockerfile " +
-        'and set "build": "CodeZip" in agentcore.json.',
+        "deploys as a container image from that Dockerfile; to go back, delete the Dockerfile, " +
+        'then in agentcore.json set "build": "CodeZip", remove "dockerfile", and add back the ' +
+        '"runtimeVersion" removed below.',
     );
   });
 
@@ -290,12 +291,55 @@ describe("build", () => {
     expect(() => prepareRuntimes(root, [container], "deploy")).toThrow(
       new ProjectStateError(
         'runtime "search": no Dockerfile in app/search/, and agentcore.json says this is a ' +
-          'Container build. Add the Dockerfile, or set "build": "CodeZip" in agentcore.json to ' +
-          "deploy the code directly. See app/search/README.md.",
+          "Container build. Add the Dockerfile, or deploy the code directly: in agentcore.json, " +
+          'set "build": "CodeZip", remove "dockerfile", and add "runtimeVersion" (for example ' +
+          '"PYTHON_3_14"). See app/search/README.md.',
       ),
     );
   });
 
+  test("the precheck names every container-only field a runtime has to drop to go back", async () => {
+    const root = await project({ "app/search/main.py": "", "docker/": "" });
+    const container = runtime({
+      build: "Container",
+      dockerfile: "Dockerfile",
+      buildContextPath: "docker" as ProjectRuntime["buildContextPath"],
+      customDockerBuildArgs: { FOO: "bar" },
+    });
+    expect(() => prepareRuntimes(root, [container], "deploy")).toThrow(
+      new ProjectStateError(
+        'runtime "search": no Dockerfile in docker/, and agentcore.json says this is a ' +
+          "Container build. Add the Dockerfile, or deploy the code directly: in agentcore.json, " +
+          'set "build": "CodeZip", remove "dockerfile", "buildContextPath", ' +
+          '"customDockerBuildArgs", and add "runtimeVersion" (for example "PYTHON_3_14"). ' +
+          "See app/search/README.md.",
+      ),
+    );
+  });
+
+  test("following the go-back instructions yields a CodeZip runtime that loads", async () => {
+    const root = await project({
+      "app/search/Dockerfile": "FROM scratch\n",
+      "app/search/main.py": "",
+      "app/search/pyproject.toml": pyproject(">=3.10,<3.13"),
+    });
+    const container = syncRuntimeBuild(runtime(), root).runtime;
+    expect(container.build).toBe("Container");
+    await rm(join(root, "app/search/Dockerfile"));
+
+    // "build" alone is what the old message said; the schema rejects it.
+    expect(ProjectRuntimeSchema.safeParse({ ...container, build: "CodeZip" }).success).toBe(false);
+
+    const { dockerfile: _removed, ...rest } = container;
+    const reverted = ProjectRuntimeSchema.parse({
+      ...rest,
+      build: "CodeZip",
+      runtimeVersion: "PYTHON_3_14",
+    });
+    const [prepared] = prepareRuntimes(root, [reverted], "deploy").changed;
+    expect(prepared?.runtime).toMatchObject({ build: "CodeZip", runtimeVersion: "PYTHON_3_12" });
+  });
+
   test("only a file named exactly Dockerfile counts", async () => {
     const root = await project({
       "app/search/dockerfile": "FROM scratch\n",
diff --git a/src/core/project/runtimeBuild.ts b/src/core/project/runtimeBuild.ts
index a0526114b2..5397e78bac 100644
--- a/src/core/project/runtimeBuild.ts
+++ b/src/core/project/runtimeBuild.ts
@@ -43,13 +43,36 @@ export function describeChange(name: string, change: RuntimeChange): string {
   const line =
     `${name}: ${change.field} ${change.from ?? "(unset)"} -> ${change.to ?? "(removed)"} ` +
     `(${change.reason})`;
-  // Switching to a container changes how the runtime builds and deploys, so say so.
+  // Switching to a container changes how the runtime builds and deploys, so say so,
+  // and spell out every edit going back takes: the schema rejects a CodeZip runtime
+  // that still has a dockerfile or lacks a runtimeVersion, so "build" alone fails.
   return change.field === "build" && change.to === "Container"
     ? `${line}. It now builds and deploys as a container image from that Dockerfile; to go ` +
-        `back, delete the Dockerfile and set "build": "CodeZip" in agentcore.json.`
+        `back, delete the Dockerfile, then in agentcore.json set "build": "CodeZip", remove ` +
+        `"dockerfile", and add back the "runtimeVersion" removed below.`
     : line;
 }
 
+/**
+ * The agentcore.json edits that turn a Container runtime back into CodeZip. The
+ * schema rejects a CodeZip runtime with container-only fields or no runtimeVersion,
+ * and agentcore.json is validated before sync runs, so every edit has to be named.
+ */
+function codeZipRevertEdits(runtime: ProjectRuntime): string {
+  const edits = ['set "build": "CodeZip"'];
+  const containerOnly = (["dockerfile", "buildContextPath", "customDockerBuildArgs"] as const)
+    .filter((field) => runtime[field] !== undefined)
+    .map((field) => `"${field}"`);
+  if (containerOnly.length > 0) edits.push(`remove ${containerOnly.join(", ")}`);
+  if (runtime.runtimeVersion === undefined) {
+    const latest = entrypointLanguage(runtime) === "Python" ? LATEST_PYTHON : LATEST_NODE;
+    edits.push(`add "runtimeVersion" (for example "${latest}")`);
+  }
+  return edits.length <= 2
+    ? edits.join(" and ")
+    : `${edits.slice(0, -1).join(", ")}, and ${edits[edits.length - 1]}`;
+}
+
 /** Re-derives a runtime's build settings. Throws a {@link ProjectStateError} when they cannot be. */
 export function syncRuntimeBuild(runtime: ProjectRuntime, projectRoot: string): RuntimeSync {
   const next: ProjectRuntime = { ...runtime };
@@ -558,7 +581,8 @@ function runtimeProblems(
           : `no Dockerfile at ${displayPath(projectRoot, join(context, dockerfile))}`;
       problems.push(
         `${prefix} ${missing}, and agentcore.json says this is a Container build. Add the ` +
-          `Dockerfile, or set "build": "CodeZip" in agentcore.json to deploy the code directly.`,
+          `Dockerfile, or deploy the code directly: in agentcore.json, ` +
+          `${codeZipRevertEdits(runtime)}.`,
       );
     }
     if (runtime.networkMode === "VPC" && !runtime.networkConfig?.vpcId) {

From 37bb9bd8f926d6b4718eca118127f3da546e2425 Mon Sep 17 00:00:00 2001
From: notgitika <gitijh@gmail.com>
Date: Mon, 19 Oct 2026 12:42:18 -0400
Subject: [PATCH 4/5] fix(docs): make TypeScript container example ESM

---
 src/assets/templates/runtime-docs/typescript/README.md | 3 ++-
 src/handlers/project/add/runtime/index.test.ts         | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/assets/templates/runtime-docs/typescript/README.md b/src/assets/templates/runtime-docs/typescript/README.md
index 2ddb82b0de..a040b6f15a 100644
--- a/src/assets/templates/runtime-docs/typescript/README.md
+++ b/src/assets/templates/runtime-docs/typescript/README.md
@@ -284,7 +284,8 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci
 COPY . .
-RUN npx esbuild main.ts --bundle --platform=node --target=node22 --outfile=dist/main.js \
+RUN npx esbuild main.ts --bundle --platform=node --target=node22 --format=esm \
+    --packages=external --outfile=dist/main.js \
     && npm prune --omit=dev
 
 USER node
diff --git a/src/handlers/project/add/runtime/index.test.ts b/src/handlers/project/add/runtime/index.test.ts
index 5ca406abd4..b5283eeed5 100644
--- a/src/handlers/project/add/runtime/index.test.ts
+++ b/src/handlers/project/add/runtime/index.test.ts
@@ -163,6 +163,10 @@ describe("project add runtime", () => {
           : "https://github.com/aws/bedrock-agentcore-sdk-typescript",
       );
       expect(readme).toContain("## How `agentcore.json` follows your code");
+      if (expected.entrypoint === "main.js") {
+        expect(readme).toContain("--format=esm");
+        expect(readme).toContain("--packages=external");
+      }
       expect(readme + agents).not.toContain("CLAUDE");
 
       expect(io.stderr()).toContain(

From cfb79f65440938c1543ccb7bffab41253ba06a74 Mon Sep 17 00:00:00 2001
From: notgitika <gitijh@gmail.com>
Date: Mon, 19 Oct 2026 12:42:22 -0400
Subject: [PATCH 5/5] fix(runtime): parse pyproject.toml with TOML parser

---
 bun.lock                              |   3 +
 package.json                          |   1 +
 src/core/project/runtimeBuild.test.ts |  58 ++++++-----
 src/core/project/runtimeBuild.ts      | 137 ++++++++++++--------------
 4 files changed, 103 insertions(+), 96 deletions(-)

diff --git a/bun.lock b/bun.lock
index daf00c170f..6a32d6753e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -37,6 +37,7 @@
         "react-devtools-core": "^7.0.1",
         "react-router": "^8.3.0",
         "semver": "^7.8.5",
+        "smol-toml": "^1.9.1",
         "string-width": "^8.2.2",
         "terminal-size": "^4.0.1",
         "winston": "^3.19.0",
@@ -1458,6 +1459,8 @@
 
     "slice-ansi": ["slice-ansi@9.0.0", "", { "dependencies": { "ansi-styles": "^6.2.3", "is-fullwidth-code-point": "^5.1.0" } }, "sha512-SO/3iYL5S3W57LLEniscOGPZgOqZUPCx6d3dB+52B80yJ0XstzsC/eV8gnA4tM3MHDrKz+OCFSLNjswdSC+/bA=="],
 
+    "smol-toml": ["smol-toml@1.9.1", "", {}, "sha512-j7WyPdf0CJoutMzMoPLF/bVXHtKZIT9Rb4eGeEbWw8X2t5oirjPgpL+OpaENZrILYaXqYwnVH+qgUwVbl+pUJQ=="],
+
     "sonic-boom": ["sonic-boom@4.2.1", "", { "dependencies": { "atomic-sleep": "^1.0.0" } }, "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q=="],
 
     "source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
diff --git a/package.json b/package.json
index 2316c23114..2e1a2cb27f 100644
--- a/package.json
+++ b/package.json
@@ -98,6 +98,7 @@
     "react-devtools-core": "^7.0.1",
     "react-router": "^8.3.0",
     "semver": "^7.8.5",
+    "smol-toml": "^1.9.1",
     "string-width": "^8.2.2",
     "terminal-size": "^4.0.1",
     "winston": "^3.19.0",
diff --git a/src/core/project/runtimeBuild.test.ts b/src/core/project/runtimeBuild.test.ts
index 517b6b2378..47ab9452d2 100644
--- a/src/core/project/runtimeBuild.test.ts
+++ b/src/core/project/runtimeBuild.test.ts
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { ProjectStateError } from "../../errors";
 import { ProjectRuntimeSchema, type ProjectRuntime } from "../../projectSchemas/runtime";
-import { describeChange, prepareRuntimes, readTomlString, syncRuntimeBuild } from "./runtimeBuild";
+import { describeChange, prepareRuntimes, syncRuntimeBuild } from "./runtimeBuild";
 
 const roots: string[] = [];
 afterEach(() => Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true }))));
@@ -145,7 +145,7 @@ describe("runtimeVersion from requires-python", () => {
       "app/search/pyproject.toml": "[project]\nrequires-python = >=3.12\n",
     });
     expect(() => syncRuntimeBuild(runtime(), root)).toThrow(
-      "cannot parse requires-python >=3.12 in app/search/pyproject.toml",
+      "cannot parse app/search/pyproject.toml as TOML",
     );
   });
 
@@ -157,24 +157,29 @@ describe("runtimeVersion from requires-python", () => {
   });
 
   test.each([
-    ['requires-python = ">=3.12"', ">=3.12"],
-    ["requires-python = '>=3.11'", ">=3.11"],
-    ['  requires-python="==3.13.*"   # pinned', "==3.13.*"],
-    ['"requires-python" = ">=3.10"', ">=3.10"],
-  ])("reads %s", (line, expected) => {
-    expect(readTomlString(`[project]\n${line}\n`, "project", "requires-python")?.value).toBe(
-      expected,
-    );
+    ['["project"]\nrequires-python = """>=3.12,<3.13"""\n', "PYTHON_3_12"],
+    ["['project']\n'requires-python' = '''<3.12'''\n", "PYTHON_3_11"],
+  ])("reads valid TOML forms: %p", async (manifest, expected) => {
+    const root = await project({ "app/search/pyproject.toml": manifest });
+    expect(syncRuntimeBuild(runtime(), root).runtime.runtimeVersion).toBe(expected as never);
   });
 
-  test("reads a key only from its own table", () => {
-    const text =
-      '[tool.other]\nrequires-python = ">=3.10"\n\n[project]\nname = "x"\n\n[tool.uv]\n' +
-      'requires-python = ">=3.11"\n';
-    expect(readTomlString(text, "project", "requires-python")).toBeUndefined();
-    expect(
-      readTomlString(`[project]\nrequires-python = [">=3"]\n`, "project", "requires-python"),
-    ).toEqual({ raw: '[">=3"]' });
+  test("reads requires-python only from the project table", async () => {
+    const root = await project({
+      "app/search/pyproject.toml":
+        '[tool.other]\nrequires-python = ">=3.10"\n\n[project]\nname = "x"\n\n[tool.uv]\n' +
+        'requires-python = ">=3.11"\n',
+    });
+    expect(syncRuntimeBuild(runtime(), root).changes).toEqual([]);
+  });
+
+  test("a non-string requires-python is an error", async () => {
+    const root = await project({
+      "app/search/pyproject.toml": '[project]\nrequires-python = [">=3"]\n',
+    });
+    expect(() => syncRuntimeBuild(runtime(), root)).toThrow(
+      'cannot parse requires-python [">=3"] in app/search/pyproject.toml',
+    );
   });
 });
 
@@ -465,15 +470,20 @@ describe("entrypoint", () => {
     '[tool]\nagentcore.entrypoint = "server.py"\n',
     'tool.agentcore.entrypoint = "server.py"\n',
     '[tool]\nagentcore = { entrypoint = "server.py" }\n',
-  ])("warns about an agentcore entrypoint form it does not read: %p", async (toml) => {
+    '["tool"."agentcore"]\nentrypoint = """server.py"""\n',
+  ])("reads valid TOML forms for the agentcore entrypoint: %p", async (toml) => {
     const root = await project({ "app/search/pyproject.toml": toml });
     const sync = syncRuntimeBuild(runtime(), root);
-    expect(sync.runtime.entrypoint).toBe("main.py");
-    expect(sync.warnings).toEqual([
-      'runtime "search": app/search/pyproject.toml sets the agentcore entrypoint in a form the ' +
-        "CLI does not read; it is ignored. Use a [tool.agentcore] table with " +
-        'entrypoint = "main.py" on one line.',
+    expect(sync.runtime.entrypoint).toBe("server.py");
+    expect(sync.changes).toEqual([
+      {
+        field: "entrypoint",
+        from: "main.py",
+        to: "server.py",
+        reason: "[tool.agentcore] entrypoint in app/search/pyproject.toml",
+      },
     ]);
+    expect(sync.warnings).toEqual([]);
   });
 });
 
diff --git a/src/core/project/runtimeBuild.ts b/src/core/project/runtimeBuild.ts
index 5397e78bac..be74f38f3b 100644
--- a/src/core/project/runtimeBuild.ts
+++ b/src/core/project/runtimeBuild.ts
@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import semver from "semver";
+import { parse as parseToml, type TomlTableWithoutBigInt } from "smol-toml";
 import { ProjectStateError } from "../../errors";
 import {
   NodeRuntimeSchema,
@@ -97,9 +98,10 @@ export function syncRuntimeBuild(runtime: ProjectRuntime, projectRoot: string):
   // entrypoint, from the manifest for the runtime's language. package.json
   // `main` only names the CodeZip bundle; a Container image decides its own.
   const language = entrypointLanguage(runtime);
+  const pyproject = language === "Python" ? readPyproject(runtime, projectRoot) : undefined;
   const entrypoint =
     language === "Python"
-      ? pythonEntrypoint(runtime, projectRoot, warnings)
+      ? pythonEntrypoint(runtime, pyproject)
       : next.build === "CodeZip"
         ? nodeEntrypoint(runtime, projectRoot, warnings)
         : undefined;
@@ -119,7 +121,7 @@ export function syncRuntimeBuild(runtime: ProjectRuntime, projectRoot: string):
     // the constraint excludes (or none at all) is replaced, with the highest match.
     const allowed =
       language === "Python"
-        ? allowedPythonVersions(runtime, projectRoot)
+        ? allowedPythonVersions(runtime, pyproject)
         : allowedNodeVersions(runtime, projectRoot);
     if (allowed !== undefined) {
       if (next.runtimeVersion === undefined || !allowed.versions.includes(next.runtimeVersion)) {
@@ -174,42 +176,67 @@ function entrypointLanguage(runtime: ProjectRuntime): Language {
   );
 }
 
-/** `[tool.agentcore] entrypoint` from pyproject.toml, when set. */
-function pythonEntrypoint(
-  runtime: ProjectRuntime,
-  projectRoot: string,
-  warnings: string[],
-): { value: string; reason: string } | undefined {
+type ParsedPyproject = {
+  file: string;
+  toml: TomlTableWithoutBigInt;
+};
+
+function readPyproject(runtime: ProjectRuntime, projectRoot: string): ParsedPyproject | undefined {
   const manifest = findManifest("pyproject.toml", runtime, projectRoot);
   if (manifest === undefined) return undefined;
-  const text = readFileSync(manifest, "utf-8");
   const file = displayPath(projectRoot, manifest);
-  const read = readTomlString(text, "tool.agentcore", "entrypoint");
-  if (read === undefined) {
-    // Only the `[tool.agentcore]` table form is read; say so rather than ignore
-    // `tool.agentcore.entrypoint = ...` or `agentcore = { entrypoint = ... }`.
-    if (/^\s*(?:tool\s*\.\s*)?agentcore\s*(?:\.\s*entrypoint\s*=|=\s*\{)/m.test(text)) {
-      warnings.push(
-        `runtime "${runtime.name}": ${file} sets the agentcore entrypoint in a form the CLI ` +
-          `does not read; it is ignored. Use a [tool.agentcore] table with ` +
-          `entrypoint = "main.py" on one line.`,
-      );
+  try {
+    return {
+      file,
+      toml: parseToml(readFileSync(manifest, "utf-8"), { integersAsBigInt: false }),
+    };
+  } catch (error) {
+    throw new ProjectStateError(`runtime "${runtime.name}": cannot parse ${file} as TOML.`, {
+      cause: error,
+    });
+  }
+}
+
+function tomlValue(toml: TomlTableWithoutBigInt, path: string[]): unknown {
+  let current: unknown = toml;
+  for (const key of path) {
+    if (
+      current === null ||
+      typeof current !== "object" ||
+      Array.isArray(current) ||
+      !Object.hasOwn(current, key)
+    ) {
+      return undefined;
     }
-    return undefined;
+    current = (current as Record<string, unknown>)[key];
   }
-  if (read.value === "") return undefined;
-  const value = read.value;
+  return current;
+}
+
+function displayManifestValue(value: unknown): string {
+  return JSON.stringify(value) ?? String(value);
+}
+
+/** `tool.agentcore.entrypoint` from pyproject.toml, when set. */
+function pythonEntrypoint(
+  runtime: ProjectRuntime,
+  manifest: ParsedPyproject | undefined,
+): { value: string; reason: string } | undefined {
+  if (manifest === undefined) return undefined;
+  const value = tomlValue(manifest.toml, ["tool", "agentcore", "entrypoint"]);
+  if (value === undefined || value === "") return undefined;
   if (
-    value === undefined ||
+    typeof value !== "string" ||
     !EntrypointSchema.safeParse(value).success ||
     !/\.py(:|$)/.test(value)
   ) {
     throw new ProjectStateError(
-      `runtime "${runtime.name}": [tool.agentcore] entrypoint ${read.raw} in ${file} is not a ` +
-        `Python file path relative to the runtime folder (for example "main.py" or "main.py:app").`,
+      `runtime "${runtime.name}": [tool.agentcore] entrypoint ${displayManifestValue(value)} in ` +
+        `${manifest.file} is not a Python file path relative to the runtime folder ` +
+        `(for example "main.py" or "main.py:app").`,
     );
   }
-  return { value, reason: `[tool.agentcore] entrypoint in ${file}` };
+  return { value, reason: `[tool.agentcore] entrypoint in ${manifest.file}` };
 }
 
 /**
@@ -277,25 +304,20 @@ export const LATEST_NODE = NODE_VERSIONS[NODE_VERSIONS.length - 1]!.option;
 /** The highest supported Python matching requires-python, or undefined when it is not set. */
 function allowedPythonVersions(
   runtime: ProjectRuntime,
-  projectRoot: string,
+  manifest: ParsedPyproject | undefined,
 ): AllowedVersions | undefined {
-  const manifest = findManifest("pyproject.toml", runtime, projectRoot);
   if (manifest === undefined) return undefined;
-  const requiresPython = readTomlString(
-    readFileSync(manifest, "utf-8"),
-    "project",
-    "requires-python",
-  );
+  const requiresPython = tomlValue(manifest.toml, ["project", "requires-python"]);
   // An empty value says nothing, so it counts as missing.
-  if (requiresPython === undefined || requiresPython.value === "") return undefined;
+  if (requiresPython === undefined || requiresPython === "") return undefined;
 
-  const file = displayPath(projectRoot, manifest);
-  const value = requiresPython.value;
-  const clauses = value === undefined ? undefined : parseSpecifierSet(value);
-  if (value === undefined || clauses === undefined) {
+  const value = requiresPython;
+  const clauses = typeof value === "string" ? parseSpecifierSet(value) : undefined;
+  if (clauses === undefined) {
     throw new ProjectStateError(
-      `runtime "${runtime.name}": cannot parse requires-python ${requiresPython.raw} in ${file}. ` +
-        `Use a PEP 440 specifier such as ">=3.12", or set runtimeVersion in agentcore.json.`,
+      `runtime "${runtime.name}": cannot parse requires-python ${displayManifestValue(value)} in ` +
+        `${manifest.file}. Use a PEP 440 specifier such as ">=3.12", or set runtimeVersion in ` +
+        `agentcore.json.`,
     );
   }
   const versions = [...PYTHON_VERSIONS]
@@ -304,11 +326,11 @@ function allowedPythonVersions(
     .map(({ option }) => option);
   if (versions.length === 0) {
     throw new ProjectStateError(
-      `runtime "${runtime.name}": requires-python "${value}" in ${file} matches no supported ` +
-        `Python version (supported: ${PYTHON_VERSIONS.map(({ minor }) => `3.${minor}`).join(", ")}).`,
+      `runtime "${runtime.name}": requires-python "${value}" in ${manifest.file} matches no ` +
+        `supported Python version (supported: ${PYTHON_VERSIONS.map(({ minor }) => `3.${minor}`).join(", ")}).`,
     );
   }
-  return { versions, source: `requires-python "${value}" in ${file}` };
+  return { versions, source: `requires-python "${value}" in ${manifest.file}` };
 }
 
 /** The supported Node.js majors engines.node allows, or undefined when it is not set. */
@@ -416,35 +438,6 @@ export function isDirectory(path: string): boolean {
   }
 }
 
-/**
- * Reads a single-line string `key` from a TOML `[table]` with a line-based parse
- * (no TOML dependency); the key may be quoted. Returns undefined when the key
- * is absent, and no `value` (only the raw text) when it is not a string.
- */
-export function readTomlString(
-  text: string,
-  table: string,
-  key: string,
-): { value?: string; raw: string } | undefined {
-  let inTable = false;
-  // Keys here are plain identifiers ("requires-python", "entrypoint"), so no escaping.
-  const keyPattern = new RegExp(`^\\s*(?:${key}|"${key}"|'${key}')\\s*=\\s*(.*?)\\s*$`);
-  for (const line of text.split(/\r?\n/)) {
-    const header = /^\s*(\[\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(line);
-    if (header) {
-      inTable = header[1] === "[" && header[2]?.replace(/\s*\.\s*/g, ".") === table;
-      continue;
-    }
-    if (!inTable) continue;
-    const field = keyPattern.exec(line);
-    if (!field) continue;
-    const rest = field[1]!;
-    const value = /^(["'])(.*?)\1\s*(?:#.*)?$/.exec(rest);
-    return value ? { value: value[2]!.trim(), raw: `"${value[2]}"` } : { raw: rest };
-  }
-  return undefined;
-}
-
 type Clause = { operator: string; release: number[]; wildcard: boolean };
 
 /** Parses a PEP 440 specifier set (comma = AND). Returns undefined when any clause is invalid. */