improved docs

Author: graz-dev

.gitignore

@@ -23,7 +23,7 @@ go.work
 kalco-dump-*/
 kalco-dump-*
 guestbook-exports/
-
+demos/
 
 # IDE files
 .vscode/

demos/gitops-validation/helm/.github/workflows/validation.yaml

@@ -16,11 +16,11 @@ jobs:
       - name: Checkout Source Code
         uses: actions/checkout@v3
 
-          # Install Tools
+      - name: Install Tools
         run: |
           curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
           # Install Kalco
-          curl -sL https://github.com/graz-dev/kalco/releases/download/v0.1.21/kalco_Linux_x86_64.tar.gz | tar xz
+          curl -sL https://github.com/graz-dev/kalco/releases/latest/download/kalco_Linux_x86_64.tar.gz | tar xz
           sudo mv kalco /usr/local/bin/
 
       - name: Configure Kalco

docs/commands/diff.md

@@ -33,40 +33,29 @@ kalco diff [flags]
 | `--snapshot-dir` | Root directory of snapshot repository | - | Yes |
 | `--refresh` | Fetch live resource from K8s via export | `false` | No |
 | `--format` | Output format (`text`, `markdown`) | `text` | No |
+| `--namespace` | Override namespace for local resources | - | No |
+| `--ignore-base` | Path to base manifest (from destination branch) for Smart Drift Detection | - | No |
+| `--ignore-extra-fields` | Ignore K8s default fields missing from local manifest | `false` | No |
 
-## Usage Examples
+## Advanced Features
 
-### Basic Diff
+### Smart Drift Detection (`--ignore-base`)
 
-Compare a local deployment file against the existing snapshot:
+When validating a Pull Request, you often have changes that are *intentional*. 
+- **Snapshot**: Old State
+- **Base Branch**: Current State
+- **PR Branch**: New State
 
-```bash
-kalco diff \
-  --target ./charts/my-app/deployment.yaml \
-  --snapshot-dir ./cluster-exports
-```
-
-### Diff with Live Refresh
+If you just diff **PR vs Snapshot**, you see *all* differences.
+By providing `--ignore-base <path-to-file-in-base-branch>`, Kalco calculates:
+`(Base -> PR)` changes are **INTENTIONAL**.
+It then masks these changes when comparing **(PR vs Snapshot)**.
+Result: You *only* see drift (unexpected changes), not your PR changes.
 
-Update the snapshot from the cluster (via export) before performing the diff. This ensures you are comparing against the latest live state.
-
-```bash
-kalco diff \
-  --target ./charts/my-app/deployment.yaml \
-  --snapshot-dir ./cluster-exports \
-  --refresh
-```
-
-### Markdown Output
-
-Generate a Markdown-formatted diff, useful for automated CI/CD pipelines (e.g., GitHub Actions PR comments):
-
-```bash
-kalco diff \
-  --target ./charts/my-app/deployment.yaml \
-  --snapshot-dir ./cluster-exports \
-  --format markdown
-```
+### Ignore Defaults (`--ignore-extra-fields`)
+Kubernetes often adds default fields (e.g., `dnsPolicy`, `strategy`, `revisionHistoryLimit`).
+If your local manifest doesn't specify them, a strict diff shows them as specific values on the cluster vs missing locally.
+Use `--ignore-extra-fields` to ensure Kalco only validates fields *you explicitly defined*.
 
 ## Output Explained
 

docs/commands/validate.md

@@ -0,0 +1,72 @@
+---
+layout: default
+title: kalco validate
+nav_order: 4
+parent: Commands Reference
+---
+
+# Validate Command
+
+The `kalco validate` command is a high-level wrapper designed specifically for **CI/CD Pipelines**. It automates the entire drift detection workflow for Pulse/Merge Requests.
+
+## Overview
+
+Unlike `kalco diff`, which compares a single file, `kalco validate`:
+1.  **Auto-Detects Changes**: Finds which manifests changed between your current branch and the base branch (e.g., `origin/master`).
+2.  **Fetches Base Content**: Automatically retrieves the "before" state of files from git to enable [Smart Drift Detection]({{ site.baseurl }}/commands/diff#smart-drift-detection---ignore-base).
+3.  **Generates Report**: Produces a consolidated Markdown report of all validations.
+4.  **Ignores Defaults**: Automatically enables `--ignore-extra-fields` to reduce noise.
+
+## Syntax
+
+```bash
+kalco validate [flags]
+```
+
+## Flags
+
+| Flag | Description | Default | Required |
+|------|-------------|---------|----------|
+| `--base` | Base branch/ref to compare against | `origin/master` | No |
+| `--snapshot-dir` | Directory containing snapshots | - | Yes |
+| `--dirs` | Directories to scan for changes | `.` | No |
+| `--namespace` | Override namespace for resources | - | No |
+| `--report-file` | File path to write Markdown report to | - | No |
+
+## Usage Examples
+
+### Basic CI Integration (GitHub Actions)
+
+In a GitHub Action workflow, use `kalco validate` to check changed manifests:
+
+```bash
+kalco validate \
+  --base origin/${{ github.base_ref }} \
+  --dirs manifests \
+  --snapshot-dir tmp-snapshot \
+  --report-file report.md
+```
+
+This single command replaces complex bash scripting loops.
+
+### Local Validation
+
+You can also run it locally to verify your changes before pushing:
+
+```bash
+# Validate changes in 'charts/' against 'main'
+kalco validate \
+  --base origin/main \
+  --dirs charts \
+  --snapshot-dir ./cluster-backup
+```
+
+## How it works (Under the hood)
+
+1.  **Git Diff**: Runs `git diff --name-only <base> -- <dirs>` to find changed YAML files.
+2.  **Loop**: Iterates through each file.
+3.  **Load Base**: Runs `git show <base>:<file>` to get the original content.
+4.  **Kalco Diff**: Runs `kalco diff` using the local file, the fetched base content (as `--ignore-base`), and the snapshot.
+5.  **Report**: Aggregates the results into a single output.
+
+If **Drift** is detected (changes that are *not* in your PR intent), the command exits with code 1.

docs/index.md

@@ -8,13 +8,23 @@ nav_order: 1
 
 Welcome to the official documentation for **Kalco** (Kubernetes Analysis & Lifecycle Control).
 
-Kalco is the CLI tool that bridges the gap between your Git configuration and your actual Kubernetes cluster state.
+Kalco is a powerful CLI tool designed to bridge the gap between your Git configuration (Intent) and your running Kubernetes cluster (Reality). It provides a robust workflow for **Snapshotting**, **Diffing**, and **Validating** cluster state.
 
 ## 🌟 Why Kalco?
 
-- **Backup & Audit**: Snapshot your entire cluster to Git-friendly YAML.
-- **GitOps Validation**: Detect "drift" between what you *think* is deployed (Git) and what *is* deployed (Cluster).
-- **Environment Management**: Switch context configurations easily between Prod, Staging, and Dev.
+In complex Kubernetes environments, "Drift" is inevitable. Someone patches a deployment manually, a controller adds default fields, or a Helm chart renders differently than expected. Kalco solves this by:
+
+- **📸 Snapshotting**: Exporting your entire cluster state into clean, Git-friendly YAML files.
+- **🔍 Diffing**: performing "Smart Diffs" that ignore noise (like timestamps, `managedFields`, and dynamic status) to show only *real* changes.
+- **🛡️ Validating**: Integrating into CI/CD pipelines to prevent drift *before* it merges.
+
+## 🏗️ How It Works
+
+Kalco operates on a simple but powerful loop:
+
+1.  **Export**: `kalco export` connects to your cluster and downloads resources, stripping away runtime noise to create a "Golden Snapshot".
+2.  **Compare**: `kalco diff` compares your local manifests (or Helm charts) against this snapshot.
+3.  **Validate**: `kalco validate` automates this process in CI, fetching the base branch, detecting changed files, and verifying that your PR matches the cluster state (or intended changes).
 
 ## 🚀 Getting Started
 
@@ -36,18 +46,22 @@ curl -fsSL https://raw.githubusercontent.com/graz-dev/kalco/master/scripts/insta
 2.  **[Export Resources]({{ site.baseurl }}/commands/export)**: Take your first snapshot.
 3.  **[Verify Drift]({{ site.baseurl }}/commands/diff)**: Compare your local manifests against the snapshot.
 
-## 📚 Command Reference
+## 📚 Documentation Sections
 
-| Command | Purpose |
-|---------|---------|
-| **[context]({{ site.baseurl }}/commands/context)** | Manage cluster connections and output settings. |
-| **[export]({{ site.baseurl }}/commands/export)** | Dump cluster state to local files. |
-| **[diff]({{ site.baseurl }}/commands/diff)** | **[NEW]** Compare local YAML vs Snapshot/Live state. |
-| **version** | Check version information. |
+### Command Reference
+Deep dive into every command and flag.
+
+- **[context]({{ site.baseurl }}/commands/context)**: Manage cluster connections.
+- **[export]({{ site.baseurl }}/commands/export)**: Snapshot cluster state.
+- **[diff]({{ site.baseurl }}/commands/diff)**: Compare local files vs cluster.
+- **[validate]({{ site.baseurl }}/commands/validate)**: **[NEW]** Automated CI/CD drift detection.
+
+### Tutorials & Use Cases
+Real-world examples of Kalco in action.
+
+- **[GitOps Validation Pipeline]({{ site.baseurl }}/tutorials/gitops-validation)**: A complete walkthrough of setting up a Drift Detection Pipeline for raw manifests using GitHub Actions and ArgoCD.
 
 ## 🤝 Support & Contributing
 
 - **Issues**: [GitHub Issues](https://github.com/graz-dev/kalco/issues)
 - **Repo**: [github.com/graz-dev/kalco](https://github.com/graz-dev/kalco)
-
-Is something missing in these docs? [Edit this page on GitHub](https://github.com/graz-dev/kalco/edit/master/docs/index.md).