From b85a06f0be28bb3ebd0c506e84becc800ce92007 Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Fri, 11 Sep 2026 17:08:54 +0000
Subject: [PATCH 1/5] feat(wizard): shared wizard shell, used by project create
 and add runtime
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds src/components/wizard: a Wizard shell that owns the step list, position,
key handling and the form → running → success | error phases, with Step and
the TextField/ChoiceField/Summary fields. Fields publish their own key hints
and own their step's input handling, so a screen only declares questions.

Migrates project create onto it (−380 lines of its own controller) and adds
the first add wizard, project add runtime: name → template → description →
review. Both paths build their input through one builder — create through
resolveScaffoldHarnessInput/resolveRuntimeTemplateShortcut as before, add
runtime through the new toAddRuntimeInput — so a value the flag path accepts
is not one a wizard rejects.

The runtime wizard scaffolds from a template; the JSON infrastructure flags,
the model provider/api-key and the Bedrock Agent import stay on the flag path.

Also: KeyValueTable grows into the space it is given, so its percentage key
cap resolves when it is laid out as a row item, and FormTextInput/
FormRadioGroup render bare when given no name or help text, since the step
already asks the question.
---
 src/components/FormRadioGroup.tsx             |  14 +-
 src/components/FormTextInput.tsx              |  12 +-
 src/components/KeyValueTable.tsx              |   7 +-
 src/components/Root.tsx                       |   5 +
 src/components/wizard/Step.tsx                |  43 ++
 src/components/wizard/Wizard.tsx              | 294 +++++++++++
 src/components/wizard/context.tsx             |  51 ++
 src/components/wizard/fields.tsx              | 251 ++++++++++
 src/components/wizard/index.ts                |  12 +
 src/components/wizard/wizard.test.tsx         | 328 ++++++++++++
 src/handlers/project/add/add.screen.test.tsx  |  73 +++
 src/handlers/project/add/index.ts             |   5 +-
 src/handlers/project/add/runtime/index.ts     |  36 +-
 .../add/runtime/runtime.screen.test.tsx       | 139 ++++++
 src/handlers/project/add/runtime/screen.tsx   | 149 ++++++
 src/handlers/project/create/screen.tsx        | 469 ++++--------------
 src/handlers/project/index.ts                 |   8 +-
 src/handlers/project/project.screen.test.tsx  |  14 +-
 18 files changed, 1508 insertions(+), 402 deletions(-)
 create mode 100644 src/components/wizard/Step.tsx
 create mode 100644 src/components/wizard/Wizard.tsx
 create mode 100644 src/components/wizard/context.tsx
 create mode 100644 src/components/wizard/fields.tsx
 create mode 100644 src/components/wizard/index.ts
 create mode 100644 src/components/wizard/wizard.test.tsx
 create mode 100644 src/handlers/project/add/add.screen.test.tsx
 create mode 100644 src/handlers/project/add/runtime/runtime.screen.test.tsx
 create mode 100644 src/handlers/project/add/runtime/screen.tsx

diff --git a/src/components/FormRadioGroup.tsx b/src/components/FormRadioGroup.tsx
index f3b5ddec6..d977b2c5a 100644
--- a/src/components/FormRadioGroup.tsx
+++ b/src/components/FormRadioGroup.tsx
@@ -21,7 +21,7 @@ export interface FormRadioGroupProps {
 // FormRadioGroup renders a column of radio rows. It is fully controlled: the
 // parent owns the focused index and the key handling that moves it.
 export function FormRadioGroup({
-  name,
+  name = "",
   helpText,
   options,
   focusedIndex,
@@ -31,10 +31,14 @@ export function FormRadioGroup({
 
   return (
     <Box flexDirection="column">
-      <Box flexDirection="column">
-        {name && <Text color={theme.colors.text}>{name}</Text>}
-        <Text color={theme.colors.muted}>{helpText}</Text>
-      </Box>
+      {/* Either row is omitted when empty, so a caller whose surrounding
+          context already asks the question renders just the options. */}
+      {(name !== "" || helpText !== "") && (
+        <Box flexDirection="column">
+          {name !== "" && <Text color={theme.colors.text}>{name}</Text>}
+          {helpText !== "" && <Text color={theme.colors.muted}>{helpText}</Text>}
+        </Box>
+      )}
       <Box
         flexDirection="column"
         paddingX={1}
diff --git a/src/components/FormTextInput.tsx b/src/components/FormTextInput.tsx
index 4c94c3153..456745ba9 100644
--- a/src/components/FormTextInput.tsx
+++ b/src/components/FormTextInput.tsx
@@ -31,10 +31,14 @@ export function FormTextInput({
 }: FormTextInputProps) {
   return (
     <Box flexDirection="column">
-      <Box flexDirection="column">
-        <Text color={theme.colors.text}>{name}</Text>
-        <Text color={theme.colors.muted}>{helpText}</Text>
-      </Box>
+      {/* Either row is omitted when empty, so a caller whose surrounding
+          context already asks the question renders just the input. */}
+      {(name !== "" || helpText !== "") && (
+        <Box flexDirection="column">
+          {name !== "" && <Text color={theme.colors.text}>{name}</Text>}
+          {helpText !== "" && <Text color={theme.colors.muted}>{helpText}</Text>}
+        </Box>
+      )}
       <Box borderStyle="round" borderColor={focused ? theme.colors.focus : theme.colors.border}>
         <TextInput
           value={value}
diff --git a/src/components/KeyValueTable.tsx b/src/components/KeyValueTable.tsx
index d4dbe49c1..1448e3bb5 100644
--- a/src/components/KeyValueTable.tsx
+++ b/src/components/KeyValueTable.tsx
@@ -13,7 +13,10 @@ export interface KeyValueTableProps {
 // legibly instead of squeezing it into the margin. The gap is inside the
 // column, so a key that fills the cap still stands clear of its value. Capped
 // by layout rather than by reading the terminal width: a resize re-lays out
-// without re-rendering, so a width computed in render would go stale.
+// without re-rendering, so a width computed in render would go stale. The table
+// grows into the space it is given for the same reason — a percentage cap needs
+// a parent whose width it can be a share of, and a table laid out as a row item
+// would otherwise be sized from its own content and wrap its keys mid-word.
 const MAX_KEY_SHARE = "50%";
 const GAP = 2;
 
@@ -23,7 +26,7 @@ export function KeyValueTable({ items }: KeyValueTableProps) {
   // Two boxes rather than one padded string, so a value that wraps continues
   // under itself, not under the key.
   return (
-    <Box flexDirection="column">
+    <Box flexDirection="column" flexGrow={1}>
       {Object.entries(items).map(([key, value]) => (
         <Box key={key}>
           <Box
diff --git a/src/components/Root.tsx b/src/components/Root.tsx
index 439056ee7..bbbf23c5b 100644
--- a/src/components/Root.tsx
+++ b/src/components/Root.tsx
@@ -118,6 +118,7 @@ import { BuildProjectScreen } from "../handlers/project/build/screen.tsx";
 import { DeployProjectScreen } from "../handlers/project/deploy/screen.tsx";
 import { ProjectCreateScreen } from "../handlers/project/create/screen.tsx";
 import { ProjectInvokePickerScreen } from "../handlers/project/invoke/screen.tsx";
+import { AddRuntimeScreen } from "../handlers/project/add/runtime/screen.tsx";
 import { ProjectStatusScreen } from "../handlers/project/status/screen.tsx";
 import { HelpScreen, RootScreen } from "../handlers/screen.tsx";
 import type { Context } from "../router";
@@ -811,6 +812,10 @@ export function Root({ path, ctx, core, queryClient }: RootProps) {
             path="agentcore/project/status"
             element={<ProjectStatusScreen ctx={ctx} core={core} />}
           />
+          <Route
+            path="agentcore/project/add/runtime"
+            element={<AddRuntimeScreen ctx={ctx} core={core} />}
+          />
           {/* Every known command without a screen of its own: a group opens its
               menu and a leaf its interactive help. Unknown routes retain the
               help-and-exit fallback. */}
diff --git a/src/components/wizard/Step.tsx b/src/components/wizard/Step.tsx
new file mode 100644
index 000000000..092dab61f
--- /dev/null
+++ b/src/components/wizard/Step.tsx
@@ -0,0 +1,43 @@
+import { isValidElement, type ReactElement, type ReactNode } from "react";
+import { Box, Text } from "ink";
+import { darkTheme } from "../ui/_core.js";
+
+const theme = darkTheme;
+
+export interface StepProps {
+  // name is the step's stable key. Position is tracked by key rather than by
+  // index because branches have different lengths: a conditional step that
+  // appears or disappears must not shift the user to a different question.
+  name: string;
+  // title labels the step in the Stepper; defaults to `name`.
+  title?: string;
+  // question is the one-line prompt shown under the Stepper. The Stepper
+  // already names the step, so the body opens with the question itself.
+  question?: string;
+  children: ReactNode;
+}
+
+// Step is one page of a <Wizard>: the stepper entry, the question line, and the
+// field that collects the answer.
+//
+// One field per step. Every field registers its own useInput and answers enter,
+// esc and the arrows itself; two fields mounted at once would both react to the
+// same keystroke. The shell has no notion of focus and is not meant to grow
+// one — a step that genuinely needs two related inputs should get a single
+// compound field that owns one useInput and manages focus internally.
+export function Step({ question, children }: StepProps) {
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      {question !== undefined && <Text color={theme.colors.muted}>{question}</Text>}
+      {children}
+    </Box>
+  );
+}
+
+// isStepElement narrows a child to a <Step>. Children.toArray already
+// drops the `false`/`null` that a `{condition && <Step/>}` branch produces, so
+// filtering with this yields exactly the steps that apply to the current
+// answers — which is how a wizard branches without a step-list useMemo.
+export function isStepElement(child: ReactNode): child is ReactElement<StepProps> {
+  return isValidElement(child) && child.type === Step;
+}
diff --git a/src/components/wizard/Wizard.tsx b/src/components/wizard/Wizard.tsx
new file mode 100644
index 000000000..754d0deae
--- /dev/null
+++ b/src/components/wizard/Wizard.tsx
@@ -0,0 +1,294 @@
+import { Children, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { Box, Text, useApp, useInput } from "ink";
+import { ErrorPanel } from "../ErrorPanel";
+import { Layout } from "../Layout";
+import { Stepper, type Step as StepperStep } from "../ui/stepper";
+import { Divider } from "../ui/divider";
+import { Spinner } from "../ui/spinner";
+import { TaskList, type Task } from "../ui/task-list";
+import { darkTheme, glyphs } from "../ui/_core.js";
+import { driveProgress, type ProgressEvent } from "../../tui/progress";
+import { isStepElement } from "./Step";
+import { WizardProvider, type KeyHint, type WizardControls } from "./context";
+
+const theme = darkTheme;
+
+// A submit either resolves once (a plain control-plane request) or streams
+// progress events (the ProjectManager's async generators). Wizard renders both.
+export type WizardSubmitResult = AsyncGenerator<ProgressEvent, unknown> | Promise<unknown>;
+
+type Phase =
+  { kind: "form" } | { kind: "running" } | { kind: "success" } | { kind: "error"; error: Error };
+
+export interface WizardProps {
+  breadcrumb: string[];
+  // description is shown dimmed after the breadcrumb; pass the command's own
+  // description so the header matches what `--help` prints.
+  description?: string;
+  // children are the <Step>s. A `{condition && <Step/>}` branch is dropped from
+  // the flow while the condition is false.
+  children: ReactNode;
+  onSubmit: () => WizardSubmitResult;
+  // onCancel runs when esc is pressed on the first step.
+  onCancel: () => void;
+  // runningLabel is the spinner label shown while onSubmit is in flight.
+  runningLabel: string;
+  // successLabel is the headline shown once onSubmit resolves.
+  successLabel: string;
+  // successHint is an optional dimmed line under successLabel.
+  successHint?: string;
+  // successNextSteps are the commands to run next, listed under successLabel —
+  // the same block ConfirmAction shows after a successful action.
+  successNextSteps?: string[];
+  // onDone runs when the success panel is acknowledged; defaults to tearing the
+  // TUI down, which is what a one-shot `project add ...` wants.
+  onDone?: () => void;
+  // onError decides what a failure does. "exit" rejects the waitUntilExit()
+  // that renderTuiAt awaits, so the error takes the normal CLI path and the
+  // process exits nonzero — right for a one-shot command. "retry" reports the
+  // message and returns to the form, right for a screen the user navigated to.
+  onError?: "exit" | "retry";
+}
+
+// Wizard is the shared shell behind every step-based flow: it derives the step
+// list from its <Step> children, owns position, key handling and the
+// form → running → success | error phases, and renders the standard
+// Layout + Stepper frame. Screens supply only the questions.
+export function Wizard({
+  breadcrumb,
+  description,
+  children,
+  onSubmit,
+  onCancel,
+  runningLabel,
+  successLabel,
+  successHint,
+  successNextSteps,
+  onDone,
+  onError = "exit",
+}: WizardProps) {
+  const { exit } = useApp();
+
+  const [phase, setPhase] = useState<Phase>({ kind: "form" });
+  const [tasks, setTasks] = useState<Task[]>([]);
+  // Fields publish their hints from an effect, which lands one paint after the
+  // first render. Seeding with the hint every field shares keeps that first
+  // frame from showing a footer with no action key in it.
+  const [hints, setHints] = useState<KeyHint[]>([{ key: "enter", label: "continue" }]);
+
+  const stepElements = useMemo(() => Children.toArray(children).filter(isStepElement), [children]);
+
+  const steps: StepperStep[] = useMemo(() => {
+    const list = stepElements.map((element) => ({
+      key: element.props.name,
+      title: element.props.title ?? element.props.name,
+    }));
+    // Position is keyed by name, so two steps sharing one would make advance()
+    // land on the first of them forever. Catch that at render time, where the
+    // author sees it, instead of as a wizard that quietly cannot move on.
+    const seen = new Set<string>();
+    for (const step of list) {
+      if (seen.has(step.key)) throw new Error(`duplicate <Step name="${step.key}">`);
+      seen.add(step.key);
+    }
+    return list;
+  }, [stepElements]);
+
+  const [stepKey, setStepKey] = useState<string>(() => steps[0]?.key ?? "");
+
+  // Position is a key, not an index, so a branch that adds or removes steps
+  // does not move the user. The clamp covers the one case a key can vanish:
+  // a branch closing while its own step is somehow still active.
+  const found = steps.findIndex((step) => step.key === stepKey);
+  const index = found === -1 ? 0 : found;
+  const activeStep = stepElements[index];
+  const isLast = index === steps.length - 1;
+
+  // Ink drains buffered keystrokes synchronously, so a second enter can arrive
+  // before the form unmounts. The ref makes submitting idempotent.
+  const submitting = useRef(false);
+
+  const submit = useCallback(async () => {
+    if (submitting.current) return;
+    submitting.current = true;
+    setPhase({ kind: "running" });
+    setTasks([]);
+    try {
+      const result = onSubmit();
+      // Same driver as create, build and deploy: driveProgress folds the stream
+      // into the Task list TaskList draws, so a wizard's steps look like every
+      // other long-running operation's — spinner on the running step, a tail of
+      // its output, ✓ once it settles.
+      if (isProgressStream(result)) await driveProgress(result, setTasks);
+      else await result;
+      setPhase({ kind: "success" });
+    } catch (error) {
+      setPhase({ kind: "error", error: toError(error) });
+    } finally {
+      submitting.current = false;
+    }
+  }, [onSubmit]);
+
+  const controls: WizardControls = useMemo(
+    () => ({
+      isLast,
+      setHints,
+      advance: () => {
+        if (isLast) {
+          void submit();
+          return;
+        }
+        const next = steps[index + 1];
+        if (next) setStepKey(next.key);
+      },
+      back: () => {
+        if (index === 0) {
+          onCancel();
+          return;
+        }
+        const previous = steps[index - 1];
+        if (previous) setStepKey(previous.key);
+      },
+    }),
+    [isLast, index, steps, submit, onCancel],
+  );
+
+  // A retry is only offered while nothing has been written yet: once a step has
+  // run, the operation is partly applied and re-submitting would fail on what
+  // it already did.
+  const retryable = onError === "retry" && tasks.length === 0;
+
+  return (
+    <Layout
+      breadcrumb={breadcrumb}
+      description={description}
+      keyHints={footerHints(phase, hints, retryable)}
+    >
+      <Box flexDirection="column">
+        {phase.kind === "form" && (
+          <>
+            <Box paddingX={1}>
+              <Stepper
+                steps={steps}
+                currentStep={steps[index]?.key ?? ""}
+                completedSteps={steps.slice(0, index).map((step) => step.key)}
+              />
+            </Box>
+            <Divider />
+            <WizardProvider value={controls}>{activeStep}</WizardProvider>
+          </>
+        )}
+
+        {phase.kind !== "form" && (
+          <Box flexDirection="column" paddingX={1}>
+            <TaskList tasks={tasks} />
+            {/* A submit that reports no steps at all — a plain request, or a
+                stream before its first step — still needs something moving. */}
+            {phase.kind === "running" && tasks.length === 0 && <Spinner label={runningLabel} />}
+            {phase.kind === "success" && (
+              <SuccessPanel
+                label={successLabel}
+                hint={successHint}
+                nextSteps={successNextSteps}
+                onContinue={onDone ?? (() => exit())}
+              />
+            )}
+            {phase.kind === "error" && onError === "exit" && <ExitOnError error={phase.error} />}
+            {phase.kind === "error" && onError === "retry" && (
+              <ErrorPanel
+                message={phase.error.message}
+                onRetry={retryable ? () => void submit() : undefined}
+                onBack={() => setPhase({ kind: "form" })}
+              />
+            )}
+          </Box>
+        )}
+      </Box>
+    </Layout>
+  );
+}
+
+// isProgressStream distinguishes an async generator from a promise. A promise
+// has no Symbol.asyncIterator, so this is a safe discriminator.
+function isProgressStream(
+  result: WizardSubmitResult,
+): result is AsyncGenerator<ProgressEvent, unknown> {
+  return (
+    result !== null &&
+    typeof result === "object" &&
+    typeof (result as AsyncIterable<ProgressEvent>)[Symbol.asyncIterator] === "function"
+  );
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+// footerHints appends the keys that mean the same thing on every step to
+// whatever the active field published.
+function footerHints(phase: Phase, fieldHints: KeyHint[], retryable: boolean): KeyHint[] {
+  if (phase.kind === "running") return [{ key: "ctrl+c", label: "quit" }];
+  if (phase.kind === "success") return [{ key: "enter", label: "continue" }];
+  if (phase.kind === "error") {
+    return [
+      ...(retryable ? [{ key: "r", label: "retry" }] : []),
+      { key: "esc", label: "back" },
+      { key: "ctrl+c", label: "quit" },
+    ];
+  }
+  return [...fieldHints, { key: "esc", label: "back" }, { key: "ctrl+c", label: "quit" }];
+}
+
+function SuccessPanel({
+  label,
+  hint,
+  nextSteps,
+  onContinue,
+}: {
+  label: string;
+  hint?: string;
+  nextSteps?: string[];
+  onContinue: () => void;
+}) {
+  useInput((_input, key) => {
+    if (key.return || key.escape) onContinue();
+  });
+
+  return (
+    <Box flexDirection="column">
+      <Text color={theme.colors.success} bold>
+        {glyphs.check} {label}
+      </Text>
+      {nextSteps !== undefined && nextSteps.length > 0 && (
+        <Box flexDirection="column" marginTop={1}>
+          <Text color={theme.colors.text}>next steps</Text>
+          {nextSteps.map((step) => (
+            <Text key={step} color={theme.colors.primary}>{`  ${step}`}</Text>
+          ))}
+        </Box>
+      )}
+      {hint !== undefined && (
+        <Box marginTop={nextSteps === undefined ? 0 : 1}>
+          <Text color={theme.colors.muted}>{hint}</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+// ExitOnError tears the TUI down through exit(error): that rejects the
+// waitUntilExit() renderTuiAt awaits, so the failure is reported by the normal
+// CLI error path instead of as a React stack trace.
+function ExitOnError({ error }: { error: Error }) {
+  const { exit } = useApp();
+
+  useEffect(() => {
+    exit(error);
+  }, [exit, error]);
+
+  return (
+    <Text color={theme.colors.error}>
+      {glyphs.cross} {error.message}
+    </Text>
+  );
+}
diff --git a/src/components/wizard/context.tsx b/src/components/wizard/context.tsx
new file mode 100644
index 000000000..daa3c4cb5
--- /dev/null
+++ b/src/components/wizard/context.tsx
@@ -0,0 +1,51 @@
+import { createContext, useContext, useEffect, useRef } from "react";
+
+export interface KeyHint {
+  key: string;
+  label: string;
+}
+
+// WizardControls is what a field needs from the wizard around it: where to go
+// next, where to go back to, and a way to tell the footer what its keys do.
+export interface WizardControls {
+  // advance moves to the next step, or submits when the active step is last.
+  advance: () => void;
+  // back steps to the previous step, or cancels out of the wizard on the first.
+  back: () => void;
+  // isLast reports whether the active step is the final one, so a field can
+  // label its enter hint "submit" rather than "continue".
+  isLast: boolean;
+  // setHints replaces the footer's action hints. Fields call it via useKeyHints.
+  setHints: (hints: KeyHint[]) => void;
+}
+
+const WizardContext = createContext<WizardControls | null>(null);
+
+export const WizardProvider = WizardContext.Provider;
+
+export function useWizard(): WizardControls {
+  const controls = useContext(WizardContext);
+  if (!controls) {
+    throw new Error("wizard fields must be rendered inside a <Wizard>");
+  }
+  return controls;
+}
+
+// useKeyHints publishes the active field's footer hints. Each field declares
+// what its own keys do, so <Wizard> never has to switch on step kind the way
+// the hand-written wizards' hintsFor() does.
+export function useKeyHints(hints: KeyHint[]): void {
+  const { setHints } = useWizard();
+
+  // The caller passes a fresh array literal on every render, so the effect
+  // runs every render — but publishes only when the content changed. Publishing
+  // the array itself unconditionally would re-render, publish, and re-render
+  // again forever; the ref remembers what the footer already shows.
+  const published = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    const signature = hints.map((hint) => `${hint.key}:${hint.label}`).join("|");
+    if (published.current === signature) return;
+    published.current = signature;
+    setHints(hints);
+  }, [hints, setHints]);
+}
diff --git a/src/components/wizard/fields.tsx b/src/components/wizard/fields.tsx
new file mode 100644
index 000000000..2bf57b3d2
--- /dev/null
+++ b/src/components/wizard/fields.tsx
@@ -0,0 +1,251 @@
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import type z from "zod";
+import { FormTextInput } from "../FormTextInput";
+import { FormRadioGroup } from "../FormRadioGroup";
+import { KeyValueTable } from "../KeyValueTable";
+import { darkTheme } from "../ui/_core.js";
+import { useKeyHints, useWizard } from "./context";
+
+const theme = darkTheme;
+
+// Every field owns the key handling for its own step — esc goes back, enter
+// advances, arrows move — so a screen never writes that boilerplate again.
+
+// firstIssue renders the schema's own message, so the wizard rejects exactly
+// what the flag-driven path rejects and says the same thing about it. The issue
+// path is prefixed when there is one: for a nested value — a component inside a
+// components map, say — "expected object, received string" alone does not say
+// which key is wrong.
+function firstIssue(schema: z.ZodType, value: unknown): string | undefined {
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return undefined;
+  const issue = parsed.error.issues[0];
+  if (!issue) return "invalid value";
+  const path = issue.path.join(".");
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+
+interface ValidateOptions {
+  label: string;
+  required: boolean;
+  schema?: z.ZodType;
+  // json parses the value before the schema sees it, so a malformed blob is
+  // reported as bad JSON rather than as a shape the schema cannot read.
+  json?: boolean;
+}
+
+// validateEntry returns the message that should block the step, or undefined to
+// let it advance. It sits outside TextField so that a further field collecting
+// text — a multi-line one, say — refuses the same input for the same stated
+// reason rather than growing its own rules.
+function validateEntry(
+  value: string,
+  { label, required, schema, json = false }: ValidateOptions,
+): string | undefined {
+  const trimmed = value.trim();
+  if (trimmed === "") return required ? `${label} is required` : undefined;
+
+  let parsed: unknown = trimmed;
+  if (json) {
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (cause) {
+      return `${label} is not valid JSON: ${(cause as Error).message}`;
+    }
+  }
+  return schema ? firstIssue(schema, parsed) : undefined;
+}
+
+export interface TextFieldProps {
+  // label names the value in validation messages ("<label> is required").
+  // It is not rendered: the <Step> already asks the question, and repeating
+  // it as a heading only adds a line to read.
+  label: string;
+  // help is the one line under the control, for what the question cannot
+  // carry — a range, a service limit, what an empty answer means. Omit it
+  // rather than restate the question.
+  help?: string;
+  placeholder?: string;
+  value: string;
+  onChange: (value: string) => void;
+  // required blocks advancing while the value is blank. Flag schemas are all
+  // `.optional()` by convention (Commander must not reject a bare command
+  // before the TUI middleware can open a screen), so required-ness is stated
+  // here the same way the handlers state it in their own bodies.
+  required?: boolean;
+  // schema validates the trimmed value before advancing. Pass the schema the
+  // flag declares.
+  schema?: z.ZodType;
+  // json parses the value before validating it. A JSON flag belongs here rather
+  // than in TextAreaField unless the value is genuinely prose: JSON is valid on
+  // one line, and this field can be edited in place.
+  json?: boolean;
+  // example is a dimmed line under `help`, kept on screen while the user types.
+  // A placeholder cannot do this job — it disappears on the first keystroke,
+  // exactly when a fiddly value most needs something to copy the shape from.
+  example?: string;
+  // live validates as the value is typed rather than only on enter. Worth it
+  // for a value with a shape the user can fix on sight — a name against a
+  // pattern — and wrong for one that is invalid until it is complete, like an
+  // ARN, where every keystroke but the last would show an error.
+  live?: boolean;
+}
+
+export function TextField({
+  label,
+  help = "",
+  placeholder = "",
+  value,
+  onChange,
+  required = false,
+  schema,
+  json = false,
+  example,
+  live = false,
+}: TextFieldProps) {
+  const { advance, back, isLast } = useWizard();
+  const [error, setError] = useState<string>();
+
+  useKeyHints([{ key: "enter", label: isLast ? "submit" : "continue" }]);
+
+  useInput((_input, key) => {
+    if (key.escape) {
+      back();
+      return;
+    }
+    if (!key.return) return;
+
+    const issue = validateEntry(value, { label, required, schema, json });
+    if (issue !== undefined) {
+      setError(issue);
+      return;
+    }
+    setError(undefined);
+    advance();
+  });
+
+  return (
+    <Box flexDirection="column">
+      {/* The example sits above the input rather than inside it, so it survives
+          the first keystroke and stays there to be copied from. */}
+      {example !== undefined && (
+        <Box flexDirection="column">
+          {help !== "" && <Text color={theme.colors.muted}>{help}</Text>}
+          <Text color={theme.colors.muted}>{`for example  ${example}`}</Text>
+        </Box>
+      )}
+      <FormTextInput
+        name=""
+        helpText={example === undefined ? help : ""}
+        placeholder={placeholder}
+        errorText=""
+        value={value}
+        onChange={(next) => {
+          onChange(next);
+          // A live field re-checks what was typed, but never reports a blank
+          // value as missing: nothing has been entered yet to be wrong.
+          setError(
+            live && next.trim() !== ""
+              ? validateEntry(next, { label, required, schema, json })
+              : undefined,
+          );
+        }}
+      />
+      {error !== undefined && <Text color={theme.colors.error}>{error}</Text>}
+    </Box>
+  );
+}
+
+export interface Choice<T> {
+  value: T;
+  label: string;
+  description?: string;
+}
+
+export interface ChoiceFieldProps<T> {
+  // help is the one line under the options, for what the question and the
+  // per-option descriptions cannot carry between them. Usually omitted.
+  help?: string;
+  choices: Choice<T>[];
+  value: T;
+  onChange: (value: T) => void;
+}
+
+// ChoiceField is a single-choice step. The arrow arithmetic here replaces the
+// copy of it in each of the hand-written wizards. It takes no `label`: one of
+// the choices is always selected, so there is no validation message to name.
+export function ChoiceField<T>({ help = "", choices, value, onChange }: ChoiceFieldProps<T>) {
+  const { advance, back, isLast } = useWizard();
+
+  useKeyHints([
+    { key: "↑↓", label: "choose" },
+    { key: "enter", label: isLast ? "submit" : "continue" },
+  ]);
+
+  const found = choices.findIndex((choice) => choice.value === value);
+  const index = found === -1 ? 0 : found;
+
+  useInput((_input, key) => {
+    if (key.escape) {
+      back();
+      return;
+    }
+    if (key.upArrow) {
+      onChange(choices[Math.max(0, index - 1)]!.value);
+      return;
+    }
+    if (key.downArrow) {
+      onChange(choices[Math.min(choices.length - 1, index + 1)]!.value);
+      return;
+    }
+    if (key.return) advance();
+  });
+
+  return (
+    <FormRadioGroup
+      name=""
+      helpText={help}
+      options={choices.map((choice) => ({
+        label: choice.label,
+        description: choice.description ?? "",
+      }))}
+      focusedIndex={index}
+    />
+  );
+}
+
+export interface SummaryProps {
+  // items is the review table: what will be created, and with what settings.
+  items: Record<string, string>;
+}
+
+// Summary is the review step. It sits last, so its enter submits.
+export function Summary({ items }: SummaryProps) {
+  const { advance, back } = useWizard();
+
+  useKeyHints([{ key: "enter", label: "submit" }]);
+
+  useInput((_input, key) => {
+    if (key.escape) {
+      back();
+      return;
+    }
+    if (key.return) advance();
+  });
+
+  return (
+    // The rule above the table is a top border rather than a <Divider> so it
+    // spans exactly the table, the same way the create wizard's review step
+    // draws its own.
+    <Box
+      borderStyle="single"
+      borderColor={theme.colors.border}
+      borderLeft={false}
+      borderRight={false}
+      borderBottom={false}
+    >
+      <KeyValueTable items={items} />
+    </Box>
+  );
+}
diff --git a/src/components/wizard/index.ts b/src/components/wizard/index.ts
new file mode 100644
index 000000000..4af773775
--- /dev/null
+++ b/src/components/wizard/index.ts
@@ -0,0 +1,12 @@
+export { Wizard, type WizardProps, type WizardSubmitResult } from "./Wizard";
+export { Step, type StepProps } from "./Step";
+export { useWizard, useKeyHints, type KeyHint, type WizardControls } from "./context";
+export {
+  TextField,
+  ChoiceField,
+  Summary,
+  type Choice,
+  type TextFieldProps,
+  type ChoiceFieldProps,
+  type SummaryProps,
+} from "./fields";
diff --git a/src/components/wizard/wizard.test.tsx b/src/components/wizard/wizard.test.tsx
new file mode 100644
index 000000000..bcecf811c
--- /dev/null
+++ b/src/components/wizard/wizard.test.tsx
@@ -0,0 +1,328 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { useState } from "react";
+import { render } from "ink-testing-library";
+import { render as inkRender } from "ink";
+import { cleanupScreens, keys, tick, ttyTestIO, waitFor } from "../../testing";
+import { Wizard, type WizardSubmitResult } from "./Wizard";
+import { Step } from "./Step";
+import { ChoiceField, Summary, TextField } from "./fields";
+
+afterEach(cleanupScreens);
+
+// The wizard shell is exercised through a synthetic flow rather than one of the
+// real screens, so these tests describe the shell's own behaviour: how it
+// derives steps from children, moves between them, and reports outcomes.
+
+interface HarnessOptions {
+  onSubmit?: () => WizardSubmitResult;
+  onCancel?: () => void;
+  onError?: "exit" | "retry";
+  onDone?: () => void;
+}
+
+const YES_NO = [
+  { value: false, label: "no", description: "skip the extra question" },
+  { value: true, label: "yes", description: "ask the extra question" },
+];
+
+// TestWizard has one conditional step, so the branch behaviour under test is
+// expressed the way a screen expresses it: `{condition && <Step/>}`.
+function TestWizard({ onSubmit, onCancel, onError, onDone }: HarnessOptions) {
+  const [name, setName] = useState("");
+  const [wantsExtra, setWantsExtra] = useState(false);
+  const [extra, setExtra] = useState("");
+
+  return (
+    <Wizard
+      breadcrumb={["agentcore", "test"]}
+      description="a synthetic flow"
+      onCancel={onCancel ?? (() => {})}
+      onSubmit={onSubmit ?? (async () => {})}
+      onError={onError}
+      onDone={onDone}
+      runningLabel="working…"
+      successLabel="all done"
+      successHint="enter exits"
+    >
+      <Step name="name" question="what is your name?">
+        <TextField label="name" value={name} onChange={setName} required />
+      </Step>
+
+      <Step name="branch" question="want the extra question?">
+        <ChoiceField choices={YES_NO} value={wantsExtra} onChange={setWantsExtra} />
+      </Step>
+
+      {wantsExtra && (
+        <Step name="extra" question="the extra question">
+          <TextField label="extra" value={extra} onChange={setExtra} />
+        </Step>
+      )}
+
+      <Step name="review" question="review">
+        <Summary items={{ name, extra: extra === "" ? "(none)" : extra }} />
+      </Step>
+    </Wizard>
+  );
+}
+
+interface Driver {
+  lastFrame: () => string | undefined;
+  write: (input: string) => Promise<void>;
+  press: (key: keyof typeof keys) => Promise<void>;
+  // pressTwice delivers two discrete key events in one drain, with no render in
+  // between — what a fast typist produces. A single "\r\r" chunk would not do:
+  // Ink reports a multi-character chunk with key.return false, so it never
+  // reaches a return handler at all.
+  pressTwice: (key: keyof typeof keys) => Promise<void>;
+  unmount: () => void;
+}
+
+function drive(options: HarnessOptions = {}): Driver {
+  const instance = render(<></>);
+  Object.defineProperties(instance.stdout, {
+    columns: { configurable: true, value: 100 },
+    rows: { configurable: true, value: 40 },
+  });
+  instance.rerender(<TestWizard {...options} />);
+
+  return {
+    lastFrame: instance.lastFrame,
+    write: async (input) => {
+      await tick();
+      instance.stdin.write(input);
+      await tick();
+    },
+    press: async (key) => {
+      await tick();
+      instance.stdin.write(keys[key]);
+      await tick();
+    },
+    pressTwice: async (key) => {
+      await tick();
+      instance.stdin.write(keys[key]);
+      instance.stdin.write(keys[key]);
+      await tick();
+    },
+    unmount: instance.unmount,
+  };
+}
+
+function waitForFrame(driver: Driver, text: string): Promise<void> {
+  return waitFor(() => (driver.lastFrame() ?? "").includes(text), 1000);
+}
+
+describe("Wizard shell", () => {
+  test("derives the stepper from its Step children", async () => {
+    const d = drive();
+
+    await waitForFrame(d, "what is your name?");
+    const frame = d.lastFrame()!;
+    expect(frame).toContain("● name");
+    expect(frame).toContain("○ branch");
+    expect(frame).toContain("○ review");
+    // The conditional step is not offered while its condition is false.
+    expect(frame).not.toContain("○ extra");
+    d.unmount();
+  });
+
+  test("a step appears mid-flow when its condition turns true", async () => {
+    const d = drive();
+
+    await waitForFrame(d, "what is your name?");
+    await d.write("Ada");
+    await d.press("return");
+
+    await waitForFrame(d, "want the extra question?");
+    expect(d.lastFrame()).not.toContain("○ extra");
+
+    // Choosing "yes" inserts the step between here and review.
+    await d.press("down");
+    await waitForFrame(d, "○ extra");
+    await d.press("return");
+
+    await waitForFrame(d, "the extra question");
+    d.unmount();
+  });
+
+  test("enter advances and esc goes back, keeping answers", async () => {
+    const d = drive();
+
+    await waitForFrame(d, "what is your name?");
+    await d.write("Ada");
+    await d.press("return");
+
+    await waitForFrame(d, "want the extra question?");
+    await d.press("escape");
+
+    await waitForFrame(d, "what is your name?");
+    expect(d.lastFrame()).toContain("Ada");
+    d.unmount();
+  });
+
+  test("esc on the first step cancels out of the wizard", async () => {
+    let cancelled = 0;
+    const d = drive({ onCancel: () => cancelled++ });
+
+    await waitForFrame(d, "what is your name?");
+    await d.press("escape");
+
+    expect(cancelled).toBe(1);
+    d.unmount();
+  });
+
+  test("the footer hints come from the active field", async () => {
+    const d = drive();
+
+    // A text field offers enter; a choice field also offers the arrows.
+    await waitForFrame(d, "what is your name?");
+    expect(d.lastFrame()).toContain("[enter] continue");
+    expect(d.lastFrame()).not.toContain("[↑↓] choose");
+
+    await d.write("Ada");
+    await d.press("return");
+
+    await waitForFrame(d, "want the extra question?");
+    expect(d.lastFrame()).toContain("[↑↓] choose");
+    d.unmount();
+  });
+
+  test("enter on the last step submits and reports success", async () => {
+    let submits = 0;
+    const d = drive({
+      onSubmit: async () => {
+        submits++;
+      },
+    });
+
+    await waitForFrame(d, "what is your name?");
+    await d.write("Ada");
+    await d.press("return");
+    await waitForFrame(d, "want the extra question?");
+    await d.press("return");
+    await waitForFrame(d, "review");
+    expect(d.lastFrame()).toContain("[enter] submit");
+    await d.press("return");
+
+    await waitForFrame(d, "✔ all done");
+    expect(submits).toBe(1);
+    d.unmount();
+  });
+
+  test("a streamed submit renders its steps through the shared TaskList", async () => {
+    // The pauses let Ink paint between events: a generator that runs to
+    // completion in one batch would only ever produce the final frame, and the
+    // tail under a running step is exactly what that frame no longer shows.
+    const pause = () => new Promise((resolve) => setTimeout(resolve, 5));
+    async function* progress() {
+      yield { type: "step", message: "wrote agentcore.json" } as const;
+      await pause();
+      yield { type: "output", line: "a line tailing the running step" } as const;
+      await pause();
+      yield { type: "step", message: "updated the deploy target" } as const;
+    }
+    const d = drive({ onSubmit: () => progress() });
+
+    await waitForFrame(d, "what is your name?");
+    await d.write("Ada");
+    await d.press("return");
+    await waitForFrame(d, "want the extra question?");
+    await d.press("return");
+    await waitForFrame(d, "review");
+    await d.press("return");
+
+    // An output line tails the step it belongs to while that step runs, and
+    // collapses with it — TaskList's behaviour everywhere else in the CLI.
+    await waitForFrame(d, "│ a line tailing the running step");
+
+    await waitForFrame(d, "✔ all done");
+    const frame = d.lastFrame()!;
+    expect(frame).toContain("✓ wrote agentcore.json");
+    expect(frame).toContain("✓ updated the deploy target");
+    expect(frame).not.toContain("a line tailing the running step");
+    d.unmount();
+  });
+
+  test("a buffered second enter does not submit twice", async () => {
+    let submits = 0;
+    const d = drive({
+      onSubmit: async () => {
+        submits++;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      },
+    });
+
+    await waitForFrame(d, "what is your name?");
+    await d.write("Ada");
+    await d.press("return");
+    await waitForFrame(d, "want the extra question?");
+    await d.press("return");
+    await waitForFrame(d, "review");
+    await d.pressTwice("return");
+
+    await waitForFrame(d, "✔ all done");
+    expect(submits).toBe(1);
+    d.unmount();
+  });
+
+  test("onError retry reports the failure and returns to the form", async () => {
+    const d = drive({
+      onError: "retry",
+      onSubmit: () => Promise.reject(new Error("the service said no")),
+    });
+
+    await waitForFrame(d, "what is your name?");
+    await d.write("Ada");
+    await d.press("return");
+    await waitForFrame(d, "want the extra question?");
+    await d.press("return");
+    await waitForFrame(d, "review");
+    await d.press("return");
+
+    await waitForFrame(d, "✗ the service said no");
+    await d.press("escape");
+
+    // Back on the review step, with the answers intact.
+    await waitForFrame(d, "review");
+    expect(d.lastFrame()).toContain("Ada");
+    d.unmount();
+  });
+
+  test("a required field blocks the step until it is filled", async () => {
+    const d = drive();
+
+    await waitForFrame(d, "what is your name?");
+    await d.press("return");
+
+    await waitForFrame(d, "name is required");
+    expect(d.lastFrame()).toContain("what is your name?");
+    d.unmount();
+  });
+});
+
+describe("Wizard authoring guards", () => {
+  // Ink's own render rather than ink-testing-library: a render-time throw
+  // reaches Ink's error boundary and rejects waitUntilExit, which the testing
+  // library does not expose.
+  test("two steps sharing a name are rejected at render", async () => {
+    const { streams } = ttyTestIO();
+    const { waitUntilExit } = inkRender(
+      <Wizard
+        breadcrumb={["agentcore", "test"]}
+        onCancel={() => {}}
+        onSubmit={async () => {}}
+        runningLabel="working…"
+        successLabel="all done"
+      >
+        <Step name="name" question="first">
+          <Summary items={{}} />
+        </Step>
+        <Step name="name" question="second">
+          <Summary items={{}} />
+        </Step>
+      </Wizard>,
+      { stdin: streams.io.stdin, stdout: streams.io.stdout, stderr: streams.io.stderr },
+    );
+
+    await expect(waitUntilExit()).rejects.toThrow('duplicate <Step name="name">');
+  });
+});
diff --git a/src/handlers/project/add/add.screen.test.tsx b/src/handlers/project/add/add.screen.test.tsx
new file mode 100644
index 000000000..ae78dce64
--- /dev/null
+++ b/src/handlers/project/add/add.screen.test.tsx
@@ -0,0 +1,73 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+  renderScreen,
+  waitForText,
+  cleanupScreens,
+  compiledRootCommand,
+  menuEntries,
+} from "../../../testing";
+
+afterEach(cleanupScreens);
+
+// addSubcommands reads the resources off the compiled Commander tree, so a
+// `project add` resource added later is covered without editing this file.
+// `help` is Commander's own, not one of ours.
+function addSubcommands(): string[] {
+  const root = compiledRootCommand();
+  const project = root.commands.find((command) => command.name() === "project")!;
+  const add = project.commands.find((command) => command.name() === "add")!;
+  return add.commands.map((command) => command.name()).filter((name) => name !== "help");
+}
+
+// The resources with a wizard. Everything else is listed below the menu's
+// "command line only" divider and opens its help instead.
+const WITH_SCREENS = ["runtime"];
+
+describe("project add menu", () => {
+  test("lists every add resource", async () => {
+    const r = renderScreen("/agentcore/project/add");
+
+    await waitForText(r.lastFrame, "add project resources");
+    const frame = r.lastFrame()!;
+    for (const command of addSubcommands()) {
+      expect(frame).toContain(command);
+    }
+    r.unmount();
+  });
+
+  test("the resources with a wizard are listed above the divider", async () => {
+    const r = renderScreen("/agentcore/project/add");
+
+    await waitForText(r.lastFrame, "command line only");
+    const { screens, cliOnly } = menuEntries(r.lastFrame()!);
+    expect(screens.toSorted()).toEqual(WITH_SCREENS.toSorted());
+    expect(cliOnly.toSorted()).toEqual(
+      addSubcommands()
+        .filter((command) => !WITH_SCREENS.includes(command))
+        .toSorted(),
+    );
+    r.unmount();
+  });
+
+  test("is reachable from the project menu", async () => {
+    const r = renderScreen("/agentcore/project");
+
+    await waitForText(r.lastFrame, "agentcore → project");
+    await r.write("add");
+    await waitForText(r.lastFrame, "❯ add");
+    await r.press("return");
+
+    await waitForText(r.lastFrame, "agentcore → project → add");
+    r.unmount();
+  });
+
+  test("esc returns to the project menu", async () => {
+    const r = renderScreen("/agentcore/project/add");
+
+    await waitForText(r.lastFrame, "agentcore → project → add");
+    await r.press("escape");
+
+    await waitForText(r.lastFrame, "manage an AgentCore project");
+    r.unmount();
+  });
+});
diff --git a/src/handlers/project/add/index.ts b/src/handlers/project/add/index.ts
index 02f0fce60..2672ec057 100644
--- a/src/handlers/project/add/index.ts
+++ b/src/handlers/project/add/index.ts
@@ -18,7 +18,10 @@ import { createAddPaymentConnectorHandler } from "./payment-connector";
 import { createAddPaymentManagerHandler } from "./payment-manager";
 
 export function createAddProjectResourceHandler(config: AddProjectResourceConfig): Router {
-  const projectAdd = new Router("add", "add project resources");
+  // The resources with a wizard of their own. Every other resource is listed in
+  // the add menu as command line only and opens its help instead (see
+  // CliOnlyScreen).
+  const projectAdd = new Router("add", "add project resources").supportedTuiCommands("runtime");
   projectAdd.use(withProject({ projectManager: config.projectManager, cwd: process.cwd() }));
   projectAdd.handler(createAddConfigBundleHandler(config));
   projectAdd.handler(createAddHarnessHandler(config));
diff --git a/src/handlers/project/add/runtime/index.ts b/src/handlers/project/add/runtime/index.ts
index fec3ad924..54965ad00 100644
--- a/src/handlers/project/add/runtime/index.ts
+++ b/src/handlers/project/add/runtime/index.ts
@@ -13,7 +13,7 @@ import {
   getDefaultMemorySpec,
   resolveRuntimeTemplateShortcut,
 } from "../../shortcuts";
-import { ModelProviderSchema, type ScaffoldRuntimeInput } from "../../types";
+import { ModelProviderSchema, type AddResourceInput, type ScaffoldRuntimeInput } from "../../types";
 import { RuntimeResourceConfigSchema, type ImportBedrockAgentInput } from "./types";
 import {
   importScaffoldRuntimeInput,
@@ -22,6 +22,31 @@ import {
 import { RegionKey } from "../../../keys";
 import { addProjectResource } from "../shared";
 
+// The infrastructure settings that arrive as JSON documents. They are parsed
+// but not yet validated when an entry point assembles a runtime, so they are
+// `unknown` until toAddRuntimeInput runs the schema over them.
+type JsonRuntimeField =
+  | "networkConfig"
+  | "authorizerConfiguration"
+  | "lifecycleConfiguration"
+  | "filesystemConfigurations";
+
+/** A runtime resource as an entry point assembles it, before validation. */
+export type RuntimeInput = Omit<z.input<typeof RuntimeResourceConfigSchema>, JsonRuntimeField> &
+  Partial<Record<JsonRuntimeField, unknown>>;
+
+/**
+ * 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.
+ */
+export function toAddRuntimeInput(input: RuntimeInput): AddResourceInput {
+  const result = RuntimeResourceConfigSchema.safeParse(input);
+  if (!result.success)
+    throw new InputValidationError(z.prettifyError(result.error), { cause: result.error });
+  return { resourceType: "runtime", resourceConfig: result.data };
+}
+
 export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
   createHandler({
     name: "runtime",
@@ -220,19 +245,12 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
         importBedrockAgent,
       };
 
-      const result = RuntimeResourceConfigSchema.safeParse(runtimeInput);
-      if (!result.success)
-        throw new InputValidationError(z.prettifyError(result.error), { cause: result.error });
-
       const project = ctx.require(ProjectKey);
       await addProjectResource(
         ctx,
         config,
         project,
-        {
-          resourceType: "runtime",
-          resourceConfig: result.data,
-        },
+        toAddRuntimeInput(runtimeInput),
         `added runtime '${flags.name}' to '${project.name}'`,
         { notes },
       );
diff --git a/src/handlers/project/add/runtime/runtime.screen.test.tsx b/src/handlers/project/add/runtime/runtime.screen.test.tsx
new file mode 100644
index 000000000..ff64887e3
--- /dev/null
+++ b/src/handlers/project/add/runtime/runtime.screen.test.tsx
@@ -0,0 +1,139 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import { join } from "node:path";
+import {
+  renderScreen,
+  waitForText,
+  waitForFlatText,
+  flatFrame,
+  cleanupScreens,
+  type RenderScreenResult,
+} from "../../../../testing";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const { cleanup, inProject, projectSpec } = createGatewayProjectTestHarness("add-runtime-wizard");
+
+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;
+    await r.press("up");
+  }
+  throw new Error(`template ${template} was never selected`);
+}
+
+async function runtimeInSpec(projectRoot: string, name: string) {
+  const spec = await projectSpec(projectRoot);
+  return spec.runtimes.find((candidate: { name: string }) => candidate.name === name);
+}
+
+describe("project add runtime wizard", () => {
+  test("collects a name, template and description, then writes the runtime", async () => {
+    const projectRoot = await inProject();
+    const r = renderScreen("/agentcore/project/add/runtime");
+
+    await waitForText(r.lastFrame, "what should this runtime be called?");
+    await r.write("orders_agent");
+    await r.press("return");
+
+    // The default template is the one the flag path scaffolds without --template.
+    await waitForText(r.lastFrame, "choose a template");
+    expect(flatFrame(r.lastFrame)).toContain("● agent-python-minimal ");
+    await r.press("return");
+
+    await waitForText(r.lastFrame, "what is this runtime for?");
+    await r.write("answers questions about orders");
+    await r.press("return");
+
+    await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
+    const review = flatFrame(r.lastFrame);
+    expect(review).toContain("runtime orders_agent");
+    expect(review).toContain("template agent-python-minimal");
+    expect(review).toContain("description answers questions about orders");
+    await r.press("return");
+
+    await waitForText(r.lastFrame, "added runtime 'orders_agent' to 'TestProject'");
+
+    expect(await runtimeInSpec(projectRoot, "orders_agent")).toMatchObject({
+      description: "answers questions about orders",
+      build: "CodeZip",
+      entrypoint: "main.py",
+      codeLocation: "app/orders_agent",
+      runtimeVersion: "PYTHON_3_14",
+    });
+    expect(await Bun.file(join(projectRoot, "app", "orders_agent", "main.py")).exists()).toBe(true);
+    r.unmount();
+  });
+
+  test("scaffolds the template the user picks", async () => {
+    const projectRoot = await inProject();
+    const r = renderScreen("/agentcore/project/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");
+
+    // The description is optional, so a blank answer advances.
+    await waitForText(r.lastFrame, "what is this runtime for?");
+    await r.press("return");
+
+    await waitForFlatText(r.lastFrame, "build Container");
+    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" });
+    expect(runtime.description).toBeUndefined();
+    expect(await Bun.file(join(projectRoot, "app", "packing_agent", "Dockerfile")).exists()).toBe(
+      true,
+    );
+    r.unmount();
+  });
+
+  test("a blank name is refused", async () => {
+    await inProject();
+    const r = renderScreen("/agentcore/project/add/runtime");
+
+    await waitForText(r.lastFrame, "what should this runtime be called?");
+    await r.press("return");
+
+    await waitForText(r.lastFrame, "Name is required");
+    expect(r.lastFrame()).not.toContain("choose a template");
+    r.unmount();
+  });
+
+  test("a name that breaks the schema's pattern is rejected as it is typed", async () => {
+    await inProject();
+    const r = renderScreen("/agentcore/project/add/runtime");
+
+    await waitForText(r.lastFrame, "what should this runtime be called?");
+    // No enter: the name is checked while it is being typed, so the rule is
+    // stated before the user has finished getting it wrong.
+    await r.write("1agent");
+
+    await waitForText(r.lastFrame, "Must begin with a letter");
+    r.unmount();
+  });
+
+  test("esc on the first step returns to the add menu", async () => {
+    await inProject();
+    const r = renderScreen("/agentcore/project/add/runtime");
+
+    await waitForText(r.lastFrame, "what should this runtime be called?");
+    await r.press("escape");
+
+    await waitForText(r.lastFrame, "add project resources");
+    r.unmount();
+  });
+});
diff --git a/src/handlers/project/add/runtime/screen.tsx b/src/handlers/project/add/runtime/screen.tsx
new file mode 100644
index 000000000..8bcceb0a6
--- /dev/null
+++ b/src/handlers/project/add/runtime/screen.tsx
@@ -0,0 +1,149 @@
+import { useState } from "react";
+import { useNavigate } from "react-router";
+import { ProjectKey } from "../../../../router";
+import { AgentNameSchema, ProjectRuntimeSchema } from "../../../../projectSchemas/runtime";
+import type { ScreenProps } from "../../../types";
+import type { Project } from "../../types";
+import { ProjectGate } from "../../ProjectGate";
+import {
+  ChoiceField,
+  Step,
+  Summary,
+  TextField,
+  Wizard,
+  type Choice,
+} from "../../../../components/wizard";
+import {
+  RUNTIME_TEMPLATE_SHORTCUTS,
+  RUNTIME_TEMPLATE_SHORTCUT_NAMES,
+  resolveRuntimeTemplateShortcut,
+  type RuntimeTemplateShortcutName,
+} from "../../shortcuts";
+import { toAddRuntimeInput, type RuntimeInput } from "./index";
+
+const BREADCRUMB = ["agentcore", "project", "add", "runtime"];
+const DESCRIPTION = "add a Runtime to the current project";
+const ADD_MENU = "/agentcore/project/add";
+
+/** The template `add runtime` scaffolds when none is named, as on the flag path. */
+const DEFAULT_TEMPLATE: RuntimeTemplateShortcutName = "agent-python-minimal";
+
+const TEMPLATE_CHOICES: Choice<RuntimeTemplateShortcutName>[] = RUNTIME_TEMPLATE_SHORTCUT_NAMES.map(
+  (template) => ({
+    value: template,
+    label: template,
+    description: RUNTIME_TEMPLATE_SHORTCUTS[template].description,
+  }),
+);
+
+interface RuntimeFormValues {
+  name: string;
+  template: RuntimeTemplateShortcutName;
+  description: string;
+}
+
+// toRuntimeInput reads the form into the RuntimeInput toAddRuntimeInput
+// validates. The wizard scaffolds from a template and leaves the infrastructure
+// settings — the role, network, authorizer and lifecycle configuration — at
+// their defaults; those are JSON documents, so they stay on the flag path, as
+// does importing a Bedrock Agent version.
+export function toRuntimeInput(values: RuntimeFormValues): RuntimeInput {
+  const name = values.name.trim();
+  const description = values.description.trim();
+  return {
+    name,
+    ...(description !== "" && { description }),
+    envVars: [],
+    scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(values.template, { runtimeName: name }),
+  };
+}
+
+function summaryOf(values: RuntimeFormValues): Record<string, string> {
+  const template = RUNTIME_TEMPLATE_SHORTCUTS[values.template];
+  return {
+    runtime: values.name.trim(),
+    template: values.template,
+    language: template.language,
+    build: template.build,
+    ...(values.description.trim() === "" ? {} : { description: values.description.trim() }),
+  };
+}
+
+// AddRuntimeScreen is the interactive flow behind a bare `agentcore project add
+// runtime`: name → template → description → review, then the add itself,
+// streaming the ProjectManager's progress events.
+export function AddRuntimeScreen({ ctx, core }: ScreenProps) {
+  const navigate = useNavigate();
+  return (
+    <ProjectGate
+      core={core}
+      breadcrumb={BREADCRUMB}
+      description={DESCRIPTION}
+      seed={ctx.value(ProjectKey)}
+      onBack={() => navigate(ADD_MENU)}
+    >
+      {(project) => <AddRuntimeWizard project={project} core={core} />}
+    </ProjectGate>
+  );
+}
+
+function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenProps["core"] }) {
+  const navigate = useNavigate();
+  const [values, setValues] = useState<RuntimeFormValues>({
+    name: "",
+    template: DEFAULT_TEMPLATE,
+    description: "",
+  });
+  const set = (update: Partial<RuntimeFormValues>) =>
+    setValues((current) => ({ ...current, ...update }));
+
+  return (
+    <Wizard
+      breadcrumb={BREADCRUMB}
+      description={DESCRIPTION}
+      onCancel={() => navigate(ADD_MENU)}
+      onSubmit={() =>
+        core.projectManager.addResource(project, toAddRuntimeInput(toRuntimeInput(values)))
+      }
+      runningLabel={`adding runtime ${values.name.trim()}…`}
+      successLabel={`added runtime '${values.name.trim()}' to '${project.name}'`}
+      successHint="enter exits"
+    >
+      <Step name="name" question="what should this runtime be called?">
+        <TextField
+          label="Name"
+          help="also the directory under app/ · letters, digits and underscores, starting with a letter"
+          placeholder="my_agent"
+          value={values.name}
+          onChange={(name) => set({ name })}
+          required
+          schema={AgentNameSchema}
+          live
+        />
+      </Step>
+
+      <Step name="template" question="choose a template">
+        <ChoiceField
+          help="the agent code scaffolded into app/"
+          choices={TEMPLATE_CHOICES}
+          value={values.template}
+          onChange={(template) => set({ template })}
+        />
+      </Step>
+
+      <Step name="description" question="what is this runtime for? (optional)">
+        <TextField
+          label="description"
+          placeholder="answers questions about orders"
+          value={values.description}
+          onChange={(description) => set({ description })}
+          schema={ProjectRuntimeSchema.shape.description}
+        />
+      </Step>
+
+      <Step name="review" question="this runtime will be added to agentcore.json">
+        <Summary items={summaryOf(values)} />
+      </Step>
+    </Wizard>
+  );
+}
diff --git a/src/handlers/project/create/screen.tsx b/src/handlers/project/create/screen.tsx
index 1ba2469e4..a6e372ffb 100644
--- a/src/handlers/project/create/screen.tsx
+++ b/src/handlers/project/create/screen.tsx
@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Box, Text, useApp, useInput } from "ink";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Box, Text, useInput } from "ink";
 import { ScrollView, type ScrollViewRef } from "ink-scroll-view";
 import { useNavigate } from "react-router";
 import { ProjectNameSchema } from "../../../projectSchemas/project";
@@ -16,17 +16,19 @@ import {
   type TemplateName,
 } from "../shortcuts";
 import { HARNESS_DEFAULT_MODEL_IDS, resolveScaffoldHarnessInput } from "./index";
-import { Layout } from "../../../components/Layout";
-import { ErrorPanel } from "../../../components/ErrorPanel";
 import { FormTextInput } from "../../../components/FormTextInput";
 import { FormRadioGroup, type FormRadioOption } from "../../../components/FormRadioGroup";
-import { KeyValueTable } from "../../../components/KeyValueTable";
-import { Stepper, type Step } from "../../../components/ui/stepper";
-import { Spinner } from "../../../components/ui/spinner";
-import { TaskList, type Task } from "../../../components/ui/task-list";
-import { Divider } from "../../../components/ui/divider";
-import { driveProgress } from "../../../tui/progress";
-import { darkTheme, glyphs } from "../../../components/ui/_core.js";
+import {
+  ChoiceField,
+  Step,
+  Summary,
+  TextField,
+  Wizard,
+  useKeyHints,
+  useWizard,
+  type Choice,
+} from "../../../components/wizard";
+import { darkTheme } from "../../../components/ui/_core.js";
 
 const theme = darkTheme;
 
@@ -104,14 +106,14 @@ function emptyCreateProjectForm(): CreateProjectFormValues {
   };
 }
 
-const PROJECT_KIND_OPTIONS: { kind: ProjectKind; label: string; description: string }[] = [
+const PROJECT_KIND_CHOICES: Choice<ProjectKind>[] = [
   {
-    kind: "agent",
+    value: "agent",
     label: "agent code",
     description: "generate runnable agent code from a template",
   },
   {
-    kind: "harness",
+    value: "harness",
     label: "harness",
     description: "a managed agent configured by spec — no agent-loop code to maintain",
   },
@@ -119,8 +121,8 @@ const PROJECT_KIND_OPTIONS: { kind: ProjectKind; label: string; description: str
 
 const DEFAULT_TEMPLATE: TemplateName = "agent-python-strands";
 
-const TEMPLATE_OPTIONS = PROJECT_TEMPLATE_NAMES.map((template) => ({
-  template,
+const TEMPLATE_CHOICES: Choice<TemplateName>[] = PROJECT_TEMPLATE_NAMES.map((template) => ({
+  value: template,
   label: template,
   description:
     template === EMPTY_TEMPLATE_NAME
@@ -189,10 +191,7 @@ function providerLabel(provider: HarnessModelProvider): string {
   return MODEL_PROVIDERS.find((candidate) => candidate.provider === provider)!.label;
 }
 
-// ─── wizard shell ─────────────────────────────────────────────────────────────
-
-type WizardPhase =
-  { kind: "form" } | { kind: "running" } | { kind: "success" } | { kind: "error"; error: Error };
+// ─── wizard ───────────────────────────────────────────────────────────────────
 
 // ProjectCreateScreen is the interactive flow behind a bare `agentcore project
 // create`: name → type → (model | template) → review, then the
@@ -202,304 +201,85 @@ type WizardPhase =
 // working directory, npm install and git init included.
 export function ProjectCreateScreen({ ctx, core }: ScreenProps) {
   const navigate = useNavigate();
-  const { exit } = useApp();
-
   const [values, setValues] = useState<CreateProjectFormValues>(emptyCreateProjectForm);
-  const [stepIndex, setStepIndex] = useState(0);
-  const [phase, setPhase] = useState<WizardPhase>({ kind: "form" });
-  const [tasks, setTasks] = useState<Task[]>([]);
-
-  // The step list is dynamic: the branch chosen on the type step decides
-  // whether the model or the template question follows.
-  const steps: Step[] = useMemo(() => {
-    const branch: Step[] =
-      values.kind === "harness"
-        ? [{ key: "model", title: "model" }]
-        : [{ key: "template", title: "template" }];
-    return [
-      { key: "name", title: "name" },
-      { key: "type", title: "type" },
-      ...branch,
-      { key: "review", title: "review" },
-    ];
-  }, [values.kind]);
-
-  const stepKey = steps[stepIndex]!.key;
+
   const patch = (update: Partial<CreateProjectFormValues>) =>
     setValues((current) => ({ ...current, ...update }));
 
-  const next = () => setStepIndex((i) => Math.min(steps.length - 1, i + 1));
-  const back = () => {
-    // Esc from the first step leaves the wizard for the project menu, the
-    // same place RouterScreen's esc goes; deeper steps step backwards.
-    if (stepIndex === 0) navigate("/agentcore/project");
-    else setStepIndex((i) => i - 1);
-  };
-
-  const submit = async () => {
-    let input: CreateProjectInput;
-    try {
-      assertProjectPathFits(values.name, ctx.require(PlatformKey));
-      input = buildCreateInput(values);
-    } catch (error) {
-      setPhase({ kind: "error", error: toError(error) });
-      return;
-    }
-    setPhase({ kind: "running" });
-    setTasks([]);
-    try {
-      await driveProgress(core.projectManager.create(input), setTasks);
-      setPhase({ kind: "success" });
-    } catch (error) {
-      setPhase({ kind: "error", error: toError(error) });
-    }
-  };
-
   return (
-    <Layout
+    <Wizard
       breadcrumb={["agentcore", "project", "create"]}
       description="create a new AgentCore project"
-      keyHints={hintsFor(stepKey, phase, tasks.length === 0)}
+      // Esc from the first step leaves the wizard for the project menu, the
+      // same place RouterScreen's esc goes.
+      onCancel={() => navigate("/agentcore/project")}
+      onSubmit={() => {
+        // Both of these throw before anything is written, so the wizard reports
+        // them the way it reports a failed create — with the retry still on
+        // offer, because nothing has to be cleaned up first.
+        assertProjectPathFits(values.name, ctx.require(PlatformKey));
+        return core.projectManager.create(buildCreateInput(values));
+      }}
+      onError="retry"
+      runningLabel={`creating ${values.name}…`}
+      successLabel={`project created in ./${values.name}`}
+      successNextSteps={[`cd ${values.name}`, "agentcore project deploy"]}
+      successHint="enter exits"
     >
-      <Box flexDirection="column">
-        {phase.kind === "form" && (
-          <>
-            <Box paddingX={1} flexShrink={0}>
-              <Stepper
-                steps={steps}
-                currentStep={stepKey}
-                completedSteps={steps.slice(0, stepIndex).map((step) => step.key)}
-              />
-            </Box>
-            <Divider />
-            <WizardStep
-              stepKey={stepKey}
-              values={values}
-              patch={patch}
-              onNext={next}
-              onBack={back}
-              onSubmit={submit}
-            />
-          </>
-        )}
-        {phase.kind !== "form" && (
-          <Box flexDirection="column" paddingX={1}>
-            <TaskList tasks={tasks} />
-            {phase.kind === "running" && tasks.length === 0 && (
-              <Spinner label={`creating ${values.name}…`} />
-            )}
-            {phase.kind === "success" && (
-              <SuccessPanel name={values.name} onContinue={() => exit()} />
-            )}
-            {phase.kind === "error" && (
-              <ErrorPanel
-                message={phase.error.message}
-                onRetry={tasks.length === 0 ? submit : undefined}
-                onBack={() => setPhase({ kind: "form" })}
-              />
-            )}
-          </Box>
-        )}
-      </Box>
-    </Layout>
-  );
-}
-
-function toError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-// A retry is only offered while nothing has been written yet: once a step has
-// run, the scaffolded directory exists and re-submitting would fail on it.
-function hintsFor(
-  stepKey: string,
-  phase: WizardPhase,
-  retryable: boolean,
-): { key: string; label: string }[] {
-  if (phase.kind === "running") return [{ key: "ctrl+c", label: "quit" }];
-  if (phase.kind === "success") return [{ key: "enter", label: "exit" }];
-  if (phase.kind === "error")
-    return [
-      ...(retryable ? [{ key: "r", label: "retry" }] : []),
-      { key: "esc", label: "back" },
-      { key: "ctrl+c", label: "quit" },
-    ];
-  const base = [
-    { key: "esc", label: "back" },
-    { key: "ctrl+c", label: "quit" },
-  ];
-  switch (stepKey) {
-    case "name":
-      return [{ key: "enter", label: "continue" }, ...base];
-    case "model":
-      return [{ key: "↑↓", label: "navigate" }, { key: "enter", label: "continue" }, ...base];
-    case "type":
-    case "template":
-    case "memory":
-      return [{ key: "↑↓", label: "navigate" }, { key: "enter", label: "continue" }, ...base];
-    case "review":
-      return [{ key: "enter", label: "create" }, ...base];
-    default:
-      return base;
-  }
-}
-
-// ─── steps ────────────────────────────────────────────────────────────────────
-
-interface WizardStepProps {
-  stepKey: string;
-  values: CreateProjectFormValues;
-  patch: (update: Partial<CreateProjectFormValues>) => void;
-  onNext: () => void;
-  onBack: () => void;
-  onSubmit: () => void;
-}
-
-function WizardStep({ stepKey, values, patch, onNext, onBack, onSubmit }: WizardStepProps) {
-  switch (stepKey) {
-    case "name":
-      return (
-        <NameStep
+      <Step name="name" question="name your project">
+        {/* The label is the schema's own subject, so a blank name is refused
+            with the message the flag-driven path prints for it. */}
+        <TextField
+          label="Project name"
+          help="also the directory name · 1–23 letters and digits, starting with a letter"
+          placeholder="MyAssistant"
           value={values.name}
           onChange={(name) => patch({ name })}
-          onNext={onNext}
-          onBack={onBack}
-        />
-      );
-    case "type":
-      return (
-        <RadioStep
-          name="what should the project be built around?"
-          helpText="a project deploys either a managed harness or your own agent code"
-          options={PROJECT_KIND_OPTIONS}
-          focusedIndex={PROJECT_KIND_OPTIONS.findIndex((option) => option.kind === values.kind)}
-          onSelect={(index) => patch({ kind: PROJECT_KIND_OPTIONS[index]!.kind })}
-          onNext={onNext}
-          onBack={onBack}
-        />
-      );
-    case "model":
-      return (
-        <ModelStep
-          value={values.model}
-          onChange={(model) => patch({ model })}
-          onNext={onNext}
-          onBack={onBack}
+          schema={ProjectNameSchema}
+          required
+          live
         />
-      );
-    case "template":
-      return (
-        <RadioStep
-          name="choose a template"
-          helpText="the agent code scaffolded into the project"
-          options={TEMPLATE_OPTIONS}
-          focusedIndex={TEMPLATE_OPTIONS.findIndex((option) => option.template === values.template)}
-          onSelect={(index) => patch({ template: TEMPLATE_OPTIONS[index]!.template })}
-          onNext={onNext}
-          onBack={onBack}
+      </Step>
+
+      <Step name="type" question="what should the project be built around?">
+        <ChoiceField
+          help="a project deploys either a managed harness or your own agent code"
+          choices={PROJECT_KIND_CHOICES}
+          value={values.kind}
+          onChange={(kind) => patch({ kind })}
         />
-      );
-    case "review":
-      return <ReviewStep values={values} onSubmit={onSubmit} onBack={onBack} />;
-    default:
-      return null;
-  }
-}
-
-// NameStep validates against ProjectNameSchema — the schema the flag-driven
-// path enforces — showing the schema's own messages inline as the user types.
-function NameStep({
-  value,
-  onChange,
-  onNext,
-  onBack,
-}: {
-  value: string;
-  onChange: (value: string) => void;
-  onNext: () => void;
-  onBack: () => void;
-}) {
-  const [submitted, setSubmitted] = useState(false);
-
-  const validation = ProjectNameSchema.safeParse(value);
-  const showError = !validation.success && (value !== "" || submitted);
-  const errorMessage = showError ? validation.error.issues[0]?.message : undefined;
-
-  useInput((_input, key) => {
-    if (key.escape) {
-      onBack();
-      return;
-    }
-    if (key.return) {
-      if (validation.success) onNext();
-      else setSubmitted(true);
-    }
-  });
-
-  return (
-    <Box flexDirection="column" paddingX={1}>
-      <FormTextInput
-        name="name your project"
-        helpText="also the directory name · 1–23 letters and digits, starting with a letter"
-        placeholder="MyAssistant"
-        errorText=""
-        value={value}
-        onChange={(next) => {
-          onChange(next);
-          setSubmitted(false);
-        }}
-      />
-      {errorMessage && <Text color={theme.colors.error}>{errorMessage}</Text>}
-    </Box>
+      </Step>
+
+      {values.kind === "harness" && (
+        <Step name="model" question="choose a model">
+          <ModelField value={values.model} onChange={(model) => patch({ model })} />
+        </Step>
+      )}
+
+      {values.kind === "agent" && (
+        <Step name="template" question="choose a template">
+          <ChoiceField
+            help="the agent code scaffolded into the project"
+            choices={TEMPLATE_CHOICES}
+            value={values.template}
+            onChange={(template) => patch({ template })}
+          />
+        </Step>
+      )}
+
+      <Step name="review" question="this project will be created">
+        <Summary items={summaryOf(values)} />
+        <Box marginTop={1}>
+          <Text color={theme.colors.muted}>
+            enter scaffolds the project, installs dependencies, and initializes git
+          </Text>
+        </Box>
+      </Step>
+    </Wizard>
   );
 }
 
-// RadioStep is a single-choice step: the parent owns the selection, this owns
-// the arrow/enter/esc handling around a FormRadioGroup.
-function RadioStep({
-  name,
-  helpText,
-  options,
-  focusedIndex,
-  onSelect,
-  onNext,
-  onBack,
-}: {
-  name: string;
-  helpText: string;
-  options: FormRadioOption[];
-  focusedIndex: number;
-  onSelect: (index: number) => void;
-  onNext: () => void;
-  onBack: () => void;
-}) {
-  useInput((_input, key) => {
-    if (key.escape) {
-      onBack();
-      return;
-    }
-    if (key.upArrow) {
-      onSelect(Math.max(0, focusedIndex - 1));
-      return;
-    }
-    if (key.downArrow) {
-      onSelect(Math.min(options.length - 1, focusedIndex + 1));
-      return;
-    }
-    if (key.return) onNext();
-  });
-
-  return (
-    <Box flexDirection="column" paddingX={1}>
-      <FormRadioGroup
-        name={name}
-        helpText={helpText}
-        options={options}
-        focusedIndex={focusedIndex}
-      />
-    </Box>
-  );
-}
+// ─── the model step ───────────────────────────────────────────────────────────
 
 type ModelFieldKey = keyof ProjectModelConfig;
 
@@ -558,17 +338,18 @@ function modelFields(provider: HarnessModelProvider): ModelField[] {
   return fields;
 }
 
-function ModelStep({
+// ModelField is a compound field: one useInput over a provider list and the
+// per-provider inputs the choice reveals. The wizard shell has no notion of
+// focus, so the two levels are managed here — the provider list until enter,
+// then the fields, with esc stepping back out.
+function ModelField({
   value,
   onChange,
-  onNext,
-  onBack,
 }: {
   value: ProjectModelValues;
   onChange: (value: ProjectModelValues) => void;
-  onNext: () => void;
-  onBack: () => void;
 }) {
+  const { advance, back } = useWizard();
   const providerIndex = MODEL_PROVIDERS.findIndex((option) => option.provider === value.provider);
   const fields = modelFields(value.provider);
   const config = value.configs[value.provider];
@@ -597,10 +378,15 @@ function ModelStep({
     keepFocusedFieldVisible();
   }, [keepFocusedFieldVisible, value.provider, error]);
 
+  useKeyHints([
+    { key: "↑↓", label: "navigate" },
+    { key: "enter", label: "continue" },
+  ]);
+
   useInput((_input, key) => {
     if (focusedField === null) {
       if (key.escape) {
-        onBack();
+        back();
         return;
       }
       if (key.upArrow || key.downArrow) {
@@ -648,7 +434,7 @@ function ModelStep({
         setError(fields[missing]!.requiredError);
         return;
       }
-      onNext();
+      advance();
     }
   });
 
@@ -658,7 +444,7 @@ function ModelStep({
   }));
 
   return (
-    <Box flexDirection="column" paddingX={1} flexGrow={1} minHeight={0}>
+    <Box flexDirection="column" flexGrow={1} minHeight={0}>
       <ScrollView
         ref={scrollRef}
         flexGrow={1}
@@ -668,7 +454,6 @@ function ModelStep({
       >
         <FormRadioGroup
           key="provider"
-          name="choose a model"
           helpText="the provider and model that will power the harness"
           options={options}
           focusedIndex={providerIndex}
@@ -705,63 +490,3 @@ function ModelStep({
     </Box>
   );
 }
-
-function ReviewStep({
-  values,
-  onSubmit,
-  onBack,
-}: {
-  values: CreateProjectFormValues;
-  onSubmit: () => void;
-  onBack: () => void;
-}) {
-  useInput((_input, key) => {
-    if (key.escape) {
-      onBack();
-      return;
-    }
-    if (key.return) onSubmit();
-  });
-
-  return (
-    <Box flexDirection="column" paddingX={1}>
-      <Text color={theme.colors.text}>this project will be created</Text>
-      <Box
-        borderStyle="single"
-        borderColor={theme.colors.border}
-        borderLeft={false}
-        borderRight={false}
-        borderBottom={false}
-      >
-        <KeyValueTable items={summaryOf(values)} />
-      </Box>
-      <Box marginTop={1}>
-        <Text color={theme.colors.muted}>
-          enter scaffolds the project, installs dependencies, and initializes git
-        </Text>
-      </Box>
-    </Box>
-  );
-}
-
-// ─── result panels ────────────────────────────────────────────────────────────
-
-function SuccessPanel({ name, onContinue }: { name: string; onContinue: () => void }) {
-  useInput((_input, key) => {
-    if (key.return || key.escape) onContinue();
-  });
-
-  return (
-    <Box flexDirection="column" gap={1}>
-      <Text color={theme.colors.success} bold>
-        {glyphs.check} project created in ./{name}
-      </Text>
-      <Box flexDirection="column">
-        <Text color={theme.colors.text}>next steps</Text>
-        <Text color={theme.colors.primary}>{`  cd ${name}`}</Text>
-        <Text color={theme.colors.primary}>{"  agentcore project deploy"}</Text>
-      </Box>
-      <Text color={theme.colors.muted}>enter exits</Text>
-    </Box>
-  );
-}
diff --git a/src/handlers/project/index.ts b/src/handlers/project/index.ts
index e50a4f040..303af1809 100644
--- a/src/handlers/project/index.ts
+++ b/src/handlers/project/index.ts
@@ -27,15 +27,17 @@ type ProjectHandlerConfig = {
 export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router {
   const projectManager: ProjectManager = core.projectManager;
   const config = { projectManager, io, bedrockAgentImporter: core.bedrockAgentImporter };
-  // The subcommands with a screen of their own. Every other subcommand — and
-  // everything beneath a group like `add` — is listed in the menu as command
-  // line only and opens its help instead (see CliOnlyScreen).
+  // The subcommands with a screen of their own. Every other subcommand is
+  // listed in the menu as command line only and opens its help instead (see
+  // CliOnlyScreen). `add` is a group: it has the resource menu, and which of
+  // its resources have a wizard is declared on that router.
   const project = new Router("project", "manage an AgentCore project").supportedTuiCommands(
     "create",
     "invoke",
     "build",
     "deploy",
     "status",
+    "add",
   );
 
   // Without a default, a bare `agentcore project` falls back to Commander's help
diff --git a/src/handlers/project/project.screen.test.tsx b/src/handlers/project/project.screen.test.tsx
index af24a228f..25248f4a6 100644
--- a/src/handlers/project/project.screen.test.tsx
+++ b/src/handlers/project/project.screen.test.tsx
@@ -75,7 +75,7 @@ describe("project menu: command-line-only subcommands", () => {
     const r = renderScreen("/agentcore/project");
 
     await waitForText(r.lastFrame, "command line only");
-    const withScreens = ["create", "deploy", "invoke", "build", "status"];
+    const withScreens = ["create", "deploy", "invoke", "build", "status", "add"];
     const { screens, cliOnly } = menuEntries(r.lastFrame()!);
     expect(screens.toSorted()).toEqual(withScreens.toSorted());
     expect(cliOnly.toSorted()).toEqual(
@@ -126,8 +126,10 @@ describe("project menu: command-line-only subcommands", () => {
     r.unmount();
   });
 
+  // These three exercise the help viewport, so they need a command-line-only
+  // resource whose help is longer than the terminal: `add payment-manager`.
   test("growing the terminal after scrolling to the bottom pulls the content back into view", async () => {
-    const r = renderScreen("/agentcore/project/add/runtime");
+    const r = renderScreen("/agentcore/project/add/payment-manager");
     await r.resize(80, 24);
     await waitForText(r.lastFrame, "this command runs from the command line");
     for (let i = 0; i < 80; i++) await r.press("down");
@@ -138,12 +140,12 @@ describe("project menu: command-line-only subcommands", () => {
     // reflows the content, which would mask a clamp that read a stale height.
     await r.resize(80, 120);
     await waitForText(r.lastFrame, "this command runs from the command line");
-    expect(r.lastFrame()).toContain("--role-arn");
+    expect(r.lastFrame()).toContain("--default-spend-limit");
     r.unmount();
   });
 
   test("a key that fills its column still stands clear of its value", async () => {
-    const r = renderScreen("/agentcore/project/add/runtime");
+    const r = renderScreen("/agentcore/project/add/payment-manager");
     await r.resize(40, 60);
     // Narrow enough that the intro wraps and the key column hits its cap.
     await waitForFlatText(r.lastFrame, "this command runs from the command line");
@@ -157,7 +159,7 @@ describe("project menu: command-line-only subcommands", () => {
   });
 
   test("every option is reachable on a small terminal", async () => {
-    const r = renderScreen("/agentcore/project/add/runtime");
+    const r = renderScreen("/agentcore/project/add/payment-manager");
     await r.resize(80, 24);
     await waitForText(r.lastFrame, "this command runs from the command line");
 
@@ -170,7 +172,7 @@ describe("project menu: command-line-only subcommands", () => {
       await r.press("down");
       collect();
     }
-    const compiled = projectCommand("add", "runtime");
+    const compiled = projectCommand("add", "payment-manager");
     for (const option of compiled.options) {
       if (option.long && option.long !== "--help") expect(seen).toContain(option.long);
     }

From 4fb735c047f0258e6db69c37f3a79a9855061014 Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Fri, 11 Sep 2026 18:04:41 +0000
Subject: [PATCH 2/5] fix(wizard): dispatch bare add runtime to the wizard,
 tighten name validation

- a bare `project add runtime` on a TTY now opens the wizard: the add router
  uses withTuiWhenInteractive, which is withTuiOnEmptyFlagsAndArgs behind a TTY
  gate. Flags, --json and non-TTY runs stay headless. The same middleware
  replaces the hand-rolled dispatch shims on create and status.
- text fields validate the value as typed rather than a trimmed copy, so a step
  cannot accept " my_agent " and then submit it.
- one shared RuntimeNameSchema (42 characters, the memory-name cap less
  "Memory") behind both --name and the wizard.
---
 src/components/wizard/fields.tsx              |  16 +-
 src/components/wizard/wizard.test.tsx         |  27 ++-
 src/handlers/project/add/index.ts             |  18 +-
 src/handlers/project/add/runtime/index.ts     |   4 +-
 .../add/runtime/runtime.screen.test.tsx       | 158 +++++++++++++++++-
 src/handlers/project/add/runtime/screen.tsx   |  27 +--
 src/handlers/project/index.ts                 |  59 ++-----
 src/middleware/index.tsx                      |   2 +-
 src/middleware/withTuiOnEmptyFlagsAndArgs.tsx |  24 +++
 src/projectSchemas/runtime.ts                 |  12 ++
 10 files changed, 277 insertions(+), 70 deletions(-)

diff --git a/src/components/wizard/fields.tsx b/src/components/wizard/fields.tsx
index 2bf57b3d2..8b69e6d39 100644
--- a/src/components/wizard/fields.tsx
+++ b/src/components/wizard/fields.tsx
@@ -43,13 +43,17 @@ function validateEntry(
   value: string,
   { label, required, schema, json = false }: ValidateOptions,
 ): string | undefined {
-  const trimmed = value.trim();
-  if (trimmed === "") return required ? `${label} is required` : undefined;
-
-  let parsed: unknown = trimmed;
+  // Blankness is the one thing judged on a trimmed copy: whitespace alone is
+  // nothing entered. Everything else is checked exactly as typed, so a field
+  // cannot pass a value its own caller then submits unchanged — " my_agent "
+  // is refused here rather than written to the project spec as a name with
+  // spaces in it. (JSON.parse ignores surrounding whitespace of its own accord.)
+  if (value.trim() === "") return required ? `${label} is required` : undefined;
+
+  let parsed: unknown = value;
   if (json) {
     try {
-      parsed = JSON.parse(trimmed);
+      parsed = JSON.parse(value);
     } catch (cause) {
       return `${label} is not valid JSON: ${(cause as Error).message}`;
     }
@@ -74,7 +78,7 @@ export interface TextFieldProps {
   // before the TUI middleware can open a screen), so required-ness is stated
   // here the same way the handlers state it in their own bodies.
   required?: boolean;
-  // schema validates the trimmed value before advancing. Pass the schema the
+  // schema validates the value as typed before advancing. Pass the schema the
   // flag declares.
   schema?: z.ZodType;
   // json parses the value before validating it. A JSON flag belongs here rather
diff --git a/src/components/wizard/wizard.test.tsx b/src/components/wizard/wizard.test.tsx
index bcecf811c..2861ae357 100644
--- a/src/components/wizard/wizard.test.tsx
+++ b/src/components/wizard/wizard.test.tsx
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { useState } from "react";
+import z from "zod";
 import { render } from "ink-testing-library";
 import { render as inkRender } from "ink";
 import { cleanupScreens, keys, tick, ttyTestIO, waitFor } from "../../testing";
@@ -20,6 +21,10 @@ interface HarnessOptions {
   onDone?: () => void;
 }
 
+// A schema with a shape a stray space breaks, the way a resource-name schema
+// does: it is what makes "validated as typed" observable.
+const NAME_SCHEMA = z.string().regex(/^[A-Za-z]+$/, "letters only");
+
 const YES_NO = [
   { value: false, label: "no", description: "skip the extra question" },
   { value: true, label: "yes", description: "ask the extra question" },
@@ -45,7 +50,7 @@ function TestWizard({ onSubmit, onCancel, onError, onDone }: HarnessOptions) {
       successHint="enter exits"
     >
       <Step name="name" question="what is your name?">
-        <TextField label="name" value={name} onChange={setName} required />
+        <TextField label="name" value={name} onChange={setName} required schema={NAME_SCHEMA} />
       </Step>
 
       <Step name="branch" question="want the extra question?">
@@ -287,6 +292,26 @@ describe("Wizard shell", () => {
     d.unmount();
   });
 
+  test("a field validates what it would submit, not a trimmed copy of it", async () => {
+    let submitted: string | undefined;
+    const d = drive({
+      onSubmit: async () => {
+        submitted = "reached";
+      },
+    });
+
+    await waitForFrame(d, "what is your name?");
+    await d.write(" Ada ");
+    await d.press("return");
+
+    // The step keeps the value as typed, so it must refuse it here rather than
+    // pass a trimmed copy and submit the padded one.
+    await waitForFrame(d, "letters only");
+    expect(d.lastFrame()).toContain("what is your name?");
+    expect(submitted).toBeUndefined();
+    d.unmount();
+  });
+
   test("a required field blocks the step until it is filled", async () => {
     const d = drive();
 
diff --git a/src/handlers/project/add/index.ts b/src/handlers/project/add/index.ts
index 2672ec057..c80a52e80 100644
--- a/src/handlers/project/add/index.ts
+++ b/src/handlers/project/add/index.ts
@@ -1,5 +1,6 @@
-import { withProject } from "../../../middleware/";
+import { withProject, withTuiWhenInteractive } from "../../../middleware/";
 import { Router } from "../../../router";
+import type { Core } from "../../types";
 import { createAddConfigBundleHandler } from "./config-bundle";
 import { createAddCredentialsHandler } from "./credentials";
 import { createAddHarnessHandler } from "./harness";
@@ -17,12 +18,23 @@ import type { AddProjectResourceConfig } from "./types";
 import { createAddPaymentConnectorHandler } from "./payment-connector";
 import { createAddPaymentManagerHandler } from "./payment-manager";
 
-export function createAddProjectResourceHandler(config: AddProjectResourceConfig): Router {
+export function createAddProjectResourceHandler(
+  config: AddProjectResourceConfig,
+  core: Core,
+): Router {
   // The resources with a wizard of their own. Every other resource is listed in
   // the add menu as command line only and opens its help instead (see
   // CliOnlyScreen).
   const projectAdd = new Router("add", "add project resources").supportedTuiCommands("runtime");
-  projectAdd.use(withProject({ projectManager: config.projectManager, cwd: process.cwd() }));
+  // withProject first, so it is the outermost wrapper: a resource added outside
+  // a project gets the CLI's own not-found guidance, and the resolved project
+  // seeds the wizard through ProjectKey. withTuiWhenInteractive then opens that
+  // wizard for a bare `add <resource>` on a TTY; it is inert for a resource
+  // declared command-line only above, and for flags, --json and non-TTY runs.
+  projectAdd.use(
+    withProject({ projectManager: config.projectManager, cwd: process.cwd() }),
+    withTuiWhenInteractive(core, config.io),
+  );
   projectAdd.handler(createAddConfigBundleHandler(config));
   projectAdd.handler(createAddHarnessHandler(config));
   projectAdd.handler(createAddMemoryHandler(config));
diff --git a/src/handlers/project/add/runtime/index.ts b/src/handlers/project/add/runtime/index.ts
index 54965ad00..6d8960716 100644
--- a/src/handlers/project/add/runtime/index.ts
+++ b/src/handlers/project/add/runtime/index.ts
@@ -3,7 +3,7 @@ import { createHandler, flag, ProjectKey } from "../../../../router";
 import type { AddProjectResourceConfig } from "../types";
 import { parseJsonFlag, parseTags } from "../../../utils";
 import { InputValidationError } from "../../../../errors";
-import { type EnvVar } from "../../../../projectSchemas/runtime";
+import { RuntimeNameSchema, type EnvVar } from "../../../../projectSchemas/runtime";
 import { RuntimeAuthorizerTypeSchema } from "../../../../projectSchemas/auth";
 import { NetworkModeSchema } from "../../../../projectSchemas/constants";
 import { SourceResolver } from "../../../../io";
@@ -52,7 +52,7 @@ export const createAddRuntimeHandler = (config: AddProjectResourceConfig) =>
     name: "runtime",
     description: "add a Runtime to the current project",
     flags: [
-      flag("name", "the name of the Runtime", z.string().max(42).optional()),
+      flag("name", "the name of the Runtime", RuntimeNameSchema.optional()),
       flag("description", "an optional description of the Runtime", z.string().optional()),
       flag(
         "type",
diff --git a/src/handlers/project/add/runtime/runtime.screen.test.tsx b/src/handlers/project/add/runtime/runtime.screen.test.tsx
index ff64887e3..8e2e5dac8 100644
--- a/src/handlers/project/add/runtime/runtime.screen.test.tsx
+++ b/src/handlers/project/add/runtime/runtime.screen.test.tsx
@@ -6,8 +6,17 @@ import {
   waitForFlatText,
   flatFrame,
   cleanupScreens,
+  createSilentLogger,
+  TestCoreClient,
+  TestGlobalConfigAccessor,
+  testIO,
+  ttyTestIO,
+  waitFor,
   type RenderScreenResult,
 } from "../../../../testing";
+import { createRootHandler } from "../../../index";
+import { InputValidationError } from "../../../../errors";
+import type { AppIO } from "../../../../io";
 import { createGatewayProjectTestHarness } from "../gateway-test-support";
 
 const { cleanup, inProject, projectSpec } = createGatewayProjectTestHarness("add-runtime-wizard");
@@ -23,11 +32,22 @@ async function selectTemplate(r: RenderScreenResult, template: string): Promise<
     // 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;
-    await r.press("up");
+    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 marker; the stepper's markers sit mid-line.
+      .filter((line) => /^[●○] /.test(line))
+  );
+}
+
 async function runtimeInSpec(projectRoot: string, name: string) {
   const spec = await projectSpec(projectRoot);
   return spec.runtimes.find((candidate: { name: string }) => candidate.name === name);
@@ -42,9 +62,11 @@ 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.
+    // 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(flatFrame(r.lastFrame)).toContain("● agent-python-minimal ");
+    expect(templateRows(r.lastFrame()!)[0]).toStartWith("● agent-python-minimal ");
     await r.press("return");
 
     await waitForText(r.lastFrame, "what is this runtime for?");
@@ -126,6 +148,35 @@ describe("project add runtime wizard", () => {
     r.unmount();
   });
 
+  test("the name is held to the same length limit as --name", async () => {
+    await inProject();
+    const r = renderScreen("/agentcore/project/add/runtime");
+
+    await waitForText(r.lastFrame, "what should this runtime be called?");
+    // 43 characters: one past what the flag path accepts, and what its own
+    // test rejects there.
+    await r.write("a".repeat(43));
+
+    await waitForText(r.lastFrame, "Must be at most 42 characters");
+    r.unmount();
+  });
+
+  test("a name that is only valid once trimmed is refused, not silently trimmed", async () => {
+    const projectRoot = await inProject();
+    const r = renderScreen("/agentcore/project/add/runtime");
+
+    await waitForText(r.lastFrame, "what should this runtime be called?");
+    await r.write(" orders_agent ");
+    await r.press("return");
+
+    // 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(await runtimeInSpec(projectRoot, " orders_agent ")).toBeUndefined();
+    r.unmount();
+  });
+
   test("esc on the first step returns to the add menu", async () => {
     await inProject();
     const r = renderScreen("/agentcore/project/add/runtime");
@@ -137,3 +188,104 @@ describe("project add runtime wizard", () => {
     r.unmount();
   });
 });
+
+// These drive the real CLI entrypoint rather than mounting the screen, because
+// what they cover is the routing in front of it: a bare `project add runtime`
+// has to reach the wizard, and everything else has to stay headless.
+describe("project add runtime dispatch", () => {
+  function buildRoot(io: AppIO) {
+    return createRootHandler(new TestCoreClient(), {
+      io,
+      logger: createSilentLogger(),
+      globalConfigAccessor: new TestGlobalConfigAccessor(),
+    });
+  }
+
+  const MISSING_NAME = "required option '--name <name>' not specified";
+
+  async function routeError(io: AppIO, args: string[]): Promise<unknown> {
+    return buildRoot(io)
+      .route(["node", "agentcore", "project", "add", "runtime", ...args])
+      .then(
+        () => undefined,
+        (caught: unknown) => caught,
+      );
+  }
+
+  test("bare add runtime in a TTY session opens the wizard", async () => {
+    await inProject();
+    const { streams, stdin } = ttyTestIO();
+
+    // outcome never rejects, so a mid-pump failure cannot trip bun's
+    // unhandled-rejection detection before the final assertion.
+    const outcome = buildRoot(streams.io)
+      .route(["node", "agentcore", "project", "add", "runtime"])
+      .then(
+        () => ({ ok: true as const }),
+        (error: unknown) => ({ ok: false as const, error }),
+      );
+    let settled = false;
+    void outcome.finally(() => {
+      settled = true;
+    });
+
+    // The wizard never finishes on its own; Ctrl+C (re-sent until the app
+    // reacts, slowly enough that repeats cannot coalesce into one chunk) closes
+    // it and resolves the route cleanly. The headless branch would instead
+    // reject with the missing --name usage error.
+    await waitFor(
+      () => {
+        if (!settled) stdin.write("\x03");
+        return settled;
+      },
+      5000,
+      150,
+    );
+    expect(await outcome).toEqual({ ok: true });
+    expect(streams.stderr()).not.toContain("required option");
+  }, 10000);
+
+  test("bare add runtime without a TTY stays headless and reports the missing --name", async () => {
+    await inProject();
+
+    const error = await routeError(testIO().io, []);
+
+    expect(error).toBeInstanceOf(InputValidationError);
+    expect((error as Error).message).toContain(MISSING_NAME);
+  });
+
+  test("any user-supplied flag stays headless even in a TTY", async () => {
+    await inProject();
+
+    const error = await routeError(ttyTestIO().streams.io, ["--description", "an agent"]);
+
+    expect(error).toBeInstanceOf(InputValidationError);
+    expect((error as Error).message).toContain(MISSING_NAME);
+  });
+
+  test("--json stays headless even in a TTY", async () => {
+    await inProject();
+
+    const error = await routeError(ttyTestIO().streams.io, ["--json"]);
+
+    expect(error).toBeInstanceOf(InputValidationError);
+    expect((error as Error).message).toContain(MISSING_NAME);
+  });
+
+  test("flag-driven add runtime still runs headless in a TTY session", async () => {
+    const projectRoot = await inProject();
+    const { streams } = ttyTestIO();
+
+    await buildRoot(streams.io).route([
+      "node",
+      "agentcore",
+      "project",
+      "add",
+      "runtime",
+      "--name",
+      "flag_agent",
+    ]);
+
+    expect(await runtimeInSpec(projectRoot, "flag_agent")).toBeDefined();
+  }, 10000);
+});
diff --git a/src/handlers/project/add/runtime/screen.tsx b/src/handlers/project/add/runtime/screen.tsx
index 8bcceb0a6..458b49ab2 100644
--- a/src/handlers/project/add/runtime/screen.tsx
+++ b/src/handlers/project/add/runtime/screen.tsx
@@ -1,7 +1,11 @@
 import { useState } from "react";
 import { useNavigate } from "react-router";
 import { ProjectKey } from "../../../../router";
-import { AgentNameSchema, ProjectRuntimeSchema } from "../../../../projectSchemas/runtime";
+import {
+  ProjectRuntimeSchema,
+  RUNTIME_NAME_MAX_LENGTH,
+  RuntimeNameSchema,
+} from "../../../../projectSchemas/runtime";
 import type { ScreenProps } from "../../../types";
 import type { Project } from "../../types";
 import { ProjectGate } from "../../ProjectGate";
@@ -28,13 +32,16 @@ const ADD_MENU = "/agentcore/project/add";
 /** The template `add runtime` scaffolds when none is named, as on the flag path. */
 const DEFAULT_TEMPLATE: RuntimeTemplateShortcutName = "agent-python-minimal";
 
-const TEMPLATE_CHOICES: Choice<RuntimeTemplateShortcutName>[] = RUNTIME_TEMPLATE_SHORTCUT_NAMES.map(
-  (template) => ({
-    value: template,
-    label: template,
-    description: RUNTIME_TEMPLATE_SHORTCUTS[template].description,
-  }),
-);
+// The default is listed first, so the step opens on its first row rather than
+// partway down the list — the same place create's opens.
+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,
+}));
 
 interface RuntimeFormValues {
   name: string;
@@ -112,12 +119,12 @@ function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenPro
       <Step name="name" question="what should this runtime be called?">
         <TextField
           label="Name"
-          help="also the directory under app/ · letters, digits and underscores, starting with a letter"
+          help={`also the directory under app/ · letters, digits and underscores, starting with a letter (max ${RUNTIME_NAME_MAX_LENGTH})`}
           placeholder="my_agent"
           value={values.name}
           onChange={(name) => set({ name })}
           required
-          schema={AgentNameSchema}
+          schema={RuntimeNameSchema}
           live
         />
       </Step>
diff --git a/src/handlers/project/index.ts b/src/handlers/project/index.ts
index 303af1809..39a26c39d 100644
--- a/src/handlers/project/index.ts
+++ b/src/handlers/project/index.ts
@@ -1,10 +1,10 @@
-import { Router, type Handler } from "../../router";
+import { Router } from "../../router";
 import { checkPort, openBrowser, startHttpServer, watchFile, type AppIO } from "../../io";
 import { CodeZipDevRunner } from "../../core/dev/codezip";
 import { ContainerDevRunner } from "../../core/dev/container";
 import { InspectorAssets } from "../../core/dev/inspectorAssets";
 import { startOtelCollector } from "../../core/dev/otel/collector";
-import { withProject, withTuiOnEmptyFlagsAndArgs } from "../../middleware";
+import { withProject, withTuiWhenInteractive } from "../../middleware";
 import { renderTui } from "../../tui";
 import type { Core } from "../types";
 import { createCreateProjectHandler } from "./create";
@@ -45,30 +45,11 @@ export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router
   project.default(renderTui(core, io));
 
   // A bare `agentcore project create` in an interactive session opens the TUI
-  // create wizard; any user-supplied flag or --json keeps the headless handler.
-  // The TTY gate wraps the middleware (rather than living inside it) so a
-  // piped/CI invocation also stays headless and reports the missing --name as
-  // a usage error instead of renderTui's "interactive mode requires a TTY".
-  const createProject = createCreateProjectHandler({
-    projectManager,
-    io,
-  });
-  const createProjectWithWizard = withTuiOnEmptyFlagsAndArgs(core, io)(createProject);
-  const isInteractive = () => io.stdin.isTTY === true && io.stdout.isTTY === true;
-  const createProjectDispatch: Handler = {
-    name: () => createProject.name(),
-    description: () => createProject.description(),
-    flags: () => createProject.flags(),
-    arguments: () => createProject.arguments(),
-    doesSupportTui: () => createProject.doesSupportTui(),
-    children: () => createProject.children(),
-    handle: (ctx, flags, args) =>
-      isInteractive()
-        ? createProjectWithWizard.handle(ctx, flags, args)
-        : createProject.handle(ctx, flags, args),
-  };
-  project.handler(createProjectDispatch);
-  project.handler(createAddProjectResourceHandler(config));
+  // create wizard; any user-supplied flag, --json, or a non-TTY invocation keeps
+  // the headless handler (see withTuiWhenInteractive).
+  const tuiWhenInteractive = withTuiWhenInteractive(core, io);
+  project.handler(tuiWhenInteractive(createCreateProjectHandler({ projectManager, io })));
+  project.handler(createAddProjectResourceHandler(config, core));
   project.handler(createExportProjectResourceHandler({ projectManager, core, io }));
   project.handler(
     withProject({ projectManager: config.projectManager })(
@@ -103,24 +84,14 @@ export function createProjectHandler({ core, io }: ProjectHandlerConfig): Router
   project.handler(createProjectInvokeHandler(core, io));
   // A bare `agentcore project status` in an interactive session opens the TUI
   // linked-resources screen; any user-supplied flag, --json, or a non-TTY
-  // invocation keeps the headless JSON report (same dispatch shape as create).
-  // withProject stays outermost so the not-found guidance outside a project is
-  // the CLI's own, and the resolved project seeds the screen via ProjectKey.
-  const statusProject = createStatusProjectHandler({ projectManager: config.projectManager });
-  const statusProjectWithTui = withTuiOnEmptyFlagsAndArgs(core, io)(statusProject);
-  const statusProjectDispatch: Handler = {
-    name: () => statusProject.name(),
-    description: () => statusProject.description(),
-    flags: () => statusProject.flags(),
-    arguments: () => statusProject.arguments(),
-    doesSupportTui: () => statusProject.doesSupportTui(),
-    children: () => statusProject.children(),
-    handle: (ctx, flags, args) =>
-      isInteractive()
-        ? statusProjectWithTui.handle(ctx, flags, args)
-        : statusProject.handle(ctx, flags, args),
-  };
-  project.handler(withProject({ projectManager: config.projectManager })(statusProjectDispatch));
+  // invocation keeps the headless JSON report. withProject stays outermost so
+  // the not-found guidance outside a project is the CLI's own, and the resolved
+  // project seeds the screen via ProjectKey.
+  project.handler(
+    withProject({ projectManager: config.projectManager })(
+      tuiWhenInteractive(createStatusProjectHandler({ projectManager: config.projectManager })),
+    ),
+  );
   // withProject wraps only the commands that require an existing project, so
   // `create` (which refuses to nest inside one) stays unaffected.
   project.handler(
diff --git a/src/middleware/index.tsx b/src/middleware/index.tsx
index 9a87c9d68..90d47c98c 100644
--- a/src/middleware/index.tsx
+++ b/src/middleware/index.tsx
@@ -1,5 +1,5 @@
 export { withRegion } from "./withRegion";
-export { withTuiOnEmptyFlagsAndArgs } from "./withTuiOnEmptyFlagsAndArgs";
+export { withTuiOnEmptyFlagsAndArgs, withTuiWhenInteractive } from "./withTuiOnEmptyFlagsAndArgs";
 export { withJsonRenderer } from "./withJsonRenderer";
 export { withLogging } from "./withLogging";
 export { withGlobalConfigAccessor } from "./withGlobalConfigAccessor";
diff --git a/src/middleware/withTuiOnEmptyFlagsAndArgs.tsx b/src/middleware/withTuiOnEmptyFlagsAndArgs.tsx
index 4574b0aa6..bd89ca433 100644
--- a/src/middleware/withTuiOnEmptyFlagsAndArgs.tsx
+++ b/src/middleware/withTuiOnEmptyFlagsAndArgs.tsx
@@ -54,3 +54,27 @@ export function withTuiOnEmptyFlagsAndArgs(core: Core, io: AppIO): Middleware {
     },
   });
 }
+
+// withTuiWhenInteractive is withTuiOnEmptyFlagsAndArgs behind a TTY gate: a bare
+// invocation opens the TUI only in an interactive session. The gate sits here
+// rather than inside renderTui so that a piped or CI run stays headless and
+// reports a missing required flag as the usage error it is, instead of
+// renderTui's "interactive mode requires a TTY".
+export function withTuiWhenInteractive(core: Core, io: AppIO): Middleware {
+  const withTui = withTuiOnEmptyFlagsAndArgs(core, io);
+  const isInteractive = () => io.stdin.isTTY === true && io.stdout.isTTY === true;
+
+  return (h) => {
+    const interactive = withTui(h);
+    return {
+      name: () => h.name(),
+      description: () => h.description(),
+      flags: () => h.flags(),
+      arguments: () => h.arguments(),
+      doesSupportTui: () => h.doesSupportTui(),
+      children: () => h.children(),
+      handle: (ctx, flags, args) =>
+        isInteractive() ? interactive.handle(ctx, flags, args) : h.handle(ctx, flags, args),
+    };
+  };
+}
diff --git a/src/projectSchemas/runtime.ts b/src/projectSchemas/runtime.ts
index d5bd8e2e5..abbf64291 100644
--- a/src/projectSchemas/runtime.ts
+++ b/src/projectSchemas/runtime.ts
@@ -21,6 +21,18 @@ export const AgentNameSchema = z
     /^[a-zA-Z][a-zA-Z0-9_]{0,47}$/,
     "Must begin with a letter and contain only alphanumeric characters and underscores (max 48 chars)",
   );
+// RUNTIME_NAME_MAX_LENGTH is six characters short of the 48 a name may hold,
+// because a runtime scaffolds a memory called `${runtimeName}Memory` (see
+// getDefaultMemorySpec) and MemoryNameSchema caps that at 48.
+export const RUNTIME_NAME_MAX_LENGTH = 42;
+
+// RuntimeNameSchema is the one runtime-name rule: the `--name` flag and the
+// interactive wizard both validate against it, so neither accepts a name the
+// other rejects.
+export const RuntimeNameSchema = AgentNameSchema.max(
+  RUNTIME_NAME_MAX_LENGTH,
+  `Must be at most ${RUNTIME_NAME_MAX_LENGTH} characters`,
+);
 export const EnvVarNameSchema = z
   .string()
   .min(1)

From 022bd11798083da89dc1cd571f3819a1eea0dceb Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Fri, 11 Sep 2026 18:54:31 +0000
Subject: [PATCH 3/5] refactor(wizard): drop the description step from add
 runtime
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The wizard asks only what scaffolding a runtime needs — name and template.
--description still sets one on the flag path.
---
 .../add/runtime/runtime.screen.test.tsx       | 13 +-----
 src/handlers/project/add/runtime/screen.tsx   | 46 ++++++-------------
 2 files changed, 16 insertions(+), 43 deletions(-)

diff --git a/src/handlers/project/add/runtime/runtime.screen.test.tsx b/src/handlers/project/add/runtime/runtime.screen.test.tsx
index 8e2e5dac8..def7b25f9 100644
--- a/src/handlers/project/add/runtime/runtime.screen.test.tsx
+++ b/src/handlers/project/add/runtime/runtime.screen.test.tsx
@@ -54,7 +54,7 @@ async function runtimeInSpec(projectRoot: string, name: string) {
 }
 
 describe("project add runtime wizard", () => {
-  test("collects a name, template and description, then writes the runtime", async () => {
+  test("collects a name and a template, then writes the runtime", async () => {
     const projectRoot = await inProject();
     const r = renderScreen("/agentcore/project/add/runtime");
 
@@ -69,21 +69,15 @@ describe("project add runtime wizard", () => {
     expect(templateRows(r.lastFrame()!)[0]).toStartWith("● agent-python-minimal ");
     await r.press("return");
 
-    await waitForText(r.lastFrame, "what is this runtime for?");
-    await r.write("answers questions about orders");
-    await r.press("return");
-
     await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
     const review = flatFrame(r.lastFrame);
     expect(review).toContain("runtime orders_agent");
     expect(review).toContain("template agent-python-minimal");
-    expect(review).toContain("description answers questions about orders");
     await r.press("return");
 
     await waitForText(r.lastFrame, "added runtime 'orders_agent' to 'TestProject'");
 
     expect(await runtimeInSpec(projectRoot, "orders_agent")).toMatchObject({
-      description: "answers questions about orders",
       build: "CodeZip",
       entrypoint: "main.py",
       codeLocation: "app/orders_agent",
@@ -105,10 +99,6 @@ describe("project add runtime wizard", () => {
     await selectTemplate(r, "agent-python-strands-container");
     await r.press("return");
 
-    // The description is optional, so a blank answer advances.
-    await waitForText(r.lastFrame, "what is this runtime for?");
-    await r.press("return");
-
     await waitForFlatText(r.lastFrame, "build Container");
     await r.press("return");
 
@@ -116,6 +106,7 @@ describe("project add runtime wizard", () => {
 
     const runtime = await runtimeInSpec(projectRoot, "packing_agent");
     expect(runtime).toMatchObject({ build: "Container", codeLocation: "app/packing_agent" });
+    // 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,
diff --git a/src/handlers/project/add/runtime/screen.tsx b/src/handlers/project/add/runtime/screen.tsx
index 458b49ab2..74ceaae39 100644
--- a/src/handlers/project/add/runtime/screen.tsx
+++ b/src/handlers/project/add/runtime/screen.tsx
@@ -1,11 +1,7 @@
 import { useState } from "react";
 import { useNavigate } from "react-router";
 import { ProjectKey } from "../../../../router";
-import {
-  ProjectRuntimeSchema,
-  RUNTIME_NAME_MAX_LENGTH,
-  RuntimeNameSchema,
-} from "../../../../projectSchemas/runtime";
+import { RUNTIME_NAME_MAX_LENGTH, RuntimeNameSchema } from "../../../../projectSchemas/runtime";
 import type { ScreenProps } from "../../../types";
 import type { Project } from "../../types";
 import { ProjectGate } from "../../ProjectGate";
@@ -46,39 +42,36 @@ const TEMPLATE_CHOICES: Choice<RuntimeTemplateShortcutName>[] = [
 interface RuntimeFormValues {
   name: string;
   template: RuntimeTemplateShortcutName;
-  description: string;
 }
 
 // toRuntimeInput reads the form into the RuntimeInput toAddRuntimeInput
-// validates. The wizard scaffolds from a template and leaves the infrastructure
-// settings — the role, network, authorizer and lifecycle configuration — at
-// their defaults; those are JSON documents, so they stay on the flag path, as
-// does importing a Bedrock Agent version.
+// validates. The wizard asks only what it takes to scaffold a runtime and
+// leaves the rest at its defaults: the description, the role, the network,
+// authorizer and lifecycle configuration, and importing a Bedrock Agent version
+// all stay on the flag path.
 export function toRuntimeInput(values: RuntimeFormValues): RuntimeInput {
-  const name = values.name.trim();
-  const description = values.description.trim();
   return {
-    name,
-    ...(description !== "" && { description }),
+    name: values.name,
     envVars: [],
-    scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(values.template, { runtimeName: name }),
+    scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(values.template, {
+      runtimeName: values.name,
+    }),
   };
 }
 
 function summaryOf(values: RuntimeFormValues): Record<string, string> {
   const template = RUNTIME_TEMPLATE_SHORTCUTS[values.template];
   return {
-    runtime: values.name.trim(),
+    runtime: values.name,
     template: values.template,
     language: template.language,
     build: template.build,
-    ...(values.description.trim() === "" ? {} : { description: values.description.trim() }),
   };
 }
 
 // AddRuntimeScreen is the interactive flow behind a bare `agentcore project add
-// runtime`: name → template → description → review, then the add itself,
-// streaming the ProjectManager's progress events.
+// runtime`: name → template → review, then the add itself, streaming the
+// ProjectManager's progress events.
 export function AddRuntimeScreen({ ctx, core }: ScreenProps) {
   const navigate = useNavigate();
   return (
@@ -99,7 +92,6 @@ function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenPro
   const [values, setValues] = useState<RuntimeFormValues>({
     name: "",
     template: DEFAULT_TEMPLATE,
-    description: "",
   });
   const set = (update: Partial<RuntimeFormValues>) =>
     setValues((current) => ({ ...current, ...update }));
@@ -112,8 +104,8 @@ function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenPro
       onSubmit={() =>
         core.projectManager.addResource(project, toAddRuntimeInput(toRuntimeInput(values)))
       }
-      runningLabel={`adding runtime ${values.name.trim()}…`}
-      successLabel={`added runtime '${values.name.trim()}' to '${project.name}'`}
+      runningLabel={`adding runtime ${values.name}…`}
+      successLabel={`added runtime '${values.name}' to '${project.name}'`}
       successHint="enter exits"
     >
       <Step name="name" question="what should this runtime be called?">
@@ -138,16 +130,6 @@ function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenPro
         />
       </Step>
 
-      <Step name="description" question="what is this runtime for? (optional)">
-        <TextField
-          label="description"
-          placeholder="answers questions about orders"
-          value={values.description}
-          onChange={(description) => set({ description })}
-          schema={ProjectRuntimeSchema.shape.description}
-        />
-      </Step>
-
       <Step name="review" question="this runtime will be added to agentcore.json">
         <Summary items={summaryOf(values)} />
       </Step>

From 5067cc7e39a83c4ab997687c183bc054da7514e0 Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Fri, 11 Sep 2026 19:13:40 +0000
Subject: [PATCH 4/5] feat(wizard): enter returns to the add menu after adding
 a runtime

Wizard takes a doneLabel so the success footer can name what enter does; add
runtime navigates back instead of exiting, the way build and deploy do.
---
 src/components/wizard/Wizard.tsx                | 17 +++++++++++++----
 .../project/add/runtime/runtime.screen.test.tsx |  6 ++++++
 src/handlers/project/add/runtime/screen.tsx     |  5 ++++-
 3 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/src/components/wizard/Wizard.tsx b/src/components/wizard/Wizard.tsx
index 754d0deae..de7e29846 100644
--- a/src/components/wizard/Wizard.tsx
+++ b/src/components/wizard/Wizard.tsx
@@ -41,8 +41,11 @@ export interface WizardProps {
   // the same block ConfirmAction shows after a successful action.
   successNextSteps?: string[];
   // onDone runs when the success panel is acknowledged; defaults to tearing the
-  // TUI down, which is what a one-shot `project add ...` wants.
+  // TUI down, which is what a one-shot `project create` wants.
   onDone?: () => void;
+  // doneLabel names what enter does on the success panel. Pass "go back" with an
+  // onDone that navigates, the way build and deploy label theirs.
+  doneLabel?: string;
   // onError decides what a failure does. "exit" rejects the waitUntilExit()
   // that renderTuiAt awaits, so the error takes the normal CLI path and the
   // process exits nonzero — right for a one-shot command. "retry" reports the
@@ -65,6 +68,7 @@ export function Wizard({
   successHint,
   successNextSteps,
   onDone,
+  doneLabel = "continue",
   onError = "exit",
 }: WizardProps) {
   const { exit } = useApp();
@@ -162,7 +166,7 @@ export function Wizard({
     <Layout
       breadcrumb={breadcrumb}
       description={description}
-      keyHints={footerHints(phase, hints, retryable)}
+      keyHints={footerHints(phase, hints, retryable, doneLabel)}
     >
       <Box flexDirection="column">
         {phase.kind === "form" && (
@@ -226,9 +230,14 @@ function toError(error: unknown): Error {
 
 // footerHints appends the keys that mean the same thing on every step to
 // whatever the active field published.
-function footerHints(phase: Phase, fieldHints: KeyHint[], retryable: boolean): KeyHint[] {
+function footerHints(
+  phase: Phase,
+  fieldHints: KeyHint[],
+  retryable: boolean,
+  doneLabel: string,
+): KeyHint[] {
   if (phase.kind === "running") return [{ key: "ctrl+c", label: "quit" }];
-  if (phase.kind === "success") return [{ key: "enter", label: "continue" }];
+  if (phase.kind === "success") return [{ key: "enter", label: doneLabel }];
   if (phase.kind === "error") {
     return [
       ...(retryable ? [{ key: "r", label: "retry" }] : []),
diff --git a/src/handlers/project/add/runtime/runtime.screen.test.tsx b/src/handlers/project/add/runtime/runtime.screen.test.tsx
index def7b25f9..3f99a7f1f 100644
--- a/src/handlers/project/add/runtime/runtime.screen.test.tsx
+++ b/src/handlers/project/add/runtime/runtime.screen.test.tsx
@@ -76,6 +76,7 @@ describe("project add runtime wizard", () => {
     await r.press("return");
 
     await waitForText(r.lastFrame, "added runtime 'orders_agent' to 'TestProject'");
+    expect(r.lastFrame()).toContain("[enter] go back");
 
     expect(await runtimeInSpec(projectRoot, "orders_agent")).toMatchObject({
       build: "CodeZip",
@@ -84,6 +85,11 @@ describe("project add runtime wizard", () => {
       runtimeVersion: "PYTHON_3_14",
     });
     expect(await Bun.file(join(projectRoot, "app", "orders_agent", "main.py")).exists()).toBe(true);
+
+    // Enter on the success panel returns to the add menu instead of tearing the
+    // TUI down, so another resource can be added straight away.
+    await r.press("return");
+    await waitForText(r.lastFrame, "add project resources");
     r.unmount();
   });
 
diff --git a/src/handlers/project/add/runtime/screen.tsx b/src/handlers/project/add/runtime/screen.tsx
index 74ceaae39..1c1c6c69c 100644
--- a/src/handlers/project/add/runtime/screen.tsx
+++ b/src/handlers/project/add/runtime/screen.tsx
@@ -106,7 +106,10 @@ function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenPro
       }
       runningLabel={`adding runtime ${values.name}…`}
       successLabel={`added runtime '${values.name}' to '${project.name}'`}
-      successHint="enter exits"
+      // Enter returns to the add menu rather than tearing the TUI down, so a
+      // second resource is one keystroke away — what build and deploy do too.
+      onDone={() => navigate(ADD_MENU)}
+      doneLabel="go back"
     >
       <Step name="name" question="what should this runtime be called?">
         <TextField

From ea5630107ad29cb5e361834d308ba531a7f1f7b4 Mon Sep 17 00:00:00 2001
From: gitikavj <gitikavj@amazon.com>
Date: Fri, 11 Sep 2026 19:55:29 +0000
Subject: [PATCH 5/5] fix(wizard): hand the form back when an add fails

An add screen the user navigated to should not tear the TUI down over a
rejected name: onError=retry reports the failure in the wizard and returns to
the form with the answers intact. project create keeps exit.
---
 .../add/runtime/runtime.screen.test.tsx       | 30 ++++++++++++++++++-
 src/handlers/project/add/runtime/screen.tsx   |  4 +++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/src/handlers/project/add/runtime/runtime.screen.test.tsx b/src/handlers/project/add/runtime/runtime.screen.test.tsx
index 3f99a7f1f..a7cd5af4a 100644
--- a/src/handlers/project/add/runtime/runtime.screen.test.tsx
+++ b/src/handlers/project/add/runtime/runtime.screen.test.tsx
@@ -19,7 +19,8 @@ import { InputValidationError } from "../../../../errors";
 import type { AppIO } from "../../../../io";
 import { createGatewayProjectTestHarness } from "../gateway-test-support";
 
-const { cleanup, inProject, projectSpec } = createGatewayProjectTestHarness("add-runtime-wizard");
+const { cleanup, inProject, projectSpec, run } =
+  createGatewayProjectTestHarness("add-runtime-wizard");
 
 afterEach(cleanup);
 afterEach(cleanupScreens);
@@ -174,6 +175,33 @@ describe("project add runtime wizard", () => {
     r.unmount();
   });
 
+  test("a rejected add reports itself and hands the form back", async () => {
+    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"]);
+    const r = renderScreen("/agentcore/project/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 r.press("return");
+    await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
+    await r.press("return");
+
+    await waitForFlatText(r.lastFrame, "a runtime with name 'orders_agent' already exists");
+    // esc, not a dead TUI: the failure is reported inside the wizard, which then
+    // returns to the form with every answer still in it.
+    await r.press("escape");
+    await waitForText(r.lastFrame, "this runtime will be added to agentcore.json");
+    expect(flatFrame(r.lastFrame)).toContain("runtime orders_agent");
+
+    // The refused add wrote nothing beyond the runtime that was already there.
+    expect((await projectSpec(projectRoot)).runtimes).toHaveLength(2);
+    r.unmount();
+  }, 15000);
+
   test("esc on the first step returns to the add menu", async () => {
     await inProject();
     const r = renderScreen("/agentcore/project/add/runtime");
diff --git a/src/handlers/project/add/runtime/screen.tsx b/src/handlers/project/add/runtime/screen.tsx
index 1c1c6c69c..1670107e1 100644
--- a/src/handlers/project/add/runtime/screen.tsx
+++ b/src/handlers/project/add/runtime/screen.tsx
@@ -110,6 +110,10 @@ function AddRuntimeWizard({ project, core }: { project: Project; core: ScreenPro
       // second resource is one keystroke away — what build and deploy do too.
       onDone={() => navigate(ADD_MENU)}
       doneLabel="go back"
+      // A failure reports itself and hands the form back, for the same reason
+      // success returns to the menu: the user navigated here, so tearing the TUI
+      // down over a rejected name would lose every other answer with it.
+      onError="retry"
     >
       <Step name="name" question="what should this runtime be called?">
         <TextField