docs: update provider documentation and examples

Author: Trozz

.goreleaser.yml

@@ -29,12 +29,31 @@ builds:
       - darwin
       - linux
       - windows
+      - freebsd
     goarch:
       - amd64
       - arm64
+      - arm
+      - 386
+    goarm:
+      - "6"
+      - "7"
     ignore:
+      # Windows doesn't support ARM
       - goos: windows
         goarch: arm64
+      - goos: windows
+        goarch: arm
+      # Darwin doesn't support 386 or ARMv6/v7
+      - goos: darwin
+        goarch: 386
+      - goos: darwin
+        goarch: arm
+      # FreeBSD only supports amd64 and 386
+      - goos: freebsd
+        goarch: arm64
+      - goos: freebsd
+        goarch: arm
 
 # Archive configuration
 archives:

docs/BUILD_MATRIX.md

@@ -0,0 +1,60 @@
+# Build Matrix for Terraform Registry
+
+This document outlines the OS and architecture combinations that are built for the Pocket-ID Terraform provider.
+
+## Terraform Registry Requirements
+
+According to [Terraform Registry documentation](https://developer.hashicorp.com/terraform/registry/providers/os-arch), providers should build for the following platforms:
+
+### Required Platforms ✅
+
+- ✅ **Darwin (macOS) / AMD64** - Intel Macs
+- ✅ **Darwin (macOS) / ARM64** - Apple Silicon Macs (M1/M2/M3)
+- ✅ **Linux / AMD64** - Standard Linux x86_64 (required for HCP Terraform)
+- ✅ **Linux / ARM64** - Linux on ARM64/AArch64
+- ✅ **Linux / ARMv6** - Linux on ARM v6 (Raspberry Pi, etc.)
+- ✅ **Windows / AMD64** - Windows 64-bit
+
+### Recommended Platforms ✅
+
+- ✅ **Linux / 386** - Linux 32-bit
+- ✅ **Windows / 386** - Windows 32-bit
+- ✅ **FreeBSD / 386** - FreeBSD 32-bit
+- ✅ **FreeBSD / AMD64** - FreeBSD 64-bit
+
+## Current Build Configuration
+
+Based on `.goreleaser.yml`, the following platforms are built:
+
+### Darwin (macOS)
+
+- `darwin/amd64` - Intel Macs
+- `darwin/arm64` - Apple Silicon Macs
+
+### Linux
+
+- `linux/386` - 32-bit
+- `linux/amd64` - 64-bit (CGO disabled for HCP Terraform compatibility)
+- `linux/arm64` - ARM64/AArch64
+- `linux/arm/6` - ARMv6 (Raspberry Pi Zero, Pi 1)
+- `linux/arm/7` - ARMv7 (Raspberry Pi 2+)
+
+### Windows
+
+- `windows/386` - 32-bit
+- `windows/amd64` - 64-bit
+
+### FreeBSD
+
+- `freebsd/386` - 32-bit
+- `freebsd/amd64` - 64-bit
+
+## Build Settings
+
+All binaries are built with:
+
+- **CGO_ENABLED=0** - Static binaries with no external dependencies
+- **-trimpath** flag - Reproducible builds
+- **Proper versioning** - Version, commit, and date embedded in binaries
+
+This configuration ensures compatibility with Terraform Registry requirements and HCP Terraform.

docs/data-sources/client.md

@@ -10,7 +10,52 @@ description: |-
 
 Fetches an OIDC client from Pocket-ID by its ID.
 
+## Example Usage
 
+```terraform
+# First create a client
+resource "pocketid_client" "app" {
+  name = "My Application"
+
+  callback_urls = [
+    "https://app.example.com/callback"
+  ]
+
+  is_public = false
+}
+
+# Fetch the client by ID
+data "pocketid_client" "app" {
+  client_id = pocketid_client.app.id
+}
+
+# Use the client data
+output "client_name" {
+  value = data.pocketid_client.app.name
+}
+
+output "client_callback_urls" {
+  value = data.pocketid_client.app.callback_urls
+}
+
+output "client_has_logo" {
+  value = data.pocketid_client.app.has_logo
+}
+
+# Example of fetching an existing client by known ID
+data "pocketid_client" "existing" {
+  client_id = "550e8400-e29b-41d4-a716-446655440000"
+}
+
+# Check client configuration
+output "existing_client_is_public" {
+  value = data.pocketid_client.existing.is_public
+}
+
+output "existing_client_pkce_enabled" {
+  value = data.pocketid_client.existing.pkce_enabled
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/clients.md

@@ -10,7 +10,68 @@ description: |-
 
 Fetches all OIDC clients from Pocket-ID.
 
+## Example Usage
 
+```terraform
+# Fetch all OIDC clients
+data "pocketid_clients" "all" {}
+
+# Output total client count
+output "total_clients" {
+  value = length(data.pocketid_clients.all.clients)
+}
+
+# List all client names
+output "client_names" {
+  value = [for client in data.pocketid_clients.all.clients : client.name]
+}
+
+# Find public clients
+locals {
+  public_clients = [
+    for client in data.pocketid_clients.all.clients : client
+    if client.is_public
+  ]
+
+  confidential_clients = [
+    for client in data.pocketid_clients.all.clients : client
+    if !client.is_public
+  ]
+}
+
+output "public_client_count" {
+  value = length(local.public_clients)
+}
+
+output "confidential_client_count" {
+  value = length(local.confidential_clients)
+}
+
+# Create a map of clients by name
+locals {
+  clients_by_name = {
+    for client in data.pocketid_clients.all.clients : client.name => client
+  }
+}
+
+# Access a specific client from the map
+output "spa_client_id" {
+  value = lookup(local.clients_by_name, "React SPA Application", null) != null ? local.clients_by_name["React SPA Application"].id : "Client not found"
+}
+
+# Find clients with specific callback URLs
+locals {
+  localhost_clients = [
+    for client in data.pocketid_clients.all.clients : client
+    if anytrue([for url in client.callback_urls : can(regex("localhost", url))])
+  ]
+}
+
+output "development_clients" {
+  description = "Clients configured for localhost development"
+  value       = [for client in local.localhost_clients : client.name]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -20,6 +81,7 @@ Fetches all OIDC clients from Pocket-ID.
 - `clients` (Attributes List) List of all OIDC clients. (see [below for nested schema](#nestedatt--clients))
 
 <a id="nestedatt--clients"></a>
+
 ### Nested Schema for `clients`
 
 Read-Only:

docs/data-sources/user.md

@@ -10,7 +10,40 @@ description: |-
 
 Fetches a user from Pocket-ID by their ID.
 
+## Example Usage
 
+```terraform
+# First create a user
+resource "pocketid_user" "example" {
+  username   = "john.doe"
+  email      = "john.doe@example.com"
+  first_name = "John"
+  last_name  = "Doe"
+}
+
+# Then fetch the user by ID
+data "pocketid_user" "example" {
+  id = pocketid_user.example.id
+}
+
+# Use the user data
+output "user_email" {
+  value = data.pocketid_user.example.email
+}
+
+output "user_groups" {
+  value = data.pocketid_user.example.groups
+}
+
+output "user_is_admin" {
+  value = data.pocketid_user.example.is_admin
+}
+
+# Example of fetching an existing user by known ID
+data "pocketid_user" "existing" {
+  id = "123e4567-e89b-12d3-a456-426614174000"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/users.md

@@ -10,7 +10,60 @@ description: |-
 
 Fetches all users from Pocket-ID.
 
+## Example Usage
 
+```terraform
+# Fetch all users
+data "pocketid_users" "all" {}
+
+# Output total user count
+output "total_users" {
+  value = length(data.pocketid_users.all.users)
+}
+
+# Output all user emails
+output "user_emails" {
+  value = [for user in data.pocketid_users.all.users : user.email]
+}
+
+# Find admin users
+locals {
+  admin_users = [
+    for user in data.pocketid_users.all.users : user
+    if user.is_admin
+  ]
+}
+
+output "admin_count" {
+  value = length(local.admin_users)
+}
+
+# Filter users by group membership
+resource "pocketid_group" "developers" {
+  name          = "developers"
+  friendly_name = "Development Team"
+}
+
+data "pocketid_users" "developers" {
+  group_id = pocketid_group.developers.id
+}
+
+output "developers_count" {
+  value = length(data.pocketid_users.developers.users)
+}
+
+# Create a map of users by username
+locals {
+  users_by_username = {
+    for user in data.pocketid_users.all.users : user.username => user
+  }
+}
+
+# Access a specific user from the map
+output "john_doe_email" {
+  value = lookup(local.users_by_username, "john.doe", null) != null ? local.users_by_username["john.doe"].email : "User not found"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -20,6 +73,7 @@ Fetches all users from Pocket-ID.
 - `users` (Attributes List) List of all users. (see [below for nested schema](#nestedatt--users))
 
 <a id="nestedatt--users"></a>
+
 ### Nested Schema for `users`
 
 Read-Only: