Document provider layering, with impl guides (#16630)

* Document provider layering, with impl guides

Today we do not really explain the layering of our various means of
writing providers, which as we've seen, can lead to confusion.

This does a pass over the provider authoring docs, explaining the
architecture, and why only Go has a higher level SDK.

It also adds reference material and implementation guides for those who
want to code to the direct gRPC/Protobuf interfaces directly, in Python,
Go, or TypeScript. (These were tested locally.)

I am not 100% convinced we should add this but for power users wanting
to really understand how providers work and how to author them, it would
seem helpful in demystifying some confusing aspects of our ecosystem.

* Address code review feedback

* Minor fix found when testing

Author: joeduffy

content/docs/iac/guides/building-extending/providers/build-a-provider.md

@@ -6,7 +6,7 @@ h1: Build a Provider
 meta_image: /images/docs/meta-images/docs-meta.png
 menu:
     iac:
-        name: Build a Provider
+        name: Build a provider
         parent: iac-guides-providers
         weight: 30
 aliases:
@@ -15,6 +15,10 @@ aliases:
 - /docs/iac/build-with-pulumi/build-a-provider/
 ---
 
+{{% notes type="info" %}}
+This guide uses the [Pulumi Go Provider SDK](/docs/iac/guides/building-extending/providers/sdks/pulumi-go-provider-sdk/) (Layer 3 in the [provider architecture](/docs/iac/guides/building-extending/providers/provider-architecture/)). If you prefer to implement providers directly using gRPC bindings for full control, or need to use a language other than Go, see [Direct provider implementation](/docs/iac/guides/building-extending/providers/implementers/).
+{{% /notes %}}
+
 ## When to use a provider
 
 A Pulumi Provider allows you to define new resource types, enabling integration with virtually any service or tool. Pulumi providers are ideal when you need to manage resources that are not yet supported by existing Pulumi providers or when you require custom behavior for managing external systems or APIs. Providers are a powerful extension point, but before building a full provider consider if your use case can be covered by [building a component](/docs/iac/using-pulumi/extending-pulumi/build-a-component/) or using [dynamic provider functions](/docs/iac/concepts/resources/dynamic-providers/).
@@ -59,9 +63,11 @@ Historically it was necessary to hand-author and maintain the `schema.json` file
 
 {{% /notes %}}
 
-## Language support and the Pulumi Provider SDK
+## Language support and the Pulumi Go Provider SDK
+
+Pulumi providers can be written in any language that supports gRPC, and used in any Pulumi program regardless of that program's language. The provider [architecture](/docs/iac/guides/building-extending/providers/provider-architecture/) has multiple layers. Layer 3 is the [Pulumi Go Provider SDK](/docs/iac/guides/building-extending/providers/sdks/pulumi-go-provider-sdk/)—the most streamlined approach for Go. Layer 2 lets you implement the gRPC interface directly in [Python](/docs/iac/guides/building-extending/providers/implementers/python/), Go, TypeScript, or any language with gRPC support.
 
-Pulumi providers can be written in Go, TypeScript, .NET, and Java, and used in any Pulumi program, in any supported language. The [Pulumi Provider SDK](/docs/iac/using-pulumi/extending-pulumi/pulumi-provider-sdk/) is a framework for building providers in Go. We strongly recommend using the SDK, as it is the most full-featured and streamlined way to create a new provider.
+We recommend using the Pulumi Go Provider SDK for Go providers, as it handles protocol complexity and generates schemas automatically. For other languages, or when you need full control over your schema and data structure mappings, use the [direct implementation](/docs/iac/guides/building-extending/providers/implementers/) approach.
 
 Some advantages of using the Pulumi Provider SDK:
 

content/docs/iac/guides/building-extending/providers/implementers/_index.md

@@ -0,0 +1,45 @@
+---
+title_tag: "Direct provider implementation"
+meta_desc: "Implement Pulumi providers directly using gRPC bindings, without higher-level SDKs."
+title: Direct provider implementation
+h1: Direct provider implementation
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+    iac:
+        name: Direct implementation
+        identifier: iac-guides-provider-implementers
+        parent: iac-guides-providers
+        weight: 50
+---
+
+This section covers implementing Pulumi providers directly using the generated gRPC bindings—Layer 2 in the [provider architecture](/docs/iac/guides/building-extending/providers/provider-architecture/).
+
+## When to use direct implementation
+
+Direct implementation gives you full control over provider behavior without SDK opinions. Choose this approach when your language lacks a higher-level SDK (such as Python or TypeScript), when you need precise control over Check/Diff/Update behavior, when you're building something unusual that doesn't fit standard patterns, or when you want to understand exactly how providers work at the protocol level.
+
+## What you'll need
+
+You'll need gRPC bindings for your language (generated from `provider.proto`), a hand-written schema defining your resources and their properties, and implementations of the provider interface methods.
+
+## Trade-offs
+
+| Aspect | Direct implementation | Higher-level SDK |
+|--------|----------------------|------------------|
+| Control | Full | Framework-guided |
+| Boilerplate | More | Less |
+| Schema | Hand-written JSON | Inferred from code |
+| Learning curve | Protocol knowledge | SDK patterns |
+
+## Guides
+
+- [Protocol reference](/docs/iac/guides/building-extending/providers/implementers/protocol-reference/) - Complete gRPC method documentation
+- [Python](/docs/iac/guides/building-extending/providers/implementers/python/) - Implement a provider in Python
+- [Go](/docs/iac/guides/building-extending/providers/implementers/go/) - Implement a provider in Go without the SDK
+- [TypeScript](/docs/iac/guides/building-extending/providers/implementers/typescript/) - Implement a provider in TypeScript
+
+## Related resources
+
+- [Provider architecture](/docs/iac/guides/building-extending/providers/provider-architecture/) - Understanding the layers
+- [Schema reference](/docs/iac/guides/building-extending/packages/schema/) - Complete schema documentation
+- [Pulumi Go Provider SDK](/docs/iac/guides/building-extending/providers/sdks/pulumi-go-provider-sdk/) - Higher-level Go SDK