Update workspace FAQ and policy values concepts with control/policy creation information

docs/concepts/controls/index.md

@@ -17,6 +17,15 @@ Resource State + Policy Setting = Control State
 
 As a concrete example: A cloud storage resource does not have encryption at rest configured. In Guardrails, the encryption at rest policy asserts that storage should be encrypted at rest. The encryption at rest control evaluates resource state against the policy then acts. In this case, the control will go into an `alarm` state. If the policy is set to check mode then the control will only go into `alarm`. If in enforce mode, the control will go into `alarm` and Guardrails will act to remediate the resource. When the remediation is successful, the control will rerun then go into `ok`.
 
+## Control Creation
+
+Control creation is controlled by the `Turbot > Materialization` policy, which supports two modes:
+
+- **Always**: Controls are created for all resources regardless of whether policy settings exist. This provides comprehensive coverage but may impact performance in large environments.
+- **Automatic**: Controls are only created when you explicitly set a policy setting for the primary policy that drives that control somewhere in the resource hierarchy. For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have a policy setting for the `AWS > S3 > Bucket > Approved` policy type. However, if you only create policy settings for its sub-policies, like `AWS > S3 > Bucket > Approved > Regions`, the control will **not** be created.
+
+Note that some controls, such as those used to discover resources and configure accounts (like `AWS > EC2 > Instance > Discovery` and `AWS > Turbot > Event Handlers`), are always created regardless of the materialization mode.
+
 ## Control Types
 
 A **Control Type** is a definition for a particular control. Each different control type is a blueprint that can be configured for resources, such the **Approved** control type for AWS S3 buckets. In this case, the control `AWS > S3 > Bucket > Approved` evaluates policy settings to determine what it means for an S3 bucket to be "Approved," and will take the action defined in the associated, identically named policy (`AWS > S3 > Bucket > Approved`).

docs/concepts/policies/values-settings.md

@@ -5,17 +5,17 @@ sidebar_label: Values & Settings
 
 # Policy Values & Settings
 
-### Policy Settings
+## Policy Settings
 
 Each policy type may have many settings for different resources.
 
-<div className="example">  The policy type <code>AWS > S3 > Bucket > Approved</code> may be set to `Enforce: Delete unapproved if new & empty` for development accounts, but deliberately limited to `Check: Approved` for production accounts.
+<div className="example">  The policy type <code>AWS > S3 > Bucket > Approved</code> may be set to <code>Enforce: Delete unapproved if new & empty</code> for development accounts, but deliberately limited to <code>Check: Approved</code> for production accounts.
 </div>
 
 **Policy Settings** are inherited down through the hierarchy of resources.
 
 <div className="example"> <code>AWS > S3 > Bucket > Approved</code> may be set
-to `Enforce: Delete unapproved if new & empty` at Turbot level - ensuring all buckets are deleted if they don't meet the approval criteria (e.g. in approved region).
+to <code>Enforce: Delete unapproved if new & empty</code> at Turbot level - ensuring all buckets are deleted if they don't meet the approval criteria (e.g. in approved region).
 </div>
 
 Policy settings are only valid for target resources and their ancestors.
@@ -25,10 +25,10 @@ Policy settings are only valid for target resources and their ancestors.
 down to the specific S3 Bucket such as <code>Turbot > Folder A > AWS 1111 > us-east-1 > my-bucket</code>.
 </div>
 
-### Policy Values
+## Policy Values
 
 A **Policy Value** is the effective policy setting on an instance of a resource
-type. Every resource that is targeted by a given policy setting will have its
+type. A resource that is targeted by a given policy setting will have its
 own value for that policy, which will be the resultant calculated policy for the
 "winning" policy in the hierarchy.
 
@@ -40,11 +40,18 @@ inherited by all resources below.
 While policy settings can exist above the target in the resource hierarchy,
 policy values exist only on the target.
 
+Policy value creation is controlled by the `Turbot > Materialization` policy, which supports two modes:
+
+- **Always**: Policy values are created for all resources regardless of whether policy settings exist. This provides comprehensive coverage but may impact performance in large environments.
+- **Automatic**: Policy values are only created when you explicitly set a policy setting somewhere in the resource hierarchy. For example, if no policy setting exists for `AWS > S3 > Bucket > Approved` at the AWS account level, then S3 buckets in that account will not have policy values for `AWS > S3 > Bucket > Approved` or its sub-policies.
+
+Note that some policy types, such as those related to CMDB and event handler configuration, always create values when resources are discovered, regardless of the materialization mode.
+
 <div className="example">
   <strong>AWS > S3 > Bucket > Approved</strong>
   <ul>
     <li> A <strong>Policy Setting</strong> for <code>AWS > S3 > Bucket > Approved</code> can be made on an AWS Account, Region, or individual bucket.</li>
-    <li> <strong>Every</strong> S3 bucket has a <strong>Policy Value</strong> for <code>AWS > S3 > Bucket > Approved</code>. The policy value may have been set at the AWS account, region, and/or individual bucket - this is the effective value for this instance.</li>
+    <li> <strong>Every</strong> S3 bucket that has a <strong>Policy Setting</strong> for <code>AWS > S3 > Bucket > Approved</code> will have a corresponding <strong>Policy Value</strong> for <code>AWS > S3 > Bucket > Approved</code>. The policy value represents the effective setting for this instance, which may have been inherited from the AWS account, region, or set directly on the individual bucket.</li>
   </ul>
 </div>
 

docs/faq/workspace-faq/index.md

@@ -12,23 +12,51 @@ sidebar_label: "Workspace FAQ"
 * [When do Guardrails API keys expire?](#when-do-guardrails-api-keys-expire)
 * [Is it possible to get an event stream out of Guardrails?](#is-it-possible-to-get-an-event-stream-out-of-guardrails)
 * [Can I make mods available for only part of the workspace?](#can-i-make-mods-available-for-only-part-of-the-workspace)
+* [Why don't I see all controls for my resources?](#why-dont-i-see-all-controls-for-my-resources)
+* [Why do some policy types have no values?](#why-do-some-policy-types-have-no-values)
 
 ---
 
 ## Can I rotate the keys embedded in Guardrails' event handlers?
+
 Sure!  Regular key rotation is a part of any strong security stance. Configuration and troubleshooting instructions can be found on the [key rotation](workspace-faq/key_rotation) page.
 
 ## The Guardrails console session expires at 12 hours.  Can it be shorter?
 
 The Guardrails console session timeout period can be adjusted with the [Turbot > Workspace > Console Session Timeout](mods/turbot/turbot-iam/policy#turbot--workspace--console-session-timeout) to as little as 15 minutes.  Keep in mind that this is a global change that affects all users in the Guardrails console. Guardrails API keys are not affected by this change.
 
 ## When do Guardrails API keys expire?
+
 By default, Guardrails API keys do not expire.  Guardrails admins can set the [Turbot > IAM > Access Key > Expiration](mods/turbot/turbot-iam/policy#turbot--iam--access-key--expiration) policy to deactivate or delete Guardrails API keys to a range of expiration periods ranging up to 90 days. Ensure that Guardrails console access can be recovered if access keys expire for any break-glass users.  A calculated policy could be written for the `Turbot > IAM > Access Key > Expiration` policy to identify and preserve the API keys for break-glass users but deactivate/destroy keys for other users.
 
 Note that this policy does not affect AWS IAM Access Keys.
 
 ## Is it possible to get an event stream out of Guardrails?
+
 The Guardrails Firehose provides a user configurable event stream of cloud environment change, Guardrails control state, and Guardrails permission assignments.  Full details on how to configure the Firehose can be found in the [Firehose guide](guides/firehose).
 
 ## Can I make mods available for only part of the workspace?
-Installing a Guardrails mod makes the resource types, controls and policies available to the entire workspace.
+
+Installing a Guardrails mod makes the resource types, controls and policies available to the entire workspace.
+
+## Why don't I see all controls for my resources?
+
+> [!NOTE]
+> Control creation based on policy settings is only enabled if the `Turbot > Materialization` policy is set to `Automatic`. If the `Turbot > Materialization` policy is set to `Always` or your workspace doesn't have the `Turbot > Materialization` policy type installed, all controls will appear regardless of policy settings.
+
+Most controls are only created when policy settings exist for the primary policy that drives that control.
+
+For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have a policy setting for the `AWS > S3 > Bucket > Approved` policy type. However, if you only create policy settings for its sub-policies, like `AWS > S3 > Bucket > Approved > Regions`, the control will **not** be created.
+
+Controls used to discover resources and configure accounts, like `AWS > EC2 > Instance > Discovery` and `AWS > Turbot > Event Handlers`, are always created with their related policy values.
+
+## Why do some policy types have no values?
+
+> [!NOTE]
+> Policy value creation based on policy settings is only enabled if the `Turbot > Materialization` policy is set to `Automatic`. If the `Turbot > Materialization` policy is set to `Always` or your workspace doesn't have the `Turbot > Materialization` policy type installed, all policy values will be created regardless of policy settings.
+
+Most policy types only create policy values when you explicitly set a policy setting somewhere in the resource hierarchy. These are typically policies that drive specific controls like `AWS > S3 > Bucket > Approved` or `AWS > EC2 > Instance > Active`.
+
+For example, if you create a policy setting for the `AWS > S3 > Bucket > Approved` policy type at the AWS account level, Guardrails will create policy values for this policy type and all of its sub-policies (like `AWS > S3 > Bucket > Approved > Regions`) for all S3 buckets in that account.
+
+Some policy types, like those related to CMDB and event handler configuration, always have values created when resources are discovered.

docs/getting-started/7-minute-labs/set-policy/index.md

@@ -33,20 +33,21 @@ values in the Turbot Guardrails Console.
 
 ## View a Policy Value
 
-1. In the Turbot Guardrails Console, navigate to the test bucket that you created in the
-   [prerequisite step](set-policy#prerequisites). Our test bucket name is
-   _turbot-bucket-version_, which we can search for at the main Turbot Guardrails screen.
-   Click on the bucket once it is found.
+1. In the Turbot Guardrails Console, search for the test bucket called _turbot-bucket-version_ that you created in the [prerequisite step](set-policy#prerequisites).
    ![](/images/docs/guardrails/search-bucket-step1.png)
+
+2. Click on the bucket once it is found.
    ![](/images/docs/guardrails/search-bucket-step2.png)
+
+3. Next, you'll see the bucket's details.
    ![](/images/docs/guardrails/search-bucket-step3.png)
 
-2. Click the **Policies** tab. It shows both
+4. Click the **Policies** tab. It shows both
    [Policy Settings](concepts/policies/values-settings#policy-settings) and
    [Policy Values](concepts/policies/values-settings#policy-values).
    ![](/images/docs/guardrails/settings-values.png)
 
-3. From the list of Policy Values for this bucket, click on the **Template
+5. From the list of Policy Values for this bucket, click on the **Template
    (Bucket > Tags > Template)** item to bring up the policy value.
    ![](/images/docs/guardrails/default-policy-value.png)