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

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

@@ -26,7 +26,7 @@ import gameConversationPng from '@assets/game-conversation.png'
 
 To create a new monorepo, from within your desired directory, run the following command:
 
-<CreateNxWorkspaceCommand workspace="dungeon-adventure" iac="cdk" />
+<CreateNxWorkspaceCommand workspace="dungeon-adventure" iac="cdk" readonly />
 
 :::note[CDK as IaC Provider]
 We use `--iac=cdk` as we will use CDK for infrastructure as code in this tutorial. The Nx Plugin for AWS also supports `terraform`.
@@ -72,7 +72,7 @@ Rather than copying the commands all at once, you can run each generator individ
 
 First, let's create our Game API. To do this, create a tRPC API called `GameApi` using these steps:
 
-<RunGenerator generator="ts#api" requiredParameters={{ name: "GameApi", framework: "trpc" }} noInteractive />
+<RunGenerator generator="ts#api" requiredParameters={{ name: "GameApi", framework: "trpc" }} noInteractive readonly />
 
 <br />
 
@@ -137,7 +137,7 @@ Below is a list of all files which have been generated by the `ts#api` generator
 
 Let us look at these key files:
 
-```ts {7}
+```ts {8}
 // packages/game-api/src/router.ts
 import { echo } from './procedures/echo.js';
 import { t } from './init.js';
@@ -152,7 +152,7 @@ export type AppRouter = typeof appRouter;
 ```
 The router defines the tRPC router for your API and is the place where you will declare all of your API methods. As you can see above, we have a method called `echo` with it's implementation in the `./procedures/echo.ts` file. The Lambda handler entrypoint is in `handler.ts`, which is configured automatically by the generator.
 
-```ts {4-6}
+```ts {5-7}
 // packages/game-api/src/procedures/echo.ts
 import { publicProcedure } from '../init.js';
 import { EchoInputSchema, EchoOutputSchema } from '../schema/index.js';
@@ -403,7 +403,7 @@ Now let's create our Story Agent.
 
 To create a Python project:
 
-<RunGenerator generator="py#project" requiredParameters={{name:"story"}} noInteractive />
+<RunGenerator generator="py#project" requiredParameters={{name:"story"}} noInteractive readonly />
 
 You will see some new files appear in your file tree.
 <details>
@@ -433,7 +433,7 @@ This has configured a Python project and [UV Workspace](https://docs.astral.sh/u
 
 To add a Strands agent to the project with the `py#agent` generator:
 
-<RunGenerator generator="py#agent" requiredParameters={{project:"story", auth:"cognito", protocol:"ag-ui"}} noInteractive />
+<RunGenerator generator="py#agent" requiredParameters={{project:"story", auth:"cognito", protocol:"ag-ui"}} noInteractive readonly />
 
 :::note[AG-UI protocol]
 We choose `--protocol=ag-ui` so the agent speaks the [Agent-User Interaction protocol](https://docs.copilotkit.ai/aws-strands/protocol) — this lets our React website talk to it directly via [CopilotKit](https://docs.copilotkit.ai/), with streaming, tool calls, and conversation history handled by the protocol instead of a hand-rolled HTTP client.
@@ -916,7 +916,7 @@ Let us create an MCP server to provide tools for our Story Agent to manage a pla
 
 First, we create a TypeScript project:
 
-<RunGenerator generator="ts#project" requiredParameters={{name:"inventory"}} noInteractive />
+<RunGenerator generator="ts#project" requiredParameters={{name:"inventory"}} noInteractive readonly />
 
 This will create an empty TypeScript project.
 
@@ -944,7 +944,7 @@ The `ts#project` generator generates these files.
 
 Next, we'll add an MCP server to our TypeScript project:
 
-<RunGenerator generator="ts#mcp-server" requiredParameters={{project:"inventory"}} noInteractive />
+<RunGenerator generator="ts#mcp-server" requiredParameters={{project:"inventory"}} noInteractive readonly />
 
 This will add an MCP server.
 <details>
@@ -977,7 +977,7 @@ The `ts#mcp-server` generator generates these files.
 
 Our game state — saved games and each player's inventory — lives in [Amazon DynamoDB](https://aws.amazon.com/dynamodb/). Create a DynamoDB project called `DungeonDb` with the `ts#dynamodb` generator:
 
-<RunGenerator generator="ts#dynamodb" requiredParameters={{name:"DungeonDb"}} noInteractive />
+<RunGenerator generator="ts#dynamodb" requiredParameters={{name:"DungeonDb"}} noInteractive readonly />
 
 :::tip[Local-first development]
 The `ts#dynamodb` generator vends a `dev` target that runs [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) in a container. Combined with the `connection` generator (which we run below), this means **the entire game runs on your machine without a deployment** until the end of the tutorial.
@@ -1029,7 +1029,7 @@ Next, we will create the UI which will allow you to interact with the game.
 
 To create the UI, create a website called `GameUI` using these steps:
 
-<RunGenerator generator="ts#website" requiredParameters={{name:"GameUI", ux:"shadcn"}} noInteractive />
+<RunGenerator generator="ts#website" requiredParameters={{name:"GameUI", ux:"shadcn"}} noInteractive readonly />
 
 :::note[Shadcn UI]
 We select `--ux=shadcn` so the generated website uses [shadcn/ui](https://ui.shadcn.com/) components styled with Tailwind — all our route code uses shadcn primitives like `Card`, `Button`, and `Input`, and the `connection` generator later wires a matching shadcn-themed [CopilotKit](https://docs.copilotkit.ai/) chat surface.
@@ -1166,7 +1166,7 @@ A component will be rendered when navigating to the `/` route. `@tanstack/react-
 
 Let us configure our Game UI to require authenticated access via Amazon Cognito using these steps:
 
-<RunGenerator generator="ts#website#auth" requiredParameters={{cognitoDomain:"game-ui", project:"@dungeon-adventure/game-ui", allowSignup:true}} noInteractive />
+<RunGenerator generator="ts#website#auth" requiredParameters={{cognitoDomain:"game-ui", project:"@dungeon-adventure/game-ui", allowSignup:true}} noInteractive readonly />
 
 You will see some new files appear/change in your file tree.
 
@@ -1250,7 +1250,7 @@ The `RuntimeConfigProvider` and `CognitoAuth` components have been added to the
 
 Let us configure our Game UI to connect to our previously created Game API.
 
-<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-ui", targetProject:"@dungeon-adventure/game-api"}} noInteractive />
+<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-ui", targetProject:"@dungeon-adventure/game-api"}} noInteractive readonly />
 
 You will see some new files have appear/change in your file tree.
 
@@ -1344,7 +1344,7 @@ The `main.tsx` file has been updated via an AST transform to inject the tRPC pro
 
 Let us connect our Story Agent to the Inventory MCP server so the agent can discover and invoke the MCP server's tools.
 
-<RunGenerator generator="connection" requiredParameters={{sourceProject:"story", targetProject:"inventory"}} noInteractive />
+<RunGenerator generator="connection" requiredParameters={{sourceProject:"story", targetProject:"inventory"}} noInteractive readonly />
 
 <details>
 <summary>Examine the Story Agent → Inventory MCP connection files</summary>
@@ -1384,7 +1384,7 @@ For more details, refer to the <Link path="guides/connection/py-agent-mcp">Pytho
 
 Let us connect our Game UI to the Story Agent. Since the agent speaks AG-UI, the `connection` generator wires up [CopilotKit](https://docs.copilotkit.ai/): a themed chat component and an `@ag-ui/client` `HttpAgent` ready to render.
 
-<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-ui", targetProject:"story"}} noInteractive />
+<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-ui", targetProject:"story"}} noInteractive readonly />
 
 <details>
 <summary>Examine the UI → Story Agent connection files</summary>
@@ -1419,9 +1419,9 @@ For more details, refer to the <Link path="guides/connection/react-agui">React t
 
 Both the Game API and the Inventory MCP server read and write our DynamoDB table, so let us connect them to the `DungeonDb` project. The `connection` generator detects that the target is a `ts#dynamodb` project and wires each source project's `dev` target to start DynamoDB Local automatically.
 
-<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-api", targetProject:"@dungeon-adventure/dungeon-db"}} noInteractive />
+<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/game-api", targetProject:"@dungeon-adventure/dungeon-db"}} noInteractive readonly />
 
-<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/inventory", targetProject:"@dungeon-adventure/dungeon-db"}} noInteractive />
+<RunGenerator generator="connection" requiredParameters={{sourceProject:"@dungeon-adventure/inventory", targetProject:"@dungeon-adventure/dungeon-db"}} noInteractive readonly />
 
 <Aside type="tip" title="One command boots the whole stack locally">
 Because the Story Agent's `agent-dev` already depends on the Inventory MCP server's `mcp-server-dev` (via the `story → inventory` connection above), and both the Game API and MCP server now depend on `dungeon-db:dev`, running any one project's `dev` target starts every dependency it needs in the right order.
@@ -1431,7 +1431,7 @@ Because the Story Agent's `agent-dev` already depends on the Inventory MCP serve
 
 Let us create the final sub-project for the CDK infrastructure.
 
-<RunGenerator generator="ts#infra" requiredParameters={{name:"infra"}} noInteractive />
+<RunGenerator generator="ts#infra" requiredParameters={{name:"infra"}} noInteractive readonly />
 
 You will see some new files have appear/change in your file tree.
 

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

@@ -10,13 +10,13 @@ import Drawer from '@components/drawer.astro';
 import RunGenerator from '@components/run-generator.astro';
 import NxCommands from '@components/nx-commands.astro';
 import InstallCommand from '@components/install-command.astro';
-import Link from '@components/link.astro';
 
 import baselineWebsitePng from '@assets/baseline-website.png'
 import baselineGamePng from '@assets/baseline-game.png'
 import nxGraphPng from '@assets/nx-graph.png'
 import gameSelectPng from '@assets/game-select.png'
 import gameConversationPng from '@assets/game-conversation.png'
+import EmbeddedGraph from '@components/embedded-graph.astro';
 
 
 Using this tutorial, you will build an Agentic AI-powered dungeon adventure game with `@aws/nx-plugin`. This tutorial does not assume any existing knowledge of the `@aws/nx-plugin` or related technologies. 
@@ -52,76 +52,9 @@ The game interface will resemble something like this diagram:
 
 ### Application architecture
 
-The Agentic AI-powered dungeon adventure game is built using the following architecture:
-
-```d2 inline=true
-direction: down
-
-browser: Web Browser {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/client.svg
-}
-
-cognito: Cognito / IAM {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/cognito.svg
-}
-
-cloudfront: CloudFront {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/cloudfront.svg
-}
-
-s3: Static Assets\n(S3) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/s3.svg
-}
-
-apigw: API Gateway\n(Game API) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/api-gateway.svg
-}
-
-lambda: tRPC API\n(Lambda) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
-}
-
-story: Story Agent\n(AgentCore) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
-}
-
-mcp: Inventory MCP\n(AgentCore) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
-}
-
-ddb: Game State\n(DynamoDB) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/dynamodb.svg
-}
-
-sessions: Story Sessions\n(S3) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/s3.svg
-}
-
-browser -> cognito: Sign in
-browser -> cloudfront
-cloudfront -> s3
-browser -> apigw
-apigw -> lambda
-lambda -> ddb
-lambda -> sessions: Read transcripts
-browser -> story: AG-UI stream
-story -> sessions: Persist turns
-story -> mcp: Tool calls
-mcp -> ddb
-ddb -> sessions: {
-  style.opacity: 0
-}
-```
+The Agentic AI-powered dungeon adventure game is built using the following architecture — switch to **Projects** to see the workspace it is built from, which you scaffold in Module 1:
+
+<EmbeddedGraph preset="dungeon-adventure" workspace="dungeon-adventure" iac="cdk" view="infrastructure" copyable={false} />
 
 - React/Vite frontend website utilising:
   - Amazon Cognito/Identity Pools for secure API calls.
@@ -138,8 +71,4 @@ Before you proceed, you will need the following global dependencies:
 
 <Snippet name="required-prerequisites" />
 - [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account, since this tutorial deploys the application and invokes Amazon Bedrock
-- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development
-
-:::tip[AI Assistant Setup]
-If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, refer to the <Link path="/get_started/building-with-ai">install the Nx Plugin for AWS MCP server</Link> page.
-:::
+- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development

package/docs/guides/agentcore-gateway.mdx

@@ -14,6 +14,7 @@ import Snippet from '@components/snippet.astro';
 import Link from '@components/link.astro';
 import NxCommands from '@components/nx-commands.astro';
 import OptionFilter from '@components/option-filter.astro';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 Generate an [Amazon Bedrock AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) project. An AgentCore Gateway is a managed entry point in front of your MCP servers or agents, authenticating inbound requests (IAM or Cognito) and signing outbound traffic to its targets with IAM SigV4.
 
@@ -89,32 +90,7 @@ The Gateway URL is automatically registered in the `agentcore.gateways.<ClassNam
 
 The deployed Gateway has the following architecture, with an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL in front of the Gateway, which routes on to its downstream MCP server targets:
 
-```d2 inline=true
-direction: right
-
-client: Client {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/client.svg
-}
-
-waf: WAF {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/waf.svg
-}
-
-gateway: AgentCore Gateway\n(MCP, IAM or Cognito auth) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-gateway.svg
-}
-
-targets: Downstream MCP Servers\n(Gateway targets) {
-  shape: rectangle
-}
-
-client -> waf
-waf -> gateway
-gateway -> targets
-```
+<ArchitectureDiagram />
 
 ## Authentication
 

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

@@ -108,7 +108,7 @@ AgentCore Runtime VPC deployments are only supported in certain availability zon
 <Fragment slot="terraform">
 In the Terraform file where you instantiate the Gateway, wire the agent target in:
 
-```hcl title="packages/infra/src/main.tf" {9-20,24-40}
+```hcl title="packages/infra/src/main.tf" {9-25,28-48}
 module "my_agent" {
   source = "../../common/terraform/src/app/agents/my-agent"
   # ...

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

@@ -72,7 +72,7 @@ The generator transforms your agent's `agent.py` to wrap the remote A2A agent as
 
 <Tabs syncKey="agent-framework">
 <TabItem label="Strands" _filter={{ framework: 'strands' }}>
-```python title="packages/my-project/my_module/agent/agent.py" {4,8-13,15}
+```python title="packages/my-project/my_module/agent/agent.py" {4,8-13,15,17}
 from contextlib import contextmanager
 from strands import Agent, tool
 
@@ -94,7 +94,7 @@ def get_agent():
 ```
 </TabItem>
 <TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
-```python title="packages/my-project/my_module/agent/agent.py" {5,8-13,15}
+```python title="packages/my-project/my_module/agent/agent.py" {5,8-13,15,18}
 from langchain.agents import create_agent
 from langchain_aws import ChatBedrockConverse
 from langchain_core.tools import tool

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

@@ -77,7 +77,7 @@ The generator transforms your agent's `agent.py` to use the Gateway client:
 
 <Tabs syncKey="agent-framework">
 <TabItem label="Strands" _filter={{ framework: 'strands' }}>
-```python title="packages/example/example/my_agent/agent.py" {4,8,9-13}
+```python title="packages/example/example/my_agent/agent.py" {4,8-11,14}
 from contextlib import contextmanager
 from strands import Agent
 

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

@@ -74,7 +74,7 @@ The generator transforms your agent's `agent.py` to use the MCP server's tools:
 
 <Tabs syncKey="agent-framework">
 <TabItem label="Strands" _filter={{ framework: 'strands' }}>
-```python title="packages/my-project/my_module/agent/agent.py" {4,8,9-13}
+```python title="packages/my-project/my_module/agent/agent.py" {4,8-11,14}
 from contextlib import contextmanager
 from strands import Agent
 

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

@@ -186,7 +186,7 @@ For information on how to define subscription procedures in your backend, see th
 
 You can consume subscriptions using the `useSubscription` hook with `subscriptionOptions` from the options proxy:
 
-```tsx {1-2,7-22}
+```tsx {1-2,7-23}
 import { useSubscription } from '@trpc/tanstack-react-query';
 import { useMyApi } from './hooks/useMyApi';
 

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

@@ -84,7 +84,7 @@ The generated code handles authentication depending on your agent's configuratio
 
 The most common use case is streaming the agent's response using the `invoke` subscription with the `use<AgentName>Agent` hook, which returns a [tRPC options proxy](https://trpc.io/docs/client/tanstack-react-query) for use with TanStack Query:
 
-```tsx {1-2,7-22}
+```tsx {1-2,7-23}
 import { useSubscription } from '@trpc/tanstack-react-query';
 import { useMyAgentAgent } from './hooks/useMyAgentAgent';
 

package/docs/guides/open-api-py-client.mdx

@@ -0,0 +1,270 @@
+---
+title: OpenAPI Python Client
+description: Reference documentation for the OpenAPI Python client generator
+generator: open-api#py-client
+sidebar:
+  # Hidden until a connection generator vends this client, matching the
+  # generator's own `hidden: true`.
+  hidden: true
+---
+import { FileTree } from '@astrojs/starlight/components';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Drawer from '@components/drawer.astro';
+
+Generate a type-safe Python client for any OpenAPI specification, built on [httpx](https://www.python-httpx.org/) and [pydantic](https://docs.pydantic.dev/).
+
+The client is the Python counterpart of the `open-api#ts-client` generator: one class per API, keyword-only methods, typed errors you can narrow, and a single extension point — your own `httpx` client — for authentication and anything else you need on the wire.
+
+## Usage
+
+<RunGenerator generator="open-api#py-client" />
+
+### Options
+
+<GeneratorParameters generator="open-api#py-client" />
+
+## Generator Output
+
+<FileTree>
+
+- \<outputPath>
+  - \_\_init\_\_.py Exports the clients, `ApiError` and the `types` module
+  - types.py pydantic models for every schema in the specification
+  - errors.py `ApiError` and a subclass per operation
+  - client.py Synchronous client, using `httpx.Client`
+  - async_client.py Asynchronous client, using `httpx.AsyncClient`
+
+</FileTree>
+
+Pass `--clientType=sync` or `--clientType=async` to emit just one of the two clients.
+
+:::tip[Generated Client in Git]
+The client is ignored from version control by default, since it is regenerated from the specification. Remove the entry from your `.gitignore` to check it in instead — but note that any manual edits will be overwritten the next time it is generated.
+:::
+
+### Dependencies
+
+The generated code imports `httpx` and `pydantic`, so add both to the project you generate into:
+
+```toml
+# pyproject.toml
+dependencies = [
+  "httpx>=0.28.1",
+  "pydantic>=2.13.4",
+]
+```
+
+Nothing else is required — no runtime of its own, and no framework to adopt.
+
+## Using the Generated Client
+
+Instantiate the client with the API's base URL:
+
+```python
+from my_api import MyApi, MyApiConfig
+
+api = MyApi(MyApiConfig(url="https://api.example.com"))
+
+pet = api.pet.add_pet(name="rex", status="available")
+print(pet.id, pet.name)
+```
+
+Methods are **keyword-only**, so a call reads as the specification does, and required parameters come first:
+
+```python
+pets = api.pet.list_pets(status=["available"], limit=10)
+pet = api.pet.get_pet_by_id(pet_id=42)
+api.pet.delete_pet(pet_id=42)
+```
+
+Operations tagged in the specification are grouped into namespaces — `api.pet.add_pet(...)` above comes from the `pet` tag. Untagged operations sit directly on the client, as `api.health()`.
+
+An operation whose body is an object has its fields flattened into the call, so there is no wrapper to construct. Where the body is a list or a dictionary it is passed positionally instead:
+
+```python
+created = api.pet.batch_create([types.Pet(name="a"), types.Pet(name="b")])
+```
+
+### Types
+
+Every schema becomes a pydantic model in `types`, so results are validated and your editor knows their shape:
+
+```python
+from my_api import types
+
+pet = api.pet.add_pet(name="rex", owner=types.Owner(name="ann"))
+
+reveal_type(pet)         # types.Pet
+reveal_type(pet.owner)   # types.Owner | None
+```
+
+Enums become `Literal` types, so an invalid value is a type error rather than a failed request:
+
+```python
+api.pet.list_pets(status=["available"])   # ok
+api.pet.list_pets(status=["on-mars"])     # rejected before it is sent
+```
+
+Dates and date-times are `datetime.date` / `datetime.datetime` on the way in and out — the client handles the ISO-8601 conversion:
+
+```python
+event = api.create_event(day=datetime.date(2026, 4, 18))
+reveal_type(event.day)   # datetime.date
+```
+
+### Errors
+
+A non-success response raises an exception. Catch `ApiError` to handle any failure from either client:
+
+```python
+from my_api import ApiError
+
+try:
+    pet = api.pet.get_pet_by_id(pet_id=42)
+except ApiError as e:
+    print(e.status, e.error)
+```
+
+Each operation also has its own subclass, whose `.error` narrows to the responses that operation declares. `isinstance` picks out one status:
+
+```python {8,10}
+from my_api import types
+from my_api.errors import GetPetByIdApiError
+
+try:
+    pet = api.pet.get_pet_by_id(pet_id=42)
+except GetPetByIdApiError as e:
+    if isinstance(e.error, types.GetPetById404Error):
+        print("no such pet:", e.error.error.detail)
+    else:
+        print("failed with", e.status)
+```
+
+There is one class per response the operation declares, named after its status code — a declared `4XX` range becomes `GetPetById4XXError`.
+
+A body that doesn't match the schema the specification declares still raises the typed exception, carrying whatever the server actually sent — so a proxy's HTML error page surfaces as an error rather than a validation failure inside your error handler.
+
+### Streaming
+
+An operation that streams returns an iterator of parsed items, so you can consume the response as it arrives:
+
+```python
+for chunk in api.stream_chunks(count=4):
+    print(chunk.index, chunk.message)
+```
+
+### Async
+
+The async client mirrors the sync one, method for method:
+
+```python
+from my_api import AsyncMyApi, AsyncMyApiConfig
+
+async with AsyncMyApi(AsyncMyApiConfig(url="https://api.example.com")) as api:
+    pet = await api.pet.add_pet(name="rex")
+
+    async for chunk in api.stream_chunks(count=4):
+        print(chunk.message)
+```
+
+Both clients raise from the same hierarchy, so `except ApiError` catches either.
+
+## Authentication
+
+Authentication is the one thing every API does differently, so the client doesn't invent an abstraction for it. Supply your own `httpx` client and whatever you configure on it applies to every request:
+
+```python {6,13}
+import httpx
+from my_api import MyApi, MyApiConfig
+
+
+class BearerAuth(httpx.Auth):
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request
+
+
+with httpx.Client(auth=BearerAuth("my-token")) as http:
+    api = MyApi(MyApiConfig(url="https://api.example.com", httpx_client=http))
+    pet = api.pet.add_pet(name="rex")
+```
+
+This is the Python equivalent of passing a custom `fetch` to the TypeScript client. An [`httpx.Auth`](https://www.python-httpx.org/advanced/authentication/), event hooks, a custom transport, timeouts, retries, proxies, HTTP/2, and the client's own headers and query parameters all apply — including on multipart uploads and streaming responses.
+
+A client you supply is never closed by the generated one, so it is safe to share across several clients.
+
+<Drawer title="Signing requests with AWS SigV4" trigger="Click here for an example which signs requests with AWS IAM credentials.">
+
+`httpx.Auth` is all a signer needs to be. For an API behind IAM authentication:
+
+```python
+import hashlib
+from collections.abc import Generator
+
+import boto3
+import httpx
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+
+from my_api import MyApi, MyApiConfig
+
+
+class SigV4HTTPXAuth(httpx.Auth):
+    requires_request_body = True
+
+    def __init__(self, credentials, service: str, region: str):
+        self.signer = SigV4Auth(credentials, service, region)
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response]:
+        headers = dict(request.headers)
+        headers.pop("connection", None)
+        headers["x-amz-content-sha256"] = hashlib.sha256(
+            request.content or b""
+        ).hexdigest()
+
+        aws_request = AWSRequest(
+            method=request.method,
+            url=str(request.url),
+            data=request.content,
+            headers=headers,
+        )
+        self.signer.add_auth(aws_request)
+
+        request.headers.clear()
+        request.headers.update(dict(aws_request.headers))
+        yield request
+
+
+session = boto3.Session()
+auth = SigV4HTTPXAuth(session.get_credentials(), "execute-api", session.region_name)
+
+with httpx.Client(auth=auth) as http:
+    api = MyApi(MyApiConfig(url="https://api.example.com", httpx_client=http))
+    pet = api.pet.add_pet(name="rex")
+```
+
+</Drawer>
+
+### Other configuration
+
+`Config` carries a small number of options beyond the URL and the client:
+
+```python
+api = MyApi(
+    MyApiConfig(
+        url="https://api.example.com",
+        # Sent with every request, where the operation sets no header of its own
+        headers={"x-tenant-id": "acme"},
+        # Omit the Content-Type the specification declares for each request
+        omit_content_type_header=False,
+    )
+)
+```
+
+A header an operation sets always wins over the same header here, so a per-call value is never merged into the configured one.

package/docs/guides/py-dynamodb.mdx

@@ -11,6 +11,7 @@ import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import Snippet from '@components/snippet.astro';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 This generator creates a new Python project backed by [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), using [PynamoDB](https://pynamodb.readthedocs.io/) for entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.
 
@@ -53,6 +54,12 @@ The local development scripts are shared across all DynamoDB projects (both Type
 
 <Snippet name="dynamodb/infrastructure" />
 
+#### Architecture
+
+The deployed project provisions the table itself, which any project it is connected to reads and writes:
+
+<ArchitectureDiagram />
+
 ## Local Development
 
 ### Starting Local DynamoDB