docs: add Terraform reference for action, policy, and policy_attachment

docs.json

@@ -473,15 +473,20 @@
                 "pages": [
                   "terraform-reference/resources/environment",
                   "terraform-reference/resources/logical_environment",
-                  "terraform-reference/resources/custom_attestation_type"
+                  "terraform-reference/resources/custom_attestation_type",
+                  "terraform-reference/resources/action",
+                  "terraform-reference/resources/policy",
+                  "terraform-reference/resources/policy_attachment"
                 ]
               },
               {
                 "group": "Data Sources",
                 "pages": [
                   "terraform-reference/data-sources/environment",
                   "terraform-reference/data-sources/logical_environment",
-                  "terraform-reference/data-sources/custom_attestation_type"
+                  "terraform-reference/data-sources/custom_attestation_type",
+                  "terraform-reference/data-sources/action",
+                  "terraform-reference/data-sources/policy"
                 ]
               }
             ]

terraform-reference/data-sources/action.mdx

@@ -0,0 +1,50 @@
+---
+title: "kosli_action data source"
+description: "Fetches details of an existing Kosli action."
+icon: "database"
+---
+
+Fetches details of an existing Kosli action.
+
+Use this data source to reference existing actions and access metadata such as the environments being monitored and the trigger types configured.
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Query an existing action
+data "kosli_action" "compliance_alerts" {
+  name = "compliance-alerts"
+}
+
+output "action_number" {
+  description = "Server-assigned number of the action"
+  value       = data.kosli_action.compliance_alerts.number
+}
+
+output "action_environments" {
+  description = "Environments monitored by this action"
+  value       = data.kosli_action.compliance_alerts.environments
+}
+```
+
+## Schema
+
+### Required
+
+- `name` (String) The name of the action to query.
+
+### Read-only
+
+- `created_by` (String) User who created the action.
+- `environments` (List of String) List of environment names this action monitors.
+- `last_modified_at` (Number) Unix timestamp (with fractional seconds) of when the action was last modified.
+- `number` (Number) Server-assigned numeric identifier for the action.
+- `triggers` (List of String) List of trigger event types that activate this action.

terraform-reference/data-sources/policy.mdx

@@ -0,0 +1,49 @@
+---
+title: "kosli_policy data source"
+description: "Fetches details of an existing Kosli policy."
+icon: "database"
+---
+
+Fetches details of an existing Kosli policy.
+
+Use this data source to reference existing policies and access metadata such as the policy content, description, and latest version number.
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Query an existing policy
+data "kosli_policy" "production" {
+  name = "prod-requirements"
+}
+
+output "policy_latest_version" {
+  description = "Latest version number of the policy"
+  value       = data.kosli_policy.production.latest_version
+}
+
+output "policy_content" {
+  description = "YAML content of the latest policy version"
+  value       = data.kosli_policy.production.content
+}
+```
+
+## Schema
+
+### Required
+
+- `name` (String) The name of the policy to query.
+
+### Read-only
+
+- `content` (String) YAML content of the latest policy version. Null if the policy has no versions.
+- `created_at` (Number) Unix timestamp of when the policy was first created.
+- `description` (String) Description of the policy.
+- `latest_version` (Number) The version number of the latest policy version. Null if the policy has no versions.

terraform-reference/index.mdx

@@ -4,7 +4,7 @@ description: "Manage Kosli resources as Infrastructure-as-Code using Terraform."
 icon: "layer-group"
 ---
 
-The Kosli provider allows you to manage Kosli resources as Infrastructure-as-Code using Terraform. Use it to define and manage custom attestation types and integrate Kosli into your compliance workflows.
+The Kosli provider allows you to manage Kosli resources as Infrastructure-as-Code using Terraform. Use it to define and manage environments, policies, actions, custom attestation types, and integrate Kosli into your compliance workflows.
 
 <Note>
 The provider is officially registered at the [Terraform Registry](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs).

terraform-reference/resources/action.mdx

@@ -0,0 +1,65 @@
+---
+title: "kosli_action resource"
+description: "Manages a Kosli action. Actions define webhook notifications triggered by environment compliance events."
+icon: "cube"
+---
+
+Manages a Kosli action. Actions define webhook notifications triggered by environment compliance events.
+
+<Note>
+Actions are identified internally by a server-assigned `number`. The `name` is used during import to look up the number.
+</Note>
+
+Use this resource to configure automated notifications when environments change compliance state. Actions send webhooks to external services such as Slack or Microsoft Teams.
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Action that fires on non-compliant environment events
+resource "kosli_action" "compliance_alerts" {
+  name         = "compliance-alerts"
+  environments = ["production-k8s"]
+  triggers     = ["ON_NON_COMPLIANT_ENV", "ON_COMPLIANT_ENV"]
+  webhook_url  = "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX"
+}
+
+# Action that fires on scaling events
+resource "kosli_action" "scaling_alerts" {
+  name         = "scaling-alerts"
+  environments = ["staging-ecs"]
+  triggers     = ["ON_SCALED_ARTIFACT"]
+  webhook_url  = "https://outlook.office.com/webhook/XXXX"
+}
+```
+
+## Import
+
+Actions can be imported using their name:
+
+```shell
+# Import an existing action by name
+terraform import kosli_action.compliance_alerts compliance-alerts
+```
+
+## Schema
+
+### Required
+
+- `environments` (List of String) List of environment names this action monitors.
+- `name` (String) Name of the action. Must be unique within the organization. Changing this will force recreation of the resource.
+- `triggers` (List of String) List of trigger event types that activate this action (e.g. `ON_NON_COMPLIANT_ENV`, `ON_COMPLIANT_ENV`).
+- `webhook_url` (String, Sensitive) Webhook URL to send notifications to.
+
+### Read-only
+
+- `created_by` (String) User who created the action.
+- `last_modified_at` (Number) Unix timestamp of when the action was last modified.
+- `number` (Number) Server-assigned numeric identifier for the action.

terraform-reference/resources/environment.mdx

@@ -7,7 +7,7 @@ icon: "cube"
 Manages a Kosli environment. Environments represent deployment targets where artifacts are deployed. Supports physical environment types: K8S, ECS, S3, docker, server, and lambda.
 
 <Warning>
-This resource manages the environment configuration only. Environment tags are managed through a separate Kosli API. Environment policies will be available in a future release. For querying environment metadata such as `last_modified_at`, `last_reported_at`, and `archived` status, use the [`kosli_environment` data source](/terraform-reference/data-sources/environment).
+This resource manages the environment configuration only. Environment tags are managed through a separate Kosli API. To attach compliance policies, use the [`kosli_policy_attachment` resource](/terraform-reference/resources/policy_attachment). For querying environment metadata such as `last_modified_at`, `last_reported_at`, and `archived` status, use the [`kosli_environment` data source](/terraform-reference/data-sources/environment).
 </Warning>
 
 Kosli environments track deployments and provide visibility into what's running in your infrastructure. Physical environments represent actual runtime locations such as:
@@ -27,9 +27,9 @@ For aggregating multiple physical environments into logical groups, use the [`ko
 Environment tags are managed through a separate Kosli API and are not included in this Terraform resource.
 </Warning>
 
-<Warning>
-Environment policies will be available in a future release as a separate resource (`kosli_environment_policy`).
-</Warning>
+<Note>
+To attach compliance policies to environments, use the [`kosli_policy_attachment` resource](/terraform-reference/resources/policy_attachment).
+</Note>
 
 ## Example usage
 

terraform-reference/resources/policy.mdx

@@ -0,0 +1,80 @@
+---
+title: "kosli_policy resource"
+description: "Manages a Kosli policy. Policies define artifact compliance requirements that can be attached to environments."
+icon: "cube"
+---
+
+Manages a Kosli policy. Policies define artifact compliance requirements (provenance, trail-compliance, attestations) that can be attached to environments.
+
+Policies are versioned and immutable: updating `content` or `description` creates a new version rather than modifying the existing one.
+
+<Warning>
+Deleting this resource removes it from Terraform state only. Kosli has no API endpoint to delete policies, so the policy will remain in Kosli after `terraform destroy`. To attach policies to environments, use the [`kosli_policy_attachment` resource](/terraform-reference/resources/policy_attachment).
+</Warning>
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Minimal policy requiring provenance for all artifacts
+resource "kosli_policy" "minimal" {
+  name = "basic-requirements"
+  content = <<-YAML
+    _schema: https://kosli.com/schemas/policy/environment/v1
+    artifacts:
+      provenance:
+        required: true
+  YAML
+}
+
+# Production policy with full compliance requirements
+resource "kosli_policy" "production" {
+  name        = "prod-requirements"
+  description = "Compliance requirements for production environments"
+  content     = <<-YAML
+    _schema: https://kosli.com/schemas/policy/environment/v1
+    artifacts:
+      provenance:
+        required: true
+      trail-compliance:
+        required: true
+      attestations:
+        - name: unit-test
+          type: junit
+        - name: dependency-scan
+          type: "*"
+  YAML
+}
+```
+
+## Import
+
+Policies can be imported using their name:
+
+```shell
+# Import a policy by name. The content attribute is populated from the API response.
+terraform import kosli_policy.example prod-requirements
+```
+
+## Schema
+
+### Required
+
+- `content` (String) YAML content of the policy, conforming to the Kosli policy schema (`_schema: https://kosli.com/schemas/policy/environment/v1`). Supports heredoc syntax for multi-line YAML. Updating this value creates a new policy version.
+- `name` (String) Name of the policy. Must be unique within the organization. Changing this will force recreation of the resource.
+
+### Optional
+
+- `description` (String) Description of the policy.
+
+### Read-only
+
+- `created_at` (Number) Unix timestamp of when the policy was first created.
+- `latest_version` (Number) The version number of the latest policy version. Null if the policy has no versions.

terraform-reference/resources/policy_attachment.mdx

@@ -0,0 +1,48 @@
+---
+title: "kosli_policy_attachment resource"
+description: "Attaches a Kosli policy to an environment. When this resource is destroyed, the policy is detached from the environment."
+icon: "cube"
+---
+
+Attaches a Kosli policy to an environment (physical or logical). When this resource is destroyed, the policy is detached from the environment.
+
+Both `environment_name` and `policy_name` are immutable: changing either attribute will destroy the existing attachment and create a new one.
+
+<Note>
+Both the policy and environment must exist before creating an attachment. Use the [`kosli_policy` resource](/terraform-reference/resources/policy) and [`kosli_environment` resource](/terraform-reference/resources/environment) to manage them.
+</Note>
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Attach a policy to an environment.
+# Both the policy and environment must exist before creating the attachment.
+resource "kosli_policy_attachment" "example" {
+  environment_name = "my-environment"
+  policy_name      = "my-policy"
+}
+```
+
+## Import
+
+Policy attachments can be imported using the composite ID `environment_name/policy_name`:
+
+```shell
+# Import a policy attachment using the composite ID: environment_name/policy_name
+terraform import kosli_policy_attachment.example my-environment/my-policy
+```
+
+## Schema
+
+### Required
+
+- `environment_name` (String) Name of the environment to attach the policy to. Changing this will force recreation of the resource.
+- `policy_name` (String) Name of the policy to attach. Changing this will force recreation of the resource.