docs(integration): add integration guide and working examples

Add comprehensive documentation for using kspec as a Discovery Tool
and Check Engine, covering both CLI and Go API usage patterns.

- Add docs/integration.md with Discovery, Check Engine, Scoring,
  Reports, CI/CD, and Provider Registration sections
- Add _examples/ with working Go examples (discovery, check-engine)
- Add CI/CD templates (GitHub Actions, GitLab CI, shell wrapper)
- Add minimal policy files for TLS and GitHub providers
- Update docs/README.md with Integration section

Author: juliankoehn

_examples/README.md

@@ -0,0 +1,80 @@
+# kspec Examples
+
+Working examples that demonstrate how to use kspec as a **Discovery Tool** and as a **Check Engine**, both via CLI and Go API.
+
+## Quick Start
+
+All Go examples live in the main module — no separate `go.mod` needed:
+
+```bash
+# From the repository root:
+go run ./_examples/discovery/basic/ example.com
+```
+
+## Examples
+
+### Discovery (Go API)
+
+| Example | Description | Run |
+|---------|-------------|-----|
+| [discovery/basic](discovery/basic/) | `discovery.Discover()` with table output | `go run ./_examples/discovery/basic/ example.com` |
+| [discovery/inventory](discovery/inventory/) | `discovery.QuickInventory()` → JSON | `go run ./_examples/discovery/inventory/ example.com` |
+| [discovery/graph](discovery/graph/) | `discovery.DiscoverWithInstances()` + graph export | `go run ./_examples/discovery/graph/ example.com` |
+
+### Check Engine (Go API)
+
+| Example | Description | Run |
+|---------|-------------|-----|
+| [check-engine/basic](check-engine/basic/) | End-to-end scan with `scanner.NewScanner()` | `go run ./_examples/check-engine/basic/ example.com` |
+| [check-engine/advanced](check-engine/advanced/) | Events, scoring, JSON/CSV report export | `go run ./_examples/check-engine/advanced/ example.com` |
+
+### CI/CD
+
+| File | Description |
+|------|-------------|
+| [ci-cd/github-actions.yml](ci-cd/github-actions.yml) | GitHub Actions workflow |
+| [ci-cd/gitlab-ci.yml](ci-cd/gitlab-ci.yml) | GitLab CI pipeline |
+| [ci-cd/scan.sh](ci-cd/scan.sh) | Shell script wrapper |
+
+### Policies
+
+| File | Description |
+|------|-------------|
+| [policies/minimal-tls.yaml](policies/minimal-tls.yaml) | Minimal TLS policy (3 checks) |
+| [policies/minimal-github.yaml](policies/minimal-github.yaml) | Minimal GitHub org policy (3 checks) |
+
+## Provider Registration
+
+Every Go example that uses kspec must import the provider registration package:
+
+```go
+import (
+    _ "github.com/kopexa-grc/kspec/provider/all"
+)
+```
+
+This blank import triggers `init()` functions that register all providers (network, GitHub, AWS, Azure, etc.). Without it, `discovery.Discover()` and `scanner.NewScanner()` will fail because no providers are available.
+
+If you only need a specific provider, import it directly:
+
+```go
+import (
+    _ "github.com/kopexa-grc/kspec/provider/network"
+)
+```
+
+## Using Examples as Standalone Projects
+
+To use an example outside the kspec repository, create your own module:
+
+```bash
+mkdir my-scanner && cd my-scanner
+go mod init my-scanner
+go get github.com/kopexa-grc/kspec@latest
+```
+
+Then copy the example `main.go` and run it:
+
+```bash
+go run . example.com
+```

_examples/check-engine/advanced/main.go

@@ -0,0 +1,137 @@
+// Copyright (c) Kopexa GmbH
+// SPDX-License-Identifier: Elastic-2.0
+
+// Example: Advanced scanner with events, scoring, and report export.
+//
+// This example demonstrates:
+//   - Listening to scan events for progress tracking
+//   - Using the scoring API (NewGraphScorer + ScoreTree)
+//   - Exporting reports to JSON and CSV
+//
+// Usage:
+//
+//	go run ./_examples/check-engine/advanced/ example.com
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/kopexa-grc/kspec/core"
+	"github.com/kopexa-grc/kspec/policy"
+	"github.com/kopexa-grc/kspec/policy/scoring"
+	"github.com/kopexa-grc/kspec/provider/scanner"
+	"github.com/kopexa-grc/kspec/report"
+
+	// IMPORTANT: Register all providers via blank import.
+	_ "github.com/kopexa-grc/kspec/provider/all"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Fprintf(os.Stderr, "Usage: %s <domain>\n", os.Args[0])
+		os.Exit(1)
+	}
+
+	target := os.Args[1]
+	ctx := context.Background()
+
+	// --- Load policy ---
+	policyPath := policyFile()
+
+	policies, err := policy.Load(policyPath, "")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to load policy: %v\n", err)
+		os.Exit(1)
+	}
+
+	policies = policy.FilterByProvider(policies, "network", "network")
+
+	// --- Create scanner ---
+	s := scanner.NewScanner(scanner.ScanConfig{
+		ProviderName:   "network",
+		ProviderConfig: map[string]string{"target": target},
+		Asset: core.Asset{
+			Type:   "host",
+			Name:   target,
+			Config: map[string]string{"target": target},
+		},
+		Policies: policies,
+	})
+
+	// --- Listen to events ---
+	s.OnEvent(func(event scanner.ScanEvent) {
+		switch event.Type {
+		case scanner.EventDiscoveryStarted:
+			fmt.Fprintln(os.Stderr, "[event] Discovery started")
+		case scanner.EventDiscoveryComplete:
+			fmt.Fprintln(os.Stderr, "[event] Discovery complete")
+		case scanner.EventScanStarted:
+			fmt.Fprintln(os.Stderr, "[event] Scan started")
+		case scanner.EventResourceScanning:
+			fmt.Fprintf(os.Stderr, "[event] Scanning: %s\n", event.ResourceType)
+		case scanner.EventResourceComplete:
+			fmt.Fprintf(os.Stderr, "[event] Complete: %s\n", event.ResourceType)
+		case scanner.EventScanComplete:
+			fmt.Fprintln(os.Stderr, "[event] Scan complete")
+		case scanner.EventError:
+			fmt.Fprintf(os.Stderr, "[event] Error: %v\n", event.Error)
+		}
+	})
+
+	// --- Initialize and run ---
+	if err := s.Initialize(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "Initialize failed: %v\n", err)
+		os.Exit(1)
+	}
+
+	result := s.Run(ctx)
+	for _, scanErr := range result.Errors {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", scanErr)
+	}
+
+	if result.Tree == nil || result.Tree.Root == nil {
+		fmt.Fprintln(os.Stderr, "No results.")
+		os.Exit(1)
+	}
+
+	// --- Scoring ---
+	scorer := scoring.NewGraphScorer(scoring.SystemBanded)
+	score := scorer.ScoreTree(result.Tree)
+	findings := scorer.GetRootFindings(result.Tree)
+
+	fmt.Println("\n=== Score Summary ===")
+	fmt.Printf("Score:      %d/100\n", score.Value)
+	fmt.Printf("Grade:      %s\n", score.Grade)
+	fmt.Printf("Risk Level: %s\n", score.RiskLevel)
+	fmt.Printf("Findings:   %d critical, %d high, %d medium, %d low\n",
+		findings.Critical, findings.High, findings.Medium, findings.Low)
+
+	// --- Export reports ---
+	rep := report.FromResourceTreeWithScoring(result.Tree, "network", scoring.SystemBanded)
+
+	// JSON report
+	jsonPath := "report.json"
+	if err := report.NewJSONExporter(true).Export(rep, jsonPath); err != nil {
+		fmt.Fprintf(os.Stderr, "JSON export failed: %v\n", err)
+	} else {
+		fmt.Printf("\nJSON report: %s\n", jsonPath)
+	}
+
+	// CSV report
+	csvPath := "report.csv"
+	if err := report.NewCSVExporter().Export(rep, csvPath); err != nil {
+		fmt.Fprintf(os.Stderr, "CSV export failed: %v\n", err)
+	} else {
+		fmt.Printf("CSV report:  %s\n", csvPath)
+	}
+}
+
+// policyFile returns the path to the bundled policy.yaml next to this example.
+func policyFile() string {
+	_, filename, _, _ := runtime.Caller(0)
+	return filepath.Join(filepath.Dir(filename), "policy.yaml")
+}

_examples/check-engine/advanced/policy.yaml

@@ -0,0 +1,58 @@
+apiVersion: kspec/v1
+kind: Policy
+metadata:
+  name: advanced-scan-example
+  version: "1.0.0"
+
+scoring_system: banded
+
+require:
+  - provider: network
+
+groups:
+  - title: TLS Security
+    checks:
+      - uid: tls-modern-version
+      - uid: tls-no-legacy
+      - uid: tls-cert-trusted
+      - uid: tls-cert-not-expiring
+
+  - title: HTTP Security Headers
+    checks:
+      - uid: http-hsts
+
+queries:
+  - uid: tls-modern-version
+    title: TLS 1.2 or higher is supported
+    resource: tls
+    severity: high
+    query: resource.versions.exists(v, v == "tls1.2") || resource.versions.exists(v, v == "tls1.3")
+    remediation: Enable TLS 1.2 or 1.3 on your server.
+
+  - uid: tls-no-legacy
+    title: Legacy TLS versions (1.0, 1.1) are disabled
+    resource: tls
+    severity: medium
+    query: "!resource.versions.exists(v, v == \"tls1.0\") && !resource.versions.exists(v, v == \"tls1.1\")"
+    remediation: Disable TLS 1.0 and TLS 1.1 in your server configuration.
+
+  - uid: tls-cert-trusted
+    title: Certificate chain is trusted
+    resource: tls
+    severity: critical
+    query: resource.certificates.size() > 0 && resource.certificates[0].isVerified == true
+
+  - uid: tls-cert-not-expiring
+    title: Certificate expires in more than 30 days
+    resource: tls
+    severity: medium
+    query: resource.certificates.size() > 0 && resource.certificates[0].expiresIn.days > 30
+
+  - uid: http-hsts
+    title: HTTP Strict-Transport-Security header is present
+    resource: http
+    severity: medium
+    query: has(resource.headers) && "Strict-Transport-Security" in resource.headers
+    remediation: |
+      Add the `Strict-Transport-Security` response header to enforce HTTPS.
+      Example: `Strict-Transport-Security: max-age=31536000; includeSubDomains`

_examples/check-engine/basic/main.go

@@ -0,0 +1,110 @@
+// Copyright (c) Kopexa GmbH
+// SPDX-License-Identifier: Elastic-2.0
+
+// Example: Basic scanner API usage (end-to-end scan).
+//
+// This example loads a policy, creates a scanner, and runs a full
+// scan against a network host. Results are printed as a summary.
+//
+// Usage:
+//
+//	go run ./_examples/check-engine/basic/ example.com
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/kopexa-grc/kspec/core"
+	"github.com/kopexa-grc/kspec/policy"
+	"github.com/kopexa-grc/kspec/policy/scoring"
+	"github.com/kopexa-grc/kspec/provider/scanner"
+	"github.com/kopexa-grc/kspec/report"
+
+	// IMPORTANT: Register all providers via blank import.
+	_ "github.com/kopexa-grc/kspec/provider/all"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Fprintf(os.Stderr, "Usage: %s <domain>\n", os.Args[0])
+		os.Exit(1)
+	}
+
+	target := os.Args[1]
+	ctx := context.Background()
+
+	// --- Step 1: Load policy ---
+	policyPath := policyFile()
+
+	policies, err := policy.Load(policyPath, "")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to load policy: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Filter policies for the network provider.
+	policies = policy.FilterByProvider(policies, "network", "network")
+	if len(policies) == 0 {
+		fmt.Fprintf(os.Stderr, "No policies found for network provider\n")
+		os.Exit(1)
+	}
+
+	// --- Step 2: Create scanner ---
+	s := scanner.NewScanner(scanner.ScanConfig{
+		ProviderName:   "network",
+		ProviderConfig: map[string]string{"target": target},
+		Asset: core.Asset{
+			Type:   "host",
+			Name:   target,
+			Config: map[string]string{"target": target},
+		},
+		Policies: policies,
+	})
+
+	// --- Step 3: Initialize provider ---
+	if err := s.Initialize(ctx); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to initialize: %v\n", err)
+		os.Exit(1)
+	}
+
+	// --- Step 4: Run scan ---
+	result := s.Run(ctx)
+
+	// Print errors if any.
+	for _, scanErr := range result.Errors {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", scanErr)
+	}
+
+	if result.Tree == nil || result.Tree.Root == nil {
+		fmt.Fprintln(os.Stderr, "No results.")
+		os.Exit(1)
+	}
+
+	// --- Step 5: Score and report ---
+	rep := report.FromResourceTreeWithScoring(result.Tree, "network", scoring.SystemBanded)
+
+	fmt.Printf("Target:  %s\n", rep.Metadata.ScanTarget)
+	fmt.Printf("Score:   %d/100 (Grade: %s)\n", rep.Metadata.Score, rep.Metadata.Grade)
+	fmt.Printf("Risk:    %s\n", rep.Metadata.RiskLevel)
+	fmt.Printf("Checks:  %d total, %d passed, %d failed, %d skipped\n",
+		rep.Metadata.TotalChecks,
+		rep.Metadata.PassedChecks,
+		rep.Metadata.FailedChecks,
+		rep.Metadata.SkippedCheck,
+	)
+
+	// Exit with non-zero code if there are failed checks.
+	if rep.Metadata.FailedChecks > 0 {
+		os.Exit(2)
+	}
+}
+
+// policyFile returns the path to the bundled policy.yaml next to this example.
+func policyFile() string {
+	_, filename, _, _ := runtime.Caller(0)
+	return filepath.Join(filepath.Dir(filename), "policy.yaml")
+}