docs: comprehensive documentation improvements (#493)

- Add Go library usage section with examples and use cases
- Add error handling and troubleshooting guide
- Enhance godoc comments for public API (Provider, ResolveAll)
- Add GCP Secret Manager examples and authentication guidance
- Standardize provider documentation format across all providers
- Fix outdated path reference in CLAUDE.md (internal -> pkg)
- Fix typo in terraform/README.md (Infrastructure)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: busser

CLAUDE.md

@@ -13,7 +13,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing
 - Run specific test: `go test ./path/to/package -run TestName`
-- Run e2e tests for specific provider: `go test -tags=e2e ./internal/murmur/providers/awssm`
+- Run e2e tests for specific provider: `go test -tags=e2e ./pkg/murmur/providers/awssm`
 
 ## Architecture
 

README.md

@@ -33,13 +33,15 @@ issue so that we can track demand for it._
 - [Adding Murmur to a container image](#adding-murmur-to-a-container-image)
 - [Adding Murmur to a Kubernetes pod](#adding-murmur-to-a-kubernetes-pod)
 - [Parsing JSON secrets](#parsing-json-secrets)
+- [Go library usage](#go-library-usage)
 - [Providers and filters](#providers-and-filters)
   - [`scwsm` provider: Scaleway Secret Manager](#scwsm-provider-scaleway-secret-manager)
   - [`awssm` provider: AWS Secrets Manager](#awssm-provider-aws-secrets-manager)
   - [`azkv` provider: Azure Key Vault](#azkv-provider-azure-key-vault)
   - [`gcpsm` provider: GCP Secret Manager](#gcpsm-provider-gcp-secret-manager)
   - [`passthrough` provider: no-op](#passthrough-provider-no-op)
   - [`jsonpath` filter: JSON parsing and templating](#jsonpath-filter-json-parsing-and-templating)
+- [Error handling and troubleshooting](#error-handling-and-troubleshooting)
 - [Changes from v0.4 to v0.5](#changes-from-v04-to-v05)
 
 ## Fetching a database password
@@ -159,6 +161,99 @@ Murmur uses the Kubernetes JSONPath syntax for the `jsonpath` filter. See the
 [Kubernetes documentation](https://kubernetes.io/docs/reference/kubectl/jsonpath/)
 for a full list of capabilities.
 
+## Go library usage
+
+As of v0.7.0, Murmur's internal components are available as a public Go library.
+You can import and use Murmur's provider system and secret resolution pipeline
+directly in your Go applications.
+
+### Basic secret resolution
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+
+    "github.com/busser/murmur/pkg/murmur"
+)
+
+func main() {
+    // Define secrets using the same syntax as environment variables
+    secrets := map[string]string{
+        "DB_PASSWORD": "awssm:my-database-secret",
+        "API_KEY":     "gcpsm:my-project/api-credentials|jsonpath:{.key}",
+        "DEBUG_MODE":  "passthrough:true", // Non-secret values pass through
+    }
+
+    // Resolve all secrets
+    resolved, err := murmur.ResolveAll(secrets)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("DB Password: %s\n", resolved["DB_PASSWORD"])
+    fmt.Printf("API Key: %s\n", resolved["API_KEY"])
+    fmt.Printf("Debug Mode: %s\n", resolved["DEBUG_MODE"])
+}
+```
+
+### Using providers directly
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/busser/murmur/pkg/murmur"
+)
+
+func main() {
+    // Get a specific provider
+    providerFactory, exists := murmur.ProviderFactories["awssm"]
+    if !exists {
+        log.Fatal("AWS Secrets Manager provider not available")
+    }
+
+    provider, err := providerFactory()
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer provider.Close()
+
+    // Fetch a secret directly
+    secret, err := provider.Resolve(context.Background(), "my-secret")
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    fmt.Printf("Secret value: %s\n", secret)
+}
+```
+
+### Available providers
+
+All built-in providers are available through `murmur.ProviderFactories`:
+
+- `"awssm"` - AWS Secrets Manager
+- `"azkv"` - Azure Key Vault  
+- `"gcpsm"` - GCP Secret Manager
+- `"scwsm"` - Scaleway Secret Manager
+- `"passthrough"` - Testing/no-op provider
+
+### Use cases
+
+The Go library enables several powerful patterns:
+
+- **Configuration-based secret resolution** instead of environment variables
+- **Custom secret injection workflows** in Go applications
+- **Testing with mock providers** for unit tests
+- **Building custom secret management tools** on top of Murmur's provider system
+
 ## Providers and filters
 
 Murmur's architecture is built around providers and filters. Providers fetch
@@ -283,8 +378,8 @@ azkv:example.vault.azure.net/my-secret#5ddc29704c1c4429a4c53605b7949100
 ```
 
 Murmur uses the environment's default credentials to authenticate to Azure. You
-can set these credentials with the [environment variables listed here](https://github.com/Azure/azure-sdk-for-go/wiki/Set-up-Your-Environment-for-Authentication#configure-defaultazurecredential),
-or with workload identity.
+can set these credentials with the [environment variables listed here](https://github.com/Azure/azure-sdk-for-go/wiki/Set-up-Your-Environment-for-Authentication#configure-defaultazurecredential)
+(such as `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`), or with workload identity.
 
 ### `gcpsm` provider: GCP Secret Manager
 
@@ -302,6 +397,20 @@ The `name` is the name of the secret.
 The `version` must be a valid version number. If `version` is not specified,
 Murmur defaults to the latest version of the secret.
 
+Examples:
+
+```plaintext
+gcpsm:my-project-123/my-secret
+gcpsm:my-project-123/my-secret#1
+gcpsm:my-project-123/my-secret#latest
+
+gcpsm:123456789012/database-credentials
+gcpsm:123456789012/database-credentials#5
+```
+
+Murmur uses the environment's default credentials to authenticate to GCP.
+You can configure Murmur the same way you can [configure the `gcloud` CLI](https://cloud.google.com/docs/authentication/provide-credentials-adc).
+
 ### `passthrough` provider: no-op
 
 This provider is meant for demo and testing purposes. It does not fetch any
@@ -343,6 +452,83 @@ scwsm:my-secret|jsonpath:postgres://{.username}:{.password}@{.hostname}:{.port}/
 scwsm:my-secret|jsonpath:the secret is {@}
 ```
 
+## Error handling and troubleshooting
+
+### Common errors
+
+**Invalid reference format**
+```
+Error: invalid reference: missing colon
+```
+This means your secret reference doesn't follow the correct format. Ensure you use:
+```
+provider_id:secret_ref[|filter_id:filter_rule]
+```
+
+**Authentication failures**
+```
+Error: failed to load AWS config: NoCredentialProviders
+```
+This indicates missing or invalid cloud provider credentials. Check:
+- AWS: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or AWS profile configuration
+- Azure: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`  
+- GCP: `GOOGLE_APPLICATION_CREDENTIALS` or `gcloud auth application-default login`
+- Scaleway: `SCW_ACCESS_KEY`, `SCW_SECRET_KEY`
+
+**Secret not found**
+```
+Error: failed to access secret "my-secret": secret not found
+```
+Verify:
+- Secret name/ID is correct
+- Secret exists in the specified region/project
+- You have the necessary permissions to read the secret
+- For versioned secrets, the version exists
+
+**JSONPath filter errors**
+```
+Error: failed to apply filter: invalid JSONPath expression
+```
+Check your JSONPath syntax against the [Kubernetes JSONPath documentation](https://kubernetes.io/docs/reference/kubectl/jsonpath/).
+
+### Debugging tips
+
+**Enable verbose logging** (when using as CLI):
+```bash
+export MURMUR_LOG_LEVEL=debug
+murmur run -- your-command
+```
+
+**Test secret resolution** (when using as library):
+```go
+resolved, err := murmur.ResolveAll(map[string]string{
+    "TEST": "passthrough:hello-world",
+})
+if err != nil {
+    log.Printf("Resolution failed: %v", err)
+}
+```
+
+**Validate individual providers**:
+```go
+provider, err := murmur.ProviderFactories["awssm"]()
+if err != nil {
+    log.Printf("Provider initialization failed: %v", err)
+}
+defer provider.Close()
+
+secret, err := provider.Resolve(context.Background(), "test-secret")
+if err != nil {
+    log.Printf("Secret resolution failed: %v", err)
+}
+```
+
+### Performance considerations
+
+- **Concurrent resolution**: Murmur fetches secrets concurrently per provider, but sequentially within each provider
+- **Caching**: Duplicate secret references are cached within a single resolution call
+- **Resource cleanup**: Always call `Close()` on providers when using the library directly
+
 ## Changes from v0.4 to v0.5
 
 Following community feedback, we have made two significant changes in v0.5:

pkg/murmur/provider.go

@@ -10,23 +10,52 @@ import (
 	"github.com/busser/murmur/pkg/murmur/providers/scwsm"
 )
 
-// A Provider fetches values from a secret store.
+// Provider fetches values from a secret store (e.g., AWS Secrets Manager, Azure Key Vault).
+// Each provider implements a specific cloud secret management service.
+//
+// Providers are designed to be:
+//   - Thread-safe for concurrent Resolve calls
+//   - Stateful (may hold connections, credentials)
+//   - Resource-managed (must call Close when done)
+//
+// Example usage:
+//
+//	provider, err := awssm.New()
+//	if err != nil {
+//	    return err
+//	}
+//	defer provider.Close()
+//
+//	secret, err := provider.Resolve(ctx, "my-secret#AWSCURRENT")
+//	if err != nil {
+//	    return err
+//	}
 type Provider interface {
-	// Resolve returns the value of the secret with the given ref. Resolve never
-	// gets called after Close.
+	// Resolve returns the value of the secret with the given ref.
+	// The ref format is provider-specific (e.g., "secret-name#version").
+	// Resolve should be thread-safe and may be called concurrently.
+	// Resolve will never be called after Close.
 	Resolve(ctx context.Context, ref string) (string, error)
 
 	// Close signals to the provider that it can release any resources it has
 	// allocated, like network connections. Close should return once those
-	// resources are released.
+	// resources are released. After Close is called, Resolve should not be called.
 	Close() error
 }
 
-// A ProviderFactory returns a new Provider.
+// ProviderFactory creates a new Provider instance.
+// Each call should return a fresh provider with its own resources.
 type ProviderFactory func() (Provider, error)
 
-// ProviderFactories contains a ProviderFactory for each prefix known to
-// murmur.
+// ProviderFactories contains a ProviderFactory for each provider prefix known to murmur.
+// This map is used by the resolution pipeline to create providers on-demand.
+//
+// Available providers:
+//   - "awssm": AWS Secrets Manager
+//   - "azkv": Azure Key Vault
+//   - "gcpsm": GCP Secret Manager  
+//   - "scwsm": Scaleway Secret Manager
+//   - "passthrough": Testing/no-op provider
 var ProviderFactories = map[string]ProviderFactory{
 	// Passthrough
 	"passthrough": func() (Provider, error) { return passthrough.New() },

pkg/murmur/resolve.go

@@ -25,8 +25,26 @@ type variable struct {
 	err error
 }
 
-// ResolveAll returns a map with the same keys as vars, where all values with
-// known prefixes have been replaced with their values.
+// ResolveAll resolves all secret references in the input map and returns the resolved values.
+// 
+// Input map keys are preserved. Values that contain valid murmur queries (format: "provider:ref|filter:rule")
+// are resolved by fetching from the appropriate secret store. Values without valid queries pass through unchanged.
+//
+// The resolution process:
+//   1. Parse each value to identify secret queries
+//   2. Group queries by provider for concurrent resolution  
+//   3. Apply filters (like JSONPath) to transform resolved secrets
+//   4. Return final environment-ready values
+//
+// Example:
+//   input := map[string]string{
+//       "DB_PASSWORD": "awssm:prod/database#AWSCURRENT",
+//       "API_KEY": "gcpsm:my-project/api-key|jsonpath:{.token}",
+//       "DEBUG": "true", // passes through unchanged
+//   }
+//   resolved, err := ResolveAll(input)
+//
+// Returns an error if any secret resolution fails. Partial results are not returned on error.
 func ResolveAll(vars map[string]string) (map[string]string, error) {
 	var (
 		rawVars  = make(chan variable, len(vars))

terraform/README.md

@@ -1,4 +1,4 @@
-# Cloud Infrastucture <!-- omit in toc -->
+# Cloud Infrastructure <!-- omit in toc -->
 
 This directory contains all Terraform code required to provision the cloud
 resources used to test murmur functionality.