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

package/docs/guides/react-website.mdx

@@ -50,16 +50,23 @@ The generator will create the following project structure in the `<directory>/<n
     - config.ts Application configuration (eg. logo)
     - components
       - AppLayout Components for the overall layout and navigation bar
+      - app-sidebar.tsx Sidebar navigation (shadcn only)
+      - alert.tsx Alert component wrapping your UX provider's own
+      - spinner.tsx Spinner component wrapping your UX provider's own
     - hooks
       - useAppLayout.tsx Hook for adjusting the AppLayout from nested components (Cloudscape only)
     - routes
+      - \_\_root.tsx Root route, wrapping every page in the AppLayout
       - index.tsx Example route (or page) for TanStack Router
+    - routeTree.gen.ts Route tree, generated and maintained by TanStack Router
     - styles.css Global styles
   - vite.config.mts Vite and Vitest configuration
+  - project.json Nx project defining the project's targets
   - tsconfig.json Base TypeScript configuration for source and tests
   - tsconfig.app.json TypeScript configuration for source code
   - tsconfig.spec.json TypeScript configuration for tests
   - package.json Project manifest defining the project's package name and dependencies
+  - README.md Project README
 </FileTree>
 
 :::note[Without TanStack Router]
@@ -157,27 +164,33 @@ Your website comes with [TanStack Router](https://tanstack.com/router/v1) config
 
 You can use the `Link` component or `useNavigate` hook to navigate between pages:
 
-```tsx {1, 4, 8-9, 14}
+```tsx {1, 8, 12-13, 18}
 import { Link, useNavigate } from '@tanstack/react-router';
 
-export const MyComponent = () => {
+export const MyComponent = ({
+  createProduct,
+}: {
+  createProduct: () => Promise<string>;
+}) => {
   const navigate = useNavigate();
 
   const submit = async () => {
-    const id = await ...
+    const id = await createProduct();
     // Use `navigate` for redirecting after some asynchronous action
-    navigate({ to: '/products/$id', { params: { id }} });
+    navigate({ to: '/products/$id', params: { id } });
   };
 
   return (
     <>
       <Link to="/products">Cancel</Link>
-      <Button onClick={submit}>Submit</Button>
+      <button onClick={submit}>Submit</button>
     </>
-  )
+  );
 };
 ```
 
+`$id` in the `to` path is a [path parameter](https://tanstack.com/router/latest/docs/framework/react/guide/path-params), supplied through `params`. Swap the plain `<button>` for your UX kit's own button component as needed.
+
 For more details, check out the [TanStack Router](https://tanstack.com/router/latest/docs/framework/react/overview) documentation.
 
 ## Deploying your Website
@@ -191,13 +204,13 @@ To deploy your website, we recommend using the <Link path="guides/typescript-inf
 You can use the CDK construct generated for you in `packages/common/constructs` to deploy your website.
 
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3, 9}
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     new MyWebsite(this, 'MyWebsite');
   }
@@ -266,13 +279,13 @@ The CloudFront distribution is protected by an [AWS WAFv2](https://docs.aws.amaz
 To opt out, set `enableWaf` to `false` when you create your website:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts" {10,15-18}
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { MyWebsite, suppressRules } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     const website = new MyWebsite(this, 'MyWebsite', {
       enableWaf: false,
@@ -318,14 +331,14 @@ The website bucket, the CloudFront distribution log bucket, and the CloudWatch L
 If you want to use a different encryption configuration, pass the `encryption`, `encryptionKey` and `enableKeyRotation` props when you create your website:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts" {11}
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { BucketEncryption } from 'aws-cdk-lib/aws-s3';
 import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     new MyWebsite(this, 'MyWebsite', {
       encryption: BucketEncryption.S3_MANAGED,
@@ -401,11 +414,12 @@ module "my_website" {
 ```
 
 :::caution[Checkov: S3_MANAGED]
-Choosing `S3_MANAGED` fails the `checkov` security scan with `CKV_AWS_145` on the website and distribution log buckets. The vended `test` target doesn't accept a `--config-file`, but `checkov` auto-discovers a `.checkov.yaml` in its working directory, so drop one in `packages/infra/src`:
+Choosing `S3_MANAGED` fails your project's `checkov` target with `CKV_AWS_145` on the website and distribution log buckets. The target runs `checkov` against your project's own `checkov.yml`, so add the check to its `skip-check` list:
 
-```yaml title="packages/infra/src/.checkov.yaml"
+```yaml title="packages/infra/checkov.yml" {3}
 skip-check:
-  - CKV_AWS_145
+  # ...
+  - CKV_AWS_145 # S3 buckets are not KMS encrypted when encryption is S3_MANAGED
 ```
 :::
 
@@ -439,11 +453,12 @@ module "my_website" {
 ```
 
 :::caution[Checkov: key rotation disabled]
-Disabling key rotation on the automatically created key fails the `checkov` security scan with `CKV_AWS_7`. Add it to the same `.checkov.yaml`:
+Disabling key rotation on the automatically created key fails your project's `checkov` target with `CKV_AWS_7`. Add it to the same `skip-check` list in `packages/infra/checkov.yml`:
 
-```yaml title="packages/infra/src/.checkov.yaml"
+```yaml title="packages/infra/checkov.yml" {3}
 skip-check:
-  - CKV_AWS_7
+  # ...
+  - CKV_AWS_7 # Key rotation is disabled on the website's KMS key
 ```
 :::
 </Fragment>
@@ -458,14 +473,14 @@ By default the distribution uses the default CloudFront domain name (`*.cloudfro
 Pass the `certificate` and `domainNames` props when you create your website:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts" {11-13}
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { Certificate } from 'aws-cdk-lib/aws-certificatemanager';
 import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     new MyWebsite(this, 'MyWebsite', {
       domainNames: ['www.example.com'],
@@ -508,13 +523,13 @@ The `RuntimeConfig` CDK construct can be used to add and retrieve configuration
 Your website CDK construct will deploy the `connection` namespace of the runtime configuration as a `runtime-config.json` file to the root of your S3 bucket.
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { Stack } from 'aws-cdk-lib';
+import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { MyWebsite, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string) {
-    super(scope, id);
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
 
     // Website can be declared at any point, since runtime config is resolved lazily
     new MyWebsite(this, 'MyWebsite');
@@ -582,6 +597,10 @@ const MyComponent = () => {
 };
 ```
 
+:::note[Added when you need it]
+`src/hooks/useRuntimeConfig.tsx` and `src/components/RuntimeConfig` are added to your website by the <Link path="/guides/react-website-auth">`ts#website#auth`</Link> generator and the <Link path="guides/connection">`connection`</Link> generators, since those are what put values into the runtime configuration. A website with neither has no runtime configuration to read, so the hook is not vended until one has run.
+:::
+
 :::note[Runtime Configuration]
 For details on how runtime configuration is stored in AWS AppConfig and how server-side consumers (Lambda functions, agents) can retrieve it, see the <Link path="guides/runtime-config">Runtime Configuration</Link> guide.
 :::

package/docs/guides/runtime-config.mdx

@@ -253,15 +253,27 @@ All generated API and agent constructs are automatically configured with:
 
 Use `getAppConfig` from [`@aws-lambda-powertools/parameters`](https://docs.aws.amazon.com/powertools/typescript/latest/features/parameters):
 
+`getAppConfig` returns any valid JSON value, so declare the shape you expect and cast the result — otherwise the property accesses do not compile under the workspace's strict `tsconfig`:
+
 ```ts
 import { getAppConfig } from '@aws-lambda-powertools/parameters/appconfig';
 
+interface ConnectionConfig {
+  apis?: Record<string, string>;
+  cognitoProps?: {
+    region: string;
+    userPoolId: string;
+    userPoolWebClientId: string;
+    identityPoolId: string;
+  };
+}
+
 // Retrieve the 'connection' namespace as a parsed JSON object
-const config = await getAppConfig('connection', {
+const config = (await getAppConfig('connection', {
   application: process.env.RUNTIME_CONFIG_APP_ID!,
   environment: 'default',
   transform: 'json',
-});
+})) as ConnectionConfig;
 
 // Access values
 const apiUrl = config.apis?.MyApi;
@@ -271,16 +283,24 @@ const cognitoProps = config.cognitoProps;
 You can also retrieve custom namespaces:
 
 ```ts
+interface TablesConfig {
+  users?: { tableName: string; tableArn: string };
+}
+
 // Retrieve a custom 'tables' namespace
-const tablesConfig = await getAppConfig('tables', {
+const tablesConfig = (await getAppConfig('tables', {
   application: process.env.RUNTIME_CONFIG_APP_ID!,
   environment: 'default',
   transform: 'json',
-});
+})) as TablesConfig;
 
 const usersTableName = tablesConfig.users?.tableName;
 ```
 
+:::tip[Validate at the boundary]
+A cast tells the compiler the shape but does not check it at runtime. For configuration you don't control, parse it with a [Zod](https://zod.dev/) schema instead, so a malformed value fails loudly rather than surfacing as `undefined` later.
+:::
+
   </TabItem>
   <TabItem label="Python" icon="seti:python">
 

package/docs/guides/security.mdx

@@ -28,7 +28,7 @@ Projects which build container images (for example agents, MCP servers, and data
 
 ### Credential Scanning
 
-Workspaces include [git-secrets](https://github.com/awslabs/git-secrets) pre-commit hooks which scan staged files for AWS credential patterns, preventing accidental commits of access keys and other sensitive values. See the <Link path="/guides/workspace#git-secrets">Git Secrets</Link> section of the workspace guide.
+Workspaces include [git-secrets](https://github.com/awslabs/git-secrets) pre-commit hooks which scan staged files for AWS credential patterns, preventing accidental commits of access keys and other sensitive values. Both creating a workspace and adopting the plugin into an existing one set these up, unless you opt out. See the <Link path="/guides/workspace#git-secrets">Git Secrets</Link> section of the workspace guide.
 
 ### Authentication
 

package/docs/guides/terraform-project.mdx

@@ -111,6 +111,8 @@ You can start writing your Terraform infrastructure inside `src/main.tf`, for ex
 +}
 ```
 
+Note that the S3 bucket above would fail the Checkov security scan, which checks that the bucket has the appropriate security settings enabled.
+
 ### Cross project dependencies
 
 If you wanted to execute a module from a separate project (lib), you could do so as follows:
@@ -134,8 +136,12 @@ To add new environments, create a new `src/env/<environment>.tfvars` file with t
 ```hcl
 # Production environment variables
 environment = "prod"
-region      = "us-west-2"
+aws_region  = "us-west-2"
 ```
+
+:::note[Variable names]
+Every name you set here must be declared in `src/variables.tf` — the generator declares `aws_region` and `environment`.
+:::
 </TabItem>
 <TabItem label="project.json">
 ```diff
@@ -200,7 +206,7 @@ region      = "us-west-2"
                     "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/dev.tfplan"
                 },
 +                "prod": {
-+                    "command": "terraform plan -var-file=env/dev.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
++                    "command": "terraform plan -var-file=env/prod.tfvars -out=../../../dist/packages/infra/terraform/prod.tfplan"
 +                }
             },
             "options": {

package/docs/guides/trpc.mdx

@@ -16,6 +16,8 @@ import NxCommands from '@components/nx-commands.astro';
 import Infrastructure from '@components/infrastructure.astro';
 import Snippet from '@components/snippet.astro';
 import OptionFilter from '@components/option-filter.astro';
+import InstallCommand from '@components/install-command.astro';
+import { TS_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
 
 [tRPC](https://trpc.io/) is a framework for building APIs in TypeScript with end-to-end type safety. Using tRPC, updates to API operation inputs and outputs are immediately reflected in client code and are visible in your IDE without the need to rebuild your project.
 
@@ -49,15 +51,18 @@ The generator will create the following project structure in the `<directory>/<a
 
 <FileTree>
   - src
+    - index.ts Package entrypoint re-exporting the router, context, client and schema
     - init.ts Backend tRPC initialisation
     - handler.ts Lambda handler entrypoint
     - router.ts tRPC router definition
     - schema Schema definitions using Zod
+      - index.ts Barrel re-exporting every schema
       - echo.ts Example definitions for the input and output of the "echo" procedure
       - z-async-iterable.ts Zod helper for subscriptions (REST API only)
     - procedures Procedures (or operations) exposed by your API
       - echo.ts Example procedure
     - middleware
+      - index.ts Barrel re-exporting the middleware, and the procedure context type
       - error.ts Middleware for error handling
       - logger.ts middleware for configuring AWS Powertools for Lambda logging
       - tracer.ts middleware for configuring AWS Powertools for Lambda tracing
@@ -65,9 +70,15 @@ The generator will create the following project structure in the `<directory>/<a
     - local-server.ts tRPC standalone adapter entrypoint for local development server
     - client
       - index.ts Type-safe client for machine-to-machine API calls
+  - rolldown.config.ts Bundle configuration for the Lambda deployment package
   - tsconfig.json TypeScript configuration
+  - tsconfig.lib.json TypeScript configuration for the library sources
+  - tsconfig.spec.json TypeScript configuration for the tests
+  - vitest.config.mts Vitest configuration
   - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
+  - README.md Project readme
+  - .gitignore Ignores the project's build output
 
 </FileTree>
 
@@ -297,6 +308,10 @@ As an example, let's implement some middlware to extract some details about the
 <OptionFilter when={{ auth: 'iam' }} description="Identity middleware example for IAM-authenticated APIs">
 This example walks through identity middleware for `IAM` authentication. We look up the caller in Cognito using the sub extracted from the API Gateway event.
 
+The lookup uses the Cognito Identity Provider client, which is not a dependency of a generated tRPC API. Install it into your API project first:
+
+<InstallCommand pkg={`@aws-sdk/client-cognito-identity-provider@${TS_VERSIONS['@aws-sdk/client-cognito-identity-provider']}`} project="@my-scope/my-api" />
+
 First, we define what we'll add to the context:
 
 ```ts
@@ -334,8 +349,8 @@ In our case, we want to extract details about the calling Cognito user. We'll do
 ```ts
 import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
 import { initTRPC, TRPCError } from '@trpc/server';
-import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
-import { APIGatewayProxyEvent } from 'aws-lambda';
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
 
 export interface IIdentityContext {
   identity?: {
@@ -345,12 +360,17 @@ export interface IIdentityContext {
 }
 
 export const createIdentityPlugin = () => {
-  const t = initTRPC.context<IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEvent>>().create();
+  const t = initTRPC
+    .context<
+      IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEvent>
+    >()
+    .create();
 
   const cognito = new CognitoIdentityProvider();
 
   return t.procedure.use(async (opts) => {
-    const cognitoAuthenticationProvider = opts.ctx.event.requestContext?.identity?.cognitoAuthenticationProvider;
+    const cognitoAuthenticationProvider =
+      opts.ctx.event.requestContext?.identity?.cognitoAuthenticationProvider;
 
     let sub: string | undefined = undefined;
     if (cognitoAuthenticationProvider) {
@@ -397,8 +417,8 @@ export const createIdentityPlugin = () => {
 ```ts
 import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
 import { initTRPC, TRPCError } from '@trpc/server';
-import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
-import { APIGatewayProxyEventV2WithIAMAuthorizer } from 'aws-lambda';
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEventV2WithIAMAuthorizer } from 'aws-lambda';
 
 export interface IIdentityContext {
   identity?: {
@@ -408,7 +428,12 @@ export interface IIdentityContext {
 }
 
 export const createIdentityPlugin = () => {
-  const t = initTRPC.context<IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEventV2WithIAMAuthorizer>>().create();
+  const t = initTRPC
+    .context<
+      IIdentityContext &
+        CreateAWSLambdaContextOptions<APIGatewayProxyEventV2WithIAMAuthorizer>
+    >()
+    .create();
 
   const cognito = new CognitoIdentityProvider();
 
@@ -481,12 +506,16 @@ export interface IIdentityContext {
 
 Note that we define an additional _optional_ property on the context. tRPC manages ensuring that this is defined in procedures which have correctly configured this middleware.
 
-Next, the middleware itself:
+Next, the middleware itself. The event type and the location of the claims differ between a REST API and an HTTP API, so the implementation depends on your selected `infra`:
+
+<Tabs syncKey="http-rest">
+<TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
+A REST API's Cognito User Pools authorizer places the claims at `event.requestContext.authorizer.claims`:
 
 ```ts
 import { initTRPC, TRPCError } from '@trpc/server';
-import { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
-import { APIGatewayProxyEvent } from 'aws-lambda';
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
 
 export interface IIdentityContext {
   identity?: {
@@ -497,7 +526,9 @@ export interface IIdentityContext {
 
 export const createIdentityPlugin = () => {
   const t = initTRPC
-    .context<IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEvent>>()
+    .context<
+      IIdentityContext & CreateAWSLambdaContextOptions<APIGatewayProxyEvent>
+    >()
     .create();
 
   return t.procedure.use(async (opts) => {
@@ -506,7 +537,7 @@ export const createIdentityPlugin = () => {
       | undefined;
 
     const sub = claims?.sub;
-    const username = claims?.username;
+    const username = claims?.username ?? claims?.['cognito:username'];
 
     if (!sub || !username) {
       throw new TRPCError({
@@ -527,6 +558,59 @@ export const createIdentityPlugin = () => {
   });
 };
 ```
+</TabItem>
+<TabItem label="HTTP API" _filter={{ infra: 'http-lambda' }}>
+An HTTP API's JWT authorizer delivers a payload-v2 event whose claims sit one level deeper, at `event.requestContext.authorizer.jwt.claims`. The context must be typed on `APIGatewayProxyEventV2WithJWTAuthorizer` to match the one the generated `publicProcedure` uses — otherwise `.concat()` fails with tRPC's `Context mismatch` error:
+
+```ts
+import { initTRPC, TRPCError } from '@trpc/server';
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEventV2WithJWTAuthorizer } from 'aws-lambda';
+
+export interface IIdentityContext {
+  identity?: {
+    sub: string;
+    username: string;
+  };
+}
+
+export const createIdentityPlugin = () => {
+  const t = initTRPC
+    .context<
+      IIdentityContext &
+        CreateAWSLambdaContextOptions<APIGatewayProxyEventV2WithJWTAuthorizer>
+    >()
+    .create();
+
+  return t.procedure.use(async (opts) => {
+    const claims = opts.ctx.event.requestContext?.authorizer?.jwt?.claims as
+      | Record<string, string>
+      | undefined;
+
+    const sub = claims?.sub;
+    const username = claims?.username ?? claims?.['cognito:username'];
+
+    if (!sub || !username) {
+      throw new TRPCError({
+        code: 'FORBIDDEN',
+        message: 'Unable to determine calling user',
+      });
+    }
+
+    return await opts.next({
+      ctx: {
+        ...opts.ctx,
+        identity: {
+          sub,
+          username,
+        },
+      },
+    });
+  });
+};
+```
+</TabItem>
+</Tabs>
 
 You can then mix the plugin into any procedure that needs the caller's identity:
 

package/docs/guides/ts-agent.mdx

@@ -61,6 +61,8 @@ The generator will add the following files to your existing TypeScript project.
         - router.ts tRPC router with agent procedures
         - agent.ts Main agent definition with sample tools
         - session.ts Resolves the SessionManager used to persist conversation state
+        - schema/
+          - z-async-iterable.ts Zod schema for the router's streamed responses
         - client.ts Vended client for invoking your agent
         - agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
         - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
@@ -81,6 +83,8 @@ The entry point uses the [Strands A2A Express Server](https://strandsagents.com/
         - index.ts A2A Express server entry point
         - agent.ts Main agent definition with sample tools
         - session.ts Resolves the SessionManager used to persist conversation state
+        - middleware/
+          - session-id-middleware.ts Binds the inbound AgentCore session ID for the request
         - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - package.json Updated with Strands and Express dependencies
     - project.json Updated with agent serve targets
@@ -99,6 +103,8 @@ The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui
         - index.ts AG-UI server entry point (Express + SSE)
         - agent.ts Main agent definition with sample tools
         - session.ts Resolves the SessionManager used to persist conversation state
+        - middleware/
+          - session-id-middleware.ts Binds the inbound AgentCore session ID for the request
         - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - package.json Updated with Strands and AG-UI dependencies
     - project.json Updated with agent serve targets
@@ -280,7 +286,9 @@ If you have added multiple components to your project (agents, MCP servers, etc.
 
 <NxCommands commands={['agent-dev your-project']} />
 
-This uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
+This uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents — read it from `metadata.ports` in the project's `project.json`).
+
+A `<your-agent-name>-serve` target is also generated, which runs the agent against your deployed infrastructure and therefore requires `RUNTIME_CONFIG_APP_ID` to be set. See the <Link path="guides/local-development">Local Development</Link> guide for the difference between `dev` and `serve`.
 
 ### Chat with Your Agent
 
@@ -400,12 +408,16 @@ Generate the session ID rather than deriving it from user-supplied values such a
 
 ## Invoking your Agent
 
+<OptionFilter when={{ protocol: 'http' }} description="tRPC-over-WebSocket client factory invocation details">
 Agent communication is transmitted via tRPC over WebSocket. As such, it's recommended to use the generated type-safe client factory in `client.ts`.
 
-<OptionFilter when={{ protocol: 'http' }} description="tRPC-over-WebSocket client factory invocation details">
 ### Invoke the Local Server
 
-You can invoke a locally running agent using the `.local` factory method from the client factory.
+Start your agent with the `<your-agent-name>-dev` target:
+
+<NxCommands commands={['agent-dev your-project']} />
+
+Then invoke it using the `.local` factory method from the client factory.
 
 You can, for example create a file named `scripts/test.ts` in your workspace which imports the client:
 
@@ -420,6 +432,8 @@ const client = MyAgentClient.local({ url: 'http://localhost:8081/ws' });
 client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, { onData: console.log });
 ```
 
+Substitute the port assigned to your agent — read it from `metadata.ports` in the project's `project.json`.
+
 :::tip[Quick Testing]
 Run with `tsx` as a quick way to test out your agent.
 

package/docs/guides/ts-dcr-proxy.mdx

@@ -41,6 +41,12 @@ The generator creates a standalone <Link path="/guides/typescript-project">TypeS
       - authorize.ts Redirects to the Cognito Hosted UI
       - token.ts Injects the App Client secret and exchanges the token
       - mcp-proxy.ts Proxies `/mcp` requests to the upstream MCP server
+    - index.ts Project entry point
+  - rolldown.config.ts Bundle configuration, one entry per handler
+  - README.md Project README
+  - package.json Declares the handlers' dependencies
+  - project.json Adds a bundle target per handler
+  - tsconfig.json / tsconfig.lib.json / tsconfig.spec.json TypeScript configuration
 
 </FileTree>
 
@@ -103,7 +109,7 @@ You provide:
 Instantiate the generated construct in your stack, passing the required properties:
 
 ```typescript
-import { DcrProxy } from ':my-scope/common-constructs';
+import { DcrProxy } from '@my-scope/common-constructs';
 
 new DcrProxy(this, 'DcrProxy', {
   userPoolId: userPool.userPoolId,
@@ -155,8 +161,9 @@ import {
   DcrProxy,
   MyProjectMcpServer,
   UserIdentity,
-} from ':my-scope/common-constructs';
+} from '@my-scope/common-constructs';
 import { OAuthScope } from 'aws-cdk-lib/aws-cognito';
+import * as kms from 'aws-cdk-lib/aws-kms';
 import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
 
 const identity = new UserIdentity(this, 'Identity');
@@ -179,6 +186,9 @@ const proxyClient = identity.userPool.addClient('DcrProxyClient', {
 // Store the App Client secret in Secrets Manager for the token handler to read
 const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
   secretStringValue: proxyClient.userPoolClientSecret,
+  encryptionKey: new kms.Key(this, 'ClientSecretKey', {
+    enableKeyRotation: true,
+  }),
 });
 
 // The MCP server, authorizing JWTs issued for the same App Client
@@ -267,8 +277,9 @@ import {
   DcrProxy,
   MyGateway,
   UserIdentity,
-} from ':my-scope/common-constructs';
+} from '@my-scope/common-constructs';
 import { OAuthScope } from 'aws-cdk-lib/aws-cognito';
+import * as kms from 'aws-cdk-lib/aws-kms';
 import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
 
 const identity = new UserIdentity(this, 'Identity');
@@ -291,6 +302,9 @@ const proxyClient = identity.userPool.addClient('DcrProxyClient', {
 // Store the App Client secret in Secrets Manager for the token handler to read
 const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
   secretStringValue: proxyClient.userPoolClientSecret,
+  encryptionKey: new kms.Key(this, 'ClientSecretKey', {
+    enableKeyRotation: true,
+  }),
 });
 
 // The gateway, authorizing JWTs issued for the same App Client
@@ -307,7 +321,7 @@ new DcrProxy(this, 'DcrProxy', {
   cognitoClientSecretArn: clientSecret.secretArn,
   cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
   // Use the gateway construct's URL rather than hardcoding it
-  upstreamUrl: gateway.gateway.gatewayUrl,
+  upstreamUrl: gateway.gatewayUrl,
 });
 ```
 </Fragment>
@@ -341,7 +355,7 @@ resource "aws_secretsmanager_secret_version" "client_secret" {
 
 # The gateway, authorizing JWTs issued for the same App Client
 module "my_gateway" {
-  source = "../../common/terraform/src/app/agentcore-gateway/my-gateway"
+  source = "../../common/terraform/src/app/gateways/my-gateway"
 
   user_pool_id         = module.user_identity.user_pool_id
   user_pool_client_ids = [aws_cognito_user_pool_client.dcr_proxy.id]
@@ -466,8 +480,9 @@ import {
   DcrProxy,
   MyProjectMcpServer,
   UserIdentity,
-} from ':my-scope/common-constructs';
+} from '@my-scope/common-constructs';
 import { OAuthScope, CfnManagedLoginBranding } from 'aws-cdk-lib/aws-cognito';
+import * as kms from 'aws-cdk-lib/aws-kms';
 import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
 
 // The user pool created by ts#website#auth for your website users
@@ -492,6 +507,9 @@ new CfnManagedLoginBranding(this, 'DcrProxyClientBranding', {
 
 const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
   secretStringValue: proxyClient.userPoolClientSecret,
+  encryptionKey: new kms.Key(this, 'ClientSecretKey', {
+    enableKeyRotation: true,
+  }),
 });
 
 const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer', {