docs(secure-policy): cross-reference managed_ruleset from custom/managed_policy

Adds note callouts to secure_custom_policy.md and secure_managed_policy.md
pointing users at secure_managed_ruleset.md for customer-owned policies
that inherit a Sysdig-managed ruleset (isDefault: false, templateId != 0).
Also expands the secure_managed_ruleset.md intro to explain when to use it.

The three policy resources are partitioned by the API's isDefault and
templateId fields, but until now the docs did not make that taxonomy
visible from the two most-discovered resources, leading users to assume
the customer-owned + template-inheriting case was unsupported.

Refs #736

Author: aaronm-sysdig

website/docs/r/secure_custom_policy.md

@@ -10,6 +10,8 @@ description: |-
 
 Creates a Sysdig Secure Custom Policy.
 
+-> **Note:** Use `sysdig_secure_custom_policy` only for policies you author from scratch (where you own the rule list). For a customer-owned policy that inherits a Sysdig-managed ruleset (e.g. created via "Copy Policy" on a Sysdig-managed policy in the UI), use [`sysdig_secure_managed_ruleset`](secure_managed_ruleset.md) instead. For tweaking a Sysdig-shipped default policy in place, use [`sysdig_secure_managed_policy`](secure_managed_policy.md). The three resources are distinguished by the API's `isDefault` and `templateId` fields: `managed_policy` for `isDefault: true`, `custom_policy` for `templateId: 0`, and `managed_ruleset` for `templateId != 0` with `isDefault: false`.
+
 -> **Note:** Sysdig Terraform Provider is under rapid development at this point. If you experience any issue or discrepancy while using it, please make sure you have the latest version. If the issue persists, or you have a Feature Request to support an additional set of resources, please open a [new issue](https://github.com/sysdiglabs/terraform-provider-sysdig/issues/new) in the GitHub repository.
 
 ## Example Usage

website/docs/r/secure_managed_policy.md

@@ -13,6 +13,8 @@ Manages configuration of a Sysdig Secure Managed Policy.
 -> **Note:** Sysdig managed policies are not resources that you create. They are provided by Sysdig. This resource
 allows you to identify and configure a managed policy. The managed policy is looked up by its name and type.
 
+-> **Note:** Use `sysdig_secure_managed_policy` only for Sysdig-shipped default policies (`isDefault: true` in the API). For a customer-owned policy that inherits a Sysdig-managed ruleset (e.g. created via "Copy Policy" on a Sysdig-managed policy in the UI), use [`sysdig_secure_managed_ruleset`](secure_managed_ruleset.md) instead. For fully customer-authored policies, use [`sysdig_secure_custom_policy`](secure_custom_policy.md).
+
 -> **Note:** Sysdig Terraform Provider is under rapid development at this point. If you experience any issue or discrepancy while using it, please make sure you have the latest version. If the issue persists, or you have a Feature Request to support an additional set of resources, please open a [new issue](https://github.com/sysdiglabs/terraform-provider-sysdig/issues/new) in the GitHub repository.
 
 ## Example Usage

website/docs/r/secure_managed_ruleset.md

@@ -8,7 +8,13 @@ description: |-
 
 # Resource: sysdig_secure_managed_ruleset
 
-Creates a Sysdig Secure Managed Ruleset
+Creates a Sysdig Secure Managed Ruleset.
+
+-> **Note:** A "managed ruleset" is the Sysdig term for a customer-owned policy whose rule list is inherited from a Sysdig-provided template (in the API, `isDefault: false` and `templateId != 0`). Use this resource when:
+
+* You want to keep Sysdig's curated rule list but customize scope, notifications, actions, severity, or which rules are enabled.
+* You can disable individual rules via `disabled_rules`, but you cannot add new rules or modify rule definitions. To gain full control over the rule list, use [`sysdig_secure_custom_policy`](secure_custom_policy.md) instead.
+* For tweaking a Sysdig-shipped default policy in place (without making a customer-owned copy), use [`sysdig_secure_managed_policy`](secure_managed_policy.md).
 
 -> **Note:** Sysdig Terraform Provider is under rapid development at this point. If you experience any issue or discrepancy while using it, please make sure you have the latest version. If the issue persists, or you have a Feature Request to support an additional set of resources, please open a [new issue](https://github.com/sysdiglabs/terraform-provider-sysdig/issues/new) in the GitHub repository.