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

package/docs/guides/react-website.mdx

@@ -1,12 +1,14 @@
 ---
 title: React Website
 description: Reference documentation for a React Website
-generator: ts#react-website
+generator: ts#website
 when:
   framework:
     - react
 ---
-import { FileTree, Steps } from '@astrojs/starlight/components';
+import { FileTree, Steps, 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';
@@ -16,12 +18,12 @@ import Infrastructure from '@components/infrastructure.astro';
 import Snippet from '@components/snippet.astro';
 import OptionFilter from '@components/option-filter.astro';
 
-This generator creates a new [React](https://react.dev/) website with [Cloudscape](http://cloudscape.design/) configured by default, along with the AWS CDK or Terraform infrastructure to deploy your website to the cloud as a static website hosted in [S3](https://aws.amazon.com/s3/), served by [CloudFront](https://aws.amazon.com/cloudfront/) and protected by [WAF](https://aws.amazon.com/waf/).
+This generator creates a new [React](https://react.dev/) website with [shadcn/ui](https://ui.shadcn.com/) configured by default, along with the AWS CDK or Terraform infrastructure to deploy your website to the cloud as a static website hosted in [S3](https://aws.amazon.com/s3/), served by [CloudFront](https://aws.amazon.com/cloudfront/) and protected by [WAF](https://aws.amazon.com/waf/).
 
 The generated application uses [Vite](https://vite.dev/) as the build tool and bundler. It uses [TanStack Router](https://tanstack.com/router/v1) for type-safe routing.
 
 :::note[UX Provider]
-The default `uxProvider` is [Cloudscape](http://cloudscape.design/). You can also select [shadcn/ui](https://ui.shadcn.com/) or `None` (bring your own component library).
+The default `ux` is [shadcn/ui](https://ui.shadcn.com/). You can also select [Cloudscape](http://cloudscape.design/) or `none` (bring your own component library).
 :::
 
 ## Usage
@@ -30,7 +32,7 @@ The default `uxProvider` is [Cloudscape](http://cloudscape.design/). You can als
 
 You can generate a new React Website in two ways:
 
-<RunGenerator generator="ts#website" />
+<RunGenerator generator="ts#website" requiredParameters={{ framework: 'react' }} />
 
 ### Options
 
@@ -57,6 +59,7 @@ The generator will create the following project structure in the `<directory>/<n
   - tsconfig.json Base TypeScript configuration for source and tests
   - tsconfig.app.json TypeScript configuration for source code
   - tsconfig.spec.json TypeScript configuration for tests
+  - package.json Project manifest defining the project's package name and dependencies
 </FileTree>
 
 :::note[Without TanStack Router]
@@ -67,7 +70,7 @@ If you opted not to use [TanStack Router](https://tanstack.com/router/v1), you w
 
 <Snippet name="shared-constructs" />
 
-The generator creates infrastructure as code for deploying your website based on your selected `iacProvider`:
+The generator creates infrastructure as code for deploying your website based on your selected `iac`:
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -126,6 +129,57 @@ waf -> cloudfront
 cloudfront -> s3
 ```
 
+#### Security Headers
+
+The CloudFront distribution applies a response headers policy that sets `Strict-Transport-Security`, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy` and a `Content-Security-Policy` on all responses.
+
+A default `Content-Security-Policy` is enforced. It restricts scripts and framing to mitigate XSS and clickjacking, while permitting HTTPS and WSS connections so the website can call AWS service endpoints (such as API Gateway, Cognito and Bedrock AgentCore) whose URLs are only known at deploy time. To adjust the policy (for example to tighten `connect-src` to your specific origins), edit the `content_security_policy` value in your generated `static-website.ts` (CDK) or `static-website.tf` (Terraform).
+
+`runtime-config.json` is served with `Cache-Control: no-cache` so that browsers always fetch the latest configuration after a redeploy, rather than using a stale cached copy.
+
+#### Custom Domain & TLS
+
+By default the distribution uses the default CloudFront domain name (`*.cloudfront.net`) and its default certificate, which does not support enforcing a minimum TLS version of 1.2. To serve your website from your own domain, supply an [ACM certificate](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html) (which must reside in `us-east-1` for use with CloudFront) and your domain names — a minimum TLS version of 1.2 is then enforced for viewers:
+
+<Infrastructure>
+<Fragment slot="cdk">
+Pass the `certificate` and `domainNames` props through in your generated website construct in `packages/common/constructs/src/app/static-websites`:
+
+```ts {6-8}
+export class MyWebsite extends StaticWebsite {
+  constructor(scope: Construct, id: string) {
+    super(scope, id, {
+      websiteName: 'MyWebsite',
+      websiteFilePath: ...,
+      domainNames: ['www.example.com'],
+      certificate: Certificate.fromCertificateArn(scope, 'Cert',
+        'arn:aws:acm:us-east-1:123456789012:certificate/...'),
+    });
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+Set the `custom_domain_names` and `acm_certificate_arn` variables in your generated website module in `packages/common/terraform/src/app/static-websites`:
+
+```hcl {5-6}
+module "static_website" {
+  source            = "../../../core/static-website"
+  website_name      = "my-website"
+  website_file_path = ...
+  custom_domain_names = ["www.example.com"]
+  acm_certificate_arn = "arn:aws:acm:us-east-1:123456789012:certificate/..."
+
+  providers = {
+    aws.us_east_1 = aws.us_east_1
+  }
+}
+```
+</Fragment>
+</Infrastructure>
+
+You will also need to create DNS records (for example in Route 53) pointing your domain at the CloudFront distribution.
+
 ## Implementing your React Website
 
 The [React documentation](https://react.dev/learn) is a good place to start to learn the basics of building with React.
@@ -185,14 +239,14 @@ Configuration from your infrastructure is provided to your website via <Link hre
 
 <Infrastructure>
 <Fragment slot="cdk">
-The `RuntimeConfig` CDK construct can be used to add and retrieve configuration in your CDK infrastructure. The CDK constructs generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#trpc-api`</Link> and <Link path="guides/fastapi">`py#fast-api`</Link>) will automatically add appropriate values to the `RuntimeConfig`.
+The `RuntimeConfig` CDK construct can be used to add and retrieve configuration in your CDK infrastructure. The CDK constructs generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#api`</Link> and <Link path="guides/fastapi">`py#api`</Link>) will automatically add appropriate values to the `RuntimeConfig`.
 
 Your website CDK construct will deploy the `connection` namespace of the runtime configuration as a `runtime-config.json` file to the root of your S3 bucket.
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, MyApi } from ':my-scope/common-constructs';
+import { MyWebsite, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -214,11 +268,11 @@ With CDK, the website construct can be declared at any point in your stack. Runt
 :::
 </Fragment>
 <Fragment slot="terraform">
-With Terraform, runtime configuration is managed through the runtime-config modules. The Terraform modules generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#trpc-api`</Link> and <Link path="guides/fastapi">`py#fast-api`</Link>) will automatically add appropriate values to the runtime configuration.
+With Terraform, runtime configuration is managed through the runtime-config modules. The Terraform modules generated by `@aws/nx-plugin` generators (such as <Link path="guides/trpc">`ts#api`</Link> and <Link path="guides/fastapi">`py#api`</Link>) will automatically add appropriate values to the runtime configuration.
 
 Your website Terraform module will deploy the `connection` namespace of the runtime configuration as a `runtime-config.json` file to the root of your S3 bucket.
 
-```hcl title="packages/infra/src/main.tf" {18-19}
+```hcl title="packages/infra/src/main.tf" {20-21}
 module "asset_bucket" {
   source = "../../common/terraform/src/core/asset-bucket"
 }
@@ -272,26 +326,30 @@ For details on how runtime configuration is stored in AWS AppConfig and how serv
 
 When running the [local development server](#local-development-server), you will need a `runtime-config.json` file in your `public` directory in order for your local website to know the backend URLs, identity configuration, etc.
 
-Your website project is configured with a `load:runtime-config` target which you can use to pull down the `runtime-config.json` file from a deployed application:
+Your website project is configured with a `load-runtime-config` target which you can use to pull down the `runtime-config.json` file from a deployed application:
 
-<NxCommands commands={['run <my-website>:"load:runtime-config"']} />
+<NxCommands commands={['load-runtime-config <my-website>']} />
 
 :::note[Custom Stage Names]
 <Infrastructure>
 <Fragment slot="cdk">
-If you change the prefix for your stage names in your infrastructure project's `src/main.ts`, you will need to update the `load:runtime-config` target in your website's `project.json` file accordingly.
+If you change the prefix for your stage names in your infrastructure project's `src/main.ts`, you will need to update the `load-runtime-config` target in your website's `project.json` file accordingly.
 
-Additionally it's worth noting that the `load:runtime-config` target assumes a single stage of your application is deployed to the environment you have AWS credentials for. You will need to adjust the command if you deploy multiple stages to the same account and region.
+Additionally it's worth noting that the `load-runtime-config` target assumes a single stage of your application is deployed to the environment you have AWS credentials for. You will need to adjust the command if you deploy multiple stages to the same account and region.
 </Fragment>
 <Fragment slot="terraform">
-For Terraform projects, the `load:runtime-config` target copies the `runtime-config.json` file that was created after your most recent local `terraform apply`.
+For Terraform projects, the `load-runtime-config` target copies the `runtime-config.json` file that was created after your most recent local `terraform apply`.
 </Fragment>
 </Infrastructure>
 :::
 
 ## Local Development Server
 
-You can run a local development server using either the `serve` or `serve-local` target.
+The canonical command for local development is `dev`, which starts your website (and any local servers for APIs you've connected it to) with one command:
+
+<NxCommands commands={['dev <my-website>']} />
+
+The `serve` target is also available for when you need to control how much of your application runs locally versus pointing at deployed AWS infrastructure. For a broader overview of local development across connected projects, including how `dev` behaves for projects with multiple components, see the <Link path="guides/local-development">Local Development</Link> guide.
 
 ### Serve Target
 
@@ -303,46 +361,50 @@ You can run this target with the following command:
 
 This target is useful for working on website changes while pointing to "real" deployed APIs and other infrastructure.
 
-### Serve Local Target
+### Dev Target
 
-The `serve-local` target starts a local development server for your website (with [Vite `MODE`](https://vite.dev/guide/env-and-mode) set to `serve-local`), as well as starting any local servers for APIs you have connected your website to via the <Link path="/guides/connection">Connection generator</Link>.
+The `dev` target starts a local development server for your website (with [Vite `MODE`](https://vite.dev/guide/env-and-mode) set to `local-dev`), as well as starting any local servers for APIs you have connected your website to via the <Link path="/guides/connection">Connection generator</Link>.
 
 When your local website server is run via this target, `runtime-config.json` is automatically overridden to point to your locally running API urls.
 
 You can run this target with the following command:
 
-<NxCommands commands={['serve-local <my-website>']} />
+<NxCommands commands={['dev <my-website>']} />
 
 This target is useful when you are working across your website and API and wish to quickly iterate without deploying your infrastructure.
 
-:::note[`dev` script]
-If no `dev` script exists in your root `package.json` when this generator runs, a `dev` script is added that invokes `serve-local` for the generated website, meaning you can also start the local development server with:
+:::note[Workspace `dev` script]
+Your workspace's root `package.json` includes a `dev` script that runs the `dev` target for every project that has one:
 
 <PackageManagerShortCommand commands={["dev"]} />
 
-This makes the first React website you generate the default `dev` target for the workspace. Subsequent websites do not overwrite the existing `dev` script — you can invoke their `serve-local` targets directly, or update the script manually.
+This starts the local development server for your website (and any other projects with a `dev` target) in one command. To run just this website, use its own `dev` target (e.g. `nx dev <my-website>`).
 :::
 
 :::warning[Mock Authentication]
 When run in this mode and no `runtime-config.json` is present, if you have configured Cognito Authentication (via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>), login will be skipped and requests to your local servers will not include authentication headers.
 
-To enable login and authentication for `serve-local`, deploy your infrastructure and load runtime config.
+To enable login and authentication for `dev`, deploy your infrastructure and load runtime config.
 :::
 
-:::tip[Serve-Local Behavior]
-When running with `serve-local`, you can specify any environment variables required by your APIs to point to other deployed AWS resources, for example:
+:::tip[Dev Behavior]
+When running with `dev`, you can specify any environment variables required by your APIs to point to other deployed AWS resources, for example:
 
-<NxCommands env={{DYNAMODB_TABLE_NAME: 'xxxxx'}} commands={['serve-local <my-website>']} />
+<NxCommands env={{DYNAMODB_TABLE_NAME: 'xxxxx'}} commands={['dev <my-website>']} />
 
 Note that your local API servers will run with the AWS credentials you have configured locally.
 :::
 
 ## Building
 
-You can build your website using the `build` target. This use Vite to create a production bundle in the root `dist/packages/<my-website>/bundle` directory, as well as type-checking, compiling and linting your website.
+You can build your website using the `build` target. This runs the `bundle`, `compile`, `test` and `lint` targets, type-checking, bundling, testing and linting your website.
 
 <NxCommands commands={['build <my-website>']} />
 
+The `bundle` target uses Vite to create a production bundle in the root `dist/packages/<my-website>/bundle` directory. This is the deployable artifact consumed by your website infrastructure. You can run it on its own:
+
+<NxCommands commands={['bundle <my-website>']} />
+
 ## Testing
 
 Testing your website is much like writing tests in a standard TypeScript project, so please refer to the <Link path="guides/typescript-project#testing">TypeScript project guide</Link> for more details.
@@ -355,7 +417,7 @@ You can run your tests using the `test` target:
 
 ## Deploying Your Website
 
-The React website generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your website.
+The React website generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your website.
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -366,7 +428,7 @@ You can use the CDK construct generated for you in `packages/common/constructs`
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3, 9}
 import { Stack } 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) {
@@ -386,7 +448,7 @@ This sets up:
 5. Automatic deployment of website files and runtime configuration
 </Fragment>
 <Fragment slot="terraform">
-To deploy your website, we recommend using the <Link path="guides/terraform-infrastructure">`terraform#project` generator</Link> to create a Terraform project.
+To deploy your website, we recommend using the <Link path="/guides/terraform-project">`terraform#project` generator</Link> to create a Terraform project.
 
 You can use the Terraform module generated for you in `packages/common/terraform` to deploy your website.
 
@@ -422,3 +484,60 @@ provider "aws" {
 </Fragment>
 </Infrastructure>
 
+## 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 tRPC"
+    description="Call a tRPC API from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-trpc`}
+    source="react"
+    target="trpc"
+  />
+  <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="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="React to Python Agent"
+    description="Call a Python Agent from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-py-agent`}
+    source="react"
+    target="strands"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="React to TypeScript Agent"
+    description="Call a TypeScript Agent from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-ts-agent`}
+    source="react"
+    target="strands"
+    targetBadge="typescript"
+  />
+  <ConnectionCard
+    title="React to AG-UI Agent"
+    description="Call an Agent exposing the AG-UI protocol from a React website via CopilotKit"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agui`}
+    source="react"
+    target="copilotkit"
+  />
+  <ConnectionCard
+    title="React Website to AgentCore Gateway"
+    description="Connect a React website to agents through an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agentcore-gateway`}
+    source="react"
+    target="agentcore"
+  />
+</CardGrid>

package/docs/guides/runtime-config.mdx

@@ -70,7 +70,7 @@ Generated constructs automatically write relevant configuration to the `connecti
 The `RuntimeConfig` CDK construct is a stage-scoped singleton. Use `set()` to write a key into a namespace:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { RuntimeConfig } from ':my-scope/common-constructs';
+import { RuntimeConfig } from '@my-scope/common-constructs';
 
 const rc = RuntimeConfig.ensure(this);
 

package/docs/guides/security.mdx

@@ -0,0 +1,75 @@
+---
+title: Security
+description: Security features included in projects generated by the Nx Plugin for AWS
+---
+
+import Link from '@components/link.astro';
+
+:::caution[Reporting Security Issues]
+To report a potential security issue in the Nx Plugin for AWS itself, please refer to [SECURITY.md](https://github.com/awslabs/nx-plugin-for-aws/blob/main/SECURITY.md) — do not create a public GitHub issue.
+:::
+
+## Security Controls
+
+Projects scaffolded by the Nx Plugin for AWS include a number of security controls out of the box. This page provides an overview of those controls and links to the relevant guides for more detail.
+
+### Infrastructure Scanning
+
+Infrastructure projects are configured with [Checkov](https://www.checkov.io/) as part of the `build` target, so insecure infrastructure configuration fails the build:
+
+- CDK projects synthesize CloudFormation templates which are scanned by Checkov. See <Link path="/guides/typescript-infrastructure#security-testing">Security Testing</Link> for details.
+- Terraform projects run Checkov directly against your Terraform code. See <Link path="/guides/terraform-project">Terraform Projects</Link>.
+
+Where vended infrastructure suppresses a Checkov rule, the suppression is scoped to the specific resource and annotated with a justification. The shared `suppressRules` helper requires a reason for every suppression, and we recommend following the same practice in your own code. See <Link path="/guides/typescript-infrastructure#suppressing-checkov-checks">Suppressing Checkov Checks</Link>.
+
+### Container Image Scanning
+
+Projects which build container images (for example agents, MCP servers, and database migration images) include a `trivy` target which scans images for HIGH and CRITICAL vulnerabilities, exiting non-zero on findings. See <Link path="/guides/docker-bundling">Docker Bundling</Link> for details, including how to suppress findings with a `.trivyignore` file.
+
+### Credential Scanning
+
+Workspaces include [git-secrets](https://github.com/awslabs/git-secrets) pre-commit hooks which scan staged files for AWS credential patterns, preventing accidental commits of access keys and other sensitive values. See the <Link path="/guides/workspace#git-secrets">Git Secrets</Link> section of the workspace guide.
+
+### Authentication
+
+APIs, agents, and MCP servers use AWS IAM (SigV4) authentication by default:
+
+- <Link path="/guides/trpc">tRPC</Link>, <Link path="/guides/fastapi">FastAPI</Link>, and <Link path="/guides/ts-smithy-api">Smithy</Link> APIs default to IAM authentication, with Cognito and custom authorizers available as options. The vended custom authorizer stub denies requests by default.
+- <Link path="/guides/ts-agent">Agents</Link> and <Link path="/guides/ts-mcp-server">MCP servers</Link> deployed to Amazon Bedrock AgentCore Runtime use IAM (SigV4) authentication by default, with JWT-based Cognito authentication as an option.
+- The <Link path="/guides/react-website-auth">website auth generator</Link> vends an Amazon Cognito user pool with multi-factor authentication (MFA) required, a strong password policy, and deletion protection enabled.
+
+### Encryption
+
+Vended infrastructure encrypts data in transit and at rest:
+
+- Websites are served via CloudFront with HTTP redirected to HTTPS, and a response headers policy including HTTP Strict Transport Security (HSTS), a Content Security Policy, and other <Link path="/guides/react-website#security-headers">security headers</Link>. A WAF with AWS managed rules is associated with the distribution.
+- S3 buckets block all public access, enforce SSL-only access via bucket policies, are encrypted (KMS with key rotation for website content), and deliver server access logs to CloudWatch log groups encrypted with customer-managed KMS keys, where they can be queried with Logs Insights and alarmed on.
+- API access logs are written to CloudWatch log groups encrypted with customer-managed KMS keys with rotation enabled.
+- <Link path="/guides/ts-rdb">Aurora databases</Link> enable storage encryption with a customer-managed KMS key, generate credentials in AWS Secrets Manager (never hardcoded), and support automatic credential rotation.
+
+### Least Privilege
+
+Vended CDK constructs and Terraform modules follow least privilege:
+
+- Constructs expose `grant*` methods (for example `grantInvokeAccess` on APIs and agents, `grantConnect` on databases) so consumers grant only the access they need.
+- IAM policies in vended infrastructure are scoped to specific resources and actions. Where a wildcard resource is required by the AWS service (for example `ecr:GetAuthorizationToken`), it is limited to those actions and scoped with conditions where supported.
+
+### Dependency Licensing
+
+The <Link path="/guides/license">license generator</Link> configures automated license header management and dependency license checking against an allowlist of approved licenses, helping you catch problematic transitive dependencies before they ship.
+
+## Responsibility
+
+Security and compliance is a shared responsibility. AWS describes this through the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/), which distinguishes between security *of* the cloud (the responsibility of AWS) and security *in* the cloud (your responsibility as the customer).
+
+The Nx Plugin for AWS helps you address parts of your side of that model. Its generators vend secure foundations and encode AWS best practices within the scope of the code they produce — the controls described above. This reduces the effort required to build securely, but it does not transfer ownership of security to the plugin.
+
+**You own the code that is generated into your workspace and remain responsible for its security.** Once vended, generated code is yours to modify, extend, and operate, and it must be treated the same as any other code you author.
+
+In particular:
+
+- **The scope of the plugin is limited to its generators.** The plugin has no knowledge of your application's business logic, data classification, threat model, or regulatory obligations, and cannot make decisions that depend on them.
+- **Authentication is configured, but authorization is not.** APIs are protected with authentication by default (for example IAM/SigV4), but the plugin cannot determine *which* authenticated principals should be permitted to perform *which* operations on *which* resources. Fine-grained authorization depends on your business logic and must be designed, implemented, and tested by you.
+- **Generated code is a starting point, not a finished product.** As you add functionality, you introduce security considerations the plugin cannot anticipate — input validation, data handling, secrets management, dependency choices, and integrations with other systems.
+
+Accordingly, you should review generated code and the applications you build on top of it in line with your own organisation's security policies, standards, and review processes, and subject them to the same threat modelling, security testing, and approval gates you apply to any production workload. The controls vended by the plugin are intended to complement those processes, not to replace them.

package/docs/guides/smithy-project.mdx

@@ -0,0 +1,167 @@
+---
+title: Smithy Projects
+description: Reference documentation for the Smithy project generator
+generator: smithy#project
+---
+import { FileTree, Steps } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+[Smithy](https://smithy.io/) is an interface definition language for describing services and the data they exchange. The Smithy project generator creates a project containing a Smithy model.
+
+There are two kinds of Smithy project:
+
+- **Service** (`--type=service`) — a model which defines a service and its operations. This is what the <Link path="guides/ts-smithy-api">`ts#api --framework=smithy` generator</Link> creates for you alongside a TypeScript implementation.
+- **Shape library** (`--type=shapes`) — a model which defines reusable shapes but no service. Connect a shape library to your Smithy projects to share shapes between them, rather than duplicating the definitions in each.
+
+:::tip
+If you want an API with an implementation, use the <Link path="guides/ts-smithy-api">`ts#api` generator</Link> instead. It creates a Smithy model project _and_ a TypeScript server which implements it.
+:::
+
+## Usage
+
+### Generate a Smithy Project
+
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes' }} />
+
+### Options
+
+<GeneratorParameters generator="smithy#project" />
+
+## Generator Output
+
+<OptionFilter when={{ type: 'shapes' }} description="Shape library: a model with no service">
+
+### Shape Library
+
+<FileTree>
+
+  - my-shapes
+    - src
+      - main.smithy Your shared shape definitions
+    - smithy-build.json Smithy build configuration
+    - project.json Project configuration and build targets
+
+</FileTree>
+
+A shape library defines shapes and nothing else:
+
+```smithy
+$version: "2.0"
+
+namespace com.example
+
+structure Customer {
+    @required
+    id: String
+
+    name: String
+    email: String
+}
+```
+
+Since a shape library has no service, its `smithy-build.json` configures no code generation — building it validates the model and assembles it into a single JSON model file at `dist/<my-shapes>/build/model.json`.
+
+</OptionFilter>
+
+<OptionFilter when={{ type: 'service' }} description="Service: a model which defines a service and its operations">
+
+### Service
+
+<FileTree>
+
+  - my-service
+    - src
+      - main.smithy Your service definition
+      - operations
+        - echo.smithy An example operation
+    - smithy-build.json Smithy build configuration, including code generation
+    - ssdk.rolldown.config.mjs Bundles the generated TypeScript Server SDK
+    - project.json Project configuration and build targets
+
+</FileTree>
+
+A service model defines a service shape and the operations it exposes:
+
+```smithy
+$version: "2.0"
+
+namespace com.example
+
+use aws.protocols#restJson1
+
+@title("MyService")
+@restJson1
+service MyService {
+    version: "1.0.0"
+    operations: [
+        Echo
+    ]
+}
+```
+
+Building a service project generates an OpenAPI specification and a TypeScript Server SDK into `dist/<my-service>/build/`.
+
+</OptionFilter>
+
+## Building
+
+Smithy projects build with the [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/index.html), which validates your model:
+
+<NxCommands commands={['build my-shapes']} />
+
+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. On Windows it is a prerequisite you install yourself — see <Link path="guides/ts-smithy-api#building-on-windows">Building on Windows</Link>.
+
+## Depending on a Shape Library
+
+Building a shape library writes an assembled model to `dist/<my-shapes>/build/model.json`. This single file contains every shape the library defines, along with any it depends on, so a consumer only ever declares the libraries it references directly.
+
+To depend on a shape library from another Smithy project, make two changes to the consuming project:
+
+<Steps>
+
+1. Add the library's built model to `imports` in the consuming project's `smithy-build.json`. Paths are relative to that file, so the number of `../` segments matches how deeply the consuming project is nested — three for `packages/my-api/model` below:
+
+   ```json ins={4}
+   {
+     "version": "1.0",
+     "sources": ["src/"],
+     "imports": ["../../../dist/packages/my-shapes/build/model.json"],
+     ...
+   }
+   ```
+
+2. Add the library's `build` target as a dependency of the consuming project's `compile` target in its `project.json`, so the model exists before the consumer builds:
+
+   ```json ins={4}
+   {
+     "targets": {
+       "compile": {
+         "dependsOn": ["@my-scope/my-shapes:build"],
+         ...
+       }
+     }
+   }
+   ```
+
+</Steps>
+
+Your model can now reference the library's shapes with `use`:
+
+```smithy
+$version: "2.0"
+
+namespace com.example.api
+
+use com.example.shared#Customer
+
+structure GetCustomerOutput {
+    @required
+    customer: Customer
+}
+```
+
+Shape libraries can depend on other shape libraries the same way. Since each library's built model already contains its own dependencies, you only need to repeat these steps for the libraries you reference directly. A library reached by more than one path is resolved once — Smithy ignores duplicate but equivalent shape definitions.

package/docs/guides/terraform-project.mdx

@@ -84,7 +84,7 @@ Application projects include full deployment capabilities with remote state mana
 
 You can start writing your Terraform infrastructure inside `src/main.tf`, for example:
 
-```diff title="src/main.tf" {2-4}
+```diff title="src/main.tf" {16-19}
 -locals {
 -  account_id = data.aws_caller_identity.current.account_id
 -  aws_region = data.aws_region.current.id
@@ -108,7 +108,7 @@ You can start writing your Terraform infrastructure inside `src/main.tf`, for ex
 
 ### Cross project dependencies
 
-If you wanted to execute a module from a seperate project (lib), you could do so as follows:
+If you wanted to execute a module from a separate project (lib), you could do so as follows:
 
 ```
 module "lib_module" {