docs(user): improve guides and add YAML support for policy config

Author: rmax

NEXT_STEPS.md

@@ -8,6 +8,7 @@
 ## Immediate Actions
 - [x] **Review Documentation**: Verify the newly created user docs in `docs/` align with the implementation and are clear.
 - [x] **M42.4 (Audit)**: Updated `docs/index.md` to link all guides (`web-ui.md`, `cli.md`) and verified `docs/installation.md` and `docs/configuration.md`.
+- [x] **M42.5 (Improvement)**: Enhanced `docs/installation.md`, switched to YAML in `docs/configuration.md` & `docs/guides/deployment.md`, and implemented YAML support in `pkg/engine`.
 - [x] **M42.3 (Refined)**: Added Policy Guide and moved/refined Deployment Guide.
 - [x] **SDK Docs**: Refreshed JS, Python, and Go SDK documentation to remove draft warnings and match implementation.
 - [ ] **Phase 16 Continues**: Run advanced simulation scenarios (Epic 28) or focus on release prep.

PROGRESS.md

@@ -84,4 +84,4 @@
 | M42.3: User Guides (CLI, Web UI, API Updates) | COMPLETED | Docs | 2026-02-07 |
 | M42.3+: Guides Refinement (Policy & Deployment) | COMPLETED | Docs | 2026-02-07 |
 | M42.3++: SDK Documentation Refresh (JS/Py/Go) | COMPLETED | Docs | 2026-02-07 |
-| M42.4: User Docs Index & Link Audit | COMPLETED | Orchestrator | 2026-02-07 |
+| M42.5: User Docs Improvement (YAML Support & Verification) | COMPLETED | Orchestrator | 2026-02-07 |

docs/configuration.md

@@ -36,39 +36,27 @@ The configuration file has four main sections:
 3.  **`pricing`**: (Optional) Defines cost models for financial governance.
 4.  **`retention`**: (Optional) Defines data lifecycle rules for events.
 
-### Example: `policy.json`
+### Example: `policy.yaml`
 
 This example tracks GitHub API limits and enforces a hard stop when the limit is exceeded.
 
-```json
-{
-  "policies": [
-    {
-      "id": "github-core-hard-limit",
-      "scope": "global",
-      "type": "hard",
-      "limit": 5000,
-      "rules": [
-        {
-          "name": "deny-exceeded-limit",
-          "condition": "remaining < 0",
-          "action": "deny",
-          "params": {
-            "reason": "hard limit exceeded for GitHub core requests"
-          }
-        }
-      ]
-    }
-  ],
-  "providers": {
-    "github": [
-      {
-        "id": "github-main",
-        "token_env_var": "GITHUB_TOKEN"
-      }
-    ]
-  }
-}
+```yaml
+policies:
+  - id: "github-core-hard-limit"
+    scope: "global"
+    type: "hard"
+    limit: 5000
+    rules:
+      - name: "deny-exceeded-limit"
+        condition: "remaining < 0"
+        action: "deny"
+        params:
+          reason: "hard limit exceeded for GitHub core requests"
+
+providers:
+  github:
+    - id: "github-main"
+      token_env_var: "GITHUB_TOKEN"
 ```
 
 ### Policy Rules
@@ -94,16 +82,12 @@ The `providers` section configures the "Ingestion Layer". It tells Ratelord how
 
 Tracks `core`, `search`, and `graphql` rate limits.
 
-```json
-"providers": {
-  "github": [
-    {
-      "id": "my-org-github",
-      "token_env_var": "GITHUB_TOKEN",
-      "enterprise_url": "https://github.example.com/api/v3" 
-    }
-  ]
-}
+```yaml
+providers:
+  github:
+    - id: "my-org-github"
+      token_env_var: "GITHUB_TOKEN"
+      enterprise_url: "https://github.example.com/api/v3"
 ```
 
 -   `token_env_var`: The environment variable containing the Personal Access Token (PAT).
@@ -113,16 +97,12 @@ Tracks `core`, `search`, and `graphql` rate limits.
 
 Tracks Request-Per-Minute (RPM) and Token-Per-Minute (TPM) limits.
 
-```json
-"providers": {
-  "openai": [
-    {
-      "id": "openai-prod",
-      "api_key_env_var": "OPENAI_API_KEY",
-      "org_id": "org-12345"
-    }
-  ]
-}
+```yaml
+providers:
+  openai:
+    - id: "openai-prod"
+      api_key_env_var: "OPENAI_API_KEY"
+      org_id: "org-12345"
 ```
 
 -   `api_key_env_var`: The environment variable containing the API Key.

docs/guides/deployment.md

@@ -9,7 +9,7 @@ This guide covers deployment via Systemd, Docker, and Kubernetes.
 - **Binary**: `ratelord-d` is a standalone Go binary.
 - **State**: Persisted to `ratelord.db` (SQLite WAL mode). **Requires a persistent filesystem.**
 - **Configuration**:
-  - `policy.json` / `policy.yaml`: Defines pools, windows, and burst limits.
+  - `policy.yaml` / `policy.yaml`: Defines pools, windows, and burst limits.
   - Environment Variables: Store sensitive tokens (e.g., `GITHUB_TOKEN`, `OPENAI_API_KEY`).
 - **Network**: Exposes an HTTP API on port `8090`.
 - **Signals**:
@@ -41,7 +41,7 @@ sudo chown ratelord:ratelord /var/lib/ratelord
 
 # Place config
 sudo mkdir -p /etc/ratelord
-sudo cp policy.json /etc/ratelord/
+sudo cp policy.yaml /etc/ratelord/
 ```
 
 ### 3.2. Unit File (`/etc/systemd/system/ratelord.service`)
@@ -57,7 +57,7 @@ Type=simple
 User=ratelord
 Group=ratelord
 # Adjust path to binary
-ExecStart=/usr/local/bin/ratelord-d --config /etc/ratelord/policy.json --db /var/lib/ratelord/ratelord.db --addr 127.0.0.1:8090
+ExecStart=/usr/local/bin/ratelord-d --config /etc/ratelord/policy.yaml --db /var/lib/ratelord/ratelord.db --addr 127.0.0.1:8090
 ExecReload=/bin/kill -HUP $MAINPID
 KillMode=process
 Restart=on-failure
@@ -102,12 +102,12 @@ WORKDIR /app
 # Install ca-certificates if ratelord needs to make outbound TLS calls (e.g. to upstream APIs)
 RUN apk add --no-cache ca-certificates
 COPY --from=builder /app/ratelord-d /usr/local/bin/
-COPY policy.json /etc/ratelord/policy.json
+COPY policy.yaml /etc/ratelord/policy.yaml
 
 # State volume
 VOLUME /data
 ENV RATELORD_DB_PATH=/data/ratelord.db
-ENV RATELORD_CONFIG_PATH=/etc/ratelord/policy.json
+ENV RATELORD_CONFIG_PATH=/etc/ratelord/policy.yaml
 ENV RATELORD_ADDR=0.0.0.0:8090
 
 CMD ["ratelord-d"]
@@ -124,7 +124,7 @@ services:
     restart: always
     volumes:
       - ratelord_data:/data
-      - ./policy.json:/etc/ratelord/policy.json:ro
+      - ./policy.yaml:/etc/ratelord/policy.yaml:ro
     environment:
       - GITHUB_TOKEN=${GITHUB_TOKEN}
       - OPENAI_API_KEY=${OPENAI_API_KEY}
@@ -168,7 +168,7 @@ spec:
           args:
             - "--addr=127.0.0.1:8090"
             - "--db=/data/ratelord.db"
-            - "--config=/etc/config/policy.json"
+            - "--config=/etc/config/policy.yaml"
           volumeMounts:
             - name: ratelord-data
               mountPath: /data
@@ -194,20 +194,20 @@ spec:
 If you run multiple replicas of `ratelord` (e.g., 3 sidecars for 3 app replicas), **state is isolated per pod**.
 - **Pros**: Zero coordination latency.
 - **Cons**: Global limits (e.g., "1000 req/min across all pods") effectively become `N * Limit`.
-- **Mitigation**: Use `policy.json` to define *per-instance* limits, or divide your global quota by the expected replica count ($Limit_{local} = Limit_{global} / N$).
+- **Mitigation**: Use `policy.yaml` to define *per-instance* limits, or divide your global quota by the expected replica count ($Limit_{local} = Limit_{global} / N$).
 
 ---
 
 ## 6. Configuration & Secrets Management
 
-### Policy (`policy.json`)
+### Policy (`policy.yaml`)
 - Treat as code. Version control it.
 - **Updates**:
   - **K8s**: Update ConfigMap -> Wait for volume update -> Send `SIGHUP` to sidecar (or let K8s restart it).
   - **Systemd**: Update file -> `systemctl reload ratelord`.
 
 ### Secrets
-- **NEVER** put tokens in `policy.json`.
+- **NEVER** put tokens in `policy.yaml`.
 - `ratelord-d` reads tokens from environment variables referenced in the policy (if feature supported) or injects them directly if acting as a proxy.
 - Use Kubernetes Secrets or `.env` files.
 

docs/installation.md

@@ -14,9 +14,18 @@ go install github.com/rmax-ai/ratelord/cmd/ratelord-d@latest
 go install github.com/rmax-ai/ratelord/cmd/ratelord-tui@latest
 ```
 
+### Verification
+
+Verify the installation by checking the versions:
+
+```bash
+ratelord version
+ratelord-d --version
+```
+
 ### From Releases
 
-Download pre-compiled binaries from the [GitHub Releases](https://github.com/rmax-ai/ratelord/releases) page.
+Download pre-compiled binaries for your platform (macOS, Linux, Windows) from the [GitHub Releases](https://github.com/rmax-ai/ratelord/releases) page.
 
 ## 2. Quickstart (Local)
 

go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/prometheus/client_golang v1.23.2
 	github.com/redis/go-redis/v9 v9.17.3
 	github.com/stretchr/testify v1.11.1
+	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
@@ -55,5 +56,4 @@ require (
 	golang.org/x/sys v0.36.0 // indirect
 	golang.org/x/text v0.28.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

pkg/engine/config.go

@@ -2,18 +2,18 @@ package engine
 
 // PolicyConfig represents the top-level structure of policy.json
 type PolicyConfig struct {
-	Policies  []PolicyDefinition          `json:"policies"`
-	Providers ProvidersConfig             `json:"providers,omitempty"`
-	Pricing   map[string]map[string]int64 `json:"pricing,omitempty"`
-	Retention *RetentionConfig            `json:"retention,omitempty"`
+	Policies  []PolicyDefinition          `json:"policies" yaml:"policies"`
+	Providers ProvidersConfig             `json:"providers,omitempty" yaml:"providers,omitempty"`
+	Pricing   map[string]map[string]int64 `json:"pricing,omitempty" yaml:"pricing,omitempty"`
+	Retention *RetentionConfig            `json:"retention,omitempty" yaml:"retention,omitempty"`
 }
 
 // RetentionConfig defines data lifecycle rules
 type RetentionConfig struct {
-	Enabled       bool              `json:"enabled"`
-	DefaultTTL    string            `json:"default_ttl"`              // e.g., "720h"
-	ByType        map[string]string `json:"by_type,omitempty"`        // event_type -> "24h"
-	CheckInterval string            `json:"check_interval,omitempty"` // e.g., "1h"
+	Enabled       bool              `json:"enabled" yaml:"enabled"`
+	DefaultTTL    string            `json:"default_ttl" yaml:"default_ttl"`                           // e.g., "720h"
+	ByType        map[string]string `json:"by_type,omitempty" yaml:"by_type,omitempty"`               // event_type -> "24h"
+	CheckInterval string            `json:"check_interval,omitempty" yaml:"check_interval,omitempty"` // e.g., "1h"
 }
 
 // GetCost looks up the cost per unit for a given provider and pool.
@@ -32,47 +32,47 @@ func (c *PolicyConfig) GetCost(providerID, poolID string) int64 {
 
 // ProvidersConfig holds configuration for various providers
 type ProvidersConfig struct {
-	GitHub []GitHubConfig `json:"github,omitempty"`
-	OpenAI []OpenAIConfig `json:"openai,omitempty"`
+	GitHub []GitHubConfig `json:"github,omitempty" yaml:"github,omitempty"`
+	OpenAI []OpenAIConfig `json:"openai,omitempty" yaml:"openai,omitempty"`
 }
 
 // GitHubConfig defines configuration for the GitHub provider
 type GitHubConfig struct {
-	ID            string `json:"id"`
-	TokenEnvVar   string `json:"token_env_var"` // Prefer env var name for security
-	EnterpriseURL string `json:"enterprise_url,omitempty"`
+	ID            string `json:"id" yaml:"id"`
+	TokenEnvVar   string `json:"token_env_var" yaml:"token_env_var"` // Prefer env var name for security
+	EnterpriseURL string `json:"enterprise_url,omitempty" yaml:"enterprise_url,omitempty"`
 }
 
 // OpenAIConfig defines configuration for the OpenAI provider
 type OpenAIConfig struct {
-	ID          string `json:"id"`
-	TokenEnvVar string `json:"token_env_var"`
-	OrgID       string `json:"org_id,omitempty"` // Optional: for 'OpenAI-Organization' header
-	BaseURL     string `json:"base_url,omitempty"`
+	ID          string `json:"id" yaml:"id"`
+	TokenEnvVar string `json:"token_env_var" yaml:"token_env_var"`
+	OrgID       string `json:"org_id,omitempty" yaml:"org_id,omitempty"` // Optional: for 'OpenAI-Organization' header
+	BaseURL     string `json:"base_url,omitempty" yaml:"base_url,omitempty"`
 }
 
 // PolicyDefinition maps a high-level policy block
 type PolicyDefinition struct {
-	ID    string           `json:"id"`
-	Scope string           `json:"scope"` // e.g., "global", "env:dev"
-	Type  string           `json:"type"`  // "hard", "soft"
-	Limit int64            `json:"limit,omitempty"`
-	Rules []RuleDefinition `json:"rules"`
+	ID    string           `json:"id" yaml:"id"`
+	Scope string           `json:"scope" yaml:"scope"` // e.g., "global", "env:dev"
+	Type  string           `json:"type" yaml:"type"`   // "hard", "soft"
+	Limit int64            `json:"limit,omitempty" yaml:"limit,omitempty"`
+	Rules []RuleDefinition `json:"rules" yaml:"rules"`
 }
 
 // RuleDefinition maps individual logic rules
 type RuleDefinition struct {
-	Name       string                 `json:"name"`
-	Condition  string                 `json:"condition"` // Simple DSL: "remaining < 100"
-	Action     string                 `json:"action"`    // "approve", "deny", "shape"
-	Params     map[string]interface{} `json:"params,omitempty"`
-	TimeWindow *TimeWindow            `json:"time_window,omitempty"`
+	Name       string                 `json:"name" yaml:"name"`
+	Condition  string                 `json:"condition" yaml:"condition"` // Simple DSL: "remaining < 100"
+	Action     string                 `json:"action" yaml:"action"`       // "approve", "deny", "shape"
+	Params     map[string]interface{} `json:"params,omitempty" yaml:"params,omitempty"`
+	TimeWindow *TimeWindow            `json:"time_window,omitempty" yaml:"time_window,omitempty"`
 }
 
 // TimeWindow defines a temporal constraint for a rule
 type TimeWindow struct {
-	StartTime string   `json:"start_time,omitempty"` // HH:MM (24-hour)
-	EndTime   string   `json:"end_time,omitempty"`   // HH:MM (24-hour)
-	Days      []string `json:"days,omitempty"`       // ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
-	Location  string   `json:"location,omitempty"`   // e.g., "America/New_York" (defaults to UTC)
+	StartTime string   `json:"start_time,omitempty" yaml:"start_time,omitempty"` // HH:MM (24-hour)
+	EndTime   string   `json:"end_time,omitempty" yaml:"end_time,omitempty"`     // HH:MM (24-hour)
+	Days      []string `json:"days,omitempty" yaml:"days,omitempty"`             // ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+	Location  string   `json:"location,omitempty" yaml:"location,omitempty"`     // e.g., "America/New_York" (defaults to UTC)
 }

pkg/engine/loader.go

@@ -3,18 +3,31 @@ package engine
 import (
 	"encoding/json"
 	"os"
+	"path/filepath"
+	"strings"
+
+	"gopkg.in/yaml.v3"
 )
 
-// LoadPolicyConfig reads and parses a policy file
+// LoadPolicyConfig reads and parses a policy file (JSON or YAML)
 func LoadPolicyConfig(path string) (*PolicyConfig, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return nil, err
 	}
 
 	var config PolicyConfig
-	if err := json.Unmarshal(data, &config); err != nil {
-		return nil, err
+	ext := strings.ToLower(filepath.Ext(path))
+
+	if ext == ".yaml" || ext == ".yml" {
+		if err := yaml.Unmarshal(data, &config); err != nil {
+			return nil, err
+		}
+	} else {
+		// Default to JSON
+		if err := json.Unmarshal(data, &config); err != nil {
+			return nil, err
+		}
 	}
 
 	return &config, nil