Add top-level README and setup validation script

- README.md: Comprehensive overview of the configuration
  - Quick start guide
  - Feature summary
  - Directory structure
  - Key commands and skills
  - Maintenance commands

- automation/validate-setup.sh: Validation script that checks:
  - Directory structure
  - Core files
  - Plugin manifest
  - Hooks configuration and executability
  - Skills and their scripts
  - State files (JSON validity)
  - Gmail integration
  - Documentation coverage

Run with: ~/.claude/automation/validate-setup.sh

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,130 @@
+# Will's Claude Code Configuration
+
+Personal assistant and multi-agent system for homelab management.
+
+## Quick Start
+
+```bash
+# Start a session
+claude
+
+# Use the personal assistant
+/pa what's on my calendar today?
+
+# Check system health
+/sysadmin:health
+
+# Check cluster status
+/k8s:cluster-status
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Personal Assistant** | Natural language interface via `/pa` |
+| **Gmail Integration** | Read emails, check urgent, search |
+| **Calendar Integration** | View agenda, check schedule |
+| **Kubernetes Management** | Cluster health, deployments, diagnostics |
+| **System Administration** | Health checks, updates, autonomy control |
+| **Usage Tracking** | Session statistics and history |
+
+## Directory Structure
+
+```
+~/.claude/
+├── .claude-plugin/      # Plugin manifest (for distribution)
+├── agents/              # Agent persona definitions
+├── automation/          # Systemd timers, scripts
+├── commands/            # Slash commands (/pa, /gcal, etc.)
+├── hooks/               # Event handlers (SessionStart, PreCompact)
+├── mcp/                 # MCP integrations (Gmail, delegation)
+├── skills/              # Agent skills (gmail, gcal, k8s, sysadmin)
+├── state/               # Shared state files (JSON)
+├── workflows/           # Workflow definitions (design docs)
+├── CLAUDE.md            # Shared memory for all agents
+└── README.md            # This file
+```
+
+Each directory has its own README with details.
+
+## Key Commands
+
+| Command | Description |
+|---------|-------------|
+| `/pa <request>` | Natural language request to personal assistant |
+| `/gcal [today\|tomorrow\|week]` | Calendar agenda |
+| `/usage [today\|week\|month]` | Usage statistics |
+| `/sysadmin:health` | System health check |
+| `/sysadmin:update` | Package updates |
+| `/k8s:cluster-status` | Kubernetes health |
+| `/k8s:diagnose` | Troubleshoot K8s issues |
+
+## Skills (Auto-Invoked)
+
+Skills are triggered automatically based on your request:
+
+| Trigger | Skill |
+|---------|-------|
+| "check my email" | gmail |
+| "what's on today" | gcal |
+| "cluster status" | k8s-quick-status |
+| "system health" | sysadmin-health |
+| "usage stats" | usage |
+
+## Hooks
+
+| Event | Action |
+|-------|--------|
+| Session Start | Load context, check pending items |
+| Pre-Compact | Remind to preserve important context |
+
+## Agent Hierarchy
+
+```
+Personal Assistant (Opus)
+└── Master Orchestrator (Opus)
+    ├── linux-sysadmin (Sonnet)
+    ├── k8s-orchestrator (Opus)
+    │   └── k8s-diagnostician, argocd-operator, etc.
+    └── programmer-orchestrator (Opus)
+        └── code-planner, code-implementer, code-reviewer
+```
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Shared instructions for all agents |
+| `settings.json` | Claude Code settings |
+| `state/component-registry.json` | Routing and discovery |
+| `state/autonomy-levels.json` | Permission levels |
+
+## Plugin Installation
+
+This configuration can be installed as a plugin:
+
+```bash
+# Add as local marketplace
+/plugin marketplace add ~/.claude
+
+# Install
+/plugin install will-homelab@will-homelab-dev
+```
+
+## Maintenance
+
+```bash
+# Validate component registry
+python3 ~/.claude/automation/validate-registry.py
+
+# Regenerate registry from files
+python3 ~/.claude/automation/generate-registry.py
+
+# Check systemd timers
+systemctl --user list-timers
+```
+
+## License
+
+MIT