@aws/nx-plugin-mcp 1.0.0-rc.97 → 1.0.0

package/bin/aws-nx-mcp.js

@@ -21915,22 +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",
-	"deepmerge-ts": "8.0.0",
-	mysql2: "3.22.0",
-	"@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/client-cognito-identity-provider": "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",
@@ -21938,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",
@@ -21953,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",
@@ -21968,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",
@@ -22018,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",
@@ -22028,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;

package/docs/get_started/building-with-ai.mdx

@@ -6,14 +6,23 @@ description: Building with AI and the Nx Plugin for AWS MCP Server
 import Link from "@components/link.astro";
 import Snippet from "@components/snippet.astro";
 import { Steps, Tabs, TabItem } from "@astrojs/starlight/components";
+import Prompt from "@components/prompt.astro";
 
-Install the [Claude Plugin](https://code.claude.com/docs/en/plugins), [Kiro Power](https://kiro.dev/docs/powers/), or [MCP Server](https://modelcontextprotocol.io/introduction) to enable AI assistants to work effectively with the plugin. By using these, you can accelerate your development workflow with AI while benefitting from your projects being scaffolded in a consistent fashion, spending less time on setting up the main components and benefitting from the security, observability, type-safety and local development built into the plugin.
+## Already configured in your workspace
 
-## Configure your AI Assistant
+Workspaces created with the Nx Plugin for AWS preset include project-level MCP configuration for common coding agents — Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot and OpenAI Codex — so an agent working inside the workspace can use the plugin's [MCP server](https://modelcontextprotocol.io/introduction) with no further setup.
 
-:::tip[Project-level configuration is automatic]
-Workspaces created with the Nx Plugin for AWS preset already include project-level MCP configuration for common coding agents (Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot and OpenAI Codex). Any agent working inside the workspace can use the MCP server without further setup. The steps below configure the MCP server globally for use across all of your projects.
-:::
+Open your workspace in your assistant and ask it for what you want:
+
+<Prompt>
+Add a React website with an AG-UI agent, an MCP server for its tools and a DynamoDB table, and wire them together.
+</Prompt>
+
+It looks up the generators the plugin offers, runs them in the order their dependencies need. Use your agent to fill in the business logic from there.
+
+## Install globally
+
+The workspace configuration above is enough to build with. You can install globally if you'd like to use AI to create new workspaces, or <Link path="get_started/existing-project">add the Nx Plugin for AWS to an existing project</Link>:
 
 <Tabs syncKey="ai-assistant">
   <TabItem label="Kiro">
@@ -101,16 +110,14 @@ Workspaces created with the Nx Plugin for AWS preset already include project-lev
 
 ## Start Vibe Coding
 
-Ask your AI Assistant to build something using the `nx-plugin-for-aws`! It will typically create a workspace, scaffold with the applicable generators, then fill in the business logic.
+With the plugin available globally, your assistant can create the workspace too. Try a prompt like:
 
-Try a prompt like:
-
-> _"Build a multi-agent application using the Nx Plugin for AWS. I want a React frontend that talks to a backend orchestrator agent which delegates to specialised research and writing agents."_
+<Prompt>
+Build a multi-agent application using the Nx Plugin for AWS. I want a React frontend that talks to a backend orchestrator agent which delegates to specialised research and writing agents.
+</Prompt>
 
 Or for a smaller starting point:
 
-> _"Use the Nx Plugin for AWS to scaffold a React website backed by a tRPC API, with Cognito auth and CDK infrastructure."_
-
-## Build your own MCP Server
-
-Check out the <Link path="/guides/ts-mcp-server">`ts#mcp-server` generator guide</Link> for details about building your own MCP Server.
+<Prompt>
+Use the Nx Plugin for AWS to scaffold a React website backed by a tRPC API, with Cognito auth and CDK infrastructure.
+</Prompt>

package/docs/get_started/concepts.mdx

@@ -50,7 +50,7 @@ In practice:
 - **Upgrading is automated, not a re-adoption exercise.** A workspace generated months ago can move forward with the plugin rather than drifting further from it.
 - **Customisations are pattern-matched, not overwritten.** Migrations check that a file still matches the shape the generator produced. Where it has diverged beyond what they can safely update, they leave your code alone and report the manual follow-up instead.
 - **Some changes arrive as agent prompts.** Where the right edit depends on what you've built, the migration is a prompt your AI coding agent applies rather than a codemod.
-- **Upgrades are opt-in.** Nothing in your workspace changes until you choose to run `nx migrate`.
+- **Upgrades are opt-in.** Nothing in your workspace changes until you choose to run `nx migrate`. After running, you drop any changes you'd rather not take before you commit.
 
 Migrations narrow the gap rather than close it: how far your code has moved decides how much they can do, and some steps will still need your hands.
 

package/docs/get_started/existing-project.mdx

@@ -10,13 +10,16 @@ import NxCommands from '@components/nx-commands.astro';
 import NxInitCommand from '@components/nx-init-command.astro';
 import TsConfigBaseCompilerOptions from '@components/tsconfig-base-compiler-options.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
+import Prompt from '@components/prompt.astro';
 
 Not every project starts with `pnpm create @aws/nx-workspace`. If you already have an [Nx workspace](https://nx.dev) — or a monorepo you can add Nx to — you can adopt `@aws/nx-plugin` incrementally without recreating your project.
 
-<Aside type="tip">
-You can use your agentic coding tool of choice to add the plugin for you, using the <Link path="get_started/building-with-ai">MCP server</Link>. Try the prompt:
+<Aside type="tip" title="Use your coding agent">
+Your agentic coding tool of choice can add the plugin for you, using the <Link path="get_started/building-with-ai">MCP server</Link>. Try the prompt:
 
-> Add the Nx Plugin for AWS to this project.
+<Prompt>
+Add the Nx Plugin for AWS to this project.
+</Prompt>
 </Aside>
 
 ## Prerequisites
@@ -56,7 +59,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:
 

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';
@@ -12,94 +13,100 @@ 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';
+import Diff from '@components/diff.astro';
+import Prompt from '@components/prompt.astro';
 
 This guide walks you through the basics of installing and using `@aws/nx-plugin` to rapidly build projects on AWS.
 
-:::tip[Full-Stack Tutorial]
-For a more in-depth tutorial for building a full-stack application, check out the <Link path="get_started/tutorials/dungeon-game/overview">Dungeon Adventure Tutorial</Link>.
-:::
-
 ## Prerequisites
 
 The following global dependencies are needed before proceeding:
 
 <Snippet name="prerequisites" />
 
-## Step 1: Initialize a New Nx Workspace
+## Step 1: Create a Workspace
 
-Run the following command to create an <Link path="guides/workspace">Nx workspace</Link> with the package manager of your choice:
+Create an <Link path="guides/workspace">Nx workspace</Link> with the package manager of your choice, and open the directory it creates:
 
 <CreateNxWorkspaceCommand workspace="my-project" />
 
-:::tip[Choosing an IaC Provider]
-You will be prompted for your preferred infrastructure as code (IaC) provider, either [CDK](https://docs.aws.amazon.com/cdk/) or [Terraform](https://developer.hashicorp.com/terraform). You can skip the prompt by running the command with `--iac`, ie:
-
-<Infrastructure>
-<Fragment slot="cdk">
-<CreateNxWorkspaceCommand workspace="my-project" iac="cdk" />
-</Fragment>
-<Fragment slot="terraform">
-<CreateNxWorkspaceCommand workspace="my-project" iac="terraform" />
-</Fragment>
-</Infrastructure>
-:::
-
-Once complete, navigate to the project directory:
-
 ```sh
 cd my-project
 ```
 
-## Step 2: Use Generators to Scaffold your Project
+You are prompted to choose your infrastructure as code provider, either [CDK](https://docs.aws.amazon.com/cdk/) or [Terraform](https://developer.hashicorp.com/terraform), and the container engine used by generators which build container images.
 
-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.
+## Step 2: Build Your Application
 
-As a shortcut, you can use the button below to copy the commands to scaffold the full application.
+We'll build a full-stack application: a tRPC API, a React website, Cognito authentication, and CDK or Terraform infrastructure. Ask an AI assistant to scaffold it for you, or run the generators yourself — both routes reach the same workspace.
 
-<EmbeddedGraph preset="quick-start" workspace="my-project" iac="cdk" orientation="horizontal" skipWorkspace />
+### With AI
 
-:::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.
-:::
+<Steps>
+1. Open the workspace in your AI coding assistant.
 
-Otherwise, follow the steps below to run each generator yourself.
+    New workspaces come with the plugin's <Link path="get_started/building-with-ai">MCP server</Link> already configured for Kiro, Claude Code, Cursor, Gemini CLI, GitHub Copilot and OpenAI Codex, so your assistant can look up the plugin's generators and run them without any setup.
 
-### Add a tRPC API
+2. Ask for the application:
+
+    <Prompt>
+    Create a tRPC API called demo-api, and a React website called demo-website. Add Cognito authentication to the website, connect the website to the API, and add an infrastructure project called infra. Then instantiate the generated infrastructure components so the website and API deploy, granting authenticated users access to the API.
+    </Prompt>
+
+    Your assistant discovers the generators through the MCP server and runs them, in the order their dependencies need. Review the changes it makes, then carry on at Step 3.
+</Steps>
 
-<RunGenerator generator="ts#api" requiredParameters={{ name: 'demo-api', framework: 'trpc', auth: 'iam' }} noInteractive />
+### With the CLI
+
+Run the generators that scaffold the application. Use the button below to copy them all, or run each one yourself as described beneath the diagram.
+
+<Infrastructure>
+<Fragment slot="cdk">
+<EmbeddedGraph preset="quick-start" workspace="my-project" iac="cdk" orientation="horizontal" skipWorkspace />
+</Fragment>
+<Fragment slot="terraform">
+<EmbeddedGraph preset="quick-start" workspace="my-project" iac="terraform" orientation="horizontal" skipWorkspace />
+</Fragment>
+</Infrastructure>
+
+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.
+
+#### Add a tRPC API
+
+<RunGenerator generator="ts#api" requiredParameters={{ name: 'demo-api', framework: 'trpc' }} positional={['name']} noInteractive />
 
 This will create the API inside the `packages/demo-api` folder.
 
-### Add a React Website
+#### Add a React Website
 
-<RunGenerator generator="ts#website" requiredParameters={{ name: 'demo-website' }} noInteractive />
+<RunGenerator generator="ts#website" requiredParameters={{ name: 'demo-website' }} positional={['name']} noInteractive />
 
 This scaffolds a new React website in `packages/demo-website`.
 
-### Add Cognito Authentication
+#### Add Cognito Authentication
 
-<RunGenerator generator="ts#website#auth" requiredParameters={{ project: '@my-project/demo-website', cognitoDomain: 'my-demo' }} noInteractive />
+<RunGenerator generator="ts#website#auth" requiredParameters={{ project: 'demo-website' }} noInteractive />
 
 This sets up the necessary infrastructure and React code to add Cognito Authentication to your website.
 
-### Connect Frontend to Backend
+#### Connect Frontend to Backend
 
-<RunGenerator generator="connection" requiredParameters={{ sourceProject: '@my-project/demo-website', targetProject: '@my-project/demo-api' }} noInteractive />
+<RunGenerator generator="connection" requiredParameters={{ sourceProject: 'demo-website', targetProject: 'demo-api' }} noInteractive />
 
 This configures the necessary providers to ensure your website can call your tRPC API.
 
-### Add Infrastructure
+#### Add Infrastructure
 
 Add the infrastructure project based on your chosen IAC provider.
 
 <Infrastructure>
 <Fragment slot="cdk">
-<RunGenerator generator="ts#infra" requiredParameters={{ name: 'infra' }} noInteractive />
+<RunGenerator generator="ts#infra" requiredParameters={{ name: 'infra' }} positional={['name']} noInteractive />
 
 This configures a CDK App which you can use to deploy your infrastructure on AWS.
 </Fragment>
 <Fragment slot="terraform">
-<RunGenerator generator="terraform#project" requiredParameters={{ name: 'infra' }} noInteractive />
+<RunGenerator generator="terraform#project" requiredParameters={{ name: 'infra' }} positional={['name']} noInteractive />
 
 This configures a Terraform project which you can use to deploy your infrastructure on AWS.
 </Fragment>
@@ -115,6 +122,67 @@ Your website will be available at `http://localhost:4200`.
 
 Changes to both your website and API will be reflected in real-time as both the local website and API servers will hot-reload.
 
+<Drawer title="Calling your API from your website" trigger="Try it: call the API from your website">
+
+Connecting the website to the API added a `useDemoApi` hook, which returns a [tRPC options proxy](https://trpc.io/docs/client/tanstack-react-query): every procedure on your API offers `queryOptions` and `mutationOptions` to hand to [TanStack Query](https://tanstack.com/query/latest).
+
+Update `packages/demo-website/src/routes/index.tsx` to call the API's `echo` procedure, showing a spinner while the request is in flight:
+
+<Diff lang="tsx" before={`import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/')({
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return (
+    <div className="text-center">
+      <header>
+        <h1>Welcome</h1>
+        <p>Welcome to your new React website!</p>
+      </header>
+    </div>
+  );
+}
+`} after={`import { useQuery } from '@tanstack/react-query';
+import { createFileRoute } from '@tanstack/react-router';
+import { Spinner } from '../components/spinner';
+import { useDemoApi } from '../hooks/useDemoApi';
+
+export const Route = createFileRoute('/')({
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  const trpc = useDemoApi();
+  const echo = useQuery(
+    trpc.echo.queryOptions({ message: 'Hello from the API!' }),
+  );
+
+  return (
+    <div className="text-center">
+      <header>
+        <h1>Welcome</h1>
+        <p>Welcome to your new React website!</p>
+      </header>
+      {echo.isLoading ? (
+        <Spinner />
+      ) : echo.error ? (
+        <p>Error: {echo.error.message}</p>
+      ) : (
+        <p>{echo.data?.message}</p>
+      )}
+    </div>
+  );
+}
+`} />
+
+Save the file and the page reloads with the message your API echoed back. The call is type-safe end to end — rename `message` in `packages/demo-api/src/schema/echo.ts` and your website stops compiling until you follow the change through.
+
+See the <Link path="guides/connection/react-trpc">React to tRPC connection guide</Link> for mutations, subscriptions, error handling and optimistic updates.
+
+</Drawer>
+
 ## Step 4: Define Cloud Resources and Deploy to AWS
 
 <Infrastructure>
@@ -122,8 +190,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 {
@@ -147,11 +219,6 @@ This is all the CDK we need to write to deploy our full stack application.
 Open `packages/infra/src/main.tf` and add the following code:
 
 ```hcl
-# Include metrics tracking for @aws/nx-plugin usage
-module "metrics" {
-  source = "../../common/terraform/src/metrics"
-}
-
 # Deploy user identity
 module "user_identity" {
   source = "../../common/terraform/src/core/user-identity"
@@ -178,8 +245,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}/*/*"
       }
     ]
@@ -206,6 +273,15 @@ module "demo_website" {
 
   depends_on = [module.user_identity, module.demo_api]
 }
+
+# Print the website URL and user pool id when the deployment finishes
+output "website_url" {
+  value = module.demo_website.website_url
+}
+
+output "user_pool_id" {
+  value = module.user_identity.user_pool_id
+}
 ```
 
 This is all the Terraform we need to write to deploy our full stack application.
@@ -218,13 +294,13 @@ 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]
+:::note[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"]} />
@@ -239,7 +315,9 @@ Bootstrap your infrastructure:
 <NxCommands commands={['bootstrap infra']} />
 
 :::tip[Bootstrap Regions]
-CDK bootstrapping is required for both your target deployment AWS region, and `us-east-1` to allow deployment of the AWS WAF WebACL for the website.
+CDK bootstrapping is required for both your target deployment AWS region, and `us-east-1` to allow deployment of the AWS WAF WebACL for the website. If you are deploying elsewhere, bootstrap `us-east-1` too:
+
+<NxCommands commands={['run infra:bootstrap --args="aws://<account-id>/us-east-1"']} />
 :::
 </Fragment>
 <Fragment slot="terraform">
@@ -280,6 +358,77 @@ 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.
 
 Congratulations! 🎉 You have successfully built and deployed a full-stack application using `@aws/nx-plugin`!
+
+## 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']} />
+
+:::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.
+:::
+</Fragment>
+<Fragment slot="terraform">
+<NxCommands commands={['destroy infra']} />
+
+:::note[Retained Resources]
+The Cognito user pool is created with deletion protection enabled, so it is not removed automatically (the destroy command will report a failure). Delete it (and the IAM role Cognito uses to send SMS messages) manually if you no longer need them.
+:::
+</Fragment>
+</Infrastructure>
+
+To remove bootstrap resources, follow below:
+
+<Infrastructure>
+<Fragment slot="cdk">
+Delete the bootstrap stack in every region you bootstrapped, including `us-east-1`. This removes the bootstrap roles and the container image repository:
+
+```sh
+aws cloudformation delete-stack --stack-name CDKToolkit --region <region>
+```
+
+:::note[Asset Bucket]
+The asset bucket is retained on purpose, so delete it separately.
+:::
+</Fragment>
+<Fragment slot="terraform">
+<NxCommands commands={['bootstrap-destroy infra']} />
+
+:::caution[Your Terraform State Is Deleted Too]
+This empties and deletes the S3 bucket holding your Terraform state, so only run it once you have torn down all deployed infrastructure.
+:::
+</Fragment>
+</Infrastructure>
+
+---
+
+## Next Steps
+
+- <Link path="get_started/tutorials/dungeon-game/overview">Dungeon Adventure Tutorial</Link> — build a full-stack AI dungeon adventure game, for a more in-depth walkthrough than this guide.
+- <Link path="guides/workspace">Workspaces</Link> — how your workspace is laid out, and the configuration the generators share.
+- <Link path="get_started/existing-project">Add to an Existing Project</Link> — adopt the plugin in your existing codebase.

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

@@ -282,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,
@@ -1397,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>`
@@ -1476,6 +1480,8 @@ new ApplicationStage(app, 'dungeon-adventure-infra-sandbox', {
   },
 });
 
+// Define other instances of stages, such as beta and prod, below
+
 app.synth();
 ```
 
@@ -1523,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:
 
@@ -1562,16 +1568,15 @@ 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

@@ -248,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/4.mdx

@@ -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>`
@@ -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/overview.mdx

@@ -10,7 +10,6 @@ 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'
@@ -138,8 +137,4 @@ Before you proceed, you will need the following global dependencies:
 
 <Snippet name="required-prerequisites" />
 - [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account, since this tutorial deploys the application and invokes Amazon Bedrock
-- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development
-
-:::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.
-:::
+- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development

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.
+:::

package/docs/guides/license.mdx

@@ -9,7 +9,6 @@ import GeneratorParameters from '@components/generator-parameters.astro';
 import Drawer from '@components/drawer.astro';
 import LicenseAllowlist from '@components/license-allowlist.astro';
 import NxCommands from '@components/nx-commands.astro';
-import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 Manage licensing across your workspace: synchronise `LICENSE` files and source code headers for your own code (`license.source`), and check that every dependency conforms to a license allowlist (`license.dependencies`).
 
@@ -45,7 +44,7 @@ Whenever you build your projects (and a `lint` target runs), the license sync ge
 
 [@aws/nx-plugin:license#sync]: Project LICENSE files are out of sync:
 - LICENSE
-- packages/<my-project>LICENSE
+- packages/<my-project>/LICENSE
 
 Project package.json files are out of sync:
 - package.json
@@ -348,7 +347,7 @@ This means you don't need to run the check explicitly, though you can still do s
 
 The wiring is a cross-project `dependsOn` on each project's `lint` target that points at the root `license-check` target. To skip the check during a lint or build, set the `LICENSE_DEPENDENCY_CHECK=skip` environment variable:
 
-<PackageManagerShortCommand commands={["LICENSE_DEPENDENCY_CHECK=skip lint"]} />
+<NxCommands commands={['run-many --target lint --all']} env={{ LICENSE_DEPENDENCY_CHECK: 'skip' }} />
 
 ### Configuration
 
@@ -381,7 +380,14 @@ To restrict the allowlist, replace `DEFAULT_LICENSE_ALLOWLIST` with your own arr
 
 #### Per-package exceptions
 
-Use `exceptions` for packages that fail the check — either because their license is not in the allowlist, or because they ship without detectable license metadata. The `reason` field is required so reviewers can see why the exception was granted.
+Use `exceptions` for packages that fail the check — either because their license is not in the allowlist, or because they ship without detectable license metadata.
+
+Each entry accepts:
+
+- `package` (required): the package name the exception applies to
+- `reason` (required): why the exception was granted, so reviewers can see it
+- `version` (optional): restrict the exception to a single version, so a later version is checked again
+- `spdx` (optional): the license to treat the package as declaring, for a package that ships license text without declaring it in its metadata. This is what the `onDependency` hook below reports
 
 ```typescript
 exceptions: [
@@ -389,6 +395,7 @@ exceptions: [
     package: 'union',
     version: '0.5.0',
     reason: 'Package ships verbatim MIT text without declaring license',
+    spdx: 'MIT',
   },
 ];
 ```
@@ -397,7 +404,24 @@ Generators that introduce dependencies with problematic metadata (e.g. the MCP s
 
 #### Collectors
 
-Collectors discover dependencies and extract license metadata. The built-in collectors are `npmCollector()` (scans `node_modules`) and `pythonCollector()` (scans Python virtual environments). The license generator configures `npmCollector()` by default and adds `pythonCollector()` when Python projects are present.
+Collectors discover dependencies and extract license metadata. The built-in collectors are `npmCollector()` (scans `node_modules`) and `pythonCollector()` (scans Python virtual environments), both exported from `@aws/nx-plugin/sdk/license`. The license generator configures `npmCollector()` by default and adds `pythonCollector()` when Python projects are present.
+
+```typescript title="aws-nx-plugin.config.mts"
+import {
+  DEFAULT_LICENSE_ALLOWLIST,
+  npmCollector,
+  pythonCollector,
+} from '@aws/nx-plugin/sdk/license';
+
+export default {
+  license: {
+    dependencies: {
+      allow: DEFAULT_LICENSE_ALLOWLIST,
+      collectors: [npmCollector(), pythonCollector()],
+    },
+  },
+} satisfies AwsNxPluginConfig;
+```
 
 To implement a custom collector, conform to the `LicenseCollector` interface:
 
@@ -443,6 +467,6 @@ Dependency license checking is enabled by the presence of the `license.dependenc
 
 To disable the checks for a single run, set the `LICENSE_DEPENDENCY_CHECK=skip` environment variable:
 
-<PackageManagerShortCommand commands={["LICENSE_DEPENDENCY_CHECK=skip lint"]} />
+<NxCommands commands={['run-many --target lint --all']} env={{ LICENSE_DEPENDENCY_CHECK: 'skip' }} />
 
 To disable permanently, remove the `license.dependencies` key from your configuration in `aws-nx-plugin.config.mts`. You can also re-run the `license` generator with `--dependencyCheck=false` to scaffold without it.

package/docs/guides/nx-generator.mdx

@@ -40,15 +40,14 @@ The generator will create the following project files within the given `project`
     - generator.ts Stub generator implementation
     - generator.spec.ts Tests for your generator
     - README.md Documentation for your generator
-  - generators.json Nx configuration to define your generators
-  - package.json Created or updated to add a "generators" entry
-  - tsconfig.json Updated to use CommonJS
+    - files/
+      - hello.ts.template Example template rendered by the stub generator
+  - src/index.ts Updated to export your generator
+  - generators.json Created or updated to define your generators
+  - project.json Updated to record the generator against the project
+  - package.json Created if absent, and pointed at `generators.json`
 </FileTree>
 
-:::warning[Project Modification]
-This generator will update the selected `project` to use CommonJS, as Nx Generators only support CommonJS at present ([refer to this GitHub issue for ESM support](https://github.com/nrwl/nx/issues/15682)).
-:::
-
 ## Local Generators
 
 :::tip[Dedicated Plugin Project]
@@ -452,7 +451,7 @@ export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
 We also expose a method which allows you to build a data structure that can be used to iterate over operations in an OpenAPI specification and therefore instrument your own code generation, for example:
 
 ```ts
-import { buildOpenApiCodeGenerationData } from '@aws/nx-plugin/sdk/open-api.js';
+import { buildOpenApiCodeGenerationData } from '@aws/nx-plugin/sdk/open-api';
 
 export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
   const data = await buildOpenApiCodeGenerationData(tree, 'path/to/spec.json');
@@ -496,15 +495,15 @@ If you don't see your generator in the VSCode plugin UI, you can refresh your Nx
 Unit tests for generators are straightforward to implement. Here's a typical pattern:
 
 ```typescript
-import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
 import { yourGenerator } from './generator.js';
 
 describe('your generator', () => {
   let tree;
 
   beforeEach(() => {
-    // Create an empty workspace tree
-    tree = createTreeWithEmptyWorkspace();
+    // Create a workspace tree matching the shape our preset generates
+    tree = createTreeUsingTsSolutionSetup();
 
     // Add any files that should already exist in the tree
     tree.write(
@@ -562,7 +561,7 @@ describe('your generator', () => {
 
 Key points for testing generators:
 
-- Use `createTreeWithEmptyWorkspace()` to create a virtual file system
+- Use `createTreeUsingTsSolutionSetup()` from `@aws/nx-plugin/sdk/utils/test` to create a virtual file system. It seeds the workspace markers our preset writes (`tsconfig.base.json`, `pnpm-workspace.yaml`, `biome.json`, a `type: module` root `package.json`), which any generator composing an `@aws/nx-plugin` generator needs
 - Set up any prerequisite files before running the generator
 - Test both the creation of new files and updates to existing files
 - Use snapshots for complex file content

package/docs/guides/ts-nx-plugin.mdx

@@ -33,22 +33,30 @@ The generator will create the following project structure:
 <FileTree>
 - your-plugin/
   - src/
-    - index.ts Empty entry point for your plugin
+    - index.ts Entry point for your plugin
     - mcp-server/
       - index.ts Exports your server
       - server.ts Main MCP server configuration
       - stdio.ts Entry point for your MCP server with STDIO transport
       - http.ts Entry point for your MCP server with Streamable HTTP transport
+      - schema.ts Shared schemas for the MCP server's tools
+      - utils.ts Utility functions for the MCP server
+      - resources/
+        - GENERAL_GUIDANCE.md Guidance served by the `general-guidance` tool
       - tools/
         - create-workspace-command.ts Tool for workspace creation guidance
         - general-guidance.ts Tool for general Nx and plugin guidance
         - list-generators.ts Tool to list available generators
         - generator-guide.ts Tool for detailed generator information
-      - utils.ts Utility functions for the MCP server
   - generators.json Nx generator configuration (initially empty)
   - package.json Plugin package configuration
-  - tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
   - project.json Nx project configuration with build and package targets
+  - tsconfig.json TypeScript configuration, referencing the two below
+  - tsconfig.lib.json TypeScript configuration for your plugin's source
+  - tsconfig.spec.json TypeScript configuration for your plugin's tests
+  - vitest.config.mts Vitest configuration for your plugin's tests
+  - README.md Documentation for your plugin, served by the `generator-guide` tool
+  - LICENSE Written by the `license` generator's sync, when configured
 </FileTree>
 
 ## Working with Your Nx Plugin
@@ -84,7 +92,7 @@ Creates a distributable package ready for NPM publishing:
 The package target includes all necessary assets:
 - Compiled JavaScript files
 - TypeScript declaration files
-- Generator and executor configuration files
+- The `generators.json`, `executors.json` and `migrations.json` manifests Nx reads from a published plugin
 - Documentation and license files
 
 ## MCP Server Integration
@@ -114,14 +122,16 @@ For more details about writing MCP Servers, refer to the <Link path="/guides/ts-
 
 ### Preparing for Publication
 
-1. **Update Package Information**: Edit your plugin's [`package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) with proper name, version, description, and repository information.
+1. **Update Package Information**: Edit your plugin's [`package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) with proper name, version, description, and repository information. Also remove `"private": true`.
 
 2. **Build the Package**:
    <NxCommands commands={['package your-plugin']} />
 
+   The package lands in `dist/<your-plugin's project root>/package` — for a plugin generated with `--name=nx-plugin --directory=tools`, that's `dist/tools/nx-plugin/package`.
+
 3. **Test Locally**: You can test your plugin locally by installing it in another workspace:
    ```bash
-   npm install /path/to/your/workspace/dist/your-plugin/package
+   npm install /path/to/your/workspace/dist/tools/nx-plugin/package
    ```
 
 ### Publishing to NPM
@@ -129,7 +139,7 @@ For more details about writing MCP Servers, refer to the <Link path="/guides/ts-
 Once your plugin is ready:
 
 ```bash
-cd dist/your-plugin/package
+cd dist/tools/nx-plugin/package
 npm publish
 ```
 

package/docs/guides/typescript-infrastructure.mdx

@@ -467,7 +467,9 @@ Destroying is irreversible, so CDK asks you to confirm the stacks it is about to
 
 The `destroy` target tears down whichever stage or stacks you name:
 
-<NxCommands commands={['destroy <my-infra> <my-infra>-sandbox/*']} />
+<NxCommands commands={['destroy <my-infra> <my-infra>-sandbox/**']} />
+
+Use `/**` rather than `/*` for a whole stage: destroying only deletes the stacks the pattern selects, and `/*` misses stacks nested below the stage's stacks, such as the `us-east-1` WebACL stack a website creates for its CloudFront distribution.
 
 To tear down an individual stack, give the full stack name:
 

package/docs/snippets/pdk-migration/example/01-migrate-api.mdx

@@ -8,6 +8,7 @@ import Link from '@components/link.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Drawer from '@components/drawer.astro';
 import InstallCommand from '@components/install-command.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 The `TypeSafeApiProject` used in the shopping list application made use of:
 
@@ -114,12 +115,12 @@ Now that we have the basic structure for our Smithy API project, we can migrate
 
 At this point, let's run a build to check our model changes and ensure we have some generated server code to work with. There will be some failures in the backend project (`@shopping-list/api`) but we'll address those next.
 
-<NxCommands commands={["run-many --target build"]} />
+<PackageManagerShortCommand commands={["build"]} />
 
 :::note
 You may see a build failure due to lint issues. These can usually be automatically fixed:
 
-<NxCommands commands={["run-many --target lint --fix"]} />
+<PackageManagerShortCommand commands={["lint"]} />
 :::
 
 #### Migrate the Lambda Handlers
@@ -132,7 +133,7 @@ The shopping list application's lambda handlers rely on the `@aws-sdk/client-dyn
 
 <InstallCommand pkg="@aws-sdk/client-dynamodb" project="@shopping-list/api" />
 
-Then, let's copy the `handlers/src/dynamo-client.ts` file from the PDK project to `backend/src/operations` so it's available for our handlers.
+Then, let's copy the `handlers/typescript/src/dynamo-client.ts` file from the PDK project to `backend/src/operations` so it's available for our handlers.
 
 The `ts#smithy-api` generator scaffolds an example `Echo` operation. Since we removed this from our model, delete the corresponding handler in `backend/src/operations/echo.ts`. We'll register our migrated operations in `service.ts` further below.
 
@@ -587,6 +588,7 @@ Additionally, update `packages/api/backend/project.json` and update `metadata.ap
 +    "apiName": "my-api",
     "auth": "iam",
     "modelProject": "@shopping-list/api-model",
+    "iac": "cdk",
     "ports": [3001]
   },
 ```
@@ -595,10 +597,10 @@ Additionally, update `packages/api/backend/project.json` and update `metadata.ap
 
 We can now build the project to check that the migration has worked so far:
 
-<NxCommands commands={["run-many --target build"]} />
+<PackageManagerShortCommand commands={["build"]} />
 
 :::note
 You may see a build failure due to lint issues. These can usually be automatically fixed:
 
-<NxCommands commands={["run-many --target lint --fix"]} />
+<PackageManagerShortCommand commands={["lint"]} />
 :::

package/docs/snippets/pdk-migration/example/02-migrate-website.mdx

@@ -8,6 +8,7 @@ import Link from '@components/link.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Drawer from '@components/drawer.astro';
 import InstallCommand from '@components/install-command.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 The `CloudscapeReactTsWebsiteProject` used in the shopping list application configured a React website with CloudScape and Cognito authentication built in.
 
@@ -100,7 +101,7 @@ Since we're using [file-based routing](https://tanstack.com/router/latest/docs/f
 
 Let's start the local website server:
 
-<NxCommands commands={["dev website"]} />
+<PackageManagerShortCommand commands={["dev"]} />
 
 :::tip
 We're using the `dev` target here, which also starts local servers for any APIs which have been connected with `connection`, and hot-reloads if your website, model, or backend changes! This allows us to test our API and website locally before we've even written any CDK code.

package/docs/snippets/pdk-migration/example/03-migrate-infra.mdx

@@ -8,6 +8,7 @@ import Link from '@components/link.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Drawer from '@components/drawer.astro';
 import InstallCommand from '@components/install-command.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 The last project we need to migrate for our shopping list application is the `InfrastructureTsProject`. This is a TypeScript CDK project, for which the Nx Plugin for AWS equivalent is the <Link path="/guides/typescript-infrastructure">`ts#infra` generator</Link>.
 
@@ -152,10 +153,10 @@ Notice that we don't pass the identity or API to the website - runtime config is
 
 Let's build the project now that we've migrated all the relevant parts of the codebase to our new project.
 
-<NxCommands commands={["run-many --target build"]} />
+<PackageManagerShortCommand commands={["build"]} />
 
 :::caution
 You may see a build failure due to lint issues. These can usually be automatically fixed:
 
-<NxCommands commands={["run-many --target lint --fix"]} />
+<PackageManagerShortCommand commands={["lint"]} />
 :::

package/docs/snippets/pdk-migration/example/04-deploy.mdx

@@ -8,6 +8,7 @@ import Link from '@components/link.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Drawer from '@components/drawer.astro';
 import InstallCommand from '@components/install-command.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 
 Now we've got our fully migrated codebase, we can look at deploying it. There are two paths we can take at this point.
@@ -22,7 +23,7 @@ The simplest approach is to treat this as a completely new application, meaning
 
 1. Deploy the new application:
 
-    <NxCommands commands={["deploy infra shopping-list-infra-sandbox/*"]} />
+    <NxCommands commands={['deploy-sandbox infra']} />
 
 </Steps>
 
@@ -63,7 +64,7 @@ For our shopping list application, the stateful resources we care about are the
 
     ```diff lang="ts"
     // packages/common/constructs/src/core/user-identity.ts
-    -this.userPool = this.createUserPool();
+    -this.userPool = this.createUserPool(mfa, mfaSecondFactor);
     +this.userPool = UserPool.fromUserPoolId(
     +  this,
     +  'UserPool',
@@ -73,9 +74,9 @@ For our shopping list application, the stateful resources we care about are the
 
 1. Build and deploy the new application:
 
-    <NxCommands commands={["run-many --target build"]} />
+    <PackageManagerShortCommand commands={["build"]} />
 
-    <NxCommands commands={["deploy infra shopping-list-infra-sandbox/*"]} />
+    <NxCommands commands={['deploy-sandbox infra']} />
 
     Now we have our new application stood up referencing the existing resources, not yet taking any traffic.
 
@@ -98,7 +99,7 @@ For our shopping list application, the stateful resources we care about are the
 
     ```diff lang="ts"
     // packages/common/constructs/src/core/user-identity.ts
-    +this.userPool = this.createUserPool();
+    +this.userPool = this.createUserPool(mfa, mfaSecondFactor);
     -this.userPool = UserPool.fromUserPoolId(
     -  this,
     -  'UserPool',
@@ -108,7 +109,7 @@ For our shopping list application, the stateful resources we care about are the
 
     And then run a build
 
-    <NxCommands commands={["run-many --target build"]} />
+    <PackageManagerShortCommand commands={["build"]} />
 
 1. Use `cdk import` in your new application's `packages/infra` folder to see which resources we'll be prompted to import.
 
@@ -199,7 +200,7 @@ For our shopping list application, the stateful resources we care about are the
 
 1. Deploy the new application again to make sure that any changes to these existing resources (now managed by your new stack) are made:
 
-    <NxCommands commands={["deploy infra shopping-list-infra-sandbox/*"]} />
+    <NxCommands commands={['deploy-sandbox infra']} />
 
 1. Perform a full test of your new application again
 

package/docs/snippets/pdk-migration/faq/type-safe-api.mdx

@@ -14,7 +14,7 @@ The most commonly used components from Type Safe API are covered in the example
 
 #### APIs Modelled with OpenAPI
 
-The Nx Plugin for AWS supports APIs modelled in Smithy, but not those modelled directly OpenAPI. The <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link> is a good starting point which you can then modify. You can define your OpenAPI specification in the `model` project's `src` folder instead of Smithy, and modify the `build.Dockerfile` to use your desired code generation tool for clients/servers if they aren't available on NPM. If your desired tools are on NPM, you can just install them as dev dependencies to your Nx workspace and call them directly as Nx build targets.
+The Nx Plugin for AWS supports APIs modelled in Smithy, but not those modelled directly OpenAPI. The <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link> is a good starting point which you can then modify. You can define your OpenAPI specification in the `model` project's `src` folder instead of Smithy, and update the `model` project's `compile` target to run your desired code generation tool for clients/servers. If your desired tools are on NPM, you can install them as dev dependencies to your Nx workspace and call them directly as Nx build targets.
 
 ##### Backend
 
@@ -153,7 +153,7 @@ const pythonLambdaHandler = new Function(this, 'PythonImplementation', {
   ...
 });
 
-new MyApi(this, 'MyApi', {
+new Api(this, 'MyApi', {
   integrations: Api.defaultIntegrations(this)
     .withOverrides({
       echo: {
@@ -199,6 +199,6 @@ Another option is to use GraphQL APIs with websockets on [AppSync](https://aws.a
 
 You can also consider rolling your own code generators which interpret the same vendor extensions as Type Safe API. Refer to the [APIs Modelled with OpenAPI](#apis-modelled-with-openapi) section for details around building custom OpenAPI-based code generators. You can find the templates Type Safe API uses for API Gateway Websocket API Lambda handlers [here](https://github.com/aws/aws-pdk/tree/mainline/packages/type-safe-api/scripts/type-safe-api/generators/typescript-async-runtime/templates), and the client [here](https://github.com/aws/aws-pdk/blob/mainline/packages/type-safe-api/scripts/type-safe-api/generators/typescript-websocket-client/templates/client.ejs).
 
-You can also consider migrating to use the <Link path="/guides/trpc.mdx">`ts#trpc-api` generator</Link> to use tRPC. At the time of writing we don't yet have support for subscriptions/streaming but if this is something you need do add a +1 to our [GitHub issue tracking this](https://github.com/awslabs/nx-plugin-for-aws/issues/194).
+You can also consider migrating to use the <Link path="/guides/trpc">`ts#trpc-api` generator</Link> to use tRPC. At the time of writing we don't yet have support for subscriptions/streaming but if this is something you need do add a +1 to our [GitHub issue tracking this](https://github.com/awslabs/nx-plugin-for-aws/issues/194).
 
 Smithy is protocol agnostic, but does not yet have support for the Websocket protocol, refer to [this GitHub issue tracking support](https://github.com/smithy-lang/smithy/issues/1505).

package/docs/snippets/prerequisites.mdx

@@ -1,7 +1,6 @@
 ---
 title: Prerequisites
 ---
-import Link from '@components/link.astro';
 import Snippet from '@components/snippet.astro';
 
 ### Required
@@ -11,7 +10,3 @@ import Snippet from '@components/snippet.astro';
 ### Recommended
 
 <Snippet name="recommended-prerequisites" parentHeading="Recommended" />
-
-:::tip[AI Assistant Setup]
-If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, you may also wish to <Link path="/get_started/building-with-ai">install the Nx Plugin for AWS MCP server.</Link>
-:::

package/docs/snippets/recommended-prerequisites.mdx

@@ -1,7 +1,7 @@
 ---
 title: Recommended Prerequisites
 ---
-- [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)
+- [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 >= 11](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.

package/docs/snippets/workspace-prerequisite.mdx

@@ -0,0 +1,8 @@
+---
+title: Workspace Prerequisite
+---
+import Link from '@components/link.astro';
+
+:::note[Start here]
+Generators run inside an Nx workspace with `@aws/nx-plugin` installed. If you don't have one yet, start by <Link path="guides/workspace">creating a workspace</Link>, or <Link path="get_started/existing-project">adding the plugin to an existing project</Link>.
+:::

package/package.json

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