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

package/docs/guides/ts-smithy-api.mdx

@@ -7,7 +7,9 @@ when:
   infra: [rest-lambda]
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, CardGrid } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -44,9 +46,10 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 <FileTree>
 
 - **model/** Smithy model project
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - smithy-build.json Smithy build configuration
-  - build.Dockerfile Docker configuration for building Smithy artifacts
+  - ssdk.rolldown.config.mjs Bundles the generated TypeScript Server SDK
   - src/
     - main.smithy Main service definition
     - operations/
@@ -67,7 +70,7 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 
 ### Infrastructure
 
-Since this generator creates infrastructure as code based on your chosen `iacProvider`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
+Since this generator creates infrastructure as code based on your chosen `iac`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
 
 The common infrastructure as code project is structured as follows:
 
@@ -221,6 +224,31 @@ You can change the folder structure however you like - all `.smithy` files in th
 For more details on Smithy and its syntax, refer to the [Smithy specification](https://smithy.io/2.0/spec/index.html).
 :::
 
+### Adding a Shape Library
+
+If you have several Smithy APIs which share the same data types, you can define those types once in a shape library rather than duplicating them in each model. A shape library is a Smithy project with no service — just reusable shapes — which any number of Smithy projects can depend on.
+
+Generate one with the <Link path="guides/smithy-project">`smithy#project`</Link> generator:
+
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes', type: 'shapes' }} />
+
+Your API's model can then reference its shapes with `use`:
+
+```smithy
+$version: "2.0"
+
+namespace com.example.api
+
+use com.example.shared#Customer
+
+structure GetCustomerOutput {
+    @required
+    customer: Customer
+}
+```
+
+See the <Link path="guides/smithy-project">Smithy project guide</Link> for how to create a shape library and wire it up as a dependency of your API's model.
+
 ### Implementing Operations in TypeScript
 
 Operation implementations are located in the backend project's `src/operations/` directory. Each operation is implemented using the generated types from the TypeScript Server SDK (generated at build time from your Smithy model).
@@ -280,7 +308,7 @@ You must construct the context yourself in both `handler.ts` (the Lambda functio
 
 The generator configures structured logging using AWS Lambda Powertools with automatic context injection via Middy middleware.
 
-```typescript {4}
+```typescript {3}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -291,7 +319,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can reference the logger from your operation implementations via the context:
 
-```typescript {6}
+```typescript {5}
 // operations/echo.ts
 import { ServiceContext } from '../context.js';
 import { Echo as EchoOperation } from '../generated/ssdk/index.js';
@@ -306,7 +334,7 @@ export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
 
 AWS X-Ray tracing is configured automatically via the `captureLambdaHandler` middleware.
 
-```typescript {3}
+```typescript {2}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -317,7 +345,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can add custom subsegments to your traces in your operations:
 
-```typescript {7, 11, 14}
+```typescript {6, 10, 13}
 // operations/echo.ts
 import { ServiceContext } from '../context.js';
 import { Echo as EchoOperation } from '../generated/ssdk/index.js';
@@ -340,7 +368,7 @@ export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
 
 CloudWatch metrics are collected automatically for each request via the `logMetrics` middleware.
 
-```typescript {5}
+```typescript {4}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -351,7 +379,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can add custom metrics in your operations:
 
-```typescript {7}
+```typescript {6}
 // operations/echo.ts
 import { MetricUnit } from '@aws-lambda-powertools/metrics';
 import { ServiceContext } from '../context.js';
@@ -401,12 +429,159 @@ export const MyOperation: MyOperationHandler<ServiceContext> = async (input) =>
 };
 ```
 
+### Accessing the Calling User
+
+When your API is protected by authentication, your operations often need to know who is calling. The recommended approach is to resolve the caller's identity once in the handler and pass it through the [service context](#service-context) for consumption by specific operations.
+
+We'll model the unauthorized case as a Smithy error so it serializes to a proper `403` response. Add it to your model, for example in `model/src/operations/errors.smithy`, and reference it on any operation that requires identity:
+
+```smithy
+$version: "2.0"
+
+namespace your.namespace
+
+/// Thrown when the calling user cannot be determined
+@error("client")
+@httpError(403)
+structure UnauthorizedError {
+    @required
+    message: String
+}
+```
+
+First, expose the resolved identity on the service context in `src/context.ts`. We provide it as a function so that the `UnauthorizedError` is thrown from within an operation (where the Server SDK serializes it to a `403`), rather than from the handler:
+
+```ts {5-8,17} ins={5-8,17}
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+export interface Identity {
+  sub: string;
+  username: string;
+}
+
+/**
+ * Context provided to all operations.
+ */
+export interface ServiceContext {
+  tracer: Tracer;
+  logger: Logger;
+  metrics: Metrics;
+  getIdentity: () => Promise<Identity>;
+}
+```
+
+Next, write the resolver in `src/identity.ts`. It throws `UnauthorizedError` when the caller cannot be determined. The implementation depends on your selected `auth` method:
+
+<OptionFilter when={{ auth: 'iam' }} description="Identity resolution for IAM-authenticated APIs">
+For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway event:
+
+```ts
+import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { Identity } from './context.js';
+import { UnauthorizedError } from './generated/ssdk/index.js';
+
+const cognito = new CognitoIdentityProvider();
+
+export const getIdentity = async (
+  event: APIGatewayProxyEvent,
+): Promise<Identity> => {
+  const cognitoAuthenticationProvider =
+    event.requestContext?.identity?.cognitoAuthenticationProvider;
+
+  let sub: string | undefined = undefined;
+  if (cognitoAuthenticationProvider) {
+    const providerParts = cognitoAuthenticationProvider.split(':');
+    sub = providerParts[providerParts.length - 1];
+  }
+
+  if (!sub) {
+    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
+  }
+
+  const { Users } = await cognito.listUsers({
+    // Assumes user pool id is configured in lambda environment
+    UserPoolId: process.env.USER_POOL_ID!,
+    Limit: 1,
+    Filter: `sub="${sub}"`,
+  });
+
+  if (!Users || Users.length !== 1) {
+    throw new UnauthorizedError({ message: `No user found with subjectId ${sub}` });
+  }
+
+  return { sub, username: Users[0].Username! };
+};
+```
+</OptionFilter>
+
+<OptionFilter when={{ auth: 'cognito' }} description="Identity resolution for Cognito-authenticated APIs">
+With `auth: 'cognito'`, the API Gateway Cognito User Pools authorizer verifies the JWT that the caller supplies in the `Authorization` header and places the verified claims on the event at `event.requestContext.authorizer.claims`:
+
+```ts
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { Identity } from './context.js';
+import { UnauthorizedError } from './generated/ssdk/index.js';
+
+export const getIdentity = async (
+  event: APIGatewayProxyEvent,
+): Promise<Identity> => {
+  const claims = event.requestContext?.authorizer?.claims as
+    | Record<string, string>
+    | undefined;
+
+  const sub = claims?.sub;
+  const username = claims?.username;
+
+  if (!sub || !username) {
+    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
+  }
+
+  return { sub, username };
+};
+```
+
+:::tip[No token verification required]
+You don't need `aws-jwt-verify` or any other JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, scopes, and expiry by the time your Lambda runs. If any of those checks fail, API Gateway returns `401 Unauthorized` and your handler is never invoked.
+:::
+</OptionFilter>
+
+Then wire the resolver into the context in `src/handler.ts`:
+
+```ts {2,8} ins={2,8}
+import { Service } from './service.js';
+import { getIdentity } from './identity.js';
+// ...
+const httpResponse = await serviceHandler.handle(httpRequest, {
+  tracer,
+  logger,
+  metrics,
+  getIdentity: () => getIdentity(event),
+});
+```
+
+We can now use the resolved identity in an operation, for example in `src/operations/echo.ts`:
+
+```ts
+import { ServiceContext } from '../context.js';
+import { Echo as EchoOperation } from '../generated/ssdk/index.js';
+
+export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
+  const identity = await ctx.getIdentity();
+  return { message: `${identity.username} says ${input.message}` };
+};
+```
+
 ## Building and Code Generation
 
-The Smithy model project uses [Docker](https://www.docker.com/) to build the Smithy artifacts and generate the TypeScript Server SDK:
+The Smithy model project uses the [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/index.html) to build the Smithy artifacts and generate the TypeScript Server SDK:
 
 <NxCommands commands={['build <model-project>']} />
 
+On macOS and Linux the CLI is resolved by [mise](https://mise.jdx.dev/), which the build fetches on demand, so there is nothing to install — it downloads and caches the pinned version the first time you build.
+
 This process:
 
 1. **Compiles the Smithy model** and validates it
@@ -418,6 +593,39 @@ The backend project automatically copies the generated SDK during compilation:
 
 <NxCommands commands={['copy-ssdk <backend-project>']} />
 
+### Building on Windows
+
+`mise` publishes no Windows package to npm, so on Windows the Smithy CLI is a prerequisite you install yourself. Install it once following the [Smithy CLI installation guide](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html) (for example `winget install smithy` or `scoop install smithy`), and make sure `smithy` is on your `PATH`. A Smithy project generated on Windows runs `smithy` directly rather than through `mise`.
+
+:::caution[Upgrading the CLI]
+Because the CLI is installed globally rather than pinned in your workspace, upgrading the workspace with `nx migrate` does **not** upgrade it. When a migration moves the Smithy dependencies forward, upgrade your global Smithy CLI to a matching version yourself.
+:::
+
+Alternatively, develop inside [WSL](https://learn.microsoft.com/en-us/windows/wsl/install), where the build runs the Linux path and `mise` resolves the CLI for you — nothing to install.
+
+A project generated on Windows commits a `compile` target that invokes `smithy` directly, so anyone else working on it — including on macOS or Linux — needs the Smithy CLI on their `PATH` too. To have those machines resolve the CLI through `mise` instead, switch the target to the `mise` command as [described below](#choosing-how-the-cli-is-resolved).
+
+### Choosing how the CLI is resolved
+
+macOS and Linux resolve the CLI through `mise` and Windows uses a globally installed CLI, but you can pick either on any platform by editing the `compile` target's command in the model project's `project.json`.
+
+To use a globally installed Smithy CLI instead of `mise`, replace the `mise` prefix with a bare `smithy`:
+
+```json title="project.json" del={5} ins={6}
+{
+  "targets": {
+    "compile": {
+      "options": {
+        "commands": ["... npx -y mise@<version> exec smithy@<version> -- smithy build ..."]
+        "commands": ["... smithy build ..."]
+      }
+    }
+  }
+}
+```
+
+To go back to `mise` resolving the CLI, restore the `npx -y mise@<version> exec smithy@<version> --` prefix.
+
 ### Bundle Target
 
 <Snippet name="ts-bundle" />
@@ -434,14 +642,14 @@ The local server will not only hot-reload when you make TypeScript changes to yo
 
 ## Deploying your Smithy API
 
-The generator creates CDK or Terraform infrastructure based on your selected `iacProvider`.
+The generator creates CDK or Terraform infrastructure based on your selected `iac`.
 
 <Infrastructure>
 <Fragment slot="cdk">
 The CDK construct for deploying your API is in the `common/constructs` folder:
 
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -468,7 +676,7 @@ This sets up:
 If you selected `Cognito` authentication, you will need to supply the `identity` property to the API construct:
 
 ```ts {9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -489,6 +697,8 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer CDK usage">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `src/authorizer.ts` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 </Fragment>
@@ -537,7 +747,7 @@ This sets up:
 :::note[Cognito Authentication]
 If you selected `Cognito` authentication, you will need to supply the Cognito configuration:
 
-```hcl {3, 5-6}
+```hcl {6-7}
 module "my_api" {
   source = "../../common/terraform/src/app/apis/my-api"
 
@@ -560,6 +770,8 @@ module "my_api" {
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer usage with Terraform">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `src/authorizer.ts` file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 
@@ -583,6 +795,10 @@ output "lambda_function_name" {
 
 <Snippet name="api/waf-configuration" parentHeading="WAF" />
 
+### Access logging
+
+<Snippet name="api/access-logging" parentHeading="Access logging" />
+
 ### Integrations
 
 <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
@@ -607,14 +823,14 @@ If you are actively working on both your CDK infrastructure and Smithy API toget
 <NxCommands
   commands={[
     'watch --projects=<ModelProject> -- \\ ',
-    'run <InfraProject>:"generate:<ApiName>-metadata"',
+    'run @<scope>/common-constructs:"generate:<ApiName>-metadata"',
   ]}
 />
 :::
 </Fragment>
 <Fragment slot="terraform">
 :::note[Terraform Limitations]
-We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iacProvider`.
+We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iac`.
 :::
 </Fragment>
 </Infrastructure>
@@ -662,3 +878,31 @@ resource "aws_iam_role_policy_attachment" "api_invoke_access" {
 ## Invoking your Smithy API
 
 To invoke your API from a React website, you can use the <Link path="guides/connection/react-smithy">`connection`</Link> generator, which provides type-safe client generation from your Smithy model.
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <ConnectionCard
+    title="React to Smithy API"
+    description="Call a Smithy API from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-smithy`}
+    source="react"
+    target="smithy"
+  />
+  <ConnectionCard
+    title="Smithy API to Relational Database"
+    description="Connect a Smithy API to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-rdb`}
+    source="smithy"
+    target="aurora"
+  />
+  <ConnectionCard
+    title="Smithy API to TypeScript DynamoDB"
+    description="Connect a Smithy API to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-dynamodb`}
+    source="smithy"
+    target="dynamodb"
+  />
+</CardGrid>

package/docs/guides/typescript-infrastructure.mdx

@@ -38,12 +38,13 @@ The generator will create the following project structure in the `<directory>/<n
     - stacks CDK Stack definitions
       - application-stack.ts Main application stack
   - cdk.json CDK configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - checkov.yml Checkov configuration file
 
 </FileTree>
 
-If you set the `enableStageConfig` option, the generator also creates two shared packages for centralized credential management (if they don't already exist):
+If you set the `stageConfig` option, the generator also creates two shared packages for centralized credential management (if they don't already exist):
 
 <FileTree>
 
@@ -95,17 +96,22 @@ new ApplicationStage(app, 'my-app-sandbox', {
     region: process.env.CDK_DEFAULT_REGION,
   },
 });
+
+// Define other instances of stages, such as beta and prod, below
 ```
 
 The `env` property tells CDK which AWS account and region to deploy to. `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are resolved automatically by the CDK CLI from your active AWS credentials. See the [CDK environments documentation](https://docs.aws.amazon.com/cdk/v2/guide/environments.html) for more details.
 
-If you generated with `enableStageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
+The sandbox stage is the one the <Link path="guides/typescript-infrastructure#deploying-your-sandbox-stage">`deploy-sandbox`</Link> and <Link path="guides/typescript-infrastructure#tearing-down-your-sandbox-stage">`destroy-sandbox`</Link> targets act on.
+
+If you generated with `stageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
 
-```ts title="src/main.ts (with enableStageConfig)"
-import stagesConfig from ':my-scope/common-infra-config';
+```ts title="src/main.ts (with stageConfig)"
+import { resolveStage } from '@my-scope/common-infra-config';
 
-const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
-const sandboxConfig = projectStages['my-app-sandbox'];
+// Looks up the stage under this project (packages/infra), falling back to
+// shared stages. Returns undefined when no config exists for the stage.
+const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
 
 new ApplicationStage(app, 'my-app-sandbox', {
   env: {
@@ -158,12 +164,12 @@ export class ApplicationStage extends Stage {
 ### Stage Credential Configuration
 
 :::note[Staged Configuration]
-This section applies when you generate with `enableStageConfig`. Without it, the generator produces a simpler setup where you manage AWS credentials yourself (e.g., by exporting `AWS_PROFILE` before deploying).
+This section applies when you generate with `stageConfig`. Without it, the generator produces a simpler setup where you manage AWS credentials yourself (e.g., by exporting `AWS_PROFILE` before deploying).
 :::
 
 When you have multiple stages targeting different AWS accounts, managing credentials manually can be error-prone, especially as the number of stages grows.
 
-The `enableStageConfig` option solves this by generating two shared packages:
+The `stageConfig` option solves this by generating two shared packages:
 
 - **`packages/common/infra-config`** — A single config file where you map each stage to its AWS credentials, account, and region. This is importable from any package in your workspace, so your CDK `main.ts` can read account and region from the same source of truth.
 - **`packages/common/scripts`** — `infra-deploy` and `infra-destroy` commands that wrap CDK with automatic credential resolution. When you run `deploy`, the script reads the config, sets the right AWS environment variables for the CDK child process, and runs `cdk deploy`. Your shell environment is never modified.
@@ -242,7 +248,7 @@ Each stage config includes a required `region` and an optional `account`:
 The generated `main.ts` reads these values from the config so that CDK synthesis and deployment use the same environment settings:
 
 ```ts title="src/main.ts"
-const sandboxConfig = projectStages['my-app-sandbox'];
+const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
 new ApplicationStage(app, 'my-app-sandbox', {
   env: {
     account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
@@ -270,7 +276,7 @@ If, for example, you created a tRPC API called `my-api`, you can simply import a
 ```ts title="src/stacks/application-stack.ts" {3, 9-12}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -286,12 +292,12 @@ export class ApplicationStack extends Stack {
 
 ### Website Infrastructure
 
-If you have used the <Link path="guides/react-website">CloudScape website</Link> generator, you will notice you already have a construct in `packages/common/constructs` to deploy it. For example:
+If you have used the <Link path="guides/react-website">React Website</Link> generator, you will notice you already have a construct in `packages/common/constructs` to deploy it. For example:
 
 ```ts title="src/stacks/application-stack.ts" {3, 9-10}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite } from ':my-scope/common-constructs';
+import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -315,6 +321,8 @@ As part of your `build` target, as well as running the <Link path="guides/typesc
 
 You will find your synthesized cloud assembly in the root `dist` folder, under `dist/packages/<my-infra-project>/cdk.out`.
 
+`synth` depends on `^assemble`, so synthesizing builds the artifacts your stacks deploy, such as the Lambda bundles, container images and generated specifications, without running every upstream project's lint, test and type-check gates. See <Link path="guides/typescript-project#assembling">Assembling</Link> for more detail on `assemble`.
+
 ## Security Testing
 
 A `checkov` target is added to your project which runs security checks on your infrastructure using [Checkov](https://www.checkov.io/).
@@ -338,7 +346,7 @@ There may be instances where you want to suppress certain rules on resources. Yo
 #### Supress a rule on a given construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // suppresses the CKV_AWS_XXX for the given construct.
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
@@ -347,7 +355,7 @@ suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
 #### Supress a rule on a descendant construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // Supresses the CKV_AWS_XXX for the construct or any of its descendants if it is an instance of Bucket
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);
@@ -369,26 +377,48 @@ For more details, please refer to the [CDK bootstrapping documentation](https://
 
 ## Deploying to AWS
 
-After a build, you can deploy your infrastructure to AWS using the `deploy` target.
+Your project has three deploy targets, each suited to a different situation:
+
+| Target           | Use it for                                                                       |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `deploy-sandbox` | Deploying your own sandbox stage during development. No stage argument needed.    |
+| `deploy`         | Deploying any stage, by naming the stage or stacks you want.                      |
+| `deploy-ci`      | Deploying from a CI/CD pipeline, using a pre-synthesized cloud assembly.          |
 
-:::caution[CI Deployment]
-Use the `deploy-ci` target if deploying in a CI/CD pipeline. See below for more details.
+`deploy-sandbox` and `deploy` depend on `^assemble`, so they build the artifacts they are about to deploy and nothing else. `deploy-ci` deploys an assembly your pipeline already built, so it has no build dependencies at all.
+
+:::caution[Use `build` in your pipeline]
+`assemble` is used for faster iteration during development. Run `build` in your CI pipeline to ensure your project passes quality gates prior to a production deployment.
 :::
 
-First, make sure you have AWS credentials configured. If you generated with `enableStageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
+First, make sure you have AWS credentials configured. If you generated with `stageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
 
-Then run the deploy target:
+### Deploying your Sandbox Stage
 
-<NxCommands commands={['deploy <my-infra> <my-infra>-sandbox/*']} />
+The `deploy-sandbox` target deploys the sandbox stage that `main.ts` declares, so you don't need to remember its stage name:
 
-:::tip[Selective Stack Deployment]
-The above command deploys _all_ stacks for the `<my-infra>-sandbox` stage. You can specify other stages so long as they are defined in `main.ts`.
+<NxCommands commands={['deploy-sandbox <my-infra>']} />
 
-You can also deploy individual stacks by specifying the full stack name, for example:
+This is the quickest way to get your own copy of the application running in AWS while you develop.
 
-<NxCommands commands={['deploy <my-infra> <my-infra>-sandbox/Application']} />
+:::tip[Express Mode for Faster Deployments]
+The deploy targets wait for full resource stabilization by default, favouring consistency over speed. To speed up iteration during development, opt into [CloudFormation express mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-express-mode.html) by passing CDK's `--express` flag:
+
+<NxCommands commands={['deploy-sandbox <my-infra> --express']} />
+
+Express mode finishes once resource configuration is confirmed applied rather than waiting for full stabilization, with propagation continuing in the background, for significantly faster iteration cycles. It is intended for development and iteration.
 :::
 
+### Deploying a Specific Stage
+
+The `deploy` target deploys whichever stage or stacks you name. Use it for stages other than your sandbox, or to deploy a single stack:
+
+<NxCommands commands={['deploy <my-infra> <my-infra>-sandbox/*']} />
+
+You can specify any stage so long as it is defined in `main.ts`. To deploy an individual stack, give the full stack name:
+
+<NxCommands commands={['deploy <my-infra> <my-infra>-sandbox/Application']} />
+
 ## Deploying to AWS in a CI/CD Pipeline
 
 Use the `deploy-ci` target if you are deploying to AWS as part of a CI/CD pipeline.
@@ -399,10 +429,34 @@ This target differs slightly from the regular `deploy` target in that it deploys
 
 ## Tearing Down AWS Infrastructure
 
-Use the `destroy` target to tear down your resources:
+Your project has three destroy targets, mirroring the deploy ones:
+
+| Target            | Use it for                                                                |
+| ----------------- | ------------------------------------------------------------------------- |
+| `destroy-sandbox` | Tearing down your own sandbox stage. No stage argument needed.             |
+| `destroy`         | Tearing down any stage, by naming the stage or stacks you want.            |
+| `destroy-ci`      | Tearing down from a CI/CD pipeline, using a pre-synthesized cloud assembly. |
+
+### Tearing Down your Sandbox Stage
+
+The `destroy-sandbox` target tears down the sandbox stage that `main.ts` declares, so you don't need to remember its stage name:
+
+<NxCommands commands={['destroy-sandbox <my-infra>']} />
+
+Destroying is irreversible, so CDK asks you to confirm the stacks it is about to delete. Pass `--force` to skip that confirmation, which is what you want when there is no terminal attached (in a script, say):
+
+<NxCommands commands={['destroy-sandbox <my-infra> --force']} />
+
+### Tearing Down a Specific Stage
+
+The `destroy` target tears down whichever stage or stacks you name:
 
 <NxCommands commands={['destroy <my-infra> <my-infra>-sandbox/*']} />
 
+To tear down an individual stack, give the full stack name:
+
+<NxCommands commands={['destroy <my-infra> <my-infra>-sandbox/Application']} />
+
 ## More Information
 
 For more information about CDK, please refer to the [CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/core_concepts.html) and [API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html).