@aws/nx-plugin-mcp 1.0.0-rc.4 → 1.0.0-rc.41

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

@@ -0,0 +1,237 @@
+---
+title: Implement the Game API and Inventory MCP server
+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';
+import { Image } from 'astro:assets';
+import Link from '@components/link.astro';
+import Drawer from '@components/drawer.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import InstallCommand from '@components/install-command.astro';
+import E2EDiff from '@components/e2e-diff.astro';
+import E2ECode from '@components/e2e-code.astro';
+import Snippet from '@components/snippet.astro';
+
+import dungeonAdventureArchitecturePng from '@assets/dungeon-game-architecture.png'
+import baselineWebsitePng from '@assets/baseline-website.png'
+import baselineGamePng from '@assets/baseline-game.png'
+import nxGraphPng from '@assets/nx-graph.png'
+import gameSelectPng from '@assets/game-select.png'
+import gameConversationPng from '@assets/game-conversation.png'
+
+import { getDungeonAdventureElectroDbDependencies } from '../../../../../../../../e2e/src/utils';
+
+## Task 1: Implement the Game API
+
+We will implement the following APIs in this section:
+
+1. `saveGame` - create or update a game.
+2. `queryGames` - return a paginated list of previously saved games.
+3. `queryInventory` - return a paginated list of items in a player's inventory.
+4. `queryActions` - return the conversation history for a given game.
+
+:::note[Where each piece of state lives]
+- `games` and `inventory` are in **DynamoDB** (via ElectroDB) — the Game API lambdas and the Inventory MCP server read/write them.
+- `actions` (chat transcript) is in **S3** — the Story Agent's `S3SessionManager` writes one JSON blob per turn, and `queryActions` in the Game API reads them back so the UI can replay history on page reload. There's no `saveAction` procedure; the agent is the only writer.
+:::
+
+### API schema
+
+To define our API inputs and outputs, let's create our schema using [Zod](https://zod.dev/) within the `packages/game-api/src/schema/index.ts` file as follows:
+
+<E2EDiff lang="typescript" before="dungeon-adventure/2/schema/index.ts.old.template" after="dungeon-adventure/2/schema/index.ts.template" />
+
+Delete the `packages/game-api/src/schema/echo.ts` file as we will not be using it in this project.
+
+<Aside type="tip" title="Automatic Type Inference">
+For each of the schemas we define in Zod, we also export an interface using the `z.TypeOf` syntax. This converts our Zod definition into a Typescript interface without having to duplicate effort.
+</Aside>
+
+### Entity modelling
+
+This is the ER diagram for our application.
+
+```d2
+direction: right
+
+game: Game {
+  shape: sql_table
+  playerName: "string  PK"
+  genre: string
+  lastUpdated: string
+}
+
+item: Item {
+  shape: sql_table
+  playerName: "string  PK"
+  itemName: "string  SK"
+  emoji: "string  (optional)"
+  lastUpdated: string
+  quantity: number
+}
+
+game -> item: 1..*
+```
+
+The `ts#dynamodb` generator set up [ElectroDB](https://electrodb.dev/en/core-concepts/introduction/), which we will use to model our data. We will persist conversation history in S3, so we add a dependency on the S3 client:
+
+<InstallCommand pkg={getDungeonAdventureElectroDbDependencies()} />
+
+<Aside title="Root Dependencies">
+All dependencies are added to the root `package.json` as the `@aws/nx-plugin` follows the [single version policy](https://nx.dev/concepts/decisions/dependency-management#single-version-policy) principle. For more information, refer to the <Link path="guides/typescript-project#dependencies">ts#project guide</Link>.
+</Aside>
+
+Replace the generated example entity in `packages/dungeon-db/src/entities/index.ts` with our `Game` and `Inventory` entities, and delete `packages/dungeon-db/src/entities/example.ts`:
+
+<E2ECode lang="typescript" path="dungeon-adventure/2/dungeon-db/entities/index.ts.template" />
+
+ElectroDB allows us to not only define our types, but can also provide defaults for certain values like timestamps. In addition, ElectroDB follows [single-table design](https://electrodb.dev/en/core-concepts/single-table-relationships/) which is the best practice when using DynamoDB.
+
+<Aside title="ElectroDB Collections">
+Whilst ElectroDB does support [collections](https://electrodb.dev/en/modeling/collections/), we have chosen not to use them in this tutorial for simplicity.
+</Aside>
+
+### Defining our procedures
+
+To implement the API methods, make the following changes within `packages/game-api/src/procedures`:
+
+<Tabs>
+  <TabItem label="games.ts">
+<E2ECode lang="typescript" path="dungeon-adventure/2/procedures/games.ts.template" />
+  </TabItem>
+  <TabItem label="inventory.ts">
+<E2ECode lang="typescript" path="dungeon-adventure/2/procedures/inventory.ts.template" />
+  </TabItem>
+  <TabItem label="actions.ts">
+<E2ECode lang="typescript" path="dungeon-adventure/2/procedures/actions.ts.template" />
+  </TabItem>
+</Tabs>
+
+Delete the `echo.ts` file (from `packages/game-api/src/procedures`) as we will not be using it in this project.
+
+### Router setup
+
+After we define our procedures, to wire them into our API, update the following file:
+
+<Tabs>
+  <TabItem label="packages/game-api/src/router.ts">
+<E2EDiff lang="typescript" before="dungeon-adventure/2/router.ts.old.template" after="dungeon-adventure/2/router.ts.template" />
+</TabItem>
+</Tabs>
+
+## Task 2: Create an Inventory MCP server
+
+Let us create an MCP server which will allow our agent to manage items in a player's inventory.
+
+We'll define the following tools for our agent:
+
+- `list-inventory-items` for retrieving the player's current inventory items
+- `add-to-inventory` for adding items to the player's inventory
+- `remove-from-inventory` for removing items from the player's inventory
+
+To save time, we will define all the tools inline:
+
+<Tabs>
+  <TabItem label="packages/inventory/src/mcp-server/server.ts">
+<E2EDiff lang="typescript" before="dungeon-adventure/2/mcp/server.ts.old.template" after="dungeon-adventure/2/mcp/server.ts.template" />
+</TabItem>
+</Tabs>
+
+As the number of tools grow, you can refactor them out into separate files if you like.
+
+Delete the `tools` and `resources` directories in `packages/inventory/src/mcp-server` as these will not be used.
+
+## Task 3: Update the infrastructure
+
+The `DungeonDb` construct generated by `ts#dynamodb` already provisions our table, so we just need to instantiate it in our stack and grant the Game API and Inventory MCP server the permissions they need. Update `packages/infra/src/stacks/application-stack.ts` as follows:
+
+<E2EDiff lang="typescript" before="dungeon-adventure/1/application-stack.ts.template" after="dungeon-adventure/2/stacks/application-stack.ts.template" />
+
+:::note[Isolated Procedures]
+Notice here that since each procedure is served by an individual lambda function, we can follow the principle of least privilege and assign only the required read/write permissions based on the procedure's implementation.
+:::
+
+:::tip[Runtime Configuration]
+The `DungeonDb` construct registers the deployed table name in <Link path="guides/runtime-config">Runtime Configuration</Link> under the `dynamodb` namespace, stored in AWS AppConfig. The Game API and Inventory MCP server retrieve it at runtime using Lambda Powertools, rather than needing it passed as an environment variable. A benefit of this approach is that as the number of tables or other infrastructure identifiers grows, you only need a single `RUNTIME_CONFIG_APP_ID` environment variable when running against deployed infrastructure.
+:::
+
+## Task 4: Test the Game API locally
+
+There's no need to deploy to AWS to try out our API — the `dev` target runs the Game API against [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html). Because we connected the Game API to the `DungeonDb` project in Module 1, this target also starts DynamoDB Local automatically.
+
+First, fix any lint issues:
+
+<PackageManagerShortCommand commands={["lint"]} />
+
+Then build the codebase:
+
+<PackageManagerShortCommand commands={["build"]} />
+
+### Start the local server
+
+Start the Game API locally with the `dev` target, which also boots DynamoDB Local:
+
+<NxCommands commands={["dev game-api"]} />
+
+<Aside type="tip" title="First run">
+The first run pulls the DynamoDB Local container image, which may take a moment. Leave the server running in this terminal and open a second terminal for the `curl` commands below.
+</Aside>
+
+### Test the API
+
+Once your server is up and running, query the (empty) list of games:
+
+```bash
+curl -X GET 'http://localhost:2022/games.query?input=%7B%7D'
+```
+
+:::note[URL Encoding]
+The `%7B%7D` we pass to test the API is a URI encoded empty JSON object (`{}`).
+:::
+
+You will see an empty list:
+
+```json
+{"result":{"data":{"items":[],"cursor":null}}}
+```
+
+Now save a game:
+
+```bash
+curl -X POST 'http://localhost:2022/games.save' \
+  -H 'Content-Type: application/json' \
+  -d '{"playerName":"Alice","genre":"zombie"}'
+```
+
+The save returns the persisted game (with the `lastUpdated` timestamp the entity sets for you):
+
+```json
+{"result":{"data":{"playerName":"Alice","genre":"zombie","lastUpdated":"..."}}}
+```
+
+Query again to confirm it's persisted in DynamoDB Local:
+
+```bash
+curl -X GET 'http://localhost:2022/games.query?input=%7B%7D'
+```
+
+This response now includes the saved game:
+
+```json
+{"result":{"data":{"items":[{"playerName":"Alice","genre":"zombie","lastUpdated":"..."}],"cursor":null}}}
+```
+
+You can stop the local server (`Ctrl+C`) once you're done.
+
+## Task 5: Test the Inventory MCP server locally
+
+We can try out the MCP server's tools with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) using the generated `mcp-server-inspect` target:
+
+<NxCommands commands={["mcp-server-inspect inventory"]} />
+
+This serves the MCP server locally (booting DynamoDB Local too) and launches the MCP Inspector at `http://localhost:6274` pre-configured to connect to it. Click **Connect**, switch to the **Tools** tab, click **List Tools**, and try `add-to-inventory` (e.g. `playerName: Alice`, `itemName: Rusty Sword`, `emoji: ⚔️`) followed by `list-inventory-items` to see it persisted to DynamoDB Local. Stop the server (`Ctrl+C`) when you're done.
+
+Congratulations, you have built and tested your first tRPC API and MCP server against a local DynamoDB table!  🎉🎉🎉

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

@@ -0,0 +1,76 @@
+---
+title: Implement and configure the Story agent
+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';
+import { Image } from 'astro:assets';
+import Drawer from '@components/drawer.astro';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import InstallCommand from '@components/install-command.astro';
+import E2ECode from '@components/e2e-code.astro';
+import E2EDiff from '@components/e2e-diff.astro';
+
+import dungeonAdventureArchitecturePng from '@assets/dungeon-game-architecture.png'
+import baselineWebsitePng from '@assets/baseline-website.png'
+import baselineGamePng from '@assets/baseline-game.png'
+import nxGraphPng from '@assets/nx-graph.png'
+import gameSelectPng from '@assets/game-select.png'
+import gameConversationPng from '@assets/game-conversation.png'
+
+## Task 1: Implement the Story Agent
+
+The Story Agent is a [Strands](https://strandsagents.com/) agent generated with `--protocol=AG-UI` in <Link path="get_started/tutorials/dungeon-game/1">Module 1</Link>, so the UI can stream from it over the [Agent-User Interaction protocol](https://docs.copilotkit.ai/aws-strands/protocol) via CopilotKit. It uses the Inventory MCP Server to manage the player's items, and Strands' built-in [`S3SessionManager`](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/agents/sessions/) to persist conversation history into the sessions bucket we provisioned in Module 2.
+
+### Agent implementation
+
+Update the following files in `packages/story/dungeon_adventure_story/agent`:
+
+<Tabs>
+  <TabItem label="main.py">
+<E2EDiff lang="python" before="dungeon-adventure/3/main.py.old.template" after="dungeon-adventure/3/main.py.template" />
+  </TabItem>
+  <TabItem label="agent.py">
+<E2EDiff lang="python" before="dungeon-adventure/3/agent.py.old.template" after="dungeon-adventure/3/agent.py.template" />
+  </TabItem>
+</Tabs>
+
+The changes are:
+
+- `main.py` adds a `session_manager_provider` that creates an `S3SessionManager` per `thread_id` when deployed, and falls back to an on-disk `FileSessionManager` under `/tmp/strands-sessions` when running under `agent-dev` (`LOCAL_DEV=true`). Deployed, the S3 bucket is the same one the Game API's `queryActions` reads from, so the browser can rebuild transcripts on revisit; locally the agent persists sessions to disk and talks to the local MCP server, without a deployment.
+- `agent.py` drops the sample `subtract` tool and swaps the system prompt for a dungeon-master one that invites the first user message to state the player's name and genre, and uses the Inventory MCP Server's tools.
+
+## Task 2: Test your Agent locally
+
+### Build the code
+
+To build the code:
+
+<PackageManagerShortCommand commands={["build"]} />
+
+<Aside type="tip" title="Fixing Lint Errors">
+If you encounter any lint errors, run the following command to automatically fix them.
+
+<PackageManagerShortCommand commands={["lint"]} />
+</Aside>
+
+### Chat with your Agent
+
+The generated `agent-chat` target opens an interactive REPL against your agent. It runs standalone and connects to your locally-running agent, so first start the agent's local server in one terminal:
+
+<NxCommands commands={["agent-dev story"]} />
+
+Then, in a second terminal, start the chat:
+
+<NxCommands commands={["agent-chat story"]} />
+
+Your first message should tell the agent your hero's name and the genre (for example: `My name is Alice. Start my zombie adventure.`) and the story will stream back.
+
+<Aside type="caution" title="AWS credentials required">
+Although the agent runs locally, it invokes [Amazon Bedrock](https://aws.amazon.com/bedrock/) for the LLM. You'll need AWS credentials in your environment with access to the [Strands default model](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/amazon-bedrock/). See the [Strands model provider documentation](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/amazon-bedrock/) for details.
+</Aside>
+
+Congratulations. You have built and tested your first Strands Agent locally!  🎉🎉🎉

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

@@ -0,0 +1,162 @@
+---
+title: Build the UI
+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';
+import { Image } from 'astro:assets';
+import Link from '@components/link.astro';
+import Drawer from '@components/drawer.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import InstallCommand from '@components/install-command.astro';
+import E2ECode from '@components/e2e-code.astro';
+import E2EDiff from '@components/e2e-diff.astro';
+
+import dungeonAdventureArchitecturePng from '@assets/dungeon-game-architecture.png'
+import baselineWebsitePng from '@assets/baseline-website.png'
+import baselineGamePng from '@assets/baseline-game.png'
+import nxGraphPng from '@assets/nx-graph.png'
+import gameSelectPng from '@assets/game-select.png'
+import gameConversationPng from '@assets/game-conversation.png'
+
+## Task 1: Run everything locally
+
+Start the full local stack — the game-ui dev server together with a local Game API and a local AG-UI Story Agent (which in turn boots the Inventory MCP server) — with one command:
+
+<NxCommands commands={["dev game-ui"]} />
+
+The `dev` target on `game-ui` has `dependsOn` on `game-api:dev` and `dungeon_adventure.story:agent-dev`, so Nx spins up every project's local server in parallel. Through the connections we set up in Module 1, those in turn boot the Inventory MCP server and DynamoDB Local. Make sure your container engine is running, then open the dev server in a browser.
+
+<Aside type="tip" title="No login locally">
+In `local-dev` mode the `CognitoAuth` component skips the Cognito login flow (there's no user pool running locally), so you'll land straight on the game without signing in. You'll create a real account when we deploy to AWS at the end of this module.
+</Aside>
+
+<Aside type="caution" title="Keep Dev Server Running">
+Leave the dev server running for the rest of this module — it hot-reloads every change below.
+</Aside>
+
+## Task 2: Where CopilotKit is already wired up
+
+When you ran the `connection` generator for `game-ui → story` in <Link path="get_started/tutorials/dungeon-game/1">Module 1</Link>, the Shadcn website's AG-UI integration was generated for you. It's worth a quick look:
+
+<FileTree>
+- packages/game-ui/src/
+  - components/
+    - AguiProvider.tsx Single `CopilotKitProvider` registered with every AG-UI agent.
+    - copilot/
+      - index.tsx Re-exports themed `CopilotChat` / `CopilotSidebar` / `CopilotPopup`.
+      - ShadcnAssistantMessage.tsx, ShadcnUserMessage.tsx, ShadcnChatInput.tsx, ShadcnCursor.tsx, copilot.css
+  - hooks/
+    - useAguiStoryAgent.tsx Instantiates an `@ag-ui/client` `HttpAgent` pointing at the deployed Story Agent and pads `threadId` to AgentCore's 33-character minimum session id.
+  - main.tsx Wraps `<App />` in `<AguiProvider>`
+</FileTree>
+
+All we need to do is drop a `<CopilotChat agentId="agent" threadId={...} />` into a route. For more detail on how the integration is put together, see the <Link path="guides/connection/react-agui">React → AG-UI connection guide</Link>.
+
+## Task 3: Restyle for the dungeon
+
+Replace `packages/game-ui/src/styles.css` — this is the *only* file we change for styling. It imports the shared Shadcn globals, overrides the palette to a torch-lit dungeon theme, and makes CopilotKit inherit those colours:
+
+<E2ECode lang="css" path="dungeon-adventure/4/styles.css.template" />
+
+## Task 4: Create the game routes
+
+We need two routes — one to pick a hero, one to play. Both use shadcn components and the CopilotKit chat; there is no hand-rolled chat UI.
+
+<Tabs>
+<TabItem label="routes/index.tsx">
+<E2EDiff before="dungeon-adventure/4/routes/index.tsx.old.template" after="dungeon-adventure/4/routes/index.tsx.template" lang="tsx" />
+
+This is the game picker: new-game form (shadcn `Input` + `Button` + `Card`) plus a "Continue" list fed by `useGameApi().games.query` with `useInfiniteQuery` — a bottom sentinel `<div>` watched by an `IntersectionObserver` auto-calls `fetchNextPage()` when scrolled into view, and spinners next to the heading and below the list surface the loading state. Starting a game `saveGame`s the `(playerName, genre)` pair (so it shows up next time) and navigates to the play route.
+</TabItem>
+<TabItem label="routes/game/$playerName.tsx">
+<E2ECode path="dungeon-adventure/4/routes/game/$playerName.tsx.template" lang="tsx" />
+
+This is the play route. It builds the deterministic `threadId` (``{player}-{genre}`` padded to 33 chars — the AG-UI hook will send it verbatim as the AgentCore session id), renders `<CopilotChat agentId="agent" threadId={threadId} />`, and overlays the inventory from `useGameApi().inventory.query` on top. On mount, `useGameApi().actions.query({ sessionId: threadId })` reads the conversation history the agent has stored in S3 and — if there is any — calls `agent.setMessages(...)` to rehydrate the chat; otherwise it sends one priming user message to kick the story off. `agent.messages` is subscribed via `useAgent({ updates: [OnMessagesChanged] })` so every new turn also refetches the inventory query (the MCP tool calls mutate DynamoDB directly).
+
+<Aside type="tip" title="Wait for `isFetching`, not `isLoading`">
+React Query's default cache retains the first result for 5 minutes, so a return visit initially sees the stale empty list from the very first load. We set `staleTime: 0` + `refetchOnMount: 'always'` and guard the hydration `useEffect` on `!isFetching && isSuccess` so the re-prime path only fires on a genuinely empty thread.
+</Aside>
+
+<Aside type="tip" title="Deterministic threadIds make /game/$playerName?genre=... sharable">
+Revisiting the same URL — whether after a reload, a redeploy, or on another device — resolves to the same `threadId`, so the agent keeps telling the same story.
+</Aside>
+
+<Aside type="tip" title="Path Parameters">
+The `$playerName` syntax tells `@tanstack/react-router` to treat `playerName` as a [path param](https://tanstack.com/router/v1/docs/framework/react/guide/path-params). `validateSearch` makes `genre` strongly typed against our enum.
+</Aside>
+</TabItem>
+</Tabs>
+
+Once saved, the dev server at `http://localhost:4200/` should now let you start an adventure and chat with the Story Agent.
+
+<Image src={gameSelectPng} alt="game-select.png" width="600" height="309" />
+<div style="margin-top: -100px; margin-left: 100px;">
+<Image src={gameConversationPng} alt="game-conversation.png" width="600" height="310" />
+</div>
+
+## Task 5: Deploy to AWS
+
+Your game is complete and you've tested every piece locally. Now let's deploy it to AWS so you can play it from anywhere.
+
+### Build your code
+
+<PackageManagerShortCommand commands={["build"]} />
+
+### Deploy your application
+
+<NxCommands commands={['deploy infra "dungeon-adventure-infra-sandbox/*"']} />
+
+:::caution[Bootstrap Required]
+If this is the first CDK deployment in your AWS account/region, bootstrap it first:
+
+<NxCommands commands={['bootstrap infra']} />
+:::
+
+Your first deployment will take around 6 minutes to complete as it waits for all resources to fully stabilize. Subsequent deployments are faster. To speed up iteration during development you can opt into [CloudFormation express mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-express-mode.html) by passing the `--express` flag, which completes each resource operation as soon as its configuration is applied rather than waiting for full stabilization.
+
+Once the deployment completes, you will see outputs similar to the following:
+
+```bash
+dungeon-adventure-infra-sandbox-Application
+dungeon-adventure-infra-sandbox-Application: deploying... [2/2]
+
+ ✅  dungeon-adventure-infra-sandbox-Application
+
+✨  Deployment time: 354s
+
+Outputs:
+dungeon-adventure-infra-sandbox-Application.GameApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
+dungeon-adventure-infra-sandbox-Application.GameUIDistributionDomainNameXXX = xxx.cloudfront.net
+dungeon-adventure-infra-sandbox-Application.InventoryMcpArn = arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY
+dungeon-adventure-infra-sandbox-Application.RuntimeConfigApplicationId = xxxx
+dungeon-adventure-infra-sandbox-Application.StoryAgentArn = arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventurecationStoryAgentXXXX-YYYY
+dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityIdentityPoolIdXXX = region:xxx
+dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolClientIdXXX = xxxxxxxxxx
+dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolIdXXX = region_xxx
+```
+
+Navigate to your CloudFront URL (`GameUIDistributionDomainName` from the CDK outputs), sign up for a new account, and play your game running entirely on AWS!
+
+## Task 6: Mixing local and deployed components
+
+You've seen two ends of the spectrum: everything local (`dev`) and everything deployed. During day-to-day development it's often useful to mix the two — for example, iterate on website code against the *real* deployed API and agent, or run the API locally against the *real* DynamoDB table.
+
+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:
+
+- **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={["serve game-ui"]} />
+
+- **Local API → real DynamoDB table.** Run the plain `serve` target with `RUNTIME_CONFIG_APP_ID` set to the deployed application id:
+
+  <NxCommands env={{RUNTIME_CONFIG_APP_ID:"<RuntimeConfigApplicationId from CDK outputs>"}} commands={["serve game-api"]} />
+
+This flexibility lets you test exactly the slice you're working on, against whichever components — local or deployed — make sense.
+
+Congratulations. You have built, tested, and deployed your Agentic Dungeon Adventure Game!  🎉🎉🎉

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

@@ -0,0 +1,144 @@
+---
+title: Agentic AI Dungeon Game
+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';
+import Snippet from '@components/snippet.astro';
+import { Image } from 'astro:assets';
+import Drawer from '@components/drawer.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import InstallCommand from '@components/install-command.astro';
+import Link from '@components/link.astro';
+
+import baselineWebsitePng from '@assets/baseline-website.png'
+import baselineGamePng from '@assets/baseline-game.png'
+import nxGraphPng from '@assets/nx-graph.png'
+import gameSelectPng from '@assets/game-select.png'
+import gameConversationPng from '@assets/game-conversation.png'
+
+
+Using this tutorial, you will build an Agentic AI-powered dungeon adventure game with `@aws/nx-plugin`. This tutorial does not assume any existing knowledge of the `@aws/nx-plugin` or related technologies. 
+The techniques you'll learn in this tutorial will help:
+- Build any `@aws/nx-plugin` based application,
+- Provide a deep understanding of the `@aws/nx-plugin`, and 
+- Get a basic understanding of how to use the [NX](https://nx.dev/) framework.
+
+<Aside title="Hands-on Learning">This tutorial is designed for people who prefer to learn by doing and want to quickly try making something tangible. If you prefer learning each concept step by step, refer to the individual component guides using the left navigation.</Aside>
+
+At the end of the tutorial, you will walk away with the knowledge to:
+
+- use the `@aws/nx-plugin` to create new applications,
+- use NX to manage/build their codebase,
+- build APIs using tRPC,
+- build Agents using Strands,
+- build MCP servers in TypeScript,
+- use Tanstack router to create new pages,
+- use Tanstack query to call backend APIs,
+- model data in DynamoDB and develop locally against DynamoDB Local, and
+- create and deploy CDK infrastructure.
+
+## What are you building?
+
+In this tutorial, you'll build an Agentic AI-powered dungeon adventure game with `@aws/nx-plugin`.
+
+The game interface will resemble something like this diagram:
+
+<Image src={gameSelectPng} alt="game-select.png" width="600" height="309" />
+<div style="margin-top: -100px; margin-left: 100px;">
+<Image src={gameConversationPng} alt="game-conversation.png" width="600" height="310" />
+</div>
+
+### Application architecture
+
+The Agentic AI-powered dungeon adventure game is built using the following architecture:
+
+```d2 inline=true
+direction: down
+
+browser: Web Browser {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+cognito: Cognito / IAM {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cognito.svg
+}
+
+cloudfront: CloudFront {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudfront.svg
+}
+
+s3: Static Assets\n(S3) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/s3.svg
+}
+
+apigw: API Gateway\n(Game API) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/api-gateway.svg
+}
+
+lambda: tRPC API\n(Lambda) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
+}
+
+story: Story Agent\n(AgentCore) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
+}
+
+mcp: Inventory MCP\n(AgentCore) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
+}
+
+ddb: Game State\n(DynamoDB) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/dynamodb.svg
+}
+
+sessions: Story Sessions\n(S3) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/s3.svg
+}
+
+browser -> cognito: Sign in
+browser -> cloudfront
+cloudfront -> s3
+browser -> apigw
+apigw -> lambda
+lambda -> ddb
+lambda -> sessions: Read transcripts
+browser -> story: AG-UI stream
+story -> sessions: Persist turns
+story -> mcp: Tool calls
+mcp -> ddb
+ddb -> sessions: {
+  style.opacity: 0
+}
+```
+
+- React/Vite frontend website utilising:
+  - Amazon Cognito/Identity Pools for secure API calls.
+  - [Tanstack router](https://tanstack.com/router/latest) which supports type-safe file based routing.
+  - Generated SDKs for calling the Game API.
+- [tRPC](https://trpc.io/) API which uses [ElectroDB](https://electrodb.dev/)/[DynamoDB](https://aws.amazon.com/dynamodb/) for managing the game state.
+- [Strands](https://strandsagents.com/) Agent hosted on [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) for running the game.
+- TypeScript MCP Server hosted on [Amazon Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) for the agent to manage the player's inventory.
+- [CDK](https://docs.aws.amazon.com/cdk/v2/guide/home.html) infrastructure to deploy the application.
+
+## Prerequisites
+
+Before you proceed, you will need the following global dependencies:
+
+<Snippet name="required-prerequisites" />
+- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development and for building the AgentCore components
+
+:::tip[AI Assistant Setup]
+If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, refer to the <Link path="/get_started/building-with-ai">install the Nx Plugin for AWS MCP server</Link> page.
+:::

package/docs/get_started/tutorials/dungeon-game/wrap-up.mdx

@@ -0,0 +1,41 @@
+---
+title: Agentic AI Dungeon Game
+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';
+import { Image } from 'astro:assets';
+import Drawer from '@components/drawer.astro';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import InstallCommand from '@components/install-command.astro';
+import dungeonAdventureArchitecturePng from '@assets/dungeon-game-architecture.png'
+import baselineWebsitePng from '@assets/baseline-website.png'
+import baselineGamePng from '@assets/baseline-game.png'
+import nxGraphPng from '@assets/nx-graph.png'
+import gameSelectPng from '@assets/game-select.png'
+import gameConversationPng from '@assets/game-conversation.png'
+
+## Wrap up
+
+Congratulations! You’ve created an Agentic AI Dungeon adventure game that uses many of the available generators found within the `@aws/nx-plugin`.  🎉🎉🎉
+
+## What next?
+
+We recommend you try your hand at extending the codebase with the following capabilities on your own:
+
+1. Add the <Link path="guides/license">license generator</Link> to your project which will automatically manage LICENSE files and source code headers in your workspace.
+2. <Link path="get_started/tutorials/contribute-generator">Contribute your own generator</Link> to simplify the addition on new tRPC APIs.
+3. Add a new `resetToAction` api (using your above generator) in GameAPI which allows you to go back in time and delete all actions from a given point. Update the UI to add a button on a conversation bubble to reset to this point (and call the newly created API).
+4. Explore the various component guides using the left navigation.
+
+## Destroying resources
+
+1. To destroy the AWS resources that were created, run the following command:
+
+<NxCommands commands={['destroy infra "dungeon-adventure-infra-sandbox/*"']} />
+
+    This will prompt you for a list of stacks to delete which should comprise of the `dungeon-adventure-infra-sandbox/Application/GameUI/waf` and `dungeon-adventure-infra-sandbox/Application`.
+
+2. Enter `Y` to continue. CloudFormation will destroy your stacks.