@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71

package/docs/guides/connection/py-mcp-server-rdb.mdx

@@ -0,0 +1,187 @@
+---
+title: Python MCP Server to Relational Database
+description: Connect a Python MCP Server to a Relational Database
+when:
+  sourceType: py#mcp-server
+  targetType: py#rdb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator wires a <Link path="guides/py-mcp-server">Python MCP Server</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, making the database session available to all tools registered in the server.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-mcp-server">`py#mcp-server`</Link> project
+2. A <Link path="guides/py-rdb">`py#rdb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your MCP server project as the source and your relational database project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+<FileTree>
+
+- packages/my\_service
+  - project.json Adds a dependency from `my_mcp_server-dev` on the database's `dev` target
+  - pyproject.toml Adds the database package as a workspace dependency
+  - my\_service
+    - my\_mcp\_server
+      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections
+
+</FileTree>
+
+## Using the Database in MCP Tools
+
+Import `session_context` from your database package and use it inside your MCP server tools:
+
+```python title="packages/my_service/my_service/my_mcp_server/server.py"
+from sqlmodel import select
+from my_scope.my_db import session_context
+from my_scope.my_db.models.example import ExampleModel
+
+@mcp.tool()
+async def list_examples() -> str:
+    """List all example records."""
+    async with session_context() as session:
+        items = (await session.execute(select(ExampleModel))).all()
+        return str([item.model_dump() for item in items])
+```
+
+## Multiple Databases
+
+Running the generator again with a different target adds the second database alongside the first. Both session contexts are available to all tools:
+
+```python title="packages/my_service/my_service/my_mcp_server/server.py"
+from my_scope.my_db import session_context as my_db_session_context
+from my_scope.other_db import session_context as other_db_session_context
+```
+
+## Infrastructure
+
+The generated MCP server construct implements `IGrantable` and `IConnectable`, so you can grant network and IAM access to the database directly on the construct.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
+import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', { vpc, ... });
+
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer', {
+  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
+    vpc,
+    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    securityGroups: [
+      new SecurityGroup(this, 'MyMcpServerSecurityGroup', { vpc, allowAllOutbound: true }),
+    ],
+  }),
+});
+
+db.allowDefaultPortFrom(myMcpServer);
+db.grantConnect(myMcpServer);
+```
+
+`allowDefaultPortFrom` opens the security group rule so the MCP server runtime can reach the database port. `grantConnect` grants IAM `rds-db:connect` permission to the server's execution role.
+
+
+</Fragment>
+<Fragment slot="terraform">
+
+Run the MCP server inside the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source              = "../../common/terraform/src/app/dbs/my-database"
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
+}
+
+module "my_mcp_server" {
+  source     = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
+  enable_vpc = true
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+}
+
+resource "aws_vpc_security_group_ingress_rule" "mcp_server_to_database" {
+  description                  = "Allow the MCP server runtime to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.my_mcp_server.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+
+resource "aws_vpc_security_group_egress_rule" "mcp_server_to_database" {
+  description                  = "Allow outbound traffic from the MCP server runtime to the database"
+  security_group_id            = module.my_mcp_server.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+```
+
+`appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```hcl title="packages/infra/src/main.tf"
+module "runtime_config_appconfig" {
+  source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+  application_name = "my-app-runtime-config"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+### SSL Requirements When Connecting Without RDS Proxy
+
+When the MCP server connects directly to the Aurora cluster (without RDS Proxy), the connection generator updates the generated MCP server Dockerfile to install the Amazon RDS CA bundle into the system trust store:
+
+```dockerfile
+ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
+RUN update-ca-certificates
+```
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in the MCP server runtime.
+
+## Local Development
+
+<NxCommands commands={["<mcp-server-name>-dev <project-name>"]} />
+
+This starts the MCP server and all connected databases. The `LOCAL_DEV=true` environment variable causes the database client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection/react-agentcore-gateway.mdx

@@ -0,0 +1,112 @@
+---
+title: React Website to AgentCore Gateway
+description: Connect a React website to agents through an AgentCore Gateway
+when:
+  sourceType: ts#react-website
+  targetType: agentcore-gateway
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can connect a <Link path="guides/react-website">React website</Link> to the agents fronted by an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link> generated with `protocol: http`.
+
+The browser talks only to the Gateway — requests to `<gatewayUrl>/<targetName>/invocations` are proxied to the agent runtime behind it. Because the website never needs to reach the runtimes directly, the agents can be deployed inside a VPC, with the Gateway as the single governed entry point providing authentication and observability.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/react-website">React website</Link> project
+2. An <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project generated with `protocol: http`
+3. At least one AG-UI or HTTP agent attached to the Gateway via the <Link path="guides/connection/agentcore-gateway-agent">Gateway to agent connection generator</Link>
+
+The generator creates a website client for **each** AG-UI or HTTP agent attached to the Gateway (A2A targets are skipped — they speak agent-to-agent JSON-RPC, not a browser protocol). It generates the same clients as connecting the website to each agent directly (<Link path="guides/connection/react-agui">AG-UI/CopilotKit</Link> for AG-UI agents, an <Link path="guides/connection/react-py-agent">OpenAPI client</Link> for Python HTTP agents), routed through the Gateway rather than at the runtime.
+
+:::note[Authentication]
+The browser authenticates with the **Gateway**, not the agents: SigV4 for an IAM Gateway (via the website's Cognito identity pool), or a JWT bearer token for a Cognito Gateway.
+:::
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the website project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+For each fronted AG-UI agent, the same files as the <Link path="guides/connection/react-agui">React to AG-UI agent connection</Link> are generated (an `AguiProvider`, a `useAgui<Agent>` hook and a themed CopilotKit component module), with the hook reading the Gateway's URL from runtime configuration:
+
+<FileTree>
+
+- packages/\<website>/src
+  - components
+    - AguiProvider.tsx CopilotKit provider registering each agent
+    - copilot/ Themed chat components
+  - hooks
+    - useAgui\<Agent>.tsx Connects to the agent via the Gateway's `/<targetName>/invocations` route
+
+</FileTree>
+
+For each fronted Python HTTP agent, the same files as the <Link path="guides/connection/react-py-agent">React to Python agent connection</Link> are generated (a type-safe OpenAPI client, hooks, and a provider), with the client's base URL routed through the Gateway.
+
+The Gateway's URL is registered in the `connection.gateways.<GatewayClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link>, so it is published to the website's `runtime-config.json`.
+
+## Granting website users access
+
+For an **IAM** Gateway, grant the website's authenticated users permission to invoke it (a **Cognito** Gateway needs no grant — the browser authenticates with its JWT bearer token instead):
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {6}
+const identity = new UserIdentity(this, 'UserIdentity');
+new Website(this, 'Website');
+
+const myGateway = new MyGateway(this, 'MyGateway');
+myGateway.addAgent(myAgent);
+myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf"
+resource "aws_iam_policy" "gateway_invoke_policy" {
+  name = "GatewayInvokePolicy"
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = ["bedrock-agentcore:InvokeGateway"]
+        Resource = [module.my_gateway.gateway_arn]
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
+  role       = module.user_identity.authenticated_role_name
+  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The website's `dev` target gains a dependency on the Gateway project's `dev` target, which starts the local gateway plus every attached agent. The website's runtime configuration is overridden in `local-dev` mode to point the Gateway's URL at the local gateway, so the browser exercises the same `/<targetName>/invocations` routes locally:
+
+<NxCommands commands={["dev <website-name>"]} />
+
+## Connecting new agents
+
+The generator connects the website to the agents attached to the Gateway **at the time it runs**. After attaching another agent to the Gateway, re-run the connection generator to generate its website client — existing clients are left untouched.

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

@@ -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.
 
@@ -102,7 +102,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 +137,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 +218,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

@@ -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

@@ -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

@@ -21,7 +21,7 @@ The `connection` generator provides a way to quickly integrate your React websit
 Before using this generator, ensure your React application has:
 
 1. A `main.tsx` file that renders your application
-2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link>)
+2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `--framework=smithy`)
 3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link> if connecting an API which uses Cognito or IAM auth
 
 <details>
@@ -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

@@ -175,7 +175,7 @@ Subscriptions are only supported when the tRPC API uses `rest-lambda` (REST API)
 
 When connecting to a REST API tRPC backend, the generated client is automatically configured with a `splitLink` that routes subscription operations through `httpSubscriptionLink` (using SSE) and regular queries/mutations through `httpLink`. This means subscriptions work out of the box with no additional configuration.
 
-For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">`ts#trpc-api` generator guide</Link>.
+For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">tRPC API generator guide</Link>.
 
 #### Using the useSubscription Hook
 

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

@@ -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,6 +1,6 @@
 ---
 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
   targetType: ts#dynamodb
@@ -12,13 +12,13 @@ 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
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/ts-smithy-api">`ts#smithy-api`</Link> project (TypeScript backend)
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
 2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
 
 ## Usage
@@ -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,