docs: add v3 upgrade troubleshooting and index guide links

docs/guides/v3-upgrade-guide.md

@@ -244,3 +244,81 @@ data "helm_template" "example" {
 **What Changed?**
 
 - `set`, `set_list`, and `set_sensitive` is now a list of nested objects using `[ { ... } ]`.
+
+## Troubleshooting
+
+### Error: Blocks of type "kubernetes" are not expected here
+
+After upgrading to v3.0.0 you may see an error similar to:
+
+```text
+Error: Unsupported block type
+
+  on main.tf line 2, in provider "helm":
+   2:   kubernetes {
+
+Blocks of type "kubernetes" are not expected here. Did you mean to define
+argument "kubernetes"? If so, use the equals sign to assign it a value.
+```
+
+This happens because v3.0.0 migrated the provider from the [Terraform Plugin SDKv2](https://github.com/hashicorp/terraform-plugin-sdk) to the [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework). Configuration that previously used **blocks** (no equals sign) must now be written as **nested attributes** (with an equals sign). The same applies to `registry` (now `registries`), `experiments`, and the `set`, `set_list`, and `set_sensitive` arguments in `helm_release` and `helm_template`.
+
+Update your configuration as follows:
+
+| v2 (block syntax)              | v3 (attribute syntax)          |
+| ------------------------------ | ------------------------------ |
+| `kubernetes { ... }`           | `kubernetes = { ... }`         |
+| `registry { ... }` (repeatable) | `registries = [ { ... } ]`    |
+| `experiments { ... }`          | `experiments = { ... }`        |
+| `set { ... }`                  | `set = [ { ... } ]`            |
+| `set_list { ... }`             | `set_list = [ { ... } ]`       |
+| `set_sensitive { ... }`        | `set_sensitive = [ { ... } ]`  |
+
+See [Changes to Provider Attributes](#changes-to-provider-attributes) above for complete before/after examples.
+
+If you are not ready to migrate, you can pin the provider to the latest v2 release until your configuration has been updated:
+
+```hcl
+terraform {
+  required_providers {
+    helm = {
+      source  = "hashicorp/helm"
+      version = "~> 2.17"
+    }
+  }
+}
+```
+
+### Error: could not login to OCI registry (The specified item already exists in the keychain)
+
+On macOS you may encounter an error similar to:
+
+```text
+Error: could not login to OCI registry "registry.example.com": error storing
+credentials - err: exit status 1, out: `The specified item already exists in
+the keychain.`
+```
+
+This is caused by an interaction between Helm's OCI registry login and the macOS `docker-credential-osxkeychain` credential helper, which fails when a stale or conflicting entry already exists in the login keychain.
+
+The recommended workaround is to configure the registry credentials directly in the provider block using the `registries` attribute, so Helm authenticates with the supplied username and password:
+
+```hcl
+provider "helm" {
+  registries = [
+    {
+      url      = "oci://registry.example.com"
+      username = "username"
+      password = "password"
+    }
+  ]
+}
+```
+
+If the error persists, remove the stale keychain entry (replace the server with your registry host) and re-run Terraform:
+
+```sh
+security delete-internet-password -s registry.example.com
+```
+
+Alternatively, remove the `credsStore` or `credHelpers` entry for the registry from your Docker configuration (`~/.docker/config.json`) so credentials are not written to the macOS keychain.

docs/index.md

@@ -19,6 +19,11 @@ Try the [hands-on tutorial](https://learn.hashicorp.com/tutorials/terraform/helm
 
 * [Data Source: helm_template](d/template.html)
 
+## Upgrade Guides
+
+* [Upgrading to v3.0.0 of the Helm provider](guides/v3-upgrade-guide.md) — migrating to the Terraform Plugin Framework, including troubleshooting for the `Blocks of type "kubernetes" are not expected here` error.
+* [Upgrading to v2.0.0 of the Helm provider](guides/v2-upgrade-guide.md)
+
 ## Example Usage
 
 ```terraform