feat: add Terraform provider reference docs under Administration

administration/managing_custom_attestation_types/overview.md

@@ -0,0 +1,99 @@
+---
+title: Managing Custom Attestation Types
+description: Learn how to manage Kosli custom attestation types via Terraform, including creating and importing types with JSON Schema and jq evaluation rules.
+---
+
+The preferred way to manage custom attestation types is via the <Tooltip tip="An official HashiCorp-registered Terraform provider that lets you manage Kosli resources (environments, flows, policies, etc.) as infrastructure as code." cta="View on Terraform Registry" href="https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/">Kosli Terraform provider</Tooltip>, so your Kosli configuration is version-controlled alongside your infrastructure. You can also manage custom attestation types through the Kosli CLI.
+
+<Info>
+This page covers managing custom attestation types via Terraform. For an introduction to custom attestation types and creating them via the CLI, see [Getting started: Attestations](/getting_started/attestations).
+</Info>
+
+Custom attestation types define how Kosli validates evidence from tools that don't have a built-in Kosli attestation command. Each type can include:
+
+- A **JSON Schema** (optional) that defines the expected structure of attestation data
+- **jq rules** (optional) that evaluate the data to determine compliance
+
+At least one of the two must be provided.
+
+## Create a custom attestation type
+
+### With schema and jq rules
+
+```hcl
+resource "kosli_custom_attestation_type" "security_scan" {
+  name        = "security-scan"
+  description = "Validates security scan results"
+
+  schema = jsonencode({
+    type = "object"
+    properties = {
+      critical_vulnerabilities = { type = "integer" }
+      high_vulnerabilities     = { type = "integer" }
+      scan_date                = { type = "string" }
+    }
+    required = ["critical_vulnerabilities", "high_vulnerabilities", "scan_date"]
+  })
+
+  jq_rules = [
+    ".critical_vulnerabilities == 0",
+    ".high_vulnerabilities < 5"
+  ]
+}
+```
+
+### With jq rules only
+
+```hcl
+resource "kosli_custom_attestation_type" "code_coverage" {
+  name        = "code-coverage"
+  description = "Requires at least 80% line coverage"
+
+  jq_rules = [".line_coverage >= 80"]
+}
+```
+
+### With schema only
+
+```hcl
+resource "kosli_custom_attestation_type" "deployment_record" {
+  name        = "deployment-record"
+  description = "Validates deployment record structure"
+
+  schema = jsonencode({
+    type = "object"
+    properties = {
+      deployed_by = { type = "string" }
+      deployed_at = { type = "string" }
+      environment = { type = "string" }
+    }
+    required = ["deployed_by", "deployed_at", "environment"]
+  })
+}
+```
+
+## Import an existing custom attestation type
+
+If you have custom attestation types created via the CLI, you can bring them under Terraform management by importing them into your <Tooltip tip="The Terraform state file tracks the mapping between your configuration and real-world resources. Importing adds an existing resource to this state without recreating it.">Terraform state</Tooltip>.
+
+1. Find the attestation type name in the Kosli UI or run:
+
+```shell
+kosli list attestation-types
+```
+
+2. Add a matching `kosli_custom_attestation_type` resource block to your configuration.
+
+3. Run the import:
+
+```shell
+terraform import kosli_custom_attestation_type.security_scan security-scan
+```
+
+4. Verify with `terraform plan` — no changes should be planned if the import succeeded.
+
+## Reference
+
+- [`kosli_custom_attestation_type` resource](/terraform-reference/resources/custom_attestation_type)
+- [`kosli_custom_attestation_type` data source](/terraform-reference/data-sources/custom_attestation_type)
+- [Kosli Terraform provider on the Terraform Registry](https://registry.terraform.io/providers/kosli-dev/kosli/latest)

administration/managing_environments/overview.md

@@ -107,7 +107,7 @@ terraform import kosli_logical_environment.production_all production-all
 
 ## Reference
 
-- [`kosli_environment` resource](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/resources/environment)
-- [`kosli_environment` data source](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/data-sources/environment)
-- [`kosli_logical_environment` resource](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/resources/logical_environment)
-- [`kosli_logical_environment` data source](https://registry.terraform.io/providers/kosli-dev/kosli/latest/docs/data-sources/logical_environment)
+- [`kosli_environment` resource](/terraform-reference/resources/environment)
+- [`kosli_environment` data source](/terraform-reference/data-sources/environment)
+- [`kosli_logical_environment` resource](/terraform-reference/resources/logical_environment)
+- [`kosli_logical_environment` data source](/terraform-reference/data-sources/logical_environment)

docs.json

@@ -84,6 +84,12 @@
                 "pages": [
                   "administration/managing_environments/overview"
                 ]
+              },
+              {
+                "group": "Managing Custom Attestation Types",
+                "pages": [
+                  "administration/managing_custom_attestation_types/overview"
+                ]
               }
             ]
           },
@@ -408,6 +414,34 @@
                 ]
               }
             ]
+          },
+          {
+            "item": "Terraform Reference",
+            "icon": "cubes",
+            "groups": [
+              {
+                "group": "Provider",
+                "pages": [
+                  "terraform-reference/index"
+                ]
+              },
+              {
+                "group": "Resources",
+                "pages": [
+                  "terraform-reference/resources/environment",
+                  "terraform-reference/resources/logical_environment",
+                  "terraform-reference/resources/custom_attestation_type"
+                ]
+              },
+              {
+                "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.mdx

@@ -0,0 +1,81 @@
+---
+title: "kosli_custom_attestation_type data source"
+description: "Fetches details of an existing custom attestation type from Kosli. Custom attestation types define how Kosli validates and evaluates evidence from proprietary tools, custom metrics, or specialized compliance requirements."
+icon: "database"
+---
+
+Fetches details of an existing custom attestation type from Kosli. Custom attestation types define how Kosli validates and evaluates evidence from proprietary tools, custom metrics, or specialized compliance requirements.
+
+Use this data source to retrieve information about an existing custom attestation type. This is useful for:
+
+- Referencing existing attestation types in other configurations
+- Creating variants of existing types with modified rules
+- Querying attestation type metadata and schemas
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Query an existing custom attestation type
+data "kosli_custom_attestation_type" "security" {
+  name = "security-scan"
+}
+
+# Use the queried schema in a new attestation type
+resource "kosli_custom_attestation_type" "security_strict" {
+  name        = "security-scan-strict"
+  description = "Stricter security requirements"
+
+  # Reuse the schema from the existing type
+  schema = data.kosli_custom_attestation_type.security.schema
+
+  # Apply stricter validation rules
+  jq_rules = [
+    ".critical_vulnerabilities == 0",
+    ".high_vulnerabilities == 0",
+    ".medium_vulnerabilities < 3"
+  ]
+}
+
+# Reference attestation type metadata
+output "security_scan_description" {
+  description = "Description of the security scan attestation type"
+  value       = data.kosli_custom_attestation_type.security.description
+}
+
+output "security_scan_rules" {
+  description = "JQ rules for the security scan attestation type"
+  value       = data.kosli_custom_attestation_type.security.jq_rules
+}
+
+output "security_scan_archived" {
+  description = "Whether the security scan attestation type is archived"
+  value       = data.kosli_custom_attestation_type.security.archived
+}
+```
+
+## Querying archived types
+
+By default, the data source retrieves active (non-archived) attestation types. Archived types can be queried but are read-only and typically represent historical configurations.
+
+The `archived` attribute indicates whether an attestation type has been deleted/archived in Kosli. Archived types cannot be modified through Terraform.
+
+## Schema
+
+### Required
+
+- `name` (String) The name of the custom attestation type. Must start with a letter or number and contain only letters, numbers, periods, hyphens, underscores, and tildes.
+
+### Read-only
+
+- `archived` (Boolean) Whether this attestation type has been archived.
+- `description` (String) A description of what this attestation type validates.
+- `jq_rules` (List of String) List of jq expressions that define evaluation rules. All rules must evaluate to `true` for compliance.
+- `schema` (String) JSON Schema that defines the structure of attestation data.

terraform-reference/data-sources/environment.mdx

@@ -0,0 +1,102 @@
+---
+title: "kosli_environment data source"
+description: "Fetches details of an existing Kosli environment. Use this data source to reference environments and access metadata like last modified and last reported timestamps."
+icon: "database"
+---
+
+Fetches details of an existing Kosli environment. Use this data source to reference environments and access metadata like last modified and last reported timestamps.
+
+Environments represent runtime locations where artifacts are deployed and tracked for compliance monitoring. Use this data source to:
+
+- Reference existing environment configurations in other resources
+- Monitor environment activity (last modified, last reported timestamps)
+- Create conditional logic based on environment state
+- Build alerts and notifications based on environment metadata
+
+## Example usage
+
+```terraform
+terraform {
+  required_providers {
+    kosli = {
+      source = "kosli-dev/kosli"
+    }
+  }
+}
+
+# Query an existing environment
+data "kosli_environment" "production" {
+  name = "production-k8s"
+}
+
+# Use the data source to create a similar environment
+resource "kosli_environment" "staging" {
+  name        = "staging-k8s"
+  type        = data.kosli_environment.production.type
+  description = "Staging environment similar to ${data.kosli_environment.production.name}"
+}
+
+# Reference environment metadata for monitoring
+output "production_last_modified" {
+  description = "Timestamp of when production environment was last modified"
+  value       = data.kosli_environment.production.last_modified_at
+}
+
+output "production_last_reported" {
+  description = "Timestamp of when production environment last reported a snapshot"
+  value       = data.kosli_environment.production.last_reported_at
+}
+
+output "production_type" {
+  description = "Type of the production environment"
+  value       = data.kosli_environment.production.type
+}
+
+output "production_includes_scaling" {
+  description = "Whether production environment includes scaling events"
+  value       = data.kosli_environment.production.include_scaling
+}
+
+# Conditional logic based on environment metadata
+locals {
+  # Check if environment has never reported a snapshot
+  needs_attention = data.kosli_environment.production.last_reported_at == null
+}
+
+output "production_needs_attention" {
+  description = "Whether production environment needs attention (never reported)"
+  value       = local.needs_attention
+}
+```
+
+## Monitoring with data sources
+
+The data source exposes timestamp fields that are useful for monitoring:
+
+- `last_modified_at`: Unix timestamp of when the environment configuration was last changed
+- `last_reported_at`: Unix timestamp of when the environment last reported a snapshot (can be null if never reported)
+
+These timestamps enable you to:
+
+- Create alerts for environments that haven't reported in a certain time period
+- Track configuration changes across your infrastructure
+- Build dashboards showing environment activity
+- Implement conditional deployment logic based on environment state
+
+## Read-only access
+
+Data sources provide read-only access to environment metadata. To modify environment configurations, use the [`kosli_environment` resource](/terraform-reference/resources/environment).
+
+## Schema
+
+### Required
+
+- `name` (String) The name of the environment to query.
+
+### Read-only
+
+- `description` (String) The description of the environment.
+- `include_scaling` (Boolean) Whether the environment includes scaling events in snapshots.
+- `last_modified_at` (Number) Unix timestamp (with fractional seconds) of when the environment was last modified.
+- `last_reported_at` (Number) Unix timestamp (with fractional seconds) of when the environment was last reported. May be null if never reported.
+- `type` (String) The environment type (e.g., K8S, ECS, S3, docker, server, lambda).