Document IDP usage tracking and in-process vs. remote components

content/docs/iac/concepts/components/_index.md

@@ -899,6 +899,18 @@ pulumi package add /path/to/local/secure-s3-component
 
 Pulumi will identify the folder as a Pulumi component project, generate a local SDK, and make it available for import in your program—even if your consumer program is in a different language.
 
+#### In-process vs. remote components {#in-process-vs-remote-components}
+
+{{< notes type="info" >}}
+**How you consume a component affects how it runs — and whether it's tracked in Pulumi Cloud.**
+
+- **Remote component** (`pulumi package add`): Pulumi launches a separate plugin process and communicates with it via gRPC. This creates a `pulumi:providers:<package-name>` resource in your stack state. Remote components are tracked on the [IDP Private Registry](/docs/idp/concepts/private-registry/) "Used by" page.
+
+- **In-process component** (direct import via `npm install`, local symlink, or language package manager): The component runs in the same language runtime as your program. No separate provider resource is created, and the stack **will not** appear on the registry's "Used by" page.
+
+If IDP usage visibility matters for your organization, consume published components via `pulumi package add`.
+{{< /notes >}}
+
 ## The Spectrum of Pulumi Components You Can Build
 
 You can use Pulumi Components with more flexibility and control depending on your use case. This table shows the variety of use cases:

content/docs/idp/concepts/private-registry.md

@@ -42,6 +42,20 @@ Both package list views display usage columns for each package: how many stacks
 
 Each package page also includes a "Used by" tab showing which stacks use that package, including the stack name, project, version in use, and last update timestamp. This helps you assess the impact of changes before updating versions and identify stacks that may need upgrading.
 
+#### How usage tracking works
+
+Pulumi Cloud determines package usage by inspecting the resources in each stack's state. Specifically, it looks for `pulumi:providers:<package-name>` resources — these are the provider resources that Pulumi creates when a component runs as a [remote component](/docs/iac/concepts/components/#consumption).
+
+These provider resources are created automatically when a component is consumed via `pulumi package add` (or through a generated SDK with the component configured as a remote plugin). When Pulumi launches a remote component, it starts a separate plugin process and creates a corresponding provider resource in the stack state.
+
+{{% notes type="warning" %}}
+If you consume a component via a direct language-level dependency — for example, using `npm install`, `npm link`, a local file path symlink, or importing the component class directly into your program — the component runs **in-process** in the same language runtime. No separate provider resource is created, and the stack **will not** appear on the package's "Used by" page.
+
+If a stack uses a registry component but doesn't appear in "Used by", verify that the component is consumed via `pulumi package add` rather than a direct dependency, then re-run `pulumi up` so the provider resource is recorded in the stack state.
+{{% /notes %}}
+
+For more details on the difference between in-process and remote component consumption, see [In-process vs. remote components](/docs/iac/concepts/components/#in-process-vs-remote-components).
+
 ## Component Publishing
 
 [Pulumi Components](/docs/iac/concepts/resources/components/) are a way to encapsulate resources in a reusable manner. Components are also a powerful way for platform teams to integrate security, compliance, and operational requirements into golden paths so that developers don't need to worry about it. Once a component is pushed to GitHub or GitLab, it is published to an organization's private registry using the `publish` CLI command. Pulumi automatically introspects the component schema and generates API docs, which are displayed in the registry.