docs: Update resource documentation

docs/resources/cluster.md

@@ -2,12 +2,12 @@
 page_title: "Resource plural_cluster - terraform-provider-plural"
 subcategory: ""
 description: |-
-  A representation of a cluster you can deploy to.
+  Cluster represents a Kubernetes cluster managed by the Plural Console for continuous deployment. Clusters serve as deployment targets for services and can be either management clusters (hosting the Plural Console and operators) or workload clusters (running application workloads). The Console tracks cluster health, versions, and coordinates service deployments across the fleet.
 ---
 
 # plural_cluster (Resource)
 
-A representation of a cluster you can deploy to.
+Cluster represents a Kubernetes cluster managed by the Plural Console for continuous deployment. Clusters serve as deployment targets for services and can be either management clusters (hosting the Plural Console and operators) or workload clusters (running application workloads). The Console tracks cluster health, versions, and coordinates service deployments across the fleet.
 
 
 

docs/resources/custom_stack_run.md

@@ -3,12 +3,12 @@
 page_title: "plural_custom_stack_run Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  A custom stack run resource that allows users to define custom commands that can be executed as part of a stack run.
 ---
 
 # plural_custom_stack_run (Resource)
 
-
+A custom stack run resource that allows users to define custom commands that can be executed as part of a stack run.
 
 
 

docs/resources/git_repository.md

@@ -3,12 +3,12 @@
 page_title: "plural_git_repository Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  GitRepository resource
+  GitRepository provides Git-based source control integration for Plural's GitOps workflows. It represents a Git repository available for deployments, enabling automated fetching of manifests, IaC code, and configuration from version-controlled sources.
 ---
 
 # plural_git_repository (Resource)
 
-GitRepository resource
+GitRepository provides Git-based source control integration for Plural's GitOps workflows. It represents a Git repository available for deployments, enabling automated fetching of manifests, IaC code, and configuration from version-controlled sources.
 
 
 

docs/resources/global_service.md

@@ -3,12 +3,12 @@
 page_title: "plural_global_service Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  GlobalService resource
+  GlobalService handles the deployment and management of services across multiple clusters. It provides a centralized way to define service deployments that should be replicated across a fleet of Kubernetes clusters, with flexible targeting based on cluster properties, tags, and organizational boundaries.
 ---
 
 # plural_global_service (Resource)
 
-GlobalService resource
+GlobalService handles the deployment and management of services across multiple clusters. It provides a centralized way to define service deployments that should be replicated across a fleet of Kubernetes clusters, with flexible targeting based on cluster properties, tags, and organizational boundaries.
 
 
 
@@ -17,14 +17,14 @@ GlobalService resource
 
 ### Required
 
-- `name` (String) Name of this GlobalService.
+- `name` (String) Name of this service. If not provided, the name from GlobalService.ObjectMeta will be used.
 - `service_id` (String) The id of the service that will be replicated by this global service.
 
 ### Optional
 
-- `distro` (String) Kubernetes distribution for this global servie, eg EKS, AKS, GKE, K3S.
+- `distro` (String) Kubernetes distribution for this global service, eg EKS, AKS, GKE, K3S.
 - `provider_id` (String) Id of a CAPI provider that this global service targets.
-- `tags` (Map of String) Key-value tags used to target clusters for this global service.
+- `tags` (Map of String) Tags specify a set of key-value pairs used to select target clusters for this global service. Only clusters that match all specified tags will be included in the deployment scope. This provides a flexible mechanism for targeting specific cluster groups or environments.
 
 ### Read-Only
 

docs/resources/group.md

@@ -3,12 +3,12 @@
 page_title: "plural_group Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  group resource
+  Group represents a group of users within the system, managed via the Console API. It includes specifications for the group's name and description.
 ---
 
 # plural_group (Resource)
 
-group resource
+Group represents a group of users within the system, managed via the Console API. It includes specifications for the group's name and description.
 
 
 

docs/resources/group_member.md

@@ -3,12 +3,12 @@
 page_title: "plural_group_member Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  GroupMember resource
+  Group member represents the membership relationship between a user and a group. It enables user assignment to groups for access control and permission management within the Plural Console.
 ---
 
 # plural_group_member (Resource)
 
-GroupMember resource
+Group member represents the membership relationship between a user and a group. It enables user assignment to groups for access control and permission management within the Plural Console.
 
 
 

docs/resources/infrastructure_stack.md

@@ -3,12 +3,12 @@
 page_title: "plural_infrastructure_stack Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  Infrastructure stack provides a scalable framework to manage infrastructure as code with a K8s-friendly, API-driven approach. It declaratively defines a stack with a type, Git repository location, and target cluster for execution. On each commit to the tracked repository, a run is created which the Plural deployment operator detects and executes on the targeted cluster, enabling fine-grained permissions and network location control for IaC runs.
 ---
 
 # plural_infrastructure_stack (Resource)
 
-
+Infrastructure stack provides a scalable framework to manage infrastructure as code with a K8s-friendly, API-driven approach. It declaratively defines a stack with a type, Git repository location, and target cluster for execution. On each commit to the tracked repository, a run is created which the Plural deployment operator detects and executes on the targeted cluster, enabling fine-grained permissions and network location control for IaC runs.
 
 
 
@@ -19,7 +19,7 @@ description: |-
 
 - `cluster_id` (String) The cluster on which the stack will be applied.
 - `configuration` (Attributes) Stack configuration. (see [below for nested schema](#nestedatt--configuration))
-- `name` (String) Human-readable name of this stack.
+- `name` (String) Name of this stack.
 - `repository` (Attributes) Repository information used to pull stack. (see [below for nested schema](#nestedatt--repository))
 - `type` (String) A type for the stack, specifies the tool to use to apply it. Allowed values include `ANSIBLE` and `TERRAFORM`.
 

docs/resources/observability_webhook.md

@@ -3,12 +3,12 @@
 page_title: "plural_observability_webhook Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  Observability provider configures external monitoring and observability platforms for use with Plural Console. It enables integration with services like Datadog and New Relic to provide enhanced monitoring capabilities for infrastructure stacks and service deployments. The provider can be used by infrastructure stacks to monitor metrics and determine if operations should be cancelled based on system health indicators.
 ---
 
 # plural_observability_webhook (Resource)
 
-
+Observability provider configures external monitoring and observability platforms for use with Plural Console. It enables integration with services like Datadog and New Relic to provide enhanced monitoring capabilities for infrastructure stacks and service deployments. The provider can be used by infrastructure stacks to monitor metrics and determine if operations should be cancelled based on system health indicators.
 
 
 

docs/resources/oidc_provider.md

@@ -3,12 +3,12 @@
 page_title: "plural_oidc_provider Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  OIDC provider configures OpenID Connect (OIDC) authentication for external applications and services. It enables third-party applications to authenticate users through the Plural Console using the standard OIDC protocol. This is useful for integrating external tools, dashboards, or custom applications with Plural's authentication system while maintaining centralized user management and access control. Common use cases include connecting monitoring dashboards, CI/CD tools, or custom applications that need to authenticate users against the Plural Console's user directory.
 ---
 
 # plural_oidc_provider (Resource)
 
-
+OIDC provider configures OpenID Connect (OIDC) authentication for external applications and services. It enables third-party applications to authenticate users through the Plural Console using the standard OIDC protocol. This is useful for integrating external tools, dashboards, or custom applications with Plural's authentication system while maintaining centralized user management and access control. Common use cases include connecting monitoring dashboards, CI/CD tools, or custom applications that need to authenticate users against the Plural Console's user directory.
 
 
 
@@ -17,7 +17,7 @@ description: |-
 
 ### Required
 
-- `name` (String) Human-readable name of this OIDC provider.
+- `name` (String) Name of this OIDC provider.
 - `type` (String)
 
 ### Optional

docs/resources/pr_automation_trigger.md

@@ -3,12 +3,12 @@
 page_title: "plural_pr_automation_trigger Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  PR automation trigger initiates the execution of a PR automation with specific parameters. This resource enables automated, event-driven, or scheduled generation of pull requests by providing configuration context and branch information to an existing PR automation.
 ---
 
 # plural_pr_automation_trigger (Resource)
 
-
+PR automation trigger initiates the execution of a PR automation with specific parameters. This resource enables automated, event-driven, or scheduled generation of pull requests by providing configuration context and branch information to an existing PR automation.
 
 
 

docs/resources/project.md

@@ -3,12 +3,12 @@
 page_title: "plural_project Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  Project provides organizational segmentation and multi-tenancy capabilities within Plural Console. It serves as a unit of an organization to control permissions for sets of resources, enabling enterprise-grade fleet management while maintaining security boundaries. Projects allow resource owners to manage their domain without accessing resources outside their scope, supporting principles of least privilege and preventing credential sprawl across the entire fleet.
 ---
 
 # plural_project (Resource)
 
-
+Project provides organizational segmentation and multi-tenancy capabilities within Plural Console. It serves as a unit of an organization to control permissions for sets of resources, enabling enterprise-grade fleet management while maintaining security boundaries. Projects allow resource owners to manage their domain without accessing resources outside their scope, supporting principles of least privilege and preventing credential sprawl across the entire fleet.
 
 
 
@@ -21,8 +21,8 @@ description: |-
 
 ### Optional
 
-- `bindings` (Attributes) Read and write policies of this project. (see [below for nested schema](#nestedatt--bindings))
-- `description` (String) Description of this project.
+- `bindings` (Attributes) Bindings contain read and write policies that control access to all resources within this project, enabling fine-grained permission management and multi-tenancy. (see [below for nested schema](#nestedatt--bindings))
+- `description` (String) Description provides a human-readable explanation of this project's purpose and the resources it manages within the organizational hierarchy.
 
 ### Read-Only
 

docs/resources/rbac.md

@@ -3,12 +3,12 @@
 page_title: "plural_rbac Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  A representation of rbac settings for a provider or cluster.
+  RBAC resource provides role-based access control settings for clusters and services. It defines read and write bindings to control user and group permissions for accessing and managing resources within the Plural Console.
 ---
 
 # plural_rbac (Resource)
 
-A representation of rbac settings for a provider or cluster.
+RBAC resource provides role-based access control settings for clusters and services. It defines read and write bindings to control user and group permissions for accessing and managing resources within the Plural Console.
 
 
 

docs/resources/scm_webhook.md

@@ -3,12 +3,12 @@
 page_title: "plural_scm_webhook Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  SCM webhook resource.
 ---
 
 # plural_scm_webhook (Resource)
 
-
+SCM webhook resource.
 
 
 

docs/resources/service_account.md

@@ -3,12 +3,12 @@
 page_title: "plural_service_account Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  service account resource
+  Service account provides a programmatic identity for automated processes and tools to interact with the Plural Console API. Unlike user accounts, service accounts are designed for non-human authentication and can be scoped to specific APIs and resources for secure, limited access. This enables to authenticate and perform operations within defined permissions boundaries.
 ---
 
 # plural_service_account (Resource)
 
-service account resource
+Service account provides a programmatic identity for automated processes and tools to interact with the Plural Console API. Unlike user accounts, service accounts are designed for non-human authentication and can be scoped to specific APIs and resources for secure, limited access. This enables to authenticate and perform operations within defined permissions boundaries.
 
 
 

docs/resources/service_context.md

@@ -3,12 +3,12 @@
 page_title: "plural_service_context Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  A representation of a service context that can be reused during service deployment templating.
+  Service context provides a reusable bundle of configuration. It enables sharing configuration data across multiple services. This is particularly useful for passing outputs from infrastructure-as-code tools to Kubernetes services.
 ---
 
 # plural_service_context (Resource)
 
-A representation of a service context that can be reused during service deployment templating.
+Service context provides a reusable bundle of configuration. It enables sharing configuration data across multiple services. This is particularly useful for passing outputs from infrastructure-as-code tools to Kubernetes services.
 
 
 

docs/resources/service_deployment.md

@@ -3,12 +3,12 @@
 page_title: "plural_service_deployment Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  Service deployment represents a Kubernetes service deployed and managed by Plural Console. It defines how applications are deployed to clusters using GitOps principles, supporting multiple deployment methods including Helm charts, Kustomize, and raw manifests. Services can be templated, configured with secrets and dependencies, and monitored for health and sync status across the deployment lifecycle.
 ---
 
 # plural_service_deployment (Resource)
 
-
+Service deployment represents a Kubernetes service deployed and managed by Plural Console. It defines how applications are deployed to clusters using GitOps principles, supporting multiple deployment methods including Helm charts, Kustomize, and raw manifests. Services can be templated, configured with secrets and dependencies, and monitored for health and sync status across the deployment lifecycle.
 
 
 

docs/resources/service_wait.md

@@ -3,12 +3,12 @@
 page_title: "plural_service_wait Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  Service wait provides a utility resource to wait for a service deployment to reach a healthy and synchronized state before proceeding. This is useful for orchestrating dependencies between services and ensuring deployment order.
 ---
 
 # plural_service_wait (Resource)
 
-
+Service wait provides a utility resource to wait for a service deployment to reach a healthy and synchronized state before proceeding. This is useful for orchestrating dependencies between services and ensuring deployment order.
 
 
 

docs/resources/stack_run_trigger.md

@@ -3,12 +3,12 @@
 page_title: "plural_stack_run_trigger Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-
+  Stack run trigger initiates the execution of an infrastructure stack from the newest SHA in the stack's run history. This resource enables programmatic triggering of infrastructure runs, allowing for event-driven or scheduled infrastructure updates.
 ---
 
 # plural_stack_run_trigger (Resource)
 
-
+Stack run trigger initiates the execution of an infrastructure stack from the newest SHA in the stack's run history. This resource enables programmatic triggering of infrastructure runs, allowing for event-driven or scheduled infrastructure updates.
 
 
 

docs/resources/user.md

@@ -3,12 +3,12 @@
 page_title: "plural_user Resource - terraform-provider-plural"
 subcategory: ""
 description: |-
-  user resource
+  User account within the Plural Console.
 ---
 
 # plural_user (Resource)
 
-user resource
+User account within the Plural Console.
 
 
 

internal/resource/cluster_schema.go

@@ -17,8 +17,8 @@ import (
 
 func (r *clusterResource) schema() schema.Schema {
 	return schema.Schema{
-		Description:         "A representation of a cluster you can deploy to.",
-		MarkdownDescription: "A representation of a cluster you can deploy to.",
+		Description:         "Cluster represents a Kubernetes cluster managed by the Plural Console for continuous deployment. Clusters serve as deployment targets for services and can be either management clusters (hosting the Plural Console and operators) or workload clusters (running application workloads). The Console tracks cluster health, versions, and coordinates service deployments across the fleet.",
+		MarkdownDescription: "Cluster represents a Kubernetes cluster managed by the Plural Console for continuous deployment. Clusters serve as deployment targets for services and can be either management clusters (hosting the Plural Console and operators) or workload clusters (running application workloads). The Console tracks cluster health, versions, and coordinates service deployments across the fleet.",
 		Version:             1,
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{

internal/resource/custom_stack_run_schema.go

@@ -12,6 +12,7 @@ import (
 
 func (r *CustomStackRunResource) schema() schema.Schema {
 	return schema.Schema{
+		MarkdownDescription: "A custom stack run resource that allows users to define custom commands that can be executed as part of a stack run.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Description:         "Internal identifier of this custom run.",

internal/resource/git_repository.go

@@ -39,7 +39,7 @@ func (r *GitRepositoryResource) Metadata(
 
 func (r *GitRepositoryResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "GitRepository resource",
+		MarkdownDescription: "GitRepository provides Git-based source control integration for Plural's GitOps workflows. It represents a Git repository available for deployments, enabling automated fetching of manifests, IaC code, and configuration from version-controlled sources.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Computed:            true,