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

package/docs/guides/typescript-project.mdx

@@ -3,12 +3,13 @@ title: TypeScript Projects
 description: Reference documentation for TypeScript projects
 generator: ts#project
 ---
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, Steps } from '@astrojs/starlight/components';
 import RunGenerator from '@components/run-generator.astro';
 import InstallCommand from '@components/install-command.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
 import Link from '@components/link.astro';
 
 The TypeScript project generator can be used to create a modern [TypeScript](https://www.typescriptlang.org/) library or application configured with best practices such as [ECMAScript Modules (ESM)](https://www.typescriptlang.org/docs/handbook/modules/reference.html), TypeScript [project references](https://www.typescriptlang.org/docs/handbook/project-references.html), [Vitest](https://vitest.dev/) for running tests and [Biome](https://biomejs.dev/) for linting and formatting.
@@ -33,6 +34,7 @@ The generator will create the following project structure in the `<directory>/<n
 
   - src TypeScript source code
     - index.ts
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - tsconfig.json Base TypeScript configuration for this project (extends workspace root tsconfig.base.json)
   - tsconfig.lib.json TypeScript configuration for your library (your runtime or packaged source)
@@ -41,8 +43,8 @@ The generator will create the following project structure in the `<directory>/<n
 
 </FileTree>
 
-:::tip[No package.json Needed]
-Notice that no `package.json` file is created for this project! You can find out why [below](#dependencies).
+:::tip[Project package.json]
+The project's `package.json` starts minimal. As you add runtime dependencies they are declared here (shared build/test tooling stays in the workspace root) — you can find out more [below](#dependencies).
 :::
 
 You will also notice some changes to the following files in your workspace root:
@@ -85,13 +87,9 @@ export * from './algorithms/index.js';
 [TypeScript aliases](https://www.typescriptlang.org/docs/handbook/modules/reference.html#paths) for your project are configured in your workspace `tsconfig.base.json`, which allows you to reference your TypeScript project from other TypeScript projects:
 
 ```ts title="packages/my-other-project/src/index.ts"
-import { sayHello } from ':my-scope/my-library';
+import { sayHello } from '@my-scope/my-library';
 ```
 
-:::note[Project Aliases]
-Aliases for your TypeScript projects begin with a `:` rather than the traditional `@`, since this avoids the possibility of name conflicts between local packages in your workspace and remote packages in [NPM](https://www.npmjs.com/).
-:::
-
 When you add an import statement for a new project in your workspace for the first time, you will likely see an error in your IDE similar to the below:
 
 <details>
@@ -106,28 +104,40 @@ File '/path/to/my/workspace/packages/my-library/src/index.ts' is not listed with
 
 </details>
 
-This is because a [project reference](https://www.typescriptlang.org/docs/handbook/project-references.html) has not yet been set up.
+This is because a [project reference](https://www.typescriptlang.org/docs/handbook/project-references.html) has not yet been set up, and the imported project has not yet been declared as a workspace dependency in your project's `package.json`.
 
-TypeScript projects are configured with the Nx TypeScript Sync generator out of the box, saving you from needing to manually configure the project reference. Simply run the following command and Nx will add the required configuration:
+Your workspace is configured with sync generators which manage both for you, so you don't need to configure them by hand. Simply run the following command and Nx will add the required configuration:
 
 <NxCommands commands={['sync']} />
 
-After this, the error in your IDE should be gone and you are ready to use your library.
+```bash wrap
+ NX   The workspace is out of sync
+
+[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on, contain stale project references, or have duplicate project references.
+[@aws/nx-plugin:ts#sync]: Local project dependencies are out of sync. The following workspace dependencies will be declared:
+packages/my-other-project/package.json:
+- @my-scope/my-library: workspace:*
+
+Syncing the workspace...
+The workspace was synced successfully!
+```
+
+Nx's TypeScript sync generator adds the project reference, and the plugin's `ts#sync` generator declares the imported project in your project's `package.json` (`workspace:*` where the package manager supports the workspace protocol, `*` on npm and yarn classic), so the package manager links the local project on install. After this, the error in your IDE should be gone and you are ready to use your library.
 
 :::tip[Build Shortcut]
-You can also just build your project and you'll be prompted with a message such as:
+You can also just build your project — the sync generators run first and you'll be prompted to apply any outstanding changes:
 
 ```bash wrap
-[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.
+ NX   The workspace is out of sync
 
-This will result in an error in CI.
+...
 
-? Would you like to sync the identified changes to get your workspace up to date?
+? Would you like to sync the identified changes to get your workspace up to date? …
 Yes, sync the changes and run the tasks
 No, run the tasks without syncing the changes
 ```
 
-Select `Yes` to allow Nx to update your project references.
+Select `Yes` to allow Nx to sync your workspace.
 :::
 
 ### Keeping Path Aliases In Sync
@@ -136,13 +146,116 @@ If you add custom `compilerOptions.paths` entries in a project's `tsconfig.json`
 
 ### Dependencies
 
-You will notice that your TypeScript project does not have a `package.json` file, which might be unexpected if you are used to traditional TypeScript monorepos.
+Each TypeScript project declares its third-party runtime dependencies in its own `package.json`. Build and test tooling shared across projects is defined in the root `package.json`.
+
+To add a runtime dependency to a project, install it into that project:
+
+<InstallCommand pkg="some-npm-package" project="@my-scope/my-library" />
+
+You can also run your package manager's plain `add`/`install` command from within the project's directory.
+
+To add a shared dev tool, install it at the workspace root:
+
+<InstallCommand pkg="some-dev-tool" dev />
+
+:::note
+Biome's [`noUndeclaredDependencies`](https://biomejs.dev/linter/rules/no-undeclared-dependencies/) lint rule enforces that a project's source only imports packages declared in its own `package.json`. Config files, build scripts and tests are exempt, so shared tooling can stay at the root.
+:::
+
+#### Catalogs
+
+For package managers which support catalogs ([pnpm](https://pnpm.io/catalogs), [yarn](https://yarnpkg.com/features/catalogs) and [bun](https://bun.com/docs/install/catalogs)), generators record each version in the catalog and reference it with the `catalog:` protocol (eg `"zod": "catalog:"`), so the catalog is the single source of truth for versions regardless of which project declares the dependency. This helps you to follow a [single version policy](https://nx.dev/concepts/decisions/dependency-management#single-version-policy), avoiding type conflicts and multiple copies of packages in deployment bundles.
+
+When you add a new dependency yourself, keep it in the catalog too:
+
+<Tabs syncKey="package-manager">
+  <TabItem label="pnpm">
+    The workspace sets [`catalogMode: strict`](https://pnpm.io/settings#catalogmode), so `pnpm add` records the version in the catalog and references it automatically — no extra steps.
+
+    ```bash
+    pnpm add some-npm-package --filter my-library
+    ```
+  </TabItem>
+  <TabItem label="yarn">
+    yarn's `catalog:` protocol only *references* an existing catalog entry — it cannot create one — so record the version first.
+
+    <Steps>
+    1. Add the version under `catalog` in `.yarnrc.yml`:
+
+       ```yaml title=".yarnrc.yml"
+       catalog:
+         some-npm-package: ^1.0.0
+       ```
+
+    2. Reference it from the project:
+
+       ```bash
+       yarn workspace @my-scope/my-library add some-npm-package@catalog:
+       ```
+    </Steps>
+  </TabItem>
+  <TabItem label="bun">
+    bun's `catalog:` protocol only *references* an existing catalog entry — it cannot create one — so record the version first.
 
-To add a dependency for any TypeScript package in your monorepo, simply add the dependency to the `package.json` in the root of your workspace. You can do this via the command line for your package manager:
+    <Steps>
+    1. Add the version under `catalog` in the root `package.json`:
 
-<InstallCommand pkg="some-npm-package" />
+       ```json title="package.json"
+       {
+         "catalog": {
+           "some-npm-package": "^1.0.0"
+         }
+       }
+       ```
 
-The dependency is then available for any of the TypeScript projects in your workspace to use.
+    2. Reference it from the project:
+
+       ```bash
+       bun add some-npm-package@catalog: --cwd packages/my-library
+       ```
+    </Steps>
+  </TabItem>
+</Tabs>
+
+:::tip[Aligning versions on npm]
+npm has no catalog feature, so versions are declared directly in each `package.json`. To keep them consistent across projects, we recommend [syncpack](https://github.com/JamieMason/syncpack) (`npx syncpack lint`).
+:::
+
+##### Opting out of catalogs
+
+Catalogs are enabled by default. To turn them off, create your workspace with `--catalog false`:
+
+<CreateNxWorkspaceCommand workspace="my-project" extraArgs="--catalog false" />
+
+Or set it in `aws-nx-plugin.config.mts` at any time:
+
+```ts title="aws-nx-plugin.config.mts"
+export default {
+  packageManager: {
+    catalogs: false,
+  },
+} satisfies AwsNxPluginConfig;
+```
+
+With catalogs disabled, generators write dependency versions directly into each project's `package.json`, and keeping versions aligned across projects is your responsibility.
+
+#### Declaring all dependencies at the root
+
+If you prefer declaring every dependency in the root `package.json` only (no per-project dependency declarations), turn off the lint rule in the workspace `biome.json`:
+
+```json title="biome.json"
+{
+  "linter": {
+    "rules": {
+      "correctness": {
+        "noUndeclaredDependencies": "off"
+      }
+    }
+  }
+}
+```
+
+Projects resolve root-installed packages at build time, so everything still builds — you give up per-project manifests as an accurate record of each project's dependencies (which matters if you later publish a project or split the repo).
 
 #### Runtime Code
 
@@ -179,7 +292,7 @@ export default defineConfig([
     output: {
       file: '../../dist/packages/my-library/bundle/index.js',
       format: 'cjs',
-      inlineDynamicImports: true,
+      codeSplitting: false,
     },
   },
 ]);
@@ -193,12 +306,6 @@ Note that in the above target, we chose `src/index.ts` as our entrypoint for the
 If you're building an AWS Lambda function, check out the <Link path="/guides/ts-lambda-function">`ts#lambda-function`</Link> generator as this configures bundling for you, as well as generating infrastructure and adding observability and type-safety.
 :::
 
-#### Publishing to NPM
-
-If you are publishing your TypeScript project to NPM, you must create a `package.json` file for it.
-
-This must declare the dependencies that your project references. Since at build time your project will resolve dependencies installed via the workspace root `package.json`, Biome's `noUndeclaredDependencies` rule will warn you if your project imports a package that isn't listed in its `package.json`.
-
 ### Building
 
 Your TypeScript project is configured with a `build` target (defined in `project.json`), which you can run via:

package/docs/guides/workspace.mdx

@@ -6,6 +6,7 @@ import { FileTree } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
 import CreateNxWorkspaceCommand from '@components/create-nx-workspace-command.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import InstallCommand from '@components/install-command.astro';
 import NxCommands from '@components/nx-commands.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 
@@ -82,7 +83,11 @@ The default monorepo setup uses a [single version policy](https://nx.dev/concept
 
 This means that all projects within your monorepo use the same version of dependencies by default, reducing issues related to packages in the same monorepo running into version mismatch issues.
 
-From a Node perspective this means a single lockfile at the root with a single `node_modules` containing all dependencies. If you need to add a new dependency, add it in the root `package.json`.
+From a Node perspective this means a single lockfile at the root, with dependencies installed once and linked into each project. Each Node project declares the runtime dependencies its source imports in its own `package.json`, while shared build/test tooling lives in the root `package.json` `devDependencies`. Add a project's runtime dependency by installing it into that project:
+
+<InstallCommand pkg="some-npm-package" project="@my-scope/my-project" />
+
+For package managers with catalog support ([pnpm](https://pnpm.io/catalogs), [yarn](https://yarnpkg.com/features/catalogs) and [bun](https://bun.com/docs/install/catalogs)), dependency versions are recorded in the catalog and referenced with the `catalog:` protocol, keeping a single source of truth for versions across every project's `package.json`. For npm workspaces, we recommend [syncpack](https://github.com/JamieMason/syncpack) to align versions declared across multiple `package.json` files.
 
 From a Python perspective, this means a single `.venv` in the root of the monorepo with all dependencies installed into it. Each Python project has its own `pyproject.toml`, but the versions of those dependencies are managed by the UV workspace and subsequently written out to the `uv.lock` file in the root.
 
@@ -108,10 +113,12 @@ Run tests across all projects:
 
 ### Dev
 
-If you have a <Link path="guides/react-website">website</Link>, start it and all connected components locally:
+Start all local development servers across your workspace:
 
 <PackageManagerShortCommand commands={["dev"]} />
 
+See the <Link path="guides/local-development">Local Development</Link> guide for more details.
+
 ### Sync
 
 Run any [sync generators](https://nx.dev/concepts/sync-generators), which for example synchronise TypeScript project references (refer to the <Link path="guides/typescript-project">ts#project</Link> generator guide for more details):
@@ -181,7 +188,7 @@ export default {
 } satisfies AwsNxPluginConfig;
 ```
 
-- **`iac.provider`** — the default infrastructure-as-code provider (`cdk` or `terraform`) used by generators that emit infrastructure (e.g. `ts#infra`, `ts#trpc-api`, `py#fast-api`). Generators that accept an `--iac` flag default to `inherit`, which reads this value.
+- **`iac.provider`** — the default infrastructure-as-code provider (`cdk` or `terraform`) used by generators that emit infrastructure (e.g. `ts#infra`, `ts#api`, `py#api`). Generators that accept an `--iac` flag default to `inherit`, which reads this value.
 - **`containers.engine`** — the container CLI (`docker` or `finch`) baked into generated build/push/login commands. CDK image-asset builds also pick this up via the `CDK_DOCKER` environment variable. See the <Link path="guides/docker-bundling">Docker bundling guide</Link> for details.
 
 You can edit either setting at any time — subsequent generator runs will pick up the new value.

package/docs/snippets/agent/architecture.mdx

@@ -23,7 +23,7 @@ ecr: ECR {
 
 agentcore: Strands Agent\n(AgentCore Runtime) {
   shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore.svg
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
 }
 
 bedrock: Bedrock\n(Model Inference) {

package/docs/snippets/agent/bedrock-deployment.mdx

@@ -15,7 +15,7 @@ A CDK construct is generated for your agent, named based on the `name` you chose
 You can use this CDK construct in a CDK application:
 
 ```ts
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -69,7 +69,7 @@ By default, your Agent will be secured using IAM authentication, simply deploy i
 <Infrastructure>
 <Fragment slot="cdk">
 ```ts {5}
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -81,7 +81,7 @@ export class ExampleStack extends Stack {
 You can grant access to invoke your agent on Bedrock AgentCore Runtime using the `grantInvokeAccess` method, for example:
 
 ```ts {8}
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -131,7 +131,7 @@ When you select `Cognito` authentication, the generator configures the agent to
 The generated construct accepts an `identity` prop which configures Cognito authentication:
 
 ```ts {8}
-import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';
+import { MyProjectAgent, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -149,7 +149,7 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
 <Fragment slot="terraform">
 The generated module accepts `user_pool_id` and `user_pool_client_ids` variables for Cognito authentication:
 
-```terraform {8-9}
+```terraform {11-12}
 module "user_identity" {
   source = "../../common/terraform/src/core/user-identity"
 }
@@ -169,4 +169,8 @@ module "my_project_agent" {
 
 :::note[Custom OIDC Providers]
 If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your agent directly. Note that the connection generator will only support `IAM` or `Cognito` authentication.
+:::
+
+:::caution[Security Best Practices]
+When implementing your agent's business logic, review the [Bedrock AgentCore Runtime security best practices](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html).
 :::

package/docs/snippets/agent/runtime-arn.mdx

@@ -12,7 +12,7 @@ You can obtain the runtime ARN from your infrastructure as follows:
 <Fragment slot="cdk">
 ```ts {9}
 import { CfnOutput } from 'aws-cdk-lib';
-import { MyProjectAgent } from ':my-scope/common-constructs';
+import { MyProjectAgent } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -26,7 +26,7 @@ export class ExampleStack extends Stack {
 ```
 </Fragment>
 <Fragment slot="terraform">
-```terraform {5-6, 10}
+```terraform {9-10}
 # Agent
 module "my_project_agent" {
   # Relative path to the generated module in the common/terraform project
@@ -61,4 +61,25 @@ The Bedrock AgentCore Runtime dataplane URL for invoking the agent is as follows
 https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations
 ```
 
+:::tip[Invocation URL]
+Your infrastructure can also output the full invocation URL directly, with the ARN encoding handled for you:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts
+new CfnOutput(this, 'AgentUrl', {
+  value: agent.invocationUrl,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+```terraform
+output "agent_url" {
+  value = module.my_project_agent.invocation_url
+}
+```
+</Fragment>
+</Infrastructure>
+:::
+
 The exact way to invoke this URL depends upon the authentication method used.

package/docs/snippets/agent/securing-your-agent.mdx

@@ -0,0 +1,39 @@
+---
+title: Securing your Agent
+---
+
+Agents act on untrusted input and can drive real actions through their tools, so it's worth considering security from the start. The following practices apply to the generated agent.
+
+### Treat model input and output as untrusted
+
+Prompts can contain adversarial instructions (prompt injection), and model output is non-deterministic — neither should be trusted in security-sensitive logic:
+
+- Define strict input schemas for your tools, as in the generated example tool. Constrain values to what the tool actually needs (enums, length limits, numeric ranges) rather than accepting free-form strings.
+- Never pass model output directly into shell commands, SQL queries, code evaluation, or rendered HTML without validation or encoding.
+- Apply authorization checks in your tools and downstream services — don't rely on the system prompt to prevent the model from misusing a tool it has access to.
+
+Strands' [Prompt Engineering](https://strandsagents.com/docs/user-guide/safety-security/prompt-engineering/) and [Responsible AI](https://strandsagents.com/docs/user-guide/safety-security/responsible-ai/) guides cover writing robust, safety-conscious system prompts.
+
+### Scope tool permissions tightly
+
+Grant the agent's IAM role only the permissions its tools need. The vended CDK constructs and Terraform modules expose `grant*` methods and scoped policies for this purpose — for example granting an agent access to invoke a specific API rather than attaching broad managed policies. Where a tool acts on behalf of a user, prefer authorizing the action using the calling user's identity (passed through via the request context) over the agent's own ambient permissions.
+
+### Provide a kill switch
+
+Because model behaviour can change in unexpected ways, plan for quickly disabling or swapping the model without a code change:
+
+- Read the model ID from configuration (for example a `MODEL_ID` environment variable) so operators can switch or roll back to a different model by updating configuration.
+- Gate the agent behind a feature flag so its AI functionality can be disabled entirely. When disabled, return a generic message rather than an error, and ensure the rest of your application degrades gracefully.
+
+Document how to flip these controls in your operational runbook.
+
+### Protect sensitive data
+
+- Avoid logging prompts and completions, which may contain user data. The generated agent's model error logging hook logs error metadata only, not conversation content — keep this property when adding your own logging.
+- Return generic error messages to users; log detailed errors server-side.
+- Isolate conversation state between users and sessions, and authorize access to any persisted session data.
+- Redact personally identifiable information (PII) from prompts and outputs — either with a Bedrock Guardrail sensitive information filter (below) or, for Strands agents, the approaches in the [PII Redaction](https://strandsagents.com/docs/user-guide/safety-security/pii-redaction/) guide.
+
+### Amazon Bedrock Guardrails
+
+[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) provide configurable content filters, denied topics, and sensitive information (PII) filters which are evaluated on model input and output. You can attach a guardrail to the model used by the generated agent:

package/docs/snippets/api/access-logging.mdx

@@ -0,0 +1,33 @@
+---
+title: Access logging
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+For REST APIs, the generated infrastructure enables [access logging](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html) by default, writing one structured JSON line per request to a dedicated CloudWatch Logs group. The log group is encrypted with a customer-managed KMS key and retained for one year.
+
+API Gateway writes access logs using an account-level CloudWatch Logs role. This role is configured on the `AWS::ApiGateway::Account` setting, which is a **singleton per region per account** — there is only one role for every REST API in the region. To manage this safely across multiple independently-deployed stacks, the generated infrastructure:
+
+- Creates a shared CloudWatch Logs role and configures it on the account only when no working role is already set, so deployments never overwrite a role another stack owns.
+- Leaves the account setting untouched on teardown, so destroying one stack never disables logging for other REST APIs in the region.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The account role is managed by the `ApiGatewayAccount` construct, a stack-scoped singleton resolved via `ApiGatewayAccount.ensure(scope)`. Each REST API's stage depends on it, and the role is configured by a Lambda-backed custom resource.
+
+You can customise the access log format by passing `deployOptions` when constructing your API:
+
+```ts {3-5}
+const api = new MyApi(this, 'MyApi', {
+  integrations: MyApi.defaultIntegrations(this).build(),
+  deployOptions: {
+    accessLogFormat: AccessLogFormat.clf(),
+  },
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+The account role is managed by the `core/api/api-gateway-account` module, which is instantiated by the generated API module. It configures the account idempotently and is never reset on `terraform destroy`.
+
+You can customise the access log format by editing the `access_log_settings` block on the `aws_api_gateway_stage` resource in the generated API module.
+</Fragment>
+</Infrastructure>

package/docs/snippets/api/cors-configuration-cdk-note.mdx

@@ -8,7 +8,7 @@ If your solution includes a website you can configure its CloudFront distributio
 You can call the API `restrictCorsTo` method with website constructs, CloudFront distributions, origin strings, or a mix of them.
 
 ```ts
-import { MyApi, MyWebsite } from ':my-scope/common-constructs';
+import { MyApi, MyWebsite } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/snippets/api/cors-configuration-terraform-note.mdx

@@ -9,7 +9,7 @@ Given a CloudFront domain name `<domain_name>`, within the Terraform module for
 - a `cors_allow_origins` property, set to `["http://localhost:4200", "http://localhost:4300", "https://<domain name>"]`, for HTTP APIs. This restricts the API gateway CORS to this distribution and local host.
 - an `ALLOWED_ORIGINS` environment variable, set to `"https://<domain_name>"`, for REST APIs. This sets the CloudFront distribution as the only permitted CORS origin (other than local host) in AWS Lambda integrations. Note that this restriction is not applied to preflight OPTIONS - please +1 [this GitHub issue](https://github.com/awslabs/nx-plugin-for-aws/issues/377) to help prioritise addressing this.
 
-```hcl {4,6,9}
+```hcl {6,9}
 module "my_api" {
   source = "../../common/terraform/src/app/apis/my-api"
 

package/docs/snippets/api/type-safe-api-integrations.mdx

@@ -69,7 +69,7 @@ api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
 
 If your API uses the `shared` pattern, the shared router Lambda is exposed as `api.integrations.$router`:
 
-```ts {6}
+```ts {5}
 const api = new MyApi(this, 'MyApi', {
   integrations: MyApi.defaultIntegrations(this).build(),
 });
@@ -172,6 +172,37 @@ module "my_api" {
 </Fragment>
 </Infrastructure>
 
+#### Customising Options Per-Operation
+
+<Infrastructure>
+<Fragment slot="cdk">
+To customise the options used to create the default integration for _specific_ operations (without affecting the others), you can use the `withOperationOptions` method. For example, if you would like to increase the Lambda function timeout for just one operation:
+
+```ts {4-6}
+const api = new MyApi(this, 'MyApi', {
+  integrations: MyApi.defaultIntegrations(this)
+    .withOperationOptions({
+      sayHello: {
+        timeout: Duration.seconds(60),
+      },
+    })
+    .build(),
+});
+
+// The selected operations remain default integrations, so they're still typed accordingly:
+api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));
+```
+
+The options you specify are merged with the default integration options (and any options set via `withDefaultOptions`). Note that you cannot specify options for operations which you have replaced via `withOverrides`, since these no longer use the default integration.
+
+You will encounter a type error if the same operation is targeted by both `withOperationOptions` and `withOverrides`, regardless of the order in which you call them.
+
+</Fragment>
+<Fragment slot="terraform">
+To customise options for specific operations with Terraform, you need to edit the generated Terraform module to configure individual Lambda functions per operation (see the [Explicit Integrations](#explicit-integrations) section below).
+</Fragment>
+</Infrastructure>
+
 #### Overriding Integrations
 
 <Infrastructure>
@@ -609,7 +640,7 @@ Generated CDK API constructs support two integration patterns:
 
 For example, setting `pattern` to `'shared'` creates a single function instead of one per integration:
 
-```ts {5,11-12}
+```ts {6}
 // packages/common/constructs/src/app/apis/my-api.ts
 export class MyApi<...> extends ... {
 

package/docs/snippets/api/waf-configuration.mdx

@@ -6,7 +6,7 @@ import Infrastructure from '@components/infrastructure.astro';
 For REST APIs, the generated construct associates an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL with the API Gateway stage by default. The Web ACL uses the AWS managed default ruleset ([`AWSManagedRulesCommonRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-crs) and [`AWSManagedRulesKnownBadInputsRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-known-bad-inputs)), providing protection against common web exploits including the OWASP Top 10. WAF request logs are written to a CloudWatch Logs group.
 
 :::caution[SizeRestrictions_BODY deviation from defaults]
-The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for most APIs. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details.
+The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for most APIs. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details. API Gateway natively enforces its [maximum payload size of 10 MB](https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html), returning a `413` for larger requests.
 :::
 
 You can edit the generated rest-api construct to add, remove, or adjust rules (for example, to add [rate-based rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-type-rate-based.html) or additional managed rule groups).
@@ -15,7 +15,7 @@ You can edit the generated rest-api construct to add, remove, or adjust rules (f
 <Fragment slot="cdk">
 To opt out (for example, to attach your own Web ACL), set `enableWaf` to `false`:
 
-```ts {4}
+```ts {3}
 const api = new MyApi(this, 'MyApi', {
   integrations: MyApi.defaultIntegrations(this).build(),
   enableWaf: false,
@@ -25,7 +25,7 @@ const api = new MyApi(this, 'MyApi', {
 <Fragment slot="terraform">
 To opt out (for example, to attach your own Web ACL), set `enable_waf` to `false`:
 
-```hcl {4-5}
+```hcl {5}
 module "my_api" {
   source = "../../common/terraform/src/app/apis/my-api"
 

package/docs/snippets/connection/a2a-infrastructure.mdx

@@ -21,7 +21,7 @@ remoteAgent.grantInvokeAccess(myAgent);
 The remote agent's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the host agent can discover it at runtime.
 </Fragment>
 <Fragment slot="terraform">
-```hcl title="packages/infra/src/main.tf" {3-6, 11-12, 16-17}
+```hcl title="packages/infra/src/main.tf" {15-34}
 module "remote_agent" {
   source = "../../common/terraform/src/app/agents/remote-agent"
 

package/docs/snippets/connection/dynamodb-local-development.mdx

@@ -2,6 +2,6 @@
 title: DynamoDB Local Development
 ---
 
-The `connection` generator configures your project's `serve-local` target to depend on the DynamoDB project's `serve-local` target. DynamoDB Local will start automatically alongside your project when running `serve-local`.
+The `connection` generator configures your project's `dev` target to depend on the DynamoDB project's `dev` target. DynamoDB Local will start automatically alongside your project when running `dev`.
 
-The `SERVE_LOCAL=true` environment variable is set automatically, so `getDynamoDBClient()` and `resolveTableName()` connect to the local DynamoDB Local instance instead of AWS.
+The `LOCAL_DEV=true` environment variable is set automatically, so `getDynamoDBClient()` and `resolveTableName()` connect to the local DynamoDB Local instance instead of AWS.

package/docs/snippets/connection/lambda-dynamodb-access.mdx

@@ -11,7 +11,7 @@ To allow Lambda functions to access the DynamoDB table, grant the necessary perm
 Call `grantReadWriteData` on the table construct. This grants both the DynamoDB and KMS permissions required by the Lambda execution role:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table');
 

package/docs/snippets/connection/py-dynamodb-local-development.mdx

@@ -0,0 +1,7 @@
+---
+title: Python DynamoDB Local Development
+---
+
+The `connection` generator configures your project's `dev` target to depend on the DynamoDB project's `dev` target. DynamoDB Local will start automatically alongside your project when running `dev`.
+
+The `LOCAL_DEV=true` environment variable is set automatically, so `is_local()` returns `True` and your PynamoDB entities connect to the local DynamoDB instance instead of AWS.

package/docs/snippets/connection/py-lambda-rdb-ssl-requirements.mdx

@@ -0,0 +1,7 @@
+---
+title: SSL Requirements when Connecting without RDS Proxy
+---
+
+The Amazon Linux 2023 Lambda execution environment's built-in CA trust store includes the Amazon Root CAs used by RDS, so no additional configuration is needed.
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in your Lambda function.