@aws/nx-plugin-mcp 1.0.0-rc.96 → 1.0.0-rc.98

package/bin/aws-nx-mcp.js

@@ -21915,19 +21915,22 @@ const kebabCase = (str) => {
 const NX_VERSION = {
 	"@a2a-js/sdk": "0.3.14",
 	"@aws/aws-distro-opentelemetry-node-autoinstrumentation": "0.12.0",
-	"@opentelemetry/propagator-jaeger": "2.10.0",
+	"@opentelemetry/propagator-jaeger": "2.11.0",
 	minimatch: "10.2.6",
-	"@aws-sdk/client-dynamodb": "3.1121.0",
-	"@aws-sdk/client-api-gateway": "3.1121.0",
-	"@aws-sdk/client-iam": "3.1121.0",
-	"@aws-sdk/client-bedrock-agentcore": "3.1121.0",
-	"@aws-sdk/client-bedrock-runtime": "3.1121.0",
-	"@aws-sdk/client-s3": "3.1121.0",
-	"@aws-sdk/client-sts": "3.1121.0",
-	"@aws-sdk/credential-providers": "3.1121.0",
+	"deepmerge-ts": "8.0.2",
+	mysql2: "3.24.3",
+	"@aws-sdk/client-dynamodb": "3.1126.0",
+	"@aws-sdk/client-api-gateway": "3.1126.0",
+	"@aws-sdk/client-iam": "3.1126.0",
+	"@aws-sdk/client-bedrock-agentcore": "3.1126.0",
+	"@aws-sdk/client-bedrock-runtime": "3.1126.0",
+	"@aws-sdk/client-s3": "3.1126.0",
+	"@aws-sdk/client-sts": "3.1126.0",
+	"@aws-sdk/client-cognito-identity-provider": "3.1126.0",
+	"@aws-sdk/credential-providers": "3.1126.0",
 	"@aws-sdk/credential-provider-cognito-identity": "3.972.69",
-	"@aws-sdk/client-secrets-manager": "3.1121.0",
-	"@aws-sdk/rds-signer": "3.1121.0",
+	"@aws-sdk/client-secrets-manager": "3.1126.0",
+	"@aws-sdk/rds-signer": "3.1126.0",
 	"@smithy/server-apigateway": "0.3.3",
 	"@smithy/server-node": "0.3.3",
 	"@aws-lambda-powertools/logger": "2.35.0",
@@ -21935,7 +21938,7 @@ const NX_VERSION = {
 	"@aws-lambda-powertools/parameters": "2.35.0",
 	"@aws-lambda-powertools/tracer": "2.35.0",
 	"@aws-lambda-powertools/parser": "2.35.0",
-	"@aws-sdk/client-appconfigdata": "3.1121.0",
+	"@aws-sdk/client-appconfigdata": "3.1126.0",
 	"@middy/core": "7.9.2",
 	"@nxlv/python": "23.0.0",
 	"@nx-extend/terraform": "10.4.1",
@@ -21950,14 +21953,14 @@ const NX_VERSION = {
 	"@swc-node/register": "1.12.1",
 	"@swc/core": "1.16.1",
 	"@modelcontextprotocol/sdk": "1.30.0",
-	"@modelcontextprotocol/inspector": "2.4.0",
+	"@modelcontextprotocol/inspector": "2.5.0",
 	"@ag-ui/a2ui-toolkit": "0.0.4",
 	"@ag-ui/aws-strands": "0.2.3",
-	"@ag-ui/client": "0.0.57",
-	"@ag-ui/core": "0.0.57",
-	"@ag-ui/encoder": "0.0.57",
+	"@ag-ui/client": "0.0.59",
+	"@ag-ui/core": "0.0.59",
+	"@ag-ui/encoder": "0.0.59",
 	"agent-chat-cli": "0.3.0",
-	"@copilotkit/react-core": "1.69.3",
+	"@copilotkit/react-core": "1.70.1",
 	rxjs: "7.8.2",
 	"@strands-agents/sdk": "1.15.0",
 	"@tanstack/react-router": "1.170.32",
@@ -21965,46 +21968,46 @@ const NX_VERSION = {
 	"@tanstack/router-generator": "1.167.33",
 	"@tanstack/virtual-file-routes": "1.162.0",
 	"@tanstack/router-utils": "1.162.2",
-	"@cloudscape-design/board-components": "3.0.221",
-	"@cloudscape-design/chat-components": "1.0.165",
-	"@cloudscape-design/components": "3.0.1356",
+	"@cloudscape-design/board-components": "3.0.222",
+	"@cloudscape-design/chat-components": "1.0.166",
+	"@cloudscape-design/components": "3.0.1359",
 	"@cloudscape-design/global-styles": "1.0.67",
 	"@tanstack/react-query": "5.102.8",
 	"@tanstack/react-query-devtools": "5.102.8",
 	"@trpc/tanstack-react-query": "11.18.0",
 	"@trpc/client": "11.18.0",
 	"@trpc/server": "11.18.0",
-	"@types/node": "26.4.0",
-	"@types/aws-lambda": "8.10.162",
+	"@types/node": "26.4.1",
+	"@types/aws-lambda": "8.10.163",
 	"@types/cors": "2.8.19",
 	"@types/pg": "8.23.1",
 	"@types/ws": "8.18.1",
 	"@types/express": "5.0.6",
 	"@smithy/config-resolver": "4.7.2",
 	"@smithy/node-config-provider": "4.6.2",
-	"@smithy/node-http-handler": "4.11.3",
-	"@smithy/types": "4.17.2",
+	"@smithy/node-http-handler": "4.12.1",
+	"@smithy/types": "4.18.0",
 	"@vitest/coverage-v8": "4.1.11",
 	"@vitest/ui": "4.1.11",
-	"@astrojs/react": "6.0.4",
-	"@astrojs/starlight": "0.41.10",
-	astro: "7.2.9",
+	"@astrojs/react": "6.0.5",
+	"@astrojs/starlight": "0.42.0",
+	astro: "7.3.1",
 	cookie: "2.0.1",
 	aws4fetch: "1.0.20",
 	"aws-cdk": "2.1139.0",
-	"aws-cdk-lib": "2.267.0",
+	"aws-cdk-lib": "2.268.0",
 	"aws-xray-sdk-core": "3.12.0",
 	constructs: "10.8.1",
 	cors: "2.8.6",
 	chalk: "6.0.0",
 	"class-variance-authority": "0.7.1",
-	clsx: "2.1.1",
+	cn: "0.2.5",
 	commander: "15.0.0",
 	electrodb: "3.9.3",
 	esbuild: "0.28.2",
 	"event-source-polyfill": "1.0.31",
 	"@types/event-source-polyfill": "1.0.5",
-	"@biomejs/biome": "2.5.11",
+	"@biomejs/biome": "2.5.12",
 	"@prisma/adapter-mariadb": "7.10.0",
 	"@prisma/adapter-pg": "7.10.0",
 	"@prisma/client": "7.10.0",
@@ -22015,8 +22018,8 @@ const NX_VERSION = {
 	husky: "9.1.7",
 	"fs-extra": "11.4.0",
 	"@types/fs-extra": "11.0.4",
-	mariadb: "3.5.3",
-	mise: "2026.8.14",
+	mariadb: "3.5.4",
+	mise: "2026.9.1",
 	npm: "12.0.2",
 	"npm-check-updates": "23.1.0",
 	"oidc-client-ts": "3.5.0",
@@ -22025,24 +22028,23 @@ const NX_VERSION = {
 	"react-oidc-context": "3.3.1",
 	react: "19.2.8",
 	"react-dom": "19.2.8",
-	rolldown: "1.2.6",
-	"rolldown-plugin-dts": "0.28.3",
+	rolldown: "1.2.7",
+	"rolldown-plugin-dts": "0.28.5",
 	shx: "0.4.0",
 	"simple-git": "3.36.0",
 	"source-map-support": "0.5.21",
 	"starlight-blog": "0.29.0",
 	tailwindcss: "4.3.3",
 	"@tailwindcss/vite": "4.3.3",
-	tsx: "4.23.12",
-	"lucide-react": "1.37.0",
+	tsx: "4.23.13",
+	"lucide-react": "1.40.0",
 	"radix-ui": "1.6.7",
-	shadcn: "4.19.0",
+	shadcn: "4.21.0",
 	"tw-animate-css": "1.4.0",
-	"tailwind-merge": "3.6.0",
 	vite: "8.2.2",
 	typescript: "6.0.3",
 	vitest: "4.1.11",
-	jsdom: "27.4.0",
+	jsdom: "29.1.1",
 	zod: "4.5.4",
 	ws: "8.21.3"
 }.nx;
@@ -55046,6 +55048,41 @@ const addToExistingProjectTool = (server, generators) => {
 	});
 };
 //#endregion
+//#region ../nx-plugin/src/mcp-server/tools/best-practices.ts
+/**
+* Guide pages documenting behaviour that spans generators, so no single
+* generator owns them and `generator-guide` never returns them. Each is
+* described for the agent so it can pick the ones relevant to its task.
+*/
+const BEST_PRACTICE_PAGES = {
+	workspace: "Workspace layout, configuration and common commands",
+	"typescript-project": "Conventions for TypeScript projects",
+	"python-project": "Conventions for Python projects",
+	security: "Security controls vended infrastructure carries, and the shared responsibility model",
+	"runtime-config": "How generated projects discover one another through AWS AppConfig",
+	"docker-bundling": "Building and deploying container images",
+	"local-development": "Running projects locally with the serve and dev targets"
+};
+const BEST_PRACTICE_PAGE_NAMES = Object.keys(BEST_PRACTICE_PAGES);
+/**
+* Add a tool which serves the cross-cutting guide pages. Kept separate from
+* `general-guidance` so an agent fetches only the pages its task needs rather
+* than every page on every call.
+*/
+const addBestPracticesTool = (server, generators) => {
+	server.registerTool("best-practices", {
+		title: "Best Practices",
+		description: "Tool to retrieve guidance which spans generators, rather than applying to one in particular. Request the pages relevant to your task:\n" + Object.entries(BEST_PRACTICE_PAGES).map(([page, description]) => `- \`${page}\`: ${description}`).join("\n"),
+		inputSchema: {
+			packageManager: PackageManagerSchema.optional(),
+			pages: array(_enum(BEST_PRACTICE_PAGE_NAMES)).min(1).describe("The guide pages to retrieve.")
+		}
+	}, async ({ packageManager, pages }) => ({ content: [{
+		type: "text",
+		text: await fetchGuidePages(pages, generators, packageManager)
+	}] }));
+};
+//#endregion
 //#region ../nx-plugin/src/utils/iac-providers.ts
 /**
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
@@ -55089,9 +55126,20 @@ Refer to the \`general-guidance\` tool for full workspace documentation includin
 };
 //#endregion
 //#region ../nx-plugin/src/mcp-server/tools/general-guidance.ts
+/**
+* The cross-cutting pages every agent needs regardless of task, inlined here
+* so a workspace's conventions land without a second tool call. The rest are
+* served on demand by `best-practices`.
+*/
+const GENERAL_GUIDANCE_PAGES = [
+	"workspace",
+	"typescript-project",
+	"python-project"
+];
 const TOOL_SELECTION_GUIDE = `## Tool Selection Guide
 
 - Use the \`general-guidance\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.
+- Use the \`best-practices\` tool for guidance which spans generators rather than applying to one in particular, such as workspace layout, security, runtime configuration, container builds and local development.
 - Use the \`create-workspace-command\` tool to discover how to create a workspace to start a new project.
 - Use the \`add-to-existing-project\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.
 - Use the \`upgrade-workspace\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.
@@ -55170,13 +55218,9 @@ ${PACKAGE_MANAGERS.map((pm) => `  \`\`\`bash
 
 ## Detailed Guides
 
-Please refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects.
+Please refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects. Use the \`best-practices\` tool for the remaining cross-cutting guides (${BEST_PRACTICE_PAGE_NAMES.filter((p) => !GENERAL_GUIDANCE_PAGES.includes(p)).map((p) => `\`${p}\``).join(", ")}).
 
-${await fetchGuidePages([
-			"workspace",
-			"typescript-project",
-			"python-project"
-		], generators)}
+${await fetchGuidePages([...GENERAL_GUIDANCE_PAGES], generators)}
 
     `
 	}] }));
@@ -55865,6 +55909,7 @@ on AWS, if the generators apply to your use case.
 ${TOOL_SELECTION_GUIDE}
 ` });
 	addGeneralGuidanceTool(server, generators);
+	addBestPracticesTool(server, generators);
 	addCreateWorkspaceCommandTool(server);
 	addListGeneratorsTool(server, generators);
 	addGeneratorGuideTool(server, generators);

package/docs/get_started/existing-project.mdx

@@ -56,7 +56,7 @@ Nx and the plugin are distributed as npm packages, so a project with no Node.js
 }
 ```
 
-Create that file, then run `nx init` and [add the plugin](#adding-the-plugin) as usual. Your existing language tooling is untouched — Nx projects generated by the plugin (including <Link path="guides/py-project">Python projects</Link>) live alongside your existing code, and you can wire your existing build into Nx incrementally.
+Create that file, then run `nx init` and [add the plugin](#adding-the-plugin) as usual. Your existing language tooling is untouched — Nx projects generated by the plugin (including <Link path="guides/python-project">Python projects</Link>) live alongside your existing code, and you can wire your existing build into Nx incrementally.
 
 To bring your existing projects under Nx, you have a few options depending on the language:
 
@@ -124,12 +124,15 @@ It creates or updates the following files:
 - tsconfig.json a root TypeScript config referencing your workspace's projects, which Nx's TypeScript sync keeps up to date
 - tsconfig.base.json the shared compiler options the plugin's TypeScript projects extend (see below for what it carries)
 - pnpm-workspace.yaml (pnpm only) allow-lists the build scripts the plugin's dependencies need (`@swc/core`, `esbuild`, `nx`, `sharp`)
-- package.json convenience scripts for common tasks, plus the `@aws/nx-plugin`, `@aws/nx-plugin-mcp`, `nx`, `@nx/js`, `@nx/workspace`, `typescript` and Biome dev dependencies
+- package.json convenience scripts for common tasks, a `prepare` script that installs the git hooks, plus the `@aws/nx-plugin`, `@aws/nx-plugin-mcp`, `nx`, `@nx/js`, `@nx/workspace`, `typescript`, husky and Biome dev dependencies
 - biome.json default Biome formatter and linter configuration
+- .git-secrets/ the vendored [git-secrets](https://github.com/awslabs/git-secrets) script, with `.gitallowed` for false positives and a `.husky/pre-commit` hook that runs it — see <Link path="guides/workspace#git-secrets">Git Secrets</Link>
 - .mcp.json configures the MCP server for supported coding agents unless disabled (also .cursor/, .kiro/, .gemini/, .vscode/ and .codex/ equivalents). It runs the workspace's own `@aws/nx-plugin-mcp`, so the server always matches the version installed in your workspace
 </FileTree>
 
-The <Link path="get_started/building-with-ai">MCP server</Link> configuration can be disabled with `--mcp=false`.
+The <Link path="get_started/building-with-ai">MCP server</Link> configuration can be disabled with `--mcp=false`, and the credential scanning hooks with `--gitSecrets=false`.
+
+Files you already have are preserved: an existing `.husky/pre-commit` hook or `prepare` script is left as it is, and the generator prints what to add so credential scanning runs alongside your own checks. An existing `.gitallowed` keeps every pattern it has.
 
 <Drawer title="tsconfig.base.json" trigger="Click here to see the compiler options a created tsconfig.base.json carries.">
 The plugin's TypeScript projects rely on these compiler options. If a `tsconfig.base.json` already exists it is left as-is, so if you keep your own these are the options to align with:
@@ -159,7 +162,7 @@ pnpm skips install scripts for packages that aren't allow-listed. `init` allow-l
 
 #### `nx sync` hangs, or `plugin worker ... exited before the connection was established`
 
-If two different `nx` versions are present in the same node_modules tree (run `npm ls nx` to confirm), their plugin-worker IPC deadlocks. The `init` generator pins the root `nx` devDependency to the version the plugin's own `@nx/*` packages resolve, but a later install of another `@nx/*` package at a different patch version can reintroduce the mismatch. Align every `nx` and `@nx/*` entry in your root `package.json` to a single version and reinstall.
+If two different `nx` versions are present in the same node_modules tree (run `npm ls nx` to confirm), their plugin-worker IPC deadlocks. `init` declares the `nx` and `@nx/*` versions the plugin is built against, but it never downgrades a version your workspace already has: a workspace already on a newer `nx` keeps it, and the plugin's own `@nx/*` packages pull in their own copy alongside it. Align every `nx` and `@nx/*` entry in your root `package.json` — and, where your package manager uses one, the dependency catalog — to a single version, then reinstall.
 
 #### `ts.readConfigFile is not a function`
 

package/docs/get_started/quick-start.mdx

@@ -3,6 +3,7 @@ title: Quick Start Guide
 description: "A quick start on how to use @aws/nx-plugin."
 ---
 import { Steps } from '@astrojs/starlight/components';
+import Drawer from '@components/drawer.astro';
 import Link from '@components/link.astro';
 import Snippet from '@components/snippet.astro';
 import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
@@ -42,6 +43,8 @@ You will be prompted for your preferred infrastructure as code (IaC) provider, e
 <CreateNxWorkspaceCommand workspace="my-project" iac="terraform" />
 </Fragment>
 </Infrastructure>
+
+You are also prompted for the container engine used by generators which build container images. Accept the default (`infer`) to select Docker if it is installed, otherwise Finch.
 :::
 
 Once complete, navigate to the project directory:
@@ -122,8 +125,12 @@ Changes to both your website and API will be reflected in real-time as both the
 Open `packages/infra/src/stacks/application-stack.ts` and add the following code:
 
 ```typescript
+import {
+  DemoApi,
+  DemoWebsite,
+  UserIdentity,
+} from '@my-project/common-constructs';
 import { Stack, StackProps } from 'aws-cdk-lib';
-import { DemoApi, DemoWebsite, UserIdentity } from '@my-project/common-constructs';
 import { Construct } from 'constructs';
 
 export class ApplicationStack extends Stack {
@@ -178,8 +185,8 @@ resource "aws_iam_policy" "api_invoke_policy" {
     Version = "2012-10-17"
     Statement = [
       {
-        Effect = "Allow"
-        Action = "execute-api:Invoke"
+        Effect   = "Allow"
+        Action   = "execute-api:Invoke"
         Resource = "${module.demo_api.api_execution_arn}/*/*"
       }
     ]
@@ -218,12 +225,20 @@ Next, run the following command to build your project:
 
 <PackageManagerShortCommand commands={["build"]} />
 
-:::tip[Fixing Lint Errors]
-If you encounter any lint errors, you can run the following command to automatically fix them.
+:::tip[Fixing Lint and Formatting Errors]
+If you encounter any lint or formatting errors, you can run the following command to automatically fix them.
 
 <PackageManagerShortCommand commands={["lint"]} />
 :::
 
+:::tip[The workspace is out of sync]
+If the build reports `The workspace is out of sync`, accept the prompt to sync the workspace or run the following sync command directly before retrying the build:
+
+<NxCommands commands={["sync"]} />
+
+This writes the TypeScript project references and `package.json` dependency entries your imports require.
+:::
+
 Bootstrap your infrastructure:
 
 <Infrastructure>
@@ -272,6 +287,44 @@ This command will first run `terraform plan` to show you what changes will be ma
 
 Your website will be available at `http://localhost:4200`, and will point to the resources you deployed for the API and authentication.
 
+To sign in, you will need to [create a user in the Cognito user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/how-to-create-user-accounts.html).
+
+<Drawer title="Creating a user with the AWS CLI" trigger="Click here for instructions using the AWS CLI">
+
+The following command creates a user in a user pool. You can find the user pool id in your deployment outputs, or in the [Amazon Cognito console](https://console.aws.amazon.com/cognito/). Substitute values for username, email, first and last name, and the temporary password.
+
+```sh
+aws cognito-idp admin-create-user \
+  --user-pool-id <user pool id> \
+  --username <username> \
+  --user-attributes Name=email,Value=<email> Name=email_verified,Value=true Name=given_name,Value=<first name> Name=family_name,Value=<last name> \
+  --temporary-password '<temporary password>' \
+  --message-action SUPPRESS
+```
+
+The first time you sign in as this user you are prompted to choose a new password, then to set up multi-factor authentication with either a code sent by SMS or a time-based one time password from an authenticator app.
+
+</Drawer>
+
+Your website is also served from CloudFront. Open its distribution domain name (which is printed to your terminal after deployment) to use the version running entirely on AWS.
+
+## Step 6: Clean Up
+
+When you have finished, delete the resources you deployed to avoid ongoing costs:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<NxCommands commands={['destroy-sandbox infra']} />
+</Fragment>
+<Fragment slot="terraform">
+<NxCommands commands={['destroy infra']} />
+</Fragment>
+</Infrastructure>
+
+:::note[Retained Resources]
+The Cognito user pool is created with deletion protection enabled, so it is not removed automatically. Delete it (and the IAM role Cognito uses to send SMS messages) manually if you no longer need them.
+:::
+
 ---
 
 Congratulations! 🎉 You have successfully built and deployed a full-stack application using `@aws/nx-plugin`!

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

@@ -130,8 +130,9 @@ Below is a list of all files which have been generated by the `ts#api` generator
       - local-server.ts used when running the tRPC server locally
       - **router.ts** defines the tRPC router and all procedures
     - project.json
+    - vitest.config.mts test configuration
     - ...
-- vitest.workspace.ts
+- vitest.config.mts root test configuration which discovers every project's tests
 </FileTree>
 
 Let us look at these key files:
@@ -151,13 +152,10 @@ export type AppRouter = typeof appRouter;
 ```
 The router defines the tRPC router for your API and is the place where you will declare all of your API methods. As you can see above, we have a method called `echo` with it's implementation in the `./procedures/echo.ts` file. The Lambda handler entrypoint is in `handler.ts`, which is configured automatically by the generator.
 
-```ts {7-10}
+```ts {4-6}
 // packages/game-api/src/procedures/echo.ts
 import { publicProcedure } from '../init.js';
-import {
-  EchoInputSchema,
-  EchoOutputSchema,
-} from '../schema/echo.js';
+import { EchoInputSchema, EchoOutputSchema } from '../schema/index.js';
 
 export const echo = publicProcedure
   .input(EchoInputSchema)
@@ -284,7 +282,10 @@ export class GameApi<
       } as FunctionProps,
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, `GameApi${op}Handler`, props);
-        handler.addEnvironment('RUNTIME_CONFIG_APP_ID', rc.appConfigApplicationId);
+        handler.addEnvironment(
+          'RUNTIME_CONFIG_APP_ID',
+          rc.appConfigApplicationId,
+        );
         rc.grantReadAppConfig(handler);
         return {
           handler,
@@ -903,9 +904,7 @@ export class StoryAgent extends Construct implements IGrantable, IConnectable {
 }
 ```
 
-This configures a CDK `AgentRuntimeArtifact` which uploads your agent Docker image to ECR, and hosts it using AgentCore Runtime. Because we chose `--auth=cognito`, the construct requires the user pool/client identity and authorizes AgentCore Runtime invocations through Cognito, forwarding the caller's `Authorization` header. It also provisions the session bucket the Story Agent's `session.py` reads back at runtime — a KMS-encrypted S3 bucket with server access logs delivered to CloudWatch Logs — grants the agent read/write access to it, grants it access to invoke Bedrock models, and registers its ARN and bucket name in `RuntimeConfig` so both the agent (at runtime, via AppConfig) and the Game API (at synth time, via `invocationUrl`) can find it.
-
-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.
+This configures a CDK `AgentRuntimeArtifact` which packages your agent's built code as a zip asset and hosts it using AgentCore Runtime. Because we chose `--auth=cognito`, the construct requires the user pool/client identity and authorizes AgentCore Runtime invocations through Cognito, forwarding the caller's `Authorization` header. It also provisions the session bucket the Story Agent's `session.py` reads back at runtime — a KMS-encrypted S3 bucket with server access logs delivered to CloudWatch Logs — grants the agent read/write access to it, grants it access to invoke Bedrock models, and registers its ARN and bucket name in `RuntimeConfig` so both the agent (at runtime, via AppConfig) and the Game API (at synth time, via `invocationUrl`) can find it.
 
 </details>
 
@@ -965,7 +964,6 @@ The `ts#mcp-server` generator generates these files.
         - sample-guidance.ts example resource
       - stdio.ts entry point for MCP with STDIO transport
       - http.ts entry point for MCP with Streamable HTTP transport
-      - Dockerfile builds the image for AgentCore Runtime
     - rolldown.config.ts configuration for bundling the MCP server for deployment to AgentCore
   - common/constructs/
     - src
@@ -1277,9 +1275,12 @@ The `connection` generator generates/updates these files. Let us examine some of
 ```tsx
 // packages/game-ui/src/hooks/useGameApi.tsx
 import { useContext } from 'react';
-import { GameApiTRPCContext } from '../components/GameApiClientProvider';
+import {
+  GameApiTRPCContext,
+  type GameApiTRPCContextValue,
+} from '../components/GameApiClientProvider';
 
-export const useGameApi = () => {
+export const useGameApi = (): GameApiTRPCContextValue['optionsProxy'] => {
   const container = useContext(GameApiTRPCContext);
   if (!container) {
     throw new Error('useGameApi must be used within GameApiClientProvider');
@@ -1287,7 +1288,7 @@ export const useGameApi = () => {
   return container.optionsProxy;
 };
 
-export const useGameApiClient = () => {
+export const useGameApiClient = (): GameApiTRPCContextValue['client'] => {
   const container = useContext(GameApiTRPCContext);
   if (!container) {
     throw new Error(
@@ -1399,6 +1400,7 @@ The `connection` generator generates/updates these files:
         - copilot/
           - **index.tsx** Shadcn-themed `CopilotChat` / `CopilotSidebar` / `CopilotPopup`
           - ShadcnAssistantMessage.tsx, ShadcnUserMessage.tsx, ShadcnChatInput.tsx, ShadcnCursor.tsx, copilot.css
+        - story-agent-chat.tsx a `CopilotChat` pre-bound to the Story Agent's `agentId`
       - hooks/
         - **useAguiStoryAgent.tsx** Builds an `HttpAgent`, injects the Cognito bearer token, and pads `threadId` to AgentCore's 33-char session id
     - **main.tsx** Wraps `<App />` in `<AguiProvider>`
@@ -1478,6 +1480,8 @@ new ApplicationStage(app, 'dungeon-adventure-infra-sandbox', {
   },
 });
 
+// Define other instances of stages, such as beta and prod, below
+
 app.synth();
 ```
 
@@ -1525,7 +1529,7 @@ The `run-many` command will run a target on multiple listed subprojects (`--all`
 
 You can also trigger a build (or any other task) for a single project target by running the target on the project directly. For example, to build the `@dungeon-adventure/infra` project, run the following command:
 
-<NxCommands commands={['build infra']} />
+<NxCommands commands={['build @dungeon-adventure/infra']} />
 
 You can also omit the scope, and use the Nx shorthand syntax if you prefer:
 
@@ -1559,21 +1563,20 @@ Then, run the following command for a full build:
 
 <PackageManagerShortCommand commands={["build"]} />
 
-You will be prompted with the following:
+You may be prompted with the following:
 
 ```bash
  NX   The workspace is out of sync
 
-[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.
-
-This will result in an error in CI.
+[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
+[@aws/nx-plugin:ts#sync]: Some files are out of sync.
 
 ? Would you like to sync the identified changes to get your workspace up to date? …
 Yes, sync the changes and run the tasks
 No, run the tasks without syncing the changes
 ```
 
-This message indicates that NX has detected some files which can be updated automatically for you. In this case, it is referring to the `tsconfig.json` files which do not have Typescript references set up on references projects.
+This message indicates that NX has detected some files which can be updated automatically for you. In this case, it is referring to the `tsconfig.json` files which do not have Typescript references set up on referenced projects, and to the workspace dependencies the `@aws/nx-plugin` sync generator declares for you.
 
 Select the **Yes, sync the changes and run the tasks** option to proceed. You should notice all of you IDE related import errors get automatically resolved as the sync generator will add the missing typescript references automatically!
 

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

@@ -170,11 +170,19 @@ The `DungeonDb` construct registers the deployed table name in <Link path="guide
 
 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:
+The procedures and MCP server we just wrote import `@dungeon-adventure/dungeon-db`, a new cross-project import, so start by syncing the workspace:
+
+<NxCommands commands={["sync"]} />
+
+<Aside type="tip" title="Why this step is needed">
+`nx sync` declares `@dungeon-adventure/dungeon-db` in the `game-api` and `inventory` `package.json` files and adds the matching TypeScript project references for you, saving you from needing to add this by hand when declaring dependencies between projects.
+</Aside>
+
+Then fix any lint issues:
 
 <PackageManagerShortCommand commands={["lint"]} />
 
-Then build the codebase:
+And build the codebase:
 
 <PackageManagerShortCommand commands={["build"]} />
 
@@ -240,6 +248,6 @@ We can try out the MCP server's tools with the [MCP Inspector](https://github.co
 
 <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.
+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. Toggle the switch next to the `localhost:8000` server to connect, switch to the **Tools** tab, 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

@@ -47,6 +47,10 @@ If you encounter any lint errors, run the following command to automatically fix
 <PackageManagerShortCommand commands={["lint"]} />
 </Aside>
 
+<Aside type="tip" title="The workspace is out of sync">
+If the build reports `The workspace is out of sync`, run `nx sync` and build again.
+</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:

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

@@ -27,7 +27,7 @@ Start the full local stack — the game-ui dev server together with a local Game
 
 <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.
+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 at `http://localhost:4200/` 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.
@@ -48,6 +48,7 @@ When you ran the `connection` generator for `game-ui → story` in <Link path="g
     - copilot/
       - index.tsx Re-exports themed `CopilotChat` / `CopilotSidebar` / `CopilotPopup`.
       - ShadcnAssistantMessage.tsx, ShadcnUserMessage.tsx, ShadcnChatInput.tsx, ShadcnCursor.tsx, copilot.css
+    - story-agent-chat.tsx A `CopilotChat` pre-bound to the Story Agent's `agentId`.
   - 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>`
@@ -90,7 +91,7 @@ The `$playerName` syntax tells `@tanstack/react-router` to treat `playerName` as
 </TabItem>
 </Tabs>
 
-Once saved, the dev server at `http://localhost:4200/` should now let you start an adventure and chat with the Story Agent.
+Once saved, the dev server 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;">
@@ -146,6 +147,10 @@ dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolIdXX
 
 Navigate to your CloudFront URL (`GameUIDistributionDomainName` from the CDK outputs), sign up for a new account, and play your game running entirely on AWS!
 
+:::note[Signing up for the first time]
+Cognito emails you a code to confirm your account, then asks you to set up multi-factor authentication (an authenticator app or an SMS code) before your first sign-in — the user pool `ts#website#auth` vends requires MFA. See <Link path="guides/react-website-auth#multi-factor-authentication-mfa">Multi-factor authentication</Link> for how to relax that.
+:::
+
 ## 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.

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

@@ -38,4 +38,13 @@ We recommend you try your hand at extending the codebase with the following capa
 
     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.
+2. Enter `y` to continue. CloudFormation will destroy your stacks.
+
+:::caution[Two resources are kept on purpose]
+Deleting the stacks leaves two resources behind, so a teardown can't take your users or their stories with it:
+
+- The **Cognito user pool**, which `ts#website#auth` creates with deletion protection enabled.
+- The **Story Agent's session bucket**, which holds the conversation history and defaults to `RemovalPolicy.RETAIN`.
+
+Delete them by hand once you no longer need them — for the user pool, turn deletion protection off first.
+:::