peg
diff --git a/‎.github/workflows/docs.yml‎
Lines changed: 8 additions & 1 deletion b/‎.github/workflows/docs.yml‎
Lines changed: 8 additions & 1 deletion
diff --git a/‎.github/workflows/render-diagrams.yml‎
Lines changed: 36 additions & 0 deletions b/‎.github/workflows/render-diagrams.yml‎
Lines changed: 36 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎README.md‎
Lines changed: 6 additions & 42 deletions b/‎README.md‎
Lines changed: 6 additions & 42 deletions
diff --git a/‎cmd/rampart/cli/cli_test.go‎
Lines changed: 6 additions & 0 deletions b/‎cmd/rampart/cli/cli_test.go‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎cmd/rampart/cli/doctor.go‎
Lines changed: 40 additions & 12 deletions b/‎cmd/rampart/cli/doctor.go‎
Lines changed: 40 additions & 12 deletions
diff --git a/‎cmd/rampart/cli/doctor_test.go‎
Lines changed: 41 additions & 1 deletion b/‎cmd/rampart/cli/doctor_test.go‎
Lines changed: 41 additions & 1 deletion
@@ -22,10 +22,17 @@ jobs:
         with:
           python-version: '3.12'
 
-      - run: pip install mkdocs-material mkdocs-minify-plugin
+      - run: pip install mkdocs-material mkdocs-minify-plugin mkdocs-d2-plugin
+
+      - name: Install D2
+        run: curl -fsSL https://d2lang.com/install.sh | sh -s --
+        env:
+          SHELL: /bin/bash
 
       - name: Build docs
         run: mkdocs build
+        env:
+          PATH: /home/runner/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 
       # Deploy to peg/rampart-docs (the repo that serves docs.rampart.sh via GitHub Pages).
       # Requires a PAT with contents:write on peg/rampart-docs stored as DOCS_DEPLOY_TOKEN.
 
@@ -0,0 +1,36 @@
+name: Render Diagrams
+
+on:
+  push:
+    branches: [main, staging]
+    paths:
+      - 'docs/architecture.d2'
+
+permissions:
+  contents: write
+
+jobs:
+  render:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install D2
+        run: curl -fsSL https://d2lang.com/install.sh | sh -s --
+        env:
+          SHELL: /bin/bash
+
+      - name: Render architecture.svg
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          d2 --theme 200 --layout elk --pad 40 \
+            docs/architecture.d2 \
+            docs/architecture.svg
+
+      - name: Commit updated SVG
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/architecture.svg
+          git diff --staged --quiet || git commit -m "chore: re-render architecture.svg from docs/architecture.d2"
+          git push
@@ -25,3 +25,4 @@ coverage.out
 .cache/
 site/
 reddit-post.md
+.home/
@@ -2,7 +2,7 @@
 
 # 🛡️ Rampart
 
-**See everything your AI agent does. Block the dangerous stuff.**
+**The security layer for AI coding agents.**
 
 [![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat&logo=go)](https://go.dev)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
@@ -14,15 +14,11 @@
 
 ---
 
-Rampart is a runtime policy engine for AI coding agents. Every tool call — bash commands, file reads, file writes, HTTP fetches — is evaluated against your YAML policies before it executes. Dangerous calls are blocked in microseconds. Everything is written to a hash-chained audit trail. Ambiguous calls can be held for human approval.
-
-It works in `--dangerously-skip-permissions` mode. [Full setup guide →](https://docs.rampart.sh/getting-started/quickstart/)
-
-### Get started in one command
+Claude Code's `--dangerously-skip-permissions` mode — and similar autonomous modes in Cursor, Cline, and Codex — give agents unrestricted shell access. Rampart sits between the agent and your system: every command, file access, and network request is evaluated against your YAML policy before it executes. Dangerous commands are blocked in microseconds. Everything is logged.
 
+One command to get protected:
 ```bash
-# Install and set up in one command:
-curl -fsSL https://rampart.sh/install | bash
+rampart setup claude-code
 ```
 
 `rampart quickstart` auto-detects Claude Code, Cursor, or Windsurf, installs `rampart serve` as a boot service, configures hooks, and runs a health check. Done.
@@ -48,39 +44,7 @@ Once running, every command Claude executes goes through Rampart's policy engine
 
 ## How it works
 
-```mermaid
-graph LR
-    subgraph "AI Agents"
-        CC[Claude Code]
-        CL[Cline]
-        OC[OpenClaw]
-        CX[Codex]
-        O[Others]
-    end
-
-    CC & CL --> H[Native Hooks]
-    OC --> S[Shell Shim]
-    CX --> P[LD_PRELOAD]
-    O --> M[MCP Proxy]
-
-    H & S & P & M --> PE[YAML Policy Eval<br/>~20μs]
-
-    PE --> AU[📋 Hash-Chained Audit<br/>Syslog · CEF · Webhooks]
-
-    AU --> PASS[✅ Execute]
-    AU --> BLOCK[❌ Blocked]
-    AU --> APR[👤 Approval]
-
-    PE -. "ambiguous ⚠️" .-> SB["⚡ rampart-verify<br/>(optional sidecar)<br/>gpt-4o-mini · Haiku · Ollama"]
-    SB -. allow/deny .-> PE
-
-    style PE fill:#238636,stroke:#fff,color:#fff
-    style AU fill:#1f6feb,stroke:#fff,color:#fff
-    style BLOCK fill:#da3633,stroke:#fff,color:#fff
-    style APR fill:#d29922,stroke:#fff,color:#fff
-    style PASS fill:#238636,stroke:#fff,color:#fff
-    style SB fill:#2d333b,stroke:#f0883e,stroke-width:2px,stroke-dasharray: 5 5
-```
+<img src="docs/architecture.svg" alt="Rampart architecture — agents flow through interception layer into policy engine, with audit trail and outcomes" width="100%">
 
 *Pattern matching handles 95%+ of decisions in microseconds. The optional [rampart-verify](https://github.com/peg/rampart-verify) sidecar adds LLM-based classification for ambiguous commands. All decisions go to a hash-chained audit trail.*
 
@@ -419,7 +383,7 @@ graph LR
     D -->|Webhook| WH["Signed URL<br/>(click to approve)"]
     D -->|CLI / API| CLI["rampart approve &lt;id&gt;"]
 
-    CC -->|user responds| R[✅ Resolved]
+    CC -->|user responds| R[Resolved]
     MCP -->|via API / dashboard| R
     OC -->|via API| R
     WH -->|HMAC-verified link| R
 
@@ -35,6 +35,12 @@ func TestVersionCommand(t *testing.T) {
 	assert.Contains(t, stdout, "rampart "+build.Version)
 }
 
+func TestVersionFlag(t *testing.T) {
+	stdout, _, err := runCLI(t, "--version")
+	require.NoError(t, err)
+	assert.Contains(t, stdout, "rampart "+build.Version)
+}
+
 func TestInitCreatesFile(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
 
@@ -131,7 +131,9 @@ func runDoctor(w io.Writer, jsonOut bool) error {
 	issues += doctorHooks(emit)
 
 	// 7. Audit directory
-	issues += doctorAudit(emit)
+	auditIssues, auditWarnings := doctorAudit(emit)
+	issues += auditIssues
+	warnings += auditWarnings
 
 	// 8. Server running on default port
 	serverIssues, serveURL := doctorServer(emit)
@@ -457,15 +459,15 @@ func doctorHooks(emit emitFn) int {
 				if count > 0 {
 					emit("Hooks", "ok", fmt.Sprintf("Claude Code (%d matchers in settings.json)", count))
 				} else {
-					emit("Hooks", "fail", "Claude Code (no Rampart hooks in settings.json)")
+					emit("Hooks", "fail", fmt.Sprintf("Claude Code hook not installed - expected hook in %s\n  Run: rampart setup claude-code", claudeSettingsPath))
 					issues++
 				}
 			} else {
-				emit("Hooks", "fail", "Claude Code (invalid settings.json)")
+				emit("Hooks", "fail", fmt.Sprintf("Claude Code settings invalid at %s\n  Run: rampart setup claude-code", claudeSettingsPath))
 				issues++
 			}
 		} else {
-			emit("Hooks", "fail", "Claude Code (no settings.json found)")
+			emit("Hooks", "fail", fmt.Sprintf("Claude Code hook not installed - expected hook in %s\n  Run: rampart setup claude-code", claudeSettingsPath))
 			issues++
 		}
 	}
@@ -484,11 +486,11 @@ func doctorHooks(emit emitFn) int {
 			if hookCount > 0 {
 				emit("Hooks", "ok", fmt.Sprintf("Cline (%d hook scripts)", hookCount))
 			} else {
-				emit("Hooks", "fail", "Cline (no Rampart hooks found)")
+				emit("Hooks", "fail", fmt.Sprintf("Cline hook not installed - expected Rampart hook scripts in %s\n  Run: rampart setup cline", clineDir))
 				issues++
 			}
 		} else {
-			emit("Hooks", "fail", "Cline (no Hooks directory found)")
+			emit("Hooks", "fail", fmt.Sprintf("Cline hook not installed - expected Rampart hook scripts in %s\n  Run: rampart setup cline", clineDir))
 			issues++
 		}
 	}
@@ -533,24 +535,24 @@ func countClaudeHookMatchers(settings map[string]any) int {
 	return count
 }
 
-func doctorAudit(emit emitFn) int {
+func doctorAudit(emit emitFn) (issues int, warnings int) {
 	home, err := os.UserHomeDir()
 	if err != nil {
-		return 0
+		return 0, 0
 	}
 	auditDir := filepath.Join(home, ".rampart", "audit")
 
 	entries, err := os.ReadDir(auditDir)
 	if err != nil {
 		emit("Audit", "fail", fmt.Sprintf("%s (not found)", auditDir))
-		return 1
+		return 1, 0
 	}
 
 	// Check writable
 	testFile := filepath.Join(auditDir, ".doctor-write-test")
 	if err := os.WriteFile(testFile, []byte("test"), 0o600); err != nil {
 		emit("Audit", "fail", fmt.Sprintf("%s (not writable)", auditDir))
-		return 1
+		return 1, 0
 	}
 	// Defer removal so the temp file is cleaned up on every exit path,
 	// including early returns and panics, not just the happy path.
@@ -566,7 +568,7 @@ func doctorAudit(emit emitFn) int {
 
 	if len(files) == 0 {
 		emit("Audit", "ok", fmt.Sprintf("~/%s (0 files)", relHome(auditDir, home)))
-		return 0
+		return 0, 0
 	}
 
 	// Find latest modification time
@@ -579,7 +581,33 @@ func doctorAudit(emit emitFn) int {
 	}
 
 	emit("Audit", "ok", fmt.Sprintf("~/%s (%d files, latest: %s)", relHome(auditDir, home), len(files), latest))
-	return 0
+
+	worldReadable := make([]string, 0, 4)
+	_ = filepath.WalkDir(auditDir, func(path string, d os.DirEntry, walkErr error) error {
+		if walkErr != nil || d.IsDir() {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return nil
+		}
+		if info.Mode().Perm()&0o004 != 0 {
+			if len(worldReadable) < 3 {
+				worldReadable = append(worldReadable, relHome(path, home))
+			}
+			warnings++
+		}
+		return nil
+	})
+	if warnings > 0 {
+		sample := strings.Join(worldReadable, ", ")
+		msg := fmt.Sprintf("%d world-readable audit file(s) found", warnings)
+		if sample != "" {
+			msg += fmt.Sprintf(" (e.g. ~/%s)", sample)
+		}
+		emit("Audit perms", "warn", msg)
+	}
+	return 0, warnings
 }
 
 func doctorVersionCheck(w io.Writer, silent bool, emit emitFn) int {
 
@@ -17,12 +17,13 @@ import (
 	"bytes"
 	"encoding/json"
 	"errors"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
 )
 
-
 func TestRunDoctor(t *testing.T) {
 	var buf bytes.Buffer
 	err := runDoctor(&buf, false)
@@ -159,3 +160,42 @@ func TestDoctorToken_Missing(t *testing.T) {
 	// Just verify no panic.
 	_, _ = doctorToken(emit)
 }
+
+func TestDoctorHooks_PathHints(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	claudeDir := filepath.Join(home, ".claude")
+	requireNoErr(t, os.MkdirAll(claudeDir, 0o755))
+	requireNoErr(t, os.WriteFile(filepath.Join(claudeDir, "settings.json"), []byte(`{"hooks":{}}`), 0o644))
+
+	clineHooksDir := filepath.Join(home, "Documents", "Cline", "Hooks")
+	requireNoErr(t, os.MkdirAll(clineHooksDir, 0o755))
+
+	var results []checkResult
+	emit := func(name, status, msg string) {
+		results = append(results, checkResult{Name: name, Status: status, Message: msg})
+	}
+	issues := doctorHooks(emit)
+	if issues != 2 {
+		t.Fatalf("expected 2 issues, got %d (%+v)", issues, results)
+	}
+
+	out := ""
+	for _, r := range results {
+		out += r.Message + "\n"
+	}
+	if !strings.Contains(out, filepath.Join(home, ".claude", "settings.json")) {
+		t.Fatalf("expected Claude settings path in output, got: %s", out)
+	}
+	if !strings.Contains(out, filepath.Join(home, "Documents", "Cline", "Hooks")) {
+		t.Fatalf("expected Cline hooks path in output, got: %s", out)
+	}
+}
+
+func requireNoErr(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatal(err)
+	}
+}
-Original file line number
+Diff line change
 .cache/
 site/
 reddit-post.md
 +.home/