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

package/docs/guides/fastapi.mdx

@@ -6,7 +6,9 @@ when:
   framework: [fastapi]
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, 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';
@@ -119,9 +121,7 @@ def read_item(item_id: int):
 The logger automatically includes:
 
 - Correlation IDs for request tracing
-- Request path and method
-- Lambda context information
-- Cold start indicators
+- Request path, matched route and method
 
 #### Tracing
 
@@ -157,8 +157,7 @@ Default metrics include:
 
 - Request counts
 - Success/failure counts
-- Cold start metrics
-- Per-route metrics
+- Per-route metrics (via a `route` dimension of `<method> <path>`)
 
 ### Error Handling
 
@@ -185,6 +184,216 @@ Unhandled exceptions are caught by the middleware and:
 It's recommended to specify response models for your API operations for better code generation if using the `connection` generator. <Link path="guides/connection/react-fastapi#errors">See here for more details</Link>.
 :::
 
+### Accessing the Calling User
+
+When your API is protected by authentication, your route handlers often need to know who is calling. The generated FastAPI runs inside AWS Lambda via the [Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter), which forwards the API Gateway request context as JSON on the `x-amzn-request-context` header. You can read it from the FastAPI `Request` to extract the caller's identity.
+
+As an example, let's add a `/me` endpoint that returns details about the calling user. We'll implement the extraction as a [FastAPI dependency](https://fastapi.tiangolo.com/tutorial/dependencies/) so it can be reused across routes. The shape of the request context — and therefore how you extract the identity — depends on both your selected `auth` method and whether you deployed a REST or HTTP API.
+
+<OptionFilter when={{ auth: 'iam' }} description="Identity extraction for IAM-authenticated APIs">
+For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway request context. Create `identity.py` alongside `main.py`:
+
+<Tabs syncKey="http-rest">
+<TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
+```python
+import json
+import os
+from typing import Annotated
+
+from boto3 import client
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+cognito = client("cognito-idp")
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    provider = request_context.get("identity", {}).get("cognitoAuthenticationProvider")
+
+    sub = provider.split(":")[-1] if provider else None
+    if not sub:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    users = cognito.list_users(
+        # Assumes user pool id is configured in lambda environment
+        UserPoolId=os.environ["USER_POOL_ID"],
+        Limit=1,
+        Filter=f'sub="{sub}"',
+    ).get("Users", [])
+
+    if len(users) != 1:
+        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")
+
+    return Identity(sub=sub, username=users[0]["Username"])
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+<TabItem label="HTTP API" _filter={{ infra: 'http-lambda' }}>
+```python
+import json
+import os
+from typing import Annotated
+
+from boto3 import client
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+cognito = client("cognito-idp")
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    amr = (
+        request_context.get("authorizer", {})
+        .get("iam", {})
+        .get("cognitoIdentity", {})
+        .get("amr", [])
+    )
+    sign_in = next((s for s in amr if ":CognitoSignIn:" in s), None)
+    sub = sign_in.split(":")[-1] if sign_in else None
+
+    if not sub:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    users = cognito.list_users(
+        # Assumes user pool id is configured in lambda environment
+        UserPoolId=os.environ["USER_POOL_ID"],
+        Limit=1,
+        Filter=f'sub="{sub}"',
+    ).get("Users", [])
+
+    if len(users) != 1:
+        raise HTTPException(status_code=403, detail=f"No user found with subjectId {sub}")
+
+    return Identity(sub=sub, username=users[0]["Username"])
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+</Tabs>
+</OptionFilter>
+
+<OptionFilter when={{ auth: 'cognito' }} description="Identity extraction 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 request context.
+
+Create `identity.py` alongside `main.py`:
+
+<Tabs syncKey="http-rest">
+<TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
+```python
+import json
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    claims = request_context.get("authorizer", {}).get("claims", {})
+
+    sub = claims.get("sub")
+    username = claims.get("username")
+
+    if not sub or not username:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    return Identity(sub=sub, username=username)
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+<TabItem label="HTTP API" _filter={{ infra: 'http-lambda' }}>
+HTTP APIs use a JWT authorizer which places the verified claims under `authorizer.jwt.claims`:
+
+```python
+import json
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request
+from pydantic import BaseModel
+
+
+class Identity(BaseModel):
+    sub: str
+    username: str
+
+
+def get_identity(request: Request) -> Identity:
+    # The Lambda Web Adapter forwards the API Gateway request context as JSON
+    request_context_header = request.headers.get("x-amzn-request-context")
+    if not request_context_header:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    request_context = json.loads(request_context_header)
+    claims = request_context.get("authorizer", {}).get("jwt", {}).get("claims", {})
+
+    sub = claims.get("sub")
+    username = claims.get("username")
+
+    if not sub or not username:
+        raise HTTPException(status_code=403, detail="Unable to determine calling user")
+
+    return Identity(sub=sub, username=username)
+
+
+CurrentUser = Annotated[Identity, Depends(get_identity)]
+```
+</TabItem>
+</Tabs>
+
+:::tip[No token verification required]
+You don't need any 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>
+
+You can then inject the `CurrentUser` dependency into any route that needs the caller's identity:
+
+```python
+from .identity import CurrentUser, Identity
+from .init import app, tracer
+
+@app.get("/me")
+@tracer.capture_method
+def me(identity: CurrentUser) -> Identity:
+    return identity
+```
+
 <OptionFilter when={{ infra: 'rest-lambda' }} description="Streaming — REST API only">
 ### Streaming
 
@@ -226,14 +435,14 @@ To consume a stream of responses, you can make use of the <Link path="guides/con
 
 ## Deploying your FastAPI
 
-The FastAPI generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your FastAPI.
+The FastAPI generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your FastAPI.
 
 <Infrastructure>
 <Fragment slot="cdk">
 The CDK construct for deploying your API in the `common/constructs` folder. You can use this in a CDK application:
 
 ```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) {
@@ -261,7 +470,7 @@ This sets up:
 If you selected to use `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) {
@@ -282,6 +491,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 `authorizer.py` 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>
@@ -330,7 +541,7 @@ This sets up:
 :::note[Cognito Authentication]
 If you selected to use `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"
 
@@ -395,6 +606,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 `authorizer.py` 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>
@@ -406,6 +619,12 @@ When using `Custom` auth, your API is protected by a Lambda Authorizer that **de
 <Snippet name="api/waf-configuration" parentHeading="WAF" />
 </OptionFilter>
 
+<OptionFilter when={{ infra: 'rest-lambda' }} description="Access logging — REST APIs log requests to CloudWatch by default">
+### Access logging
+
+<Snippet name="api/access-logging" parentHeading="Access logging" />
+</OptionFilter>
+
 ### Integrations
 
 <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
@@ -430,14 +649,14 @@ If you are actively working on both your CDK infrastructure and FastAPI together
 <NxCommands
   commands={[
     'watch --projects=<FastAPIProject> -- \\ ',
-    '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>
@@ -509,3 +728,25 @@ This starts a local FastAPI development server with:
 ## Invoking your FastAPI
 
 To invoke your API from a React website, you can use the <Link path="guides/connection/react-fastapi">`connection` generator</Link>.
+
+## 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 FastAPI"
+    description="Call a Python FastAPI from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-fastapi`}
+    source="react"
+    target="fastapi"
+  />
+  <ConnectionCard
+    title="FastAPI to Python DynamoDB"
+    description="Connect a FastAPI to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-fast-api-dynamodb`}
+    source="fastapi"
+    target="dynamodb"
+    targetBadge="python"
+  />
+</CardGrid>

package/docs/guides/local-development.mdx

@@ -0,0 +1,87 @@
+---
+title: Local Development
+description: How local development works with the serve and dev targets
+---
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+
+Connected projects expose two targets for running them on your machine: `serve` and `dev`. The difference is one of **scope** — how much of your application runs locally versus pointing at deployed AWS infrastructure.
+
+Consider a workspace with the following connections: a website that calls a tRPC `api`, and also calls an `agent` which in turn calls an `mcp` server.
+
+## `serve`
+
+The `serve` target runs **only the targeted project** locally. Every other project it connects to is expected to be **deployed**, and is reached at its real AWS URL.
+
+<NxCommands commands={['serve website']} />
+
+Because the targeted project talks to deployed resources, it needs to know where they are. For a website this is provided by its `runtime-config.json` (see <Link path="guides/react-website#local-runtime-config">Local Runtime Config</Link>), which you load from a deployed application. For server-side projects (APIs and agents) that read <Link path="guides/runtime-config">Runtime Configuration</Link>, set the `RUNTIME_CONFIG_APP_ID` environment variable to point at your deployed AppConfig application.
+
+```d2
+direction: right
+
+local: Local {
+  style.stroke-dash: 3
+  website: website
+}
+deployed: Deployed {
+  style.stroke-dash: 3
+  api: api
+  agent: agent
+  mcp: mcp
+}
+
+local.website -> deployed.api
+local.website -> deployed.agent
+deployed.agent -> deployed.mcp
+```
+
+Use `serve` when you want to iterate on a single project against the "real", deployed versions of everything it depends on.
+
+## `dev`
+
+The `dev` target runs the **targeted project** and **every project connected to it transitively**, all on your machine. The connection generator wires this up automatically — running `dev` on the website also starts local servers for the `api`, the `agent`, and the `mcp` server it reaches through the agent.
+
+<NxCommands commands={['dev website']} />
+
+When run this way, the website's `runtime-config.json` is automatically overridden (via [Vite's `MODE`](https://vite.dev/guide/env-and-mode), set to `local-dev`) so that it points at your locally running servers instead of deployed URLs.
+
+```d2
+direction: right
+
+local: Local {
+  style.stroke-dash: 3
+  website: website
+  api: api
+  agent: agent
+  mcp: mcp
+
+  website -> api
+  website -> agent
+  agent -> mcp
+}
+```
+
+Every project runs locally, so there are no deployed dependencies.
+
+Use `dev` when you are working across several connected projects at once and want to iterate quickly without deploying your infrastructure.
+
+### Projects with multiple components
+
+Some project types can hold multiple components in a single project (for example a TypeScript or Python project containing several agents and MCP servers). For these:
+
+- The project-level `dev` target starts **all** of the project's components together. Each component is added to `dev` as it is generated:
+
+<NxCommands commands={['dev my-project']} />
+- Each component also exposes a `<component-name>-dev` target, so you can run a single component on its own:
+
+<NxCommands commands={['my-component-dev my-project']} />
+
+:::tip[Workspace `dev` script]
+Your workspace's root `package.json` includes a `dev` script that runs `nx run-many --target dev`, starting the `dev` target for every project that has one. Spin up your whole workspace's local development servers with:
+
+<PackageManagerShortCommand commands={["dev"]} />
+:::
+
+For more detail on each project type's local development server, see the relevant guide — for example the <Link path="guides/react-website#local-development-server">React Website</Link> guide.

package/docs/guides/nx-generator.mdx

@@ -286,7 +286,7 @@ import { generateFiles, joinPathFragments } from '@nx/devkit';
 // Generate files from templates
 generateFiles(
   tree,
-  joinPathFragments(__dirname, 'files'), // Template directory
+  joinPathFragments(import.meta.dirname, 'files'), // Template directory
   'path/to/output', // Output directory
   {
     // Variables to replace in templates
@@ -459,7 +459,7 @@ export const myGenerator = async (tree: Tree, schema: MyGeneratorSchema) => {
 
   generateFiles(
     tree,
-    joinPathFragments(__dirname, 'files'), // Template directory
+    joinPathFragments(import.meta.dirname, 'files'), // Template directory
     'path/to/output', // Output directory
     data,
   );
@@ -497,7 +497,7 @@ Unit tests for generators are straightforward to implement. Here's a typical pat
 
 ```typescript
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
-import { yourGenerator } from './generator';
+import { yourGenerator } from './generator.js';
 
 describe('your generator', () => {
   let tree;
@@ -583,6 +583,7 @@ When this generator is run in our repository, it'll generate the following files
   - docs/src/content/docs/guides/
     - \<name>.mdx Documentation page for your generator
   - packages/nx-plugin/generators.json Updated to include your generator
+  - packages/nx-plugin/sdk/\<prefix>.ts Updated to expose your generator from the SDK (for `ts#` and `py#` generators)
 </FileTree>
 
 You can then start to implement your generator.

package/docs/guides/nx-migration.mdx

@@ -0,0 +1,165 @@
+---
+title: Nx Migration Generator
+description: Generates an Nx Migration for an Nx Plugin
+generator: ts#nx-migration
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Link from '@components/link.astro';
+
+Adds an [Nx Migration](https://nx.dev/docs/kb/migration-generators) to an Nx Plugin. Migrations let `nx migrate` automatically update projects that were generated by a previous version of your plugin when you make a breaking change — renamed targets, changed vended config, or a dependency bump that requires accompanying code changes.
+
+The generator scaffolds the migration, registers it in your plugin's `migrations.json`, and wires the `nx-migrations` field into your plugin's `package.json` (creating both if they don't exist yet).
+
+:::tip[Recommended Setup]
+We recommend using the <Link path="/guides/ts-nx-plugin">`ts#nx-plugin`</Link> generator as the base project for your migrations, since it configures a plugin project set up to publish generators and migrations.
+:::
+
+## Usage
+
+### Generate a Migration
+
+<RunGenerator generator="ts#nx-migration" />
+
+### Options
+
+<GeneratorParameters generator="ts#nx-migration" />
+
+## The three kinds of migration
+
+Migrations come in three forms, discriminated by which fields the `migrations.json` entry carries. Pass `--kind` to choose (default `deterministic`):
+
+- **Deterministic** (`implementation`) — a codemod with an exact before/after, and the one to reach for first. It runs unattended, including in CI and non-interactive terminals, and applies identically for every user. Use it alone when the change has a shape you can match reliably everywhere it appears, reporting anything it skipped via `nextSteps`.
+- **Hybrid** (`implementation` + `prompt`) — both halves of one change. Use it when a change is breaking and can't be fully applied mechanically: the codemod does as much as it can safely match and returns `agentContext` describing what it changed *and what it skipped*; Nx passes that context to the paired `prompt`, which directs the agent at the rest. The prompt is what stops a workspace being left broken when the leftover edits span too many shapes to codemod.
+- **Agentic** (`prompt`) — a markdown instruction file applied by the user's local coding agent via Nx's agentic `nx migrate` flow. Use it alone when no mechanical before/after holds at all, because the correct edit depends on what the user has built. When no agent runs (CI, no agent installed, consent declined), Nx surfaces the prompt as manual instructions — so write prompts as self-contained, human-actionable steps.
+
+## Generator Output
+
+The generator creates the following files under your plugin project's source folder, depending on the chosen `kind`:
+
+<FileTree>
+  - src/migrations/latest/\<name>/
+    - migration.ts Codemod implementation (deterministic and hybrid)
+    - migration.spec.ts Tests for your migration (deterministic and hybrid)
+    - prompt.md Agent/human instructions (agentic and hybrid)
+  - migrations.json Created or updated to register your migration
+  - package.json Created or updated to add an "nx-migrations" entry
+</FileTree>
+
+A new migration lands in `latest/`. Grouping migrations by the release that ships them keeps their order visible at a glance as the collection grows — move a migration into a `v<x.y.z>/` folder (and update its paths in `migrations.json`) when you assign its version.
+
+It registers the migration in `migrations.json` with the fields for its kind and no `version` — see [Versioning](#versioning) below. The registered key is prefixed with the folder the migration lives in (`latest-<name>`), so reusing a name for a later change can't silently overwrite a migration that has already shipped.
+
+## Implementing a Migration
+
+A deterministic (or hybrid) migration is a function which mutates the virtual filesystem (the `Tree`), returning a [`MigrationReturnObject`](https://nx.dev/docs/reference/devkit/MigrationReturnObject). Here's a hybrid one, which returns both:
+
+```ts
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';
+
+export default async function migration(
+  tree: Tree,
+): Promise<MigrationReturnObject> {
+  const nextSteps: string[] = [];
+  const agentContext: string[] = [];
+
+  // Read and update the files your generators produce here.
+
+  await formatFilesInSubtree(tree);
+
+  return { nextSteps, agentContext };
+}
+```
+
+- **`nextSteps`** — the follow-up actions Nx prints for the user after `nx migrate` runs. Every entry should be something they need to do by hand: reconcile a file you skipped (see the guardrails below), or finish something beyond the migration's reach, like an install to refresh a lock file. They aren't a log of what you changed — when a transform applies cleanly, add nothing, otherwise the entries that do need action get buried.
+- **`agentContext`** (hybrid only) — a summary of what the codemod changed, passed to the paired `prompt` when it runs under Nx's agentic flow so the agent can focus on the user-owned parts.
+
+For some example operations you can perform in your migration (generating files, modifying existing files using GritQL, reading and updating JSON), refer to the <Link path="/guides/nx-generator">Nx Generator guide</Link>.
+
+### Guardrails
+
+Migrations run against workspaces you don't control, so it is recommended to adhere to the following (the scaffolded skeleton bakes these in):
+
+- **Transform source code with GritQL.** Use the <Link path="/guides/nx-generator">GritQL helpers</Link> (`applyGritQL`, `matchGritQL`) to edit source rather than regexes or string replacements. GritQL matches the AST, so one pattern holds across the formatting, whitespace and quoting a user's copy may have drifted into, where text matching quietly misses equivalent code or corrupts the file. Use `updateJson` for JSON and the matching parser for other structured config.
+- **Pattern-match before writing.** If a target file has diverged from the shape your generators produce, skip it and report it via `nextSteps`, or consider a hybrid migration, rather than clobbering the user's changes. `matchGritQL` is a convenient way to make that check.
+- **Report only what's left to do.** `nextSteps` is for work the user has to pick up, not a record of the edits you made — those are already in their `git diff`.
+- **Idempotent.** Re-running the migration must be a no-op. Guard GritQL rewrites that inject code with a `where { ... <: not contains ... }` clause so a second run doesn't append a duplicate.
+- **Format what you write.** Finish with `formatFilesInSubtree(tree)` so the files your migration wrote are formatted correctly.
+
+### Testing Your Migration
+
+The scaffolded `migration.spec.ts` uses `createTreeUsingTsSolutionSetup()` to build a virtual workspace matching the shape our preset generates. Test that the migration takes a workspace from the "before" state to the target state, skips (and reports) code it doesn't recognise, and is idempotent:
+
+```ts
+import type { Tree } from '@nx/devkit';
+import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
+import migration from './migration.js';
+
+describe('my migration', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeUsingTsSolutionSetup();
+  });
+
+  it('should update the generated shape', async () => {
+    // Set up a tree with the "before" state
+    tree.write('project.json', JSON.stringify({ targets: { foo: {} } }));
+
+    // Run the migration
+    await migration(tree);
+
+    // Check that the tree matches the target state
+    const projectJson = JSON.parse(tree.read('project.json', 'utf-8'));
+    expect(projectJson.targets).toHaveProperty('bar');
+    expect(projectJson.targets).not.toHaveProperty('foo');
+  });
+});
+```
+
+Unit tests only prove the migration does what you wrote it to do. Also test it against a workspace generated by the **published** version of your plugin — the state your users upgrade from — and confirm the result matches what your generators produce today: inspect the diff, generate the same projects into a fresh workspace and compare, check the workspace still builds, then re-run the migration to confirm it changes nothing. Repeat with a workspace you've customised first, to check the migration leaves your edits alone and reports them instead.
+
+## Versioning
+
+Nx runs a migration when the user's installed plugin version is less than the migration's `version`. This generator writes **no** `version` field — assign it (or stamp it from your release process) when you cut the release that ships the migration, so it runs for everyone upgrading from an earlier version.
+
+Once you assign versions, a `migrations.json` registering one migration of each kind looks like this:
+
+```json
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "my-plugin",
+  "generators": {
+    "v2.0.0-rename-foo-target": {
+      "version": "2.0.0",
+      "description": "Rename the foo target to bar",
+      "implementation": "./src/migrations/v2.0.0/rename-foo-target/migration"
+    },
+    "v3.0.0-migrate-custom-handlers": {
+      "version": "3.0.0",
+      "description": "Update custom handlers for the new API",
+      "prompt": "./src/migrations/v3.0.0/migrate-custom-handlers/prompt.md"
+    },
+    "v4.0.0-upgrade-framework": {
+      "version": "4.0.0",
+      "description": "Upgrade the framework and reconcile call sites",
+      "implementation": "./src/migrations/v4.0.0/upgrade-framework/migration",
+      "prompt": "./src/migrations/v4.0.0/upgrade-framework/prompt.md"
+    }
+  }
+}
+```
+
+## Running Migrations
+
+Users apply your plugin's migrations with the two-step `nx migrate` flow — generate the pending migrations, install, then run them:
+
+<NxCommands commands={['migrate my-plugin@latest', 'migrate --run-migrations']} />
+
+Agentic and hybrid migrations are applied by the user's local coding agent during `nx migrate --run-migrations` when one is available.
+
+For the full flow from the upgrading user's perspective — including example output for deterministic and agentic migrations — see <Link path="get_started/upgrading">Upgrading Your Workspace</Link>.