@aws/nx-plugin-mcp 1.0.0-rc.60 → 1.0.0-rc.62

package/bin/aws-nx-mcp.js

@@ -53897,7 +53897,7 @@ ${PACKAGE_MANAGERS.map((pm) => buildNxCommand("<options>", pm)).join(" - \n")}
 - Carefully examine the files that have been generated and always refer back to the generator guide when working in a generated project
 - Generate all projects into the \`packages/\` directory
 - After making changes to your projects, fix linting issues, then run a full build
-- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load:runtime-config target after a deployment to point a local website at a sandbox stack.
+- When it's time to start testing a project, suggest to the user that infrastructure is deployed to AWS. For websites, if a runtime-config.json is needed, use the load-runtime-config target after a deployment to point a local website at a sandbox stack.
 
 ## Batching Generators
 

package/docs/get_started/quick-start.mdx

@@ -1,6 +1,6 @@
 ---
 title: Quick Start Guide
-description: A quick start on how to use @aws/nx-plugin.
+description: "A quick start on how to use @aws/nx-plugin."
 ---
 import { Steps } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
@@ -11,6 +11,7 @@ import InstallCommand from '@components/install-command.astro';
 import RunGenerator from '@components/run-generator.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Infrastructure from '@components/infrastructure.astro';
+import EmbeddedGraph from '@components/embedded-graph.astro';
 
 This guide walks you through the basics of installing and using `@aws/nx-plugin` to rapidly build projects on AWS.
 
@@ -51,7 +52,17 @@ cd my-project
 
 ## Step 2: Use Generators to Scaffold your Project
 
-We'll add a tRPC API, React Website, Cognito Authentication, and CDK or Terraform Infrastructure in this quick-start guide. Depending on the type of project you're building, you can choose any combination of generators to quickly bootstrap your project. Check out the __Guides__ in the navigation bar to the left to see the full list of options.
+We'll add a tRPC API, React Website, Cognito Authentication, and CDK or Terraform Infrastructure in this quick-start guide. Depending on the type of project you're building, you can choose any combination of generators to quickly bootstrap your project. Check out the __Generators__ in the navigation bar to the left to see the full list of options, or try the <Link path="get_started/graph-builder">graph builder</Link> to construct your workspace visually.
+
+As a shortcut, you can use the button below to copy the commands to scaffold the full application.
+
+<EmbeddedGraph preset="quick-start" workspace="my-project" iac="cdk" orientation="horizontal" skipWorkspace />
+
+:::tip[Build with AI]
+The <Link path="get_started/building-with-ai">Nx Plugin for AWS MCP Server</Link> is already configured in your workspace, so you can ask your favourite AI coding agent like Kiro or Claude to build these projects for you instead of typing the CLI commands yourself.
+:::
+
+Otherwise, follow the steps below to run each generator yourself.
 
 ### Add a tRPC API
 
@@ -252,7 +263,7 @@ This command will first run `terraform plan` to show you what changes will be ma
 <Steps>
 1. Fetch the `runtime-config.json` file:
 
-    <NxCommands commands={['run demo-website:load:runtime-config']} />
+    <NxCommands commands={['load-runtime-config demo-website']} />
 
 2. Start the local website server
 

package/docs/get_started/tutorials/dungeon-game/1.mdx

@@ -1,6 +1,6 @@
 ---
 title: Set up a monorepo
-description: A walkthrough of how to build an agentic AI-powered dungeon adventure game using the @aws/nx-plugin.
+description: "A walkthrough of how to build an agentic AI-powered dungeon adventure game using the @aws/nx-plugin."
 ---
 
 import { Aside, Code, FileTree, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
@@ -12,6 +12,7 @@ import NxCommands from '@components/nx-commands.astro';
 import InstallCommand from '@components/install-command.astro';
 import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import EmbeddedGraph from '@components/embedded-graph.astro';
 import E2EDiff from '@components/e2e-diff.astro';
 
 import dungeonAdventureArchitecturePng from '@assets/dungeon-game-architecture.png'
@@ -50,11 +51,24 @@ This will set up a NX monorepo within the `dungeon-adventure` directory. When yo
 - aws-nx-plugin.config.mts configuraton for the Nx Plugin for AWS
 </FileTree>
 
-We can now start creating our different sub-projects using the `@aws/nx-plugin`.
-
 <Aside type="tip" title="Commit Often">It is best practice to ensure all your unstaged files are committed in Git before running any generators. This allows you to see what has changed after running your generator via `git diff`.</Aside>
 
-## Task 2: Create a Game API
+## Task 2: Scaffold the Dungeon Adventure Game
+
+With the workspace in place, we scaffold the game's sub-projects — the Game API, Story Agent, Inventory MCP server, game database, and website — along with the connections that wire them together. There are two ways to do this:
+
+- **Quick** — copy the commands straight from the diagram below and run them. The fastest way to reach the same starting point.
+- **Step By Step** — expand the section below to run each generator yourself and examine exactly what each one produces.
+
+The diagram below _is_ the Dungeon Adventure workspace: every project, component, and connection you'll build in this module. Hit **Copy commands** to take the whole series, then run them from within the `dungeon-adventure` directory you created in Task 1.
+
+<EmbeddedGraph preset="dungeon-adventure" workspace="dungeon-adventure" iac="cdk" skipWorkspace />
+
+<Drawer title="Step By Step" trigger="Step By Step: run each generator yourself and see what it produces">
+
+Rather than copying the commands all at once, you can run each generator individually. This is the best way to understand what each generator adds to your workspace. Run each generator in turn, from within the `dungeon-adventure` directory you created in Task 1.
+
+##### Create a Game API
 
 First, let's create our Game API. To do this, create a tRPC API called `GameApi` using these steps:
 
@@ -69,7 +83,9 @@ The root `package.json` is now configured with a `type` of `module`, which means
 For more details on working with TypeScript projects, refer to the <Link path="guides/typescript-project">ts#project generator guide</Link>.
 </Aside>
 
-<Drawer title="ts#api updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#api` files in detail</summary>
+
 Below is a list of all files which have been generated by the `ts#api` generator. We are going to examine some of the key files highlighted in the file tree:
 <FileTree>
 - packages/
@@ -364,20 +380,22 @@ export class GameApi<
 
 This is the CDK construct that defines our `GameApi`. It provides a `defaultIntegrations` method which automatically creates a Lambda function for each procedure in our tRPC API, pointing to the bundled API implementation. This means that at `cdk synth` time, bundling does not occur (opposed to using [NodeJsFunction](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html)) as we have already bundled it as part of the backend project's build target.
 
-</Drawer>
+</details>
 
-## Task 3: Create Story agents
+##### Create the Story Agent
 
-Now let's create our Story Agents.
+Now let's create our Story Agent.
 
-### Story agent: Python project
+###### Story agent: Python project
 
 To create a Python project:
 
 <RunGenerator generator="py#project" requiredParameters={{name:"story"}} noInteractive />
 
 You will see some new files appear in your file tree.
-<Drawer title="py#project updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `py#project` files in detail</summary>
+
 The `py#project` generates these files:
 
 <FileTree>
@@ -396,9 +414,9 @@ The `py#project` generates these files:
 
 This has configured a Python project and [UV Workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with shared virtual environment.
 
-</Drawer>
+</details>
 
-### Story agent
+###### Story agent
 
 To add a Strands agent to the project with the `py#agent` generator:
 
@@ -409,7 +427,9 @@ We choose `--protocol=ag-ui` so the agent speaks the [Agent-User Interaction pro
 :::
 
 You will see some new files appear in your file tree.
-<Drawer title="py#agent updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `py#agent` files in detail</summary>
+
 The `py#agent` generates these files:
 
 <FileTree>
@@ -417,7 +437,6 @@ The `py#agent` generates these files:
   - story/
     - dungeon_adventure_story/ python module
       - agent/
-        - init.py sets up the FastAPI app and middleware
         - main.py entrypoint for your agent in Bedrock AgentCore Runtime
         - agent.py defines an example agent and tools
         - Dockerfile defines the docker image for deployment to AgentCore Runtime
@@ -462,10 +481,15 @@ This creates an example Strands agent and defines a subtraction tool.
 # agent/main.py
 import logging
 import uuid
-
-from ag_ui_strands import StrandsAgent, create_strands_app
-from dungeon_adventure_agent_connection import session_id_context
-from fastapi import Request
+from contextlib import asynccontextmanager
+
+from ag_ui.core import EventType, RunAgentInput, RunErrorEvent
+from ag_ui.encoder import EventEncoder
+from ag_ui_strands import StrandsAgent
+from dungeon_adventure_agent_connection import get_current_session_id, session_id_context
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
 from starlette.middleware.base import BaseHTTPMiddleware
 
 from .agent import get_agent
@@ -474,15 +498,16 @@ logging.basicConfig(level=logging.INFO)
 
 SESSION_ID_HEADER = "x-amzn-bedrock-agentcore-runtime-session-id"
 
-# Create AG-UI agent wrapper
-_agent_ctx = get_agent()
-_agent = _agent_ctx.__enter__()
 
-agui_agent = StrandsAgent(
-    agent=_agent,
-    name="StoryAgent",
-    description="An Agent exposed via the AG-UI protocol.",
-)
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    with get_agent() as agent:
+        app.state.agui_agent = StrandsAgent(
+            agent=agent,
+            name="StoryAgent",
+            description="A Strands Agent exposed via the AG-UI protocol.",
+        )
+        yield
 
 
 class _SessionIdMiddleware(BaseHTTPMiddleware):
@@ -494,12 +519,58 @@ class _SessionIdMiddleware(BaseHTTPMiddleware):
             return await call_next(request)
 
 
-# Create FastAPI app with AG-UI endpoint and health check
-app = create_strands_app(agui_agent, path="/invocations")
+app = FastAPI(title="AWS Strands - StoryAgent", lifespan=lifespan)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
 app.add_middleware(_SessionIdMiddleware)
+
+
+@app.post("/invocations")
+async def invocations(request: Request):
+    # Validate the body manually since AgentCore may omit Content-Type.
+    encoder = EventEncoder(accept=request.headers.get("accept") or "")
+    raw = await request.body()
+    try:
+        input_data = RunAgentInput.model_validate_json(raw)
+    except Exception as exc:
+        message = f"Invalid RunAgentInput: {str(exc)[:200]}"
+
+        async def _bad():
+            yield encoder.encode(RunErrorEvent(type=EventType.RUN_ERROR, message=message, code="BAD_REQUEST"))
+
+        return StreamingResponse(_bad(), media_type=encoder.get_content_type())
+
+    session_id = request.headers.get(SESSION_ID_HEADER) or get_current_session_id()
+
+    async def event_generator():
+        # Re-bind the session: the streaming body runs outside the middleware.
+        with session_id_context(session_id or str(uuid.uuid4())):
+            async for event in request.app.state.agui_agent.run(input_data):
+                try:
+                    yield encoder.encode(event)
+                except Exception as e:
+                    error_event = RunErrorEvent(
+                        type=EventType.RUN_ERROR,
+                        message=f"Encoding error: {e}",
+                        code="ENCODING_ERROR",
+                    )
+                    yield encoder.encode(error_event)
+                    break
+
+    return StreamingResponse(event_generator(), media_type=encoder.get_content_type())
+
+
+@app.get("/ping")
+async def ping():
+    return {"status": "healthy"}
 ```
 
-This is the entrypoint for the agent. Because we selected `--protocol=ag-ui`, the generator wraps our Strands `Agent` with `StrandsAgent` from [`ag_ui_strands`](https://docs.copilotkit.ai/aws-strands/integration) and mounts it on a FastAPI app that speaks the [AG-UI protocol](https://docs.copilotkit.ai/aws-strands/protocol) — this is what CopilotKit will talk to from the React website. The `_SessionIdMiddleware` binds the inbound AgentCore runtime session ID onto a `ContextVar` so any downstream MCP/A2A client we wire up later (e.g. the Inventory MCP server in <Link path="get_started/tutorials/dungeon-game/2">Module 2</Link>) automatically forwards it on its outbound calls. In <Link path="get_started/tutorials/dungeon-game/3">Module 3</Link> we'll also add a `session_manager_provider` so each thread id gets its own `S3SessionManager` and conversation history persists across turns.
+This is the entrypoint for the agent. Because we selected `--protocol=ag-ui`, the generator wraps our Strands `Agent` with `StrandsAgent` from [`ag_ui_strands`](https://docs.copilotkit.ai/aws-strands/integration) and mounts it on a FastAPI app that speaks the [AG-UI protocol](https://docs.copilotkit.ai/aws-strands/protocol) — this is what CopilotKit will talk to from the React website. The agent is built inside a `lifespan` handler — not at import time — so container startup, not module import, owns construction, and each AgentCore session gets its own container. The `_SessionIdMiddleware` binds the inbound AgentCore runtime session ID onto a `ContextVar` so any downstream MCP/A2A client we wire up later (e.g. the Inventory MCP server in <Link path="get_started/tutorials/dungeon-game/2">Module 2</Link>) automatically forwards it on its outbound calls. In <Link path="get_started/tutorials/dungeon-game/3">Module 3</Link> we'll also add a `session_manager_provider` so each thread id gets its own `S3SessionManager` and conversation history persists across turns.
 
 ```ts
 // common/constructs/src/app/agents/story-agent.ts
@@ -561,11 +632,11 @@ This configures a CDK `AgentRuntimeArtifact` which uploads your agent Docker ima
 
 You may notice an extra `Dockerfile`, that references the Docker image from the `story` project, allowing us to co-locate the Dockerfile and agent source code.
 
-</Drawer>
+</details>
 
-## Task 4: Set up inventory tools
+##### Set up the Inventory tools
 
-### Inventory: TypeScript project
+###### Inventory: TypeScript project
 
 Let us create an MCP server to provide tools for our Story Agent to manage a player's inventory.
 
@@ -575,7 +646,9 @@ First, we create a TypeScript project:
 
 This will create an empty TypeScript project.
 
-<Drawer title="ts#project updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#project` files in detail</summary>
+
 The `ts#project` generator generates these files.
 
 <FileTree>
@@ -591,16 +664,18 @@ The `ts#project` generator generates these files.
 - tsconfig.base.json updated to configure an alias for other projects to reference this
 </FileTree>
 
-</Drawer>
+</details>
 
-### Inventory: MCP server
+###### Inventory: MCP server
 
 Next, we'll add an MCP server to our TypeScript project:
 
 <RunGenerator generator="ts#mcp-server" requiredParameters={{project:"inventory"}} noInteractive />
 
 This will add an MCP server.
-<Drawer title="ts#mcp-server updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#mcp-server` files in detail</summary>
+
 The `ts#mcp-server` generator generates these files.
 
 <FileTree>
@@ -623,9 +698,9 @@ The `ts#mcp-server` generator generates these files.
         - inventory-mcp-server.ts construct for deploying your inventory MCP server to AgentCore Runtime
 </FileTree>
 
-</Drawer>
+</details>
 
-## Task 5: Create the game database
+##### Create the game database
 
 Our game state — saved games and each player's inventory — lives in [Amazon DynamoDB](https://aws.amazon.com/dynamodb/). Create a DynamoDB project called `DungeonDb` with the `ts#dynamodb` generator:
 
@@ -636,7 +711,9 @@ The `ts#dynamodb` generator vends a `dev` target that runs [DynamoDB Local](http
 :::
 
 You will see some new files appear in your file tree.
-<Drawer title="ts#dynamodb updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#dynamodb` files in detail</summary>
+
 The `ts#dynamodb` generator generates these files.
 
 <FileTree>
@@ -669,13 +746,13 @@ The generated `src/client.ts` exports `getDynamoDBClient()` and `resolveTableNam
 
 For more details, refer to the <Link path="guides/ts-dynamodb">ts#dynamodb generator guide</Link>.
 
-</Drawer>
+</details>
 
-## Task 6: Create the User Interface (UI)
+##### Create the User Interface (UI)
 
-In this task, we will create the UI which will allow you to interact with the game.
+Next, we will create the UI which will allow you to interact with the game.
 
-### Game UI: Website
+###### Game UI: Website
 
 To create the UI, create a website called `GameUI` using these steps:
 
@@ -687,7 +764,9 @@ We select `--ux=shadcn` so the generated website uses [shadcn/ui](https://ui.sha
 
 You will see some new files appear in your file tree.
 
-<Drawer title="ts#website updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#website` files in detail</summary>
+
 The `ts#website` generates these files. Let us examine some of the key files highlighted in the file tree:
 
 <FileTree>
@@ -802,9 +881,9 @@ function RouteComponent() {
 
 A component will be rendered when navigating to the `/` route. `@tanstack/react-router` will manage the `Route` for you whenever you create/move this file (as long as the dev server is running).
 
-</Drawer>
+</details>
 
-### Game UI: Auth
+###### Game UI: Auth
 
 Let us configure our Game UI to require authenticated access via Amazon Cognito using these steps:
 
@@ -812,7 +891,9 @@ Let us configure our Game UI to require authenticated access via Amazon Cognito
 
 You will see some new files appear/change in your file tree.
 
-<Drawer title="ts#website#auth updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#website#auth` files in detail</summary>
+
 The `ts#website#auth` generator updates/generates these files. Let us examine some of the key files highlighted in the file tree:
 
 <FileTree>
@@ -884,9 +965,9 @@ root &&
 
 The `RuntimeConfigProvider` and `CognitoAuth` components have been added to the `main.tsx` file via an AST transform. This allows the `CognitoAuth` component to authenticate with Amazon Cognito by fetching the `runtime-config.json` which contains the required cognito connection configuration in order to make the backend calls to the correct destination.
 
-</Drawer>
+</details>
 
-### Game UI: Connect to Game API
+###### Game UI: Connect to Game API
 
 Let us configure our Game UI to connect to our previously created Game API.
 
@@ -894,7 +975,9 @@ Let us configure our Game UI to connect to our previously created Game API.
 
 You will see some new files have appear/change in your file tree.
 
-<Drawer title="UI -> tRPC connection updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the UI → tRPC connection files</summary>
+
 The `connection` generator generates/updates these files. Let us examine some of the key files highlighted in the file tree:
 
 <FileTree>
@@ -973,15 +1056,17 @@ root &&
 
 The `main.tsx` file has been updated via an AST transform to inject the tRPC providers.
 
-</Drawer>
+</details>
 
-### Story Agent: Connect to Inventory MCP Server
+###### Story Agent: Connect to Inventory MCP Server
 
 Let us connect our Story Agent to the Inventory MCP server so the agent can discover and invoke the MCP server's tools.
 
 <RunGenerator generator="connection" requiredParameters={{sourceProject:"story", targetProject:"inventory"}} noInteractive />
 
-<Drawer title="Story Agent -> Inventory MCP connection updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the Story Agent → Inventory MCP connection files</summary>
+
 The `connection` generator generates/updates these files:
 
 <FileTree>
@@ -1011,15 +1096,17 @@ The generator:
 - Updates the `dev` target to automatically start the MCP server when running locally
 
 For more details, refer to the <Link path="guides/connection/py-agent-mcp">Python Agent to MCP connection guide</Link>.
-</Drawer>
+</details>
 
-### Game UI: Connect to Story Agent
+###### Game UI: Connect to Story Agent
 
 Let us connect our Game UI to the Story Agent. Since the agent speaks AG-UI, the `connection` generator wires up [CopilotKit](https://docs.copilotkit.ai/): a themed chat component and an `@ag-ui/client` `HttpAgent` ready to render.
 
 <RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-ui", targetProject:"story"}} noInteractive />
 
-<Drawer title="UI -> Story Agent connection updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the UI → Story Agent connection files</summary>
+
 The `connection` generator generates/updates these files:
 
 <FileTree>
@@ -1043,9 +1130,9 @@ The generator:
 - Reads the agent's runtime ARN from Runtime Configuration, builds the AgentCore invocation URL, and attaches the Cognito bearer token plus the AgentCore session id header.
 
 For more details, refer to the <Link path="guides/connection/react-agui">React to AG-UI connection guide</Link>.
-</Drawer>
+</details>
 
-### Connect the Game API and Inventory MCP server to the database
+###### Connect the Game API and Inventory MCP server to the database
 
 Both the Game API and the Inventory MCP server read and write our DynamoDB table, so let us connect them to the `DungeonDb` project. The `connection` generator detects that the target is a `ts#dynamodb` project and wires each source project's `dev` target to start DynamoDB Local automatically.
 
@@ -1057,7 +1144,7 @@ Both the Game API and the Inventory MCP server read and write our DynamoDB table
 Because the Story Agent's `agent-dev` already depends on the Inventory MCP server's `mcp-server-dev` (via the `story → inventory` connection above), and both the Game API and MCP server now depend on `dungeon-db:dev`, running any one project's `dev` target starts every dependency it needs in the right order.
 </Aside>
 
-### Game UI: Infrastructure
+###### Game UI: Infrastructure
 
 Let us create the final sub-project for the CDK infrastructure.
 
@@ -1065,7 +1152,9 @@ Let us create the final sub-project for the CDK infrastructure.
 
 You will see some new files have appear/change in your file tree.
 
-<Drawer title="ts#infra updated files" trigger="Click here to examine these files in more detail.">
+<details>
+<summary>Examine the generated `ts#infra` files in detail</summary>
+
 The `ts#infra` generator generates/updates these. Let us examine some of the key files highlighted in the file tree:
 
 <FileTree>
@@ -1131,9 +1220,11 @@ export class ApplicationStack extends Stack {
 
 Let us instantiate our CDK constructs to build our dungeon adventure game.
 
+</details>
+
 </Drawer>
 
-## Task 7: Update our infrastructure
+## Task 3: Update our infrastructure
 
 Let's update `packages/infra/src/stacks/application-stack.ts` to instantiate some of our generated constructs:
 
@@ -1143,7 +1234,7 @@ Let's update `packages/infra/src/stacks/application-stack.ts` to instantiate som
 We supply default integrations for our Game API. By default, each operation in our API is mapped to an individual Lambda function to handle that operation.
 :::
 
-## Task 8: Build the code
+## Task 4: Build the code
 
 <Drawer title="Nx commands" trigger="Now it's time for us to build our code for the first time">
 

package/docs/get_started/tutorials/dungeon-game/4.mdx

@@ -146,11 +146,11 @@ You've seen two ends of the spectrum: everything local (`dev`) and everything de
 
 The key is the `RUNTIME_CONFIG_APP_ID` environment variable. When a project runs **without** `LOCAL_DEV=true`, the runtime config lookups fetch their configuration from AWS AppConfig using this application id — the `RuntimeConfigApplicationId` value from your CDK outputs.
 
-Each website has a `load:runtime-config` target that downloads the deployed `runtime-config.json` (Cognito pool, API endpoints, agent ARN) into the local dev server. Some useful combinations:
+Each website has a `load-runtime-config` target that downloads the deployed `runtime-config.json` (Cognito pool, API endpoints, agent ARN) into the local dev server. Some useful combinations:
 
 - **Local website → deployed backend.** Pull the deployed config once, then run the plain `serve` target so the UI talks to the deployed API and agent:
 
-  <NxCommands commands={["run game-ui:load:runtime-config"]} />
+  <NxCommands commands={["load-runtime-config game-ui"]} />
   <NxCommands commands={["serve game-ui"]} />
 
 - **Local API → real DynamoDB table.** Run the plain `serve` target with `RUNTIME_CONFIG_APP_ID` set to the deployed application id:

package/docs/guides/py-agent.mdx

@@ -383,8 +383,8 @@ Most users will not need to modify this file; edit `agent.py` to change tools or
 
 The generated `main.py` exposes a single POST endpoint that streams [AG-UI](https://docs.ag-ui.com/) events over Server-Sent Events (SSE), as well as `/ping` for the AgentCore runtime health check. The wiring depends on the framework:
 
-- **Strands**: wraps your `Agent` in an `ag_ui_strands.StrandsAgent` and creates the FastAPI app via `create_strands_app()`.
-- **LangChain**: wraps the compiled graph in an `ag_ui_langgraph.LangGraphAgent` and serves it from a hand-rolled FastAPI `/invocations` loop.
+- **Strands**: wraps your `Agent` in an `ag_ui_strands.StrandsAgent`, built inside a FastAPI `lifespan` handler (so construction happens at container/session startup rather than import time), and served from a hand-rolled FastAPI `/invocations` loop.
+- **LangChain**: wraps the compiled graph in an `ag_ui_langgraph.LangGraphAgent`, built the same way inside `lifespan`, and served from a hand-rolled FastAPI `/invocations` loop.
 
 Most users will not need to modify this file — edit `agent.py` to change tools or the system prompt.
 

package/docs/guides/react-website.mdx

@@ -326,19 +326,19 @@ For details on how runtime configuration is stored in AWS AppConfig and how serv
 
 When running the [local development server](#local-development-server), you will need a `runtime-config.json` file in your `public` directory in order for your local website to know the backend URLs, identity configuration, etc.
 
-Your website project is configured with a `load:runtime-config` target which you can use to pull down the `runtime-config.json` file from a deployed application:
+Your website project is configured with a `load-runtime-config` target which you can use to pull down the `runtime-config.json` file from a deployed application:
 
-<NxCommands commands={['run <my-website>:"load:runtime-config"']} />
+<NxCommands commands={['load-runtime-config <my-website>']} />
 
 :::note[Custom Stage Names]
 <Infrastructure>
 <Fragment slot="cdk">
-If you change the prefix for your stage names in your infrastructure project's `src/main.ts`, you will need to update the `load:runtime-config` target in your website's `project.json` file accordingly.
+If you change the prefix for your stage names in your infrastructure project's `src/main.ts`, you will need to update the `load-runtime-config` target in your website's `project.json` file accordingly.
 
-Additionally it's worth noting that the `load:runtime-config` target assumes a single stage of your application is deployed to the environment you have AWS credentials for. You will need to adjust the command if you deploy multiple stages to the same account and region.
+Additionally it's worth noting that the `load-runtime-config` target assumes a single stage of your application is deployed to the environment you have AWS credentials for. You will need to adjust the command if you deploy multiple stages to the same account and region.
 </Fragment>
 <Fragment slot="terraform">
-For Terraform projects, the `load:runtime-config` target copies the `runtime-config.json` file that was created after your most recent local `terraform apply`.
+For Terraform projects, the `load-runtime-config` target copies the `runtime-config.json` file that was created after your most recent local `terraform apply`.
 </Fragment>
 </Infrastructure>
 :::

package/docs/snippets/prerequisites.mdx

@@ -10,6 +10,8 @@ import Snippet from '@components/snippet.astro';
 
 ### Recommended
 
+- [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
+  - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version`
 - [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account are required to deploy your application (as well as for some local development workflows).
 - [Docker](https://www.docker.com/) or [Finch >= 1.6.0](https://runfinch.com/) is required for some generators. For Docker, [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) must be set up; Finch supports [multi-platform builds](https://runfinch.com/docs/getting-started/building-images/#building-a-multi-architecture-container-image) out of the box.
 - [Terraform >= 1.12](https://developer.hashicorp.com/terraform/install) is required if you choose to use this for infrastructure as code instead of CDK

package/docs/snippets/required-prerequisites.mdx

@@ -4,8 +4,6 @@ title: Required Prerequisites
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 - [Node >= 22](https://nodejs.org/en/download) (We recommend using something like [NVM](https://github.com/nvm-sh/nvm) to manage your node versions)
   - verify by running `node --version`
-- [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
-  - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version`
 - [UV >= 0.5.29](https://docs.astral.sh/uv/getting-started/installation/)
   1. install Python 3.14 by running: `uv python install 3.14.0`
   2. verify with `uv python list --only-installed`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.60",
+  "version": "1.0.0-rc.62",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",