Document reserved tracking tag in caching guide

docs/guides/caching.md

@@ -39,6 +39,7 @@ Like `global` mode, but scopes the cache to only the resources managed by this s
 - Cache population is filtered to objects tagged `nsx-tf/tf-run-id: <context_id>` (in addition to the resource type), instead of fetching every resource of that type in scope.
 - **The provider will write that tracking tag to NSX objects it reads that don't already have it.** Concretely: the first time a cache-integrated resource is read (refreshed) in `config_scope` mode and its NSX object is missing the `nsx-tf/tf-run-id` tag, the provider issues a PATCH to NSX to add it — even for objects that pre-date this Terraform config, or that were created outside Terraform entirely. This is a genuine write side effect of a read operation.
 - That tracking tag is stripped from Terraform state before it reaches your configuration's `tag` attribute, `terraform plan` diffs, or `terraform state show` output — you will not see it there. It **is** visible if you inspect the object directly via the NSX UI or API.
+- **Important**: `nsx-tf/tf-run-id` is a **reserved internal tag scope**. Do **not** manually define `tag` blocks with `scope = "nsx-tf/tf-run-id"` in your HCL configurations. Because the provider always filters this scope out of Terraform state, manually specifying it in HCL will cause Terraform to detect permanent configuration drift (`+ tag`) on subsequent `terraform plan` runs.
 - If `context_id` is left unset, the tag is never added (there is nothing to scope by), and `config_scope` mode behaves like `global` mode functionally, just with the extra (skipped, harmless) bookkeeping overhead of checking for a tag that will never be applied. **Always set `context_id` when using `config_scope`** — otherwise you get no isolation benefit over `global` mode.
 
 Use `config_scope` when several independent Terraform configurations (or teams/pipelines) manage different resources of the same type against the same NSX manager, and you want each configuration's cache to only "see" the resources it manages — at the cost of the tag-write side effect above. Use `global` when a single configuration owns everything of a given type in that scope, or when you cannot accept the tag being written to your objects.
@@ -70,6 +71,8 @@ Both `global` and `config_scope` share one more property: the cache is keyed by
 
 **I don't want any tags written to my NSX objects.** Use `global` mode instead of `config_scope`, or disable caching entirely.
 
+**`terraform plan` persistently shows an in-place change to add an `nsx-tf/tf-run-id` tag.** Check your `.tf` files to ensure you have not explicitly written `tag { scope = "nsx-tf/tf-run-id" ... }` in your resource definitions. The provider automatically manages and strips this tag from state; defining it directly in HCL creates a state-to-configuration mismatch. Remove any explicit `nsx-tf/tf-run-id` tag blocks from your HCL.
+
 **I'm using `config_scope` but don't see any caching benefit.** Check that `context_id` is actually set (via the provider argument or `NSXT_CONTEXT_ID`) — without it, no objects ever match the scoping tag on first population, so most reads still fall through to NSX. Set a stable, unique `context_id` per configuration.
 
 **I'm running multiple aliased `nsxt` provider blocks in one run.** Each aliased provider's `cache_mode` is independent — one alias can use `config_scope` while another uses `global` or `disabled`. If two aliases point at the same NSX manager host with the same `context_id` and resource scope, they can legitimately share cached data for that overlap; this is intentional (it's the same underlying NSX state), not a bug.