Clarify package installation and move packages page to concepts (#16702)

Moved the packages concepts page from guides to concepts directory to match its nav location. Updated package consumption documentation to emphasize pulumi install as the recommended approach for installing all dependencies, including both standard package manager dependencies and local packages. Added best practices to Terraform provider and module docs.

Fixes #16699

Update package installation guidance to recommend pulumi install

Rewrote the consuming packages section to emphasize pulumi install as the recommended approach for installing dependencies. Added clear guidance on when to use standard package managers versus pulumi package add, and updated related docs to mention pulumi install in best practices.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: jkodroff

content/docs/iac/guides/building-extending/packages/packages.md renamed to content/docs/iac/concepts/packages/packages.md

@@ -17,6 +17,7 @@ aliases:
 - /docs/iac/using-pulumi/pulumi-packages/
 - /docs/iac/concepts/packages/
 - /docs/iac/guides/building-extending/packages/
+- /docs/iac/guides/building-extending/packages/packages/
 ---
 
 Pulumi Packages are the core technology that enables Pulumi [resources](/docs/iac/concepts/resources/), [components](/docs/iac/concepts/components/), and [functions](/docs/iac/concepts/functions/) to be defined once and used in all Pulumi languages.
@@ -30,10 +31,34 @@ Pulumi packages consist of two parts that allow them to be consumed in any Pulum
 
 ## Consuming packages
 
-How you consume a Pulumi package depends on whether it has published SDKs:
+There are two ways to add Pulumi packages to your program:
 
-- For packages with published SDKs, you can consume the package by adding a reference to the published SDK from the package feed, e.g. `npm install`, `dotnet package add`, etc. The published SDKs contain commands to automatically download the provider code/binary.
-- For packages without published SDKs, called [local packages](/docs/iac/guides/building-extending/packages/local-packages/#updating-local-packages), you can consume a package via the [`pulumi package add`](/docs/iac/cli/commands/pulumi_package_add/) command, which will download the provider plugin and generate a local SDK. Generated local SDKs may be committed to version control, or they can be regenerated at any time with the [`pulumi install`](/docs/iac/cli/commands/pulumi_install/) command.
+- **Packages with published SDKs**: Use your language's standard package manager. Most packages in the [Pulumi Registry](/registry/) have published SDKs. Each package's Installation & Configuration page shows the specific command for your language ([example](/registry/packages/aws/installation-configuration/)).
+- **Local packages**: Use [`pulumi package add`](/docs/iac/cli/commands/pulumi_package_add/), which generates an SDK locally and adds a reference to `Pulumi.yaml`. This is used for components, Terraform providers, and other packages without published SDKs.
+
+### Installing packages
+
+To install all dependencies, use [`pulumi install`](/docs/iac/cli/commands/pulumi_install/). This is the recommended approach because it handles both standard package manager dependencies (from `package.json`, `requirements.txt`, etc.) and any local packages defined in `Pulumi.yaml` in a single command.
+
+Run `pulumi install` when:
+
+- Setting up a project after cloning from source control
+- Adding or updating packages
+- Ensuring all team members have the same dependencies
+
+### Adding local packages
+
+For packages without published SDKs, called [local packages](/docs/iac/guides/building-extending/packages/local-packages/), use the [`pulumi package add`](/docs/iac/cli/commands/pulumi_package_add/) command. This downloads the provider plugin, generates a local SDK in your language, and adds the package to your `Pulumi.yaml`:
+
+```bash
+# Example: Add a Terraform provider
+pulumi package add terraform-provider hashicorp/random
+
+# Example: Add a component from a git repository
+pulumi package add example.com/org/repo.git/path@version
+```
+
+After adding a local package, run `pulumi install` to complete the installation.
 
 Some common use cases for local packages include:
 
@@ -45,7 +70,7 @@ In order to consume a Pulumi package, there may be additional runtime requiremen
 
 - TypeScript packages require the NodeJS runtime.
 - Python packages require a Python interpreter.
-- Go packages do not require a runtime if they are compiled. If they are referenced via source (e.g. a Pulumi component published via Pulumi IDP), they require a compatible version the Go language to be installed.
+- Go packages do not require a runtime if they are compiled. If they are referenced via source (e.g. a Pulumi component published via Pulumi IDP), they require a compatible version of the Go language to be installed.
 - .NET packages do not require a runtime if they are compiled as runtime-included binaries, which is Pulumi's recommended approach. .NET packages compiled as runtime-dependent binaries require a runtime.
 - Java packages require a JVM runtime.
 - YAML packages do not have any specific runtime requirements.

content/docs/iac/get-started/terraform/terraform-modules.md

@@ -921,6 +921,7 @@ output "website_url" {
 4. **Monitor module updates**: Keep track of module updates and breaking changes
 5. **Use reputable sources**: Prefer well-maintained modules from trusted sources
 6. **Document module usage**: Document why you chose specific modules and their configuration
+7. **Use `pulumi install` for setup**: When cloning a project that uses Terraform modules, run [`pulumi install`](/docs/iac/cli/commands/pulumi_install/) to install all dependencies, including local packages defined in `Pulumi.yaml`
 
 ## Clean up
 

content/docs/iac/get-started/terraform/terraform-providers.md

@@ -404,5 +404,6 @@ output "availability_zones" {
 1. **Use native providers when available**: Prefer native Pulumi providers over Terraform providers for better performance and type safety
 2. **Document provider usage**: Document which Terraform providers your team uses and why
 3. **Monitor provider updates**: Keep track of provider updates and breaking changes
+4. **Use `pulumi install` for setup**: When cloning a project that uses Terraform providers, run [`pulumi install`](/docs/iac/cli/commands/pulumi_install/) to install all dependencies, including local packages defined in `Pulumi.yaml`
 
 {{< get-started-stepper >}}

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

@@ -173,7 +173,7 @@ pulumi package add <provider|schema|path> [provider-parameter...] [flags]
 
 For packages from Git repositories, specify a version tag or commit hash to control which version is used.
 
-After regenerating the SDK, ensure you reinstall or relink the SDK in your project using your language's package manager (e.g., `npm add`, `pip install -e`, etc.).
+After regenerating the SDK, run [`pulumi install`](/docs/iac/cli/commands/pulumi_install/) to install all dependencies, including the updated local package.
 
 ## Versioning considerations