@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.90

package/docs/guides/connection/react-agui.mdx

@@ -2,7 +2,7 @@
 title: React to AG-UI Agent
 description: Connect a React website to an Agent via the AG-UI protocol using CopilotKit
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType:
     - ts#agent
     - py#agent
@@ -22,7 +22,7 @@ Nx Plugin for AWS provides a generator to connect a React website to an Agent th
 Before using this generator, ensure you have:
 
 1. A React website (generated using the <Link path="guides/react-website">`ts#website` generator</Link>)
-2. A TypeScript or Python Agent with `protocol=AG-UI` (generated using the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator)
+2. A TypeScript or Python Agent with `protocol=ag-ui` (generated using the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator)
 3. For deployed agents, Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>
 
 ## Usage
@@ -47,8 +47,8 @@ The generator creates a **single shared** `AguiProvider` component, one hook per
   - components
     - AguiProvider.tsx Single `CopilotKitProvider` for every AG-UI agent. Created on the first `connection` run and updated on subsequent runs to register each new agent.
     - copilot
-      - index.tsx Re-exports `CopilotChat`, `CopilotSidebar` and `CopilotPopup` with slot defaults that match your website's `uxProvider` (Cloudscape, Shadcn, or no theme at all).
-      - *ThemeComponents*.tsx Per-slot theme components (e.g. `CloudscapeAssistantMessage.tsx`, `ShadcnChatInput.tsx`). Only vended when `uxProvider` is `Cloudscape` or `Shadcn`.
+      - index.tsx Re-exports `CopilotChat`, `CopilotSidebar` and `CopilotPopup` with slot defaults that match your website's `ux` (Cloudscape, Shadcn, or no theme at all).
+      - *ThemeComponents*.tsx Per-slot theme components (e.g. `CloudscapeAssistantMessage.tsx`, `ShadcnChatInput.tsx`). Only vended when `ux` is `cloudscape` or `shadcn`.
   - hooks
     - useAgui\<AgentName>.tsx Registers one AG-UI agent. One file per `connection` run.
     - useSigV4.tsx SigV4 signing (IAM only)
@@ -71,7 +71,7 @@ The following dependencies are added to the root `package.json`:
 Each `useAgui<AgentName>` hook reads its agent's runtime value from <Link path="guides/runtime-config">Runtime Configuration</Link> and instantiates an `@ag-ui/client` `HttpAgent`:
 
 - **Deployed**: the runtime value is a Bedrock AgentCore Runtime ARN, which is converted to the AgentCore HTTPS endpoint: `https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT`
-- **Local development**: `serve-local` overrides the value to the agent's local URL (e.g. `http://localhost:8081`)
+- **Local development**: `dev` overrides the value to the agent's local URL (e.g. `http://localhost:8081`)
 
 The shared `AguiProvider` calls every generated hook and spreads each one into `selfManagedAgents` on a single `CopilotKitProvider`, which exposes them all to CopilotKit components.
 
@@ -92,6 +92,25 @@ The generated code handles authentication depending on your agent's configuratio
 - **IAM** (default): uses AWS SigV4-signed HTTP requests. Credentials are obtained from the Cognito Identity Pool configured with your website's auth.
 - **Cognito**: embeds the JWT access token in the `Authorization` header as a Bearer token.
 
+### Sessions and Threads
+
+AG-UI and AgentCore Runtime each identify a conversation differently, and the generated hook ties them together:
+
+- **`threadId`** — the AG-UI conversation identifier, sent in the request body. CopilotKit generates a random UUID per chat unless you pass an explicit `threadId`.
+- **Session ID** — the AgentCore Runtime session, sent in the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header. It selects the [microVM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html) serving the request, and is what your agent's `session.ts` / `session.py` keys conversation state on.
+
+The hook derives the session ID from the thread ID, right-padding it to the 33 characters AgentCore Runtime requires:
+
+```ts
+function agentCoreSessionId(input: RunAgentInput): string {
+  return (input.threadId ?? '').padEnd(33, '0');
+}
+```
+
+Leaving `threadId` unset is simplest — CopilotKit's generated UUID is already 36 characters. If you pass one explicitly, make it at least 33 characters, since padding maps thread IDs that differ only in trailing characters onto the same session.
+
+Both Session ID and Thread ID are provided by the browser. To restrict each user to their own conversations, refer to the <Link path="guides/py-agent">`py#agent`</Link> or <Link path="guides/ts-agent">`ts#agent`</Link> guide.
+
 ## Infrastructure
 
 <Snippet name="connection/react-agent-infrastructure" parentHeading="Infrastructure" />
@@ -102,7 +121,7 @@ The generated code handles authentication depending on your agent's configuratio
 
 Instantiate CopilotKit components with `agentId` to select which agent to use. The id is the agent's name — the same one you chose when you ran the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator — and you can also find it in the generated hook file (e.g. the key returned from `packages/web/src/hooks/useAgui<AgentName>.tsx`).
 
-Import the chat components from the generated `./components/copilot` module so the theme that matches your website's `uxProvider` is applied automatically:
+Import the chat components from the generated `./components/copilot` module so the theme that matches your website's `ux` is applied automatically:
 
 ```tsx
 import { CopilotChat } from './components/copilot';
@@ -137,13 +156,13 @@ import { CopilotChat } from './components/copilot';
 
 ### Built-in Themes
 
-The generator reads `metadata.uxProvider` from your React website project and vends a themed wrapper module at `src/components/copilot/index.tsx` so the chat components match the rest of your UI without any extra configuration:
+The generator reads `metadata.ux` from your React website project and vends a themed wrapper module at `src/components/copilot/index.tsx` so the chat components match the rest of your UI without any extra configuration:
 
-| `uxProvider` | Styling applied to `CopilotChat` / `CopilotSidebar` / `CopilotPopup` |
+| `ux` | Styling applied to `CopilotChat` / `CopilotSidebar` / `CopilotPopup` |
 | ------------ | -------------------------------------------------------------------- |
-| `Cloudscape` | Messages render inside Cloudscape `ChatBubble`s with gen-AI `Avatar`s (matching the [Cloudscape generative AI chat pattern](https://cloudscape.design/patterns/genai/generative-AI-chat/)); the typing indicator becomes a `LoadingBar` and the input is a `PromptInput`. Built from `@cloudscape-design/components` and `@cloudscape-design/chat-components`. |
-| `Shadcn` | Assistant messages render in a `bg-muted` bubble with a `Sparkles` avatar; user messages render right-aligned in a `bg-primary` bubble with a `User` avatar. The input is a rounded `Textarea` + pill-shaped send/stop `Button` (Enter submits, Shift+Enter newlines). Uses shadcn primitives from the shared `common-shadcn` package. |
-| `None` (or anything else) | No theme — the module just re-exports the default CopilotKit components. |
+| `cloudscape` | Messages render inside Cloudscape `ChatBubble`s with gen-AI `Avatar`s (matching the [Cloudscape generative AI chat pattern](https://cloudscape.design/patterns/genai/generative-AI-chat/)); the typing indicator becomes a `LoadingBar` and the input is a `PromptInput`. Built from `@cloudscape-design/components` and `@cloudscape-design/chat-components`. |
+| `shadcn` | Assistant messages render in a `bg-muted` bubble with a `Sparkles` avatar; user messages render right-aligned in a `bg-primary` bubble with a `User` avatar. The input is a rounded `Textarea` + pill-shaped send/stop `Button` (Enter submits, Shift+Enter newlines). Uses shadcn primitives from the shared `common-shadcn` package. |
+| `none` (or anything else) | No theme — the module just re-exports the default CopilotKit components. |
 
 Import the themed components from the **local theme module** (not `@copilotkit/react-core/v2` directly) so the theme is applied automatically:
 
@@ -218,13 +237,13 @@ Deeper overrides follow the same shape — e.g. replace just the copy button on
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration:
+The connection generator automatically configures `dev` integration:
 
-1. Running `nx serve-local <website>` will also start the agent's local server
+1. Running `nx dev <website>` will also start the agent's local server
 2. The runtime config is overridden to point to the local AG-UI URL (e.g. `http://localhost:8081`)
 3. Both the website and the agent hot-reload together
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 :::tip[Hot Reloading]
 The website and connected agent hot-reload together, enabling you to quickly iterate on both sides without deploying to AWS.

package/docs/guides/connection/react-fastapi.mdx

@@ -2,7 +2,7 @@
 title: React to FastAPI
 description: Connect a React website to a Python FastAPI
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: py#fast-api
 ---
 
@@ -115,9 +115,9 @@ Whenever you make changes to your FastAPI, you need to rebuild your project in o
 :::
 
 :::tip[Auto-Regeneration]
-If you're actively working on both your React application and FastAPI together, use the React application's `serve-local` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local FastAPI server:
+If you're actively working on both your React application and FastAPI together, use the React application's `dev` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local FastAPI server:
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 For more fine-grained control, you can use the `watch-generate:<ApiName>-client` target for your React application to regenerate the client every time you make API changes:
 
@@ -312,6 +312,42 @@ function CreateItemForm() {
 ```
 </Drawer>
 
+### File Uploads
+
+For endpoints that accept a file upload, the generated client sends the request as `FormData`. Define an operation with a `multipart/form-data` body in your FastAPI, for example using `UploadFile`:
+
+```python
+from fastapi import UploadFile
+
+@app.post("/files")
+async def upload_file(file: UploadFile, description: str = "") -> FileMetadata:
+    contents = await file.read()
+    ...
+```
+
+Binary fields are typed as `Blob` on the generated client, and other fields (such as `description` above) keep their modelled types. Pass a `Blob` or `File` — for example one obtained from an `<input type="file">`:
+
+```tsx {9-12}
+import { useMutation } from '@tanstack/react-query';
+import { useMyApi } from './hooks/useMyApi';
+
+function UploadForm() {
+  const api = useMyApi();
+  const uploadFile = useMutation(api.uploadFile.mutationOptions());
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      uploadFile.mutate({ file, description: file.name });
+    }
+  };
+
+  return <input type="file" onChange={handleChange} />;
+}
+```
+
+The client builds a `FormData` body and lets `fetch` set the `Content-Type` (including the multipart boundary) automatically.
+
 ### Pagination with Infinite Queries
 
 For endpoints that accept a `cursor` parameter as input, the generated hooks provide support for infinite queries using TanStack Query's `useInfiniteQuery` hook. This makes it easy to implement "load more" or infinite scrolling functionality.

package/docs/guides/connection/react-py-agent.mdx

@@ -2,7 +2,7 @@
 title: React to Python Agent
 description: Connect a React website to a Python Agent
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: py#agent
   protocol: http
 ---
@@ -16,7 +16,7 @@ import Snippet from '@components/snippet.astro';
 Nx Plugin for AWS provides a generator to quickly integrate your <Link path="guides/py-agent">Python Agent</Link> with a React website. It sets up all necessary configuration for connecting to your agent via a type-safe OpenAPI-generated client, including AWS IAM and Cognito authentication support.
 
 :::tip[AG-UI agents]
-If your Python Agent was generated with `protocol=AG-UI`, the connection generator instead wires up [CopilotKit](https://docs.copilotkit.ai/aws-strands) and an [`@ag-ui/client`](https://docs.ag-ui.com/) `HttpAgent` on the React website. See the <Link path="guides/connection/react-agui">React to AG-UI Agent</Link> guide for details.
+If your Python Agent was generated with `protocol=ag-ui`, the connection generator instead wires up [CopilotKit](https://docs.copilotkit.ai/aws-strands) and an [`@ag-ui/client`](https://docs.ag-ui.com/) `HttpAgent` on the React website. See the <Link path="guides/connection/react-agui">React to AG-UI Agent</Link> guide for details.
 :::
 
 ## Prerequisites
@@ -24,7 +24,7 @@ If your Python Agent was generated with `protocol=AG-UI`, the connection generat
 Before using this generator, ensure you have:
 
 1. A React website (generated using the <Link path="guides/react-website">`ts#website` generator</Link>)
-2. A Python Agent with `protocol=HTTP` (generated using the <Link path="guides/py-agent">`py#agent` generator</Link>)
+2. A Python Agent with `protocol=http` (generated using the <Link path="guides/py-agent">`py#agent` generator</Link>)
 3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>
 
 ## Usage
@@ -122,11 +122,8 @@ function ChatComponent() {
     },
   }));
 
-  const handleSend = (message: string) => {
-    invoke.mutate({
-      prompt: message,
-      sessionId: 'my-session',
-    });
+  const handleSend = (prompt: string) => {
+    invoke.mutate({ prompt });
   };
 
   return (
@@ -154,12 +151,9 @@ function ChatComponent() {
   const client = useMyAgentClient();
   const [chunks, setChunks] = useState<StreamChunk[]>([]);
 
-  const handleSend = async (message: string) => {
+  const handleSend = async (prompt: string) => {
     setChunks([]);
-    for await (const chunk of client.invoke({
-      prompt: message,
-      sessionId: 'my-session',
-    })) {
+    for await (const chunk of client.invoke({ prompt })) {
       setChunks((prev) => [...prev, chunk]);
     }
   };
@@ -177,13 +171,13 @@ function ChatComponent() {
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration:
+The connection generator automatically configures `dev` integration:
 
-1. Running `nx serve-local <website>` will also start the agent's local FastAPI server
+1. Running `nx dev <website>` will also start the agent's local FastAPI server
 2. The runtime config is overridden to point to the local HTTP URL (e.g., `http://localhost:8081/`)
 3. The TypeScript client is automatically regenerated when the agent's API changes
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 :::tip[Hot Reloading]
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.

package/docs/guides/connection/react-smithy.mdx

@@ -2,8 +2,8 @@
 title: React to Smithy API
 description: Connect a React website to a Smithy TypeScript API
 when:
-  sourceType: react
-  targetType: smithy
+  sourceType: ts#react-website
+  targetType: ts#smithy-api
 ---
 
 import { FileTree, Steps } from '@astrojs/starlight/components';
@@ -116,9 +116,9 @@ Whenever you make changes to your Smithy API model, you need to rebuild your pro
 :::
 
 :::tip[Auto-Regeneration]
-If you're actively working on both your React application and Smithy API together, use the React application's `serve-local` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local Smithy API server:
+If you're actively working on both your React application and Smithy API together, use the React application's `dev` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local Smithy API server:
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 For more fine-grained control, you can use the `watch-generate:<ApiName>-client` target for your React application to regenerate the client every time you make API changes:
 

package/docs/guides/connection/react-trpc.mdx

@@ -2,7 +2,7 @@
 title: React to tRPC
 description: Connect a React website to a tRPC API
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: ts#trpc-api
 ---
 import { FileTree } from '@astrojs/starlight/components';

package/docs/guides/connection/react-ts-agent.mdx

@@ -2,7 +2,7 @@
 title: React to TypeScript Agent
 description: Connect a React website to a TypeScript Agent
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: ts#agent
   protocol: http
 ---
@@ -64,13 +64,13 @@ Additionally, it installs the required dependencies:
 The generated client connects to your Agent via tRPC over WebSocket. The agent exposes a tRPC router (including the `invoke` subscription for streaming agent responses) over a WebSocket endpoint.
 
 - **Deployed**: The agent runtime ARN is loaded from <Link path="guides/runtime-config">Runtime Configuration</Link>. Running this connection generator also patches the agent's generated CDK/Terraform construct to publish its ARN to the website's `runtime-config.json` (under the `connection` namespace), so only agents you explicitly connect are exposed to the frontend. The ARN is converted to a WebSocket URL following the Bedrock AgentCore Runtime WebSocket protocol: `wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws`
-- **Local development**: When running with `serve-local`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
+- **Local development**: When running with `dev`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
 
 ### Authentication
 
 The generated code handles authentication depending on your agent's configuration:
 
-- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `serve-local` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `dev` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
 - **Cognito**: Embeds the JWT access token in the `Sec-WebSocket-Protocol` header as a base64url-encoded bearer token, following the [AgentCore WebSocket auth protocol](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html)
 
 
@@ -93,7 +93,7 @@ function ChatComponent() {
 
   const subscription = useSubscription(
     trpc.invoke.subscriptionOptions(
-      { message: 'What can you help me with?' },
+      { prompt: 'What can you help me with?' },
       {
         enabled: true,
         onStarted: () => {
@@ -135,9 +135,9 @@ function ChatComponent() {
   const client = useMyAgentAgentClient();
   const [messages, setMessages] = useState<string[]>([]);
 
-  const sendMessage = (message: string) => {
+  const sendMessage = (prompt: string) => {
     const subscription = client.invoke.subscribe(
-      { message },
+      { prompt },
       {
         onData: (token) => {
           setMessages((prev) => [...prev, token]);
@@ -174,11 +174,11 @@ For more details on the vanilla tRPC client, see the [tRPC Vanilla Client docume
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration for your react website:
+The connection generator automatically configures `dev` integration for your react website:
 
-1. Running `nx serve-local <website>` will also start the agent's local server
+1. Running `nx dev <website>` will also start the agent's local server
 2. The runtime config is overridden to point to the local WebSocket URL (e.g., `ws://localhost:8081/ws`)
-3. Like with connected APIs, authentication is skipped in `serve-local` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+3. Like with connected APIs, authentication is skipped in `dev` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
 
 :::tip[Hot Reloading]
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.

package/docs/guides/connection/smithy-dynamodb.mdx

@@ -1,8 +1,8 @@
 ---
 title: Smithy API to DynamoDB
-description: Connect a Smithy API to a DynamoDB table
+description: Connect a Smithy API to a TypeScript DynamoDB project
 when:
-  sourceType: smithy
+  sourceType: ts#smithy-api
   targetType: ts#dynamodb
 ---
 import { FileTree } from '@astrojs/starlight/components';
@@ -12,7 +12,7 @@ import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Snippet from '@components/snippet.astro';
 
-The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 
@@ -35,14 +35,14 @@ Select your Smithy API backend project as the source and your DynamoDB project a
 
 ## Generator Output
 
-The generator updates your Smithy API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
+The generator updates your Smithy API's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target. No source files are modified.
 
 ## Using DynamoDB in Operations
 
 Import entity factories from the DynamoDB package and use them inside your operation implementations:
 
 ```ts title="packages/api/src/operations/list-examples.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 import {
   ListExamplesOperationInput,
   ListExamplesOperationOutput,

package/docs/guides/connection/smithy-rdb.mdx

@@ -2,7 +2,7 @@
 title: Smithy API to Relational Database
 description: Connect a Smithy API to a Relational Database
 when:
-  sourceType: smithy
+  sourceType: ts#smithy-api
   targetType: ts#rdb
 ---
 import { FileTree } from '@astrojs/starlight/components';
@@ -46,7 +46,7 @@ The generator modifies three existing files in your Smithy API backend:
 
 </FileTree>
 
-Additionally, it updates the API's `serve-local` target to start the database automatically.
+Additionally, it updates the API's `dev` target to start the database automatically.
 
 ## How It Works
 
@@ -55,7 +55,7 @@ Additionally, it updates the API's `serve-local` target to start the database au
 The generator adds a typed `db` property to `ServiceContext` in `context.ts`:
 
 ```ts title="packages/api/src/context.ts" {1,7}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export interface ServiceContext {
   tracer: Tracer;
@@ -69,8 +69,8 @@ export interface ServiceContext {
 
 The Prisma client is instantiated inside `lambdaHandler` and passed through the service context:
 
-```ts title="packages/api/src/handler.ts" {1,10}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+```ts title="packages/api/src/handler.ts" {1,5,10}
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export const lambdaHandler = async (event: APIGatewayProxyEvent) => {
   const httpRequest = convertEvent(event);
@@ -134,14 +134,14 @@ const httpResponse = await serviceHandler.handle(httpRequest, {
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development
 
 The generator applies the same Prisma client injection inside the request handler in `local-server.ts`:
 
 ```ts title="packages/api/src/local-server.ts" {1,5,10}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 const server = createServer(async function (req, res) {
   const httpRequest = convertRequest(req);
@@ -156,6 +156,6 @@ const server = createServer(async function (req, res) {
 });
 ```
 
-<NxCommands commands={["serve-local <api-project-name>"]} />
+<NxCommands commands={["dev <api-project-name>"]} />
 
-This starts both the API and the local database. The `SERVE_LOCAL=true` environment variable is set automatically, so the Prisma client connects to the local Docker database instead of Aurora.
+This starts both the API and the local database. The `LOCAL_DEV=true` environment variable is set automatically, so the Prisma client connects to the local Docker database instead of Aurora.

package/docs/guides/connection/trpc-dynamodb.mdx

@@ -1,6 +1,6 @@
 ---
 title: tRPC API to DynamoDB
-description: Connect a tRPC API to a DynamoDB table
+description: Connect a tRPC API to a TypeScript DynamoDB project
 when:
   sourceType: ts#trpc-api
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Snippet from '@components/snippet.astro';
 
-The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 
@@ -35,14 +35,14 @@ Select your tRPC API project as the source and your DynamoDB project as the targ
 
 ## Generator Output
 
-The generator updates your tRPC API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
+The generator updates your tRPC API's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target. No source files are modified.
 
 ## Using DynamoDB in Procedures
 
 Import entity factories from the DynamoDB package and use them inside your tRPC procedures:
 
 ```ts title="packages/api/src/procedures/example.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 import { publicProcedure } from '../init.js';
 
 export const listExamples = publicProcedure

package/docs/guides/connection/trpc-rdb.mdx

@@ -45,7 +45,7 @@ The generator creates a middleware file in your tRPC API project:
 
 </FileTree>
 
-Additionally, it updates your tRPC API's `serve-local` target to start the database automatically when running locally.
+Additionally, it updates your tRPC API's `dev` target to start the database automatically when running locally.
 
 ## Using the Middleware
 
@@ -65,7 +65,7 @@ export const authenticatedProcedure = t.procedure
 
 The plugin merges `IMyDbContext` into your procedure context, making `myDb` available as an optional property:
 
-```ts title="packages/api/src/procedures/users.ts" {8,12}
+```ts title="packages/api/src/procedures/users.ts" {7-8}
 import { z } from 'zod';
 import { authenticatedProcedure } from '../router.js';
 
@@ -116,12 +116,12 @@ export const dbProcedure = t.procedure
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development
 
-The generator configures your tRPC API's `serve-local` target to depend on the database's `serve-local` target, so running:
+The generator configures your tRPC API's `dev` target to depend on the database's `dev` target, so running:
 
-<NxCommands commands={["serve-local <api-project-name>"]} />
+<NxCommands commands={["dev <api-project-name>"]} />
 
 will automatically start the local database alongside your API.

package/docs/guides/connection/ts-agent-a2a.mdx

@@ -23,7 +23,7 @@ The generator sets up all the necessary wiring so your agent can discover and in
 Before using this generator, ensure you have:
 
 1. A TypeScript project with a <Link path="guides/ts-agent">Strands Agent</Link> component (any protocol)
-2. A project with an Agent component generated with `--protocol=A2A` and `--auth=IAM` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
+2. A project with an Agent component generated with `--protocol=a2a` and `--auth=iam` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
 3. Both components created with `infra: agentcore`
 
 ## Usage
@@ -47,9 +47,12 @@ The generator creates a shared `agent-connection` package and modifies your agen
 - packages/common/agent-connection
   - src
     - app
-      - \<target-agent-name>-client.ts High-level client for the connected A2A agent
+      - \<target-agent-name>-client-strands.ts High-level Strands client for the connected A2A agent
     - core
-      - agentcore-a2a-client.ts Low-level AgentCore A2A client with SigV4 authentication
+      - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-a2a-client-config.ts Framework-agnostic A2A client config (signed `clientFactory`)
+      - agentcore-a2a-client-strands.ts Strands A2A client wrapping the config
     - index.ts Exports all clients
   - project.json
   - tsconfig.json
@@ -58,20 +61,20 @@ The generator creates a shared `agent-connection` package and modifies your agen
 
 Additionally, it:
 - Transforms your agent's `agent.ts` to register the remote A2A agent as a Strands `tool`
-- Updates the agent's `serve-local` target to depend on the target agent's `serve-local` target
+- Updates the agent's `dev` target to depend on the target agent's `dev` target
 - Installs required dependencies
 
 ## Using the Connected A2A Agent
 
 The generator transforms your agent's `agent.ts` to wrap the remote A2A agent as a tool:
 
-```ts title="packages/example/src/my-agent/agent.ts" {2,5-11,14}
+```ts title="packages/example/src/my-agent/agent.ts" {2,5-12,15}
 import { Agent, tool } from '@strands-agents/sdk';
-import { RemoteAgentClient } from ':my-scope/agent-connection';
+import { RemoteAgentClientStrands } from '@my-scope/agent-connection';
 import { z } from 'zod';
 
 export const getAgent = async (sessionId: string) => {
-  const remoteAgent = await RemoteAgentClient.create(sessionId);
+  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
   const remoteAgentTool = tool({
     name: 'askRemoteAgent',
     description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
@@ -87,7 +90,7 @@ export const getAgent = async (sessionId: string) => {
 
 The `sessionId` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
-Under the hood, `RemoteAgentClient.create(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+Under the hood, `RemoteAgentClientStrands.create(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `LOCAL_DEV=true`. The signing and endpoint resolution live in the framework-agnostic `agentcore-a2a-client-config.ts`; only the thin `agentcore-a2a-client-strands.ts` depends on Strands.
 
 ## Infrastructure
 
@@ -95,12 +98,12 @@ Under the hood, `RemoteAgentClient.create(sessionId)` returns a Strands `A2AAgen
 
 ## Local Development
 
-The generator configures the host agent's `serve-local` target to:
+The generator configures the host agent's `dev` target to:
 1. Start the connected A2A agent(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the host agent and all connected A2A agents, with the host agent calling the remote agents over plain HTTP on their assigned local ports.