Document how to use components with local packages

content/docs/iac/guides/building-extending/components/build-a-component.md

@@ -41,6 +41,10 @@ Pulumi Components are implemented as custom classes in any Pulumi-supported lang
 
 Pulumi Components inherently support multi-language use. Regardless of the language a component was written in, it is a fast one-step process to generate a SDK, allowing you to use it in all Pulumi-supported languages.
 
+{{< notes type="warning" >}}
+If your component uses a local package (such as any Terraform provider via `terraform-provider`, or another component that contains a local package), you must commit the generated SDK code to version control. See [Using components with local packages](/docs/iac/guides/building-extending/packages/local-packages/#components-with-local-packages) for details.
+{{< /notes >}}
+
 ## Structure of a Component
 
 A Pulumi Component consists of three main parts:

content/docs/iac/guides/building-extending/packages/local-packages.md

@@ -66,10 +66,10 @@ This clones the repo and executes the source, enabling you to use packages from
 #### Using `terraform-provider`
 
 ```bash
-pulumi package add terraform-provider hashicorp/random
+pulumi package add terraform-provider hashicorp/random 3.5.1
 ```
 
-Refer to the [Terraform Provider documentation](/docs/iac/using-pulumi/pulumi-packages/terraform-provider/) for more details.
+Refer to the [Any Terraform Provider documentation](/docs/iac/using-pulumi/pulumi-packages/terraform-provider/) for more details.
 
 ## Using generated SDKs
 
@@ -206,11 +206,42 @@ When working with local packages, it's important to understand how breaking chan
   To ensure stability, you should specify the version of both:
 
   ```bash
-  pulumi package add terraform-provider hashicorp/random --version=3.5.1
+  pulumi package add terraform-provider hashicorp/random 3.5.1
   ```
 
   This pins the Terraform provider version, protecting you from unexpected breaking changes when the underlying provider is updated.
 
+## Using components with local packages {#components-with-local-packages}
+
+When creating a component that contains a local package, you must ensure the generated SDK is available to consumers of your component. This applies when your component uses:
+
+- Any Terraform provider via [`terraform-provider`](/registry/packages/terraform-provider/)
+- Another component that itself contains a local package
+- Any other Pulumi plugin that generates code in the `sdk` folder
+
+### Requirements
+
+1. You must be using Pulumi 3.200.0 or later.
+1. In your component code, run `pulumi package add` to generate the upstream SDK.
+1. Ensure the generated code in the `sdk` folder is committed to version control.
+
+### Why this is necessary
+
+When someone consumes your component, they need access to all the SDKs your component depends on. For published packages from the Pulumi Registry, these dependencies are automatically resolved. However, for local packages generated within your component, the generated SDK code must be available in your repository so that consumers can use it.
+
+### Example workflow
+
+If you're building a component that uses a Terraform provider:
+
+```bash
+cd my-component
+pulumi package add terraform-provider hashicorp/random 3.5.1
+git add sdk/
+git commit -m "Add generated SDK for terraform-provider random"
+```
+
+Consumers of your component will then be able to use it without needing to regenerate the SDK themselves.
+
 ## See also
 
 For more information about developing and publishing your own packages, see the [Publishing Packages](/docs/iac/build-with-pulumi/publishing-packages/) guide.