diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..261adf2
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,116 @@
+# Contributing to Obsidian + Claude Code PKM
+
+Thanks for your interest in contributing! This project aims to be the best AI-powered accountability system for Obsidian, and community contributions make it better for everyone.
+
+## Ways to Contribute
+
+### Report Bugs
+- Open an [issue](https://github.com/ballred/obsidian-claude-pkm/issues/new) with steps to reproduce
+- Include your OS, Claude Code version, and relevant vault structure
+
+### Suggest Features
+- Open an issue with the `enhancement` label
+- Describe the problem you're solving, not just the solution
+- Bonus: explain how it connects to the goal cascade
+
+### Submit Code
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/my-improvement`)
+3. Make your changes in `vault-template/`
+4. Test by copying to a fresh vault and running the affected skills
+5. Commit with a clear message
+6. Open a PR against `main`
+
+### Improve Documentation
+- Fix typos, clarify instructions, add examples
+- Documentation PRs are always welcome and easy to review
+
+## Good First Issues
+
+Look for issues labeled [`good first issue`](https://github.com/ballred/obsidian-claude-pkm/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). These are scoped tasks that don't require deep knowledge of the full system.
+
+Good candidates for first contributions:
+- **New goal templates** — Add alternative goal structures (OKRs, SMART goals, theme-based)
+- **New output styles** — Create personas beyond Productivity Coach (Socratic tutor, stoic mentor, etc.)
+- **Template variations** — Alternative daily/weekly note formats
+- **Documentation** — Improve setup guides, add workflow examples, fix unclear instructions
+- **Rule files** — Add new path-specific conventions (e.g., health tracking, learning logs)
+
+## Architecture Overview
+
+Understanding the system helps you contribute effectively:
+
+```
+vault-template/
+├── .claude/
+│   ├── skills/          # Slash commands — each has a SKILL.md
+│   │                    # user-invocable: true → shows in /skill-name
+│   │                    # user-invocable: false → auto-triggered
+│   ├── agents/          # Multi-turn personas with memory
+│   ├── hooks/           # Bash scripts triggered by events
+│   ├── rules/           # Always-loaded context conventions
+│   ├── output-styles/   # Tone/persona configurations
+│   └── settings.json    # Permissions, env vars, hook config
+├── Goals/               # The cascade files
+├── Templates/           # Note templates
+└── CLAUDE.md            # Root context file
+```
+
+### Key Design Principles
+
+1. **Zero dependencies** — No npm, no Python, no external tools. Everything is bash + markdown. This is intentional — keep it that way.
+
+2. **The cascade is the moat** — Every feature should strengthen the connection between goals → projects → daily tasks. If a feature doesn't connect to the cascade, it probably doesn't belong.
+
+3. **Skills, not scripts** — Skills are markdown files that instruct Claude, not executable code. They describe *what to do*, and Claude figures out *how*.
+
+4. **Agents have opinions** — Agents aren't generic assistants. The goal-aligner should challenge you. The weekly-reviewer should ask uncomfortable questions. The productivity coach should hold you accountable.
+
+5. **User content is sacred** — Never modify Daily Notes, Goals, Projects, or Archives without explicit user confirmation. System files in `.claude/` are fair game for upgrades.
+
+## Adding a New Skill
+
+1. Create `vault-template/.claude/skills/your-skill/SKILL.md`
+2. Add YAML frontmatter:
+   ```yaml
+   ---
+   name: your-skill
+   description: One-line description of what it does.
+   allowed-tools: Read, Write, Edit, Glob, Grep
+   model: sonnet
+   user-invocable: true
+   ---
+   ```
+3. Write the skill prompt — describe the workflow, output format, and integration points
+4. Add it to `vault-template/CLAUDE.md` skills table
+5. Update `README.md` skills table
+6. Test in a fresh vault
+
+## Adding a New Agent
+
+1. Create `vault-template/.claude/agents/your-agent.md`
+2. Add frontmatter with `memory: project` for cross-session learning
+3. Define the agent's personality, responsibilities, and output format
+4. Add to `vault-template/CLAUDE.md` agents table
+5. Test multi-turn interactions
+
+## Code Style
+
+- **Markdown** — Follow `vault-template/.claude/rules/markdown-standards.md`
+- **Bash scripts** — POSIX-compatible where possible, handle both macOS and Linux
+- **Commit messages** — Imperative mood, concise summary, body for context
+- **File naming** — Skills: `SKILL.md`. Agents: `kebab-case.md`. Rules: `kebab-case.md`.
+
+## Testing
+
+There's no automated test suite (yet). To test your changes:
+
+1. Copy `vault-template/` to a temporary location
+2. Open it as an Obsidian vault
+3. Start Claude Code in that directory
+4. Run the affected skills/agents
+5. Verify the output matches expectations
+
+## Questions?
+
+Open an issue or start a discussion. We're happy to help you find the right place to contribute.
diff --git a/README.md b/README.md
index 57d2760..325ec5c 100644
--- a/README.md
+++ b/README.md
@@ -2,144 +2,9 @@
 
 ---
 
-# Obsidian + Claude Code PKM Starter Kit 🚀
+# Obsidian + Claude Code: AI Accountability System
 
-A complete personal knowledge management system that combines Obsidian's powerful note-taking with Claude Code's AI assistance. Go from zero to a fully functional PKM in 15 minutes or less.
-
-**v3.0** - The Cascade: end-to-end goals-to-tasks flow with `/project` and `/monthly` skills, agent memory, and agent teams.
-
-## ✨ Features
-
-### Core PKM
-- **🎯 Goal-Aligned System** - Cascading goals from 3-year vision to daily tasks
-- **📅 Daily Notes System** - Structured daily planning and reflection
-- **📱 Mobile Ready** - GitHub integration for notes on any device
-- **🔄 Version Controlled** - Never lose a thought with automatic Git backups
-- **🎨 Fully Customizable** - Adapt templates and structure to your needs
-
-### AI-Powered (v3.0)
-- **🔗 The Cascade** - End-to-end flow: 3-year vision → yearly goals → projects → monthly → weekly → daily tasks
-- **📁 Project Management** - `/project` skill to create, track, and archive projects linked to goals
-- **📆 Monthly Reviews** - `/monthly` skill rolls up weekly reviews, checks quarterly milestones
-- **🧠 Agent Memory** - Agents learn your vault patterns across sessions (goal-aligner remembers misalignment patterns, weekly-reviewer learns your reflection style)
-- **👥 Agent Teams** - Parallel weekly reviews with collector, goal-analyzer, and project-scanner agents
-- **⚡ Unified Skills** - Skills and slash commands merged (`/daily`, `/weekly`, `/monthly`, `/project`, `/push`, `/onboard`)
-- **🪝 Hooks** - Auto-commit on save, session initialization with priority surfacing
-- **🤖 Custom Agents** - Note organizer, weekly reviewer, goal aligner, inbox processor
-- **📏 Modular Rules** - Path-specific conventions for markdown, productivity, projects
-- **🎭 Output Styles** - Productivity Coach for accountability
-- **📊 Status Line** - Vault stats in terminal (note count, inbox, uncommitted changes)
-- **👁️ Progress Visibility** - See spinner updates during multi-step operations like morning routines
-
-## 🚀 Quick Start
-
-### Prerequisites
-- [Obsidian](https://obsidian.md/) installed
-- [Claude Code CLI](https://code.claude.com/docs) installed
-- Git installed
-- GitHub account (optional, for mobile sync)
-
-### 15-Minute Quickstart
-```bash
-# 1) Install prerequisites (once)
-# - Obsidian: https://obsidian.md/
-# - Git: https://git-scm.com/
-# - Claude Code CLI: https://code.claude.com/docs
-
-# 2) Clone this repository
-git clone https://github.com/ballred/obsidian-claude-pkm.git
-cd obsidian-claude-pkm
-
-# 3) Run setup (macOS/Linux)
-chmod +x scripts/setup.sh
-./scripts/setup.sh
-
-# 3b) Windows
-scripts\setup.bat
-```
-
-### Manual Copy (alternative)
-```bash
-# Copy the vault template to your preferred location
-cp -r vault-template ~/Documents/ObsidianPKM
-```
-
-### Open in Obsidian
-1. Launch Obsidian
-2. Click "Open folder as vault"
-3. Select your vault folder (e.g., ~/Documents/ObsidianPKM)
-4. Start with today's daily note!
-
-## 📖 Documentation
-
-- **[Setup Guide](docs/SETUP_GUIDE.md)** - Detailed installation instructions
-- **[Customization](docs/CUSTOMIZATION.md)** - Make it yours
-- **[Workflow Examples](docs/WORKFLOW_EXAMPLES.md)** - Daily routines and best practices
-- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
-
-## 🗂️ Structure
-
-```
-Your Vault/
-├── CLAUDE.md                    # AI context and navigation
-├── CLAUDE.local.md.template     # Template for personal overrides
-├── .claude-plugin/
-│   └── plugin.json              # Plugin manifest
-├── .claude/
-│   ├── agents/                  # Custom AI agents
-│   │   ├── note-organizer.md
-│   │   ├── weekly-reviewer.md
-│   │   ├── goal-aligner.md
-│   │   └── inbox-processor.md
-│   ├── skills/                  # Unified skills (invoke with /skill-name)
-│   │   ├── daily/               # /daily - Create daily notes, routines
-│   │   ├── weekly/              # /weekly - Weekly review process
-│   │   ├── monthly/             # /monthly - Monthly review and planning (NEW)
-│   │   ├── project/             # /project - Create and track projects (NEW)
-│   │   ├── push/                # /push - Git commit and push
-│   │   ├── onboard/             # /onboard - Load vault context
-│   │   ├── goal-tracking/       # Auto: Track goal progress
-│   │   └── obsidian-vault-ops/  # Auto: Vault file operations
-│   ├── hooks/                   # Event automation (NEW)
-│   │   ├── session-init.sh
-│   │   └── auto-commit.sh
-│   ├── rules/                   # Path-specific conventions (NEW)
-│   │   ├── markdown-standards.md
-│   │   ├── productivity-workflow.md
-│   │   └── project-management.md
-│   ├── scripts/
-│   │   └── statusline.sh        # Terminal status display (NEW)
-│   ├── output-styles/
-│   │   └── coach.md             # Productivity Coach
-│   └── settings.json            # Permissions and config (NEW)
-├── Daily Notes/
-├── Goals/
-├── Projects/
-├── Templates/
-└── Archives/
-```
-
-## 🧠 Output Styles
-
-This starter kit includes a **Productivity Coach** output style that transforms Claude into an accountability partner. The coach will:
-
-- Challenge you to clarify your true intentions
-- Point out misalignments between stated goals and actions
-- Ask powerful questions to drive momentum
-- Hold you accountable to your commitments
-- Help you identify and overcome resistance
-
-To use the coach style in Claude Code:
-1. The output style is automatically included in `.claude/output-styles/`
-2. Start Claude Code and type `/output-style` to select from available styles
-3. Or directly activate with: `/output-style coach`
-4. The style preference is automatically saved for your project
-
-Learn more about [customizing output styles](docs/CUSTOMIZATION.md#output-styles).
-
-## 🔗 The Cascade
-
-The complete goals-to-tasks flow — the #1 requested feature:
+**Not another PKM starter kit.** This is an execution system that connects your 3-year vision to what you do today — and holds you accountable with AI.
 
 ```
 3-Year Vision ──→ Yearly Goals ──→ Projects ──→ Monthly Goals ──→ Weekly Review ──→ Daily Tasks
@@ -148,89 +13,186 @@ The complete goals-to-tasks flow — the #1 requested feature:
                          (the bridge layer)
 ```
 
-Every layer connects:
-- **`/project new`** creates a project linked to a yearly goal
-- **`/daily`** morning routine surfaces your ONE Big Thing + project next-actions
-- **`/weekly`** review includes a project progress table
-- **`/monthly`** review rolls up weekly reviews and checks quarterly milestones
-- **`/goal-tracking`** includes project completion % in goal progress calculations
+Every layer connects. `/daily` surfaces your ONE Big Thing from the weekly review. `/weekly` shows project progress. `/monthly` checks quarterly milestones. `/goal-tracking` knows which goals have no active project. Nothing falls through the cracks.
 
-## 🤖 Custom Agents (v3.0)
+**v3.1** · Zero dependencies · MIT License
 
-Ask Claude to use specialized agents for common PKM tasks:
+## The Cascade
+
+The #1 reason people star this repo: **"I want goals → projects → daily notes → tasks to actually connect."**
+
+| Layer | File | Skill | What It Does |
+|-------|------|-------|-------------|
+| Vision | `Goals/0. Three Year Goals.md` | `/goal-tracking` | Life areas, long-term direction |
+| Annual | `Goals/1. Yearly Goals.md` | `/goal-tracking` | Measurable objectives, quarterly milestones |
+| Projects | `Projects/*/CLAUDE.md` | `/project` | Active initiatives linked to goals |
+| Monthly | `Goals/2. Monthly Goals.md` | `/monthly` | Roll up weekly reviews, check quarterly progress |
+| Weekly | `Goals/3. Weekly Review.md` | `/weekly` | Reflect, realign, plan next week |
+| Daily | `Daily Notes/YYYY-MM-DD.md` | `/daily` | Morning planning, evening reflection |
+
+### How It Flows
+
+**Morning** — `/daily` creates today's note, shows your week's ONE Big Thing and active project next-actions. You pick your focus.
+
+**Evening** — `/daily` summarizes which goals and projects got attention today. Unlinked tasks get flagged.
+
+**Sunday** — `/weekly` reads all your daily notes, scans project status, calculates goal progress, and helps you plan next week. Optional agent team mode parallelizes the collection.
+
+**End of month** — `/monthly` rolls up the weekly reviews, checks quarterly milestones against yearly goals, and sets next month's priorities.
+
+**Ad hoc** — `/project new` creates a project linked to a goal. `/project status` shows a dashboard. `/review` auto-detects the right review type based on context.
+
+## Quick Start
+
+### Prerequisites
+- [Obsidian](https://obsidian.md/) installed
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
+- Git installed
+
+### Setup
 
 ```bash
-# Organize your vault and fix broken links
-claude "Use the note-organizer agent to audit my vault"
+# Clone and set up
+git clone https://github.com/ballred/obsidian-claude-pkm.git
+cd obsidian-claude-pkm
+chmod +x scripts/setup.sh && ./scripts/setup.sh
 
-# Facilitate weekly review aligned with goals
-claude "Use the weekly-reviewer agent for my weekly review"
+# Open vault in Obsidian, then start Claude Code:
+cd ~/your-vault-location
+claude
+```
 
-# Check if daily work aligns with long-term goals
-claude "Use the goal-aligner agent to analyze my recent activity"
+On first run, you'll see a welcome message with the cascade visualization. Run `/onboard` to personalize your vault — it asks your name, preferred review day, and goal areas, then configures everything.
 
-# Process inbox items using GTD principles
+### Windows
+
+```bash
+git clone https://github.com/ballred/obsidian-claude-pkm.git
+cd obsidian-claude-pkm
+scripts\setup.bat
+```
+
+## Skills (Slash Commands)
+
+| Skill | Command | Purpose |
+|-------|---------|---------|
+| Daily | `/daily` | Morning planning, midday check-in, evening reflection |
+| Weekly | `/weekly` | 30-min weekly review with project rollup |
+| Monthly | `/monthly` | Monthly review, quarterly milestone check |
+| Project | `/project` | Create, track, archive projects linked to goals |
+| Review | `/review` | Smart router — detects morning/Sunday/end-of-month context |
+| Push | `/push` | Commit and push vault changes to Git |
+| Onboard | `/onboard` | Interactive setup + load vault context |
+| Upgrade | `/upgrade` | Update to latest version, preserving your content |
+| Goal Tracking | *(auto)* | Track progress across the full cascade |
+| Vault Ops | *(auto)* | Read/write files, manage wiki-links |
+
+## AI Agents
+
+Four specialized agents with cross-session memory:
+
+| Agent | What It Does |
+|-------|-------------|
+| `goal-aligner` | Audits daily activity against stated goals. Flags misalignment. |
+| `weekly-reviewer` | Facilitates the 3-phase weekly review. Learns your reflection style. |
+| `note-organizer` | Fixes broken links, consolidates duplicates, maintains vault hygiene. |
+| `inbox-processor` | GTD-style inbox processing — categorize, clarify, organize. |
+
+```bash
+claude "Use the goal-aligner agent to analyze my last 2 weeks"
 claude "Use the inbox-processor agent to clear my inbox"
 ```
 
-## 🔄 Upgrading
+Agents use `memory: project` to learn your patterns across sessions — the goal-aligner remembers recurring misalignment patterns, the weekly-reviewer learns what reflection questions resonate.
 
-### From v2.1 to v3.0
+## Productivity Coach
+
+An output style that transforms Claude into an accountability partner:
 
 ```bash
-# 1. Copy new skill directories
+/output-style coach
+```
+
+The coach challenges assumptions, points out goal-action misalignment, asks powerful questions, and holds you to your commitments. Pairs naturally with `/daily` and `/weekly`.
+
+## Automation
+
+**Zero dependencies.** Everything runs on bash and markdown.
+
+- **Auto-commit** — Every file write/edit triggers a Git commit via PostToolUse hook
+- **Session init** — Surfaces your ONE Big Thing, active project count, and days since last review
+- **First-run welcome** — New vaults get a guided onboarding experience
+- **Skill discovery** — Mention "skill" or "help" and available commands are listed automatically
+- **Path-specific rules** — Markdown standards, productivity workflow, and project management conventions loaded contextually
+
+## Structure
+
+```
+Your Vault/
+├── CLAUDE.md                    # AI context and navigation
+├── .claude/
+│   ├── agents/                  # 4 specialized AI agents (with memory)
+│   ├── skills/                  # 10 skills (8 listed above + 2 auto)
+│   ├── hooks/                   # Auto-commit, session init, skill discovery
+│   ├── rules/                   # Path-specific conventions
+│   ├── output-styles/           # Productivity Coach
+│   └── settings.json            # Permissions, env vars, hooks config
+├── Daily Notes/                 # YYYY-MM-DD.md
+├── Goals/                       # The cascade (3-year → weekly)
+├── Projects/                    # Active projects with CLAUDE.md each
+├── Templates/                   # Reusable note structures
+├── Archives/                    # Completed/inactive content
+└── Inbox/                       # Quick captures (optional)
+```
+
+## Upgrading
+
+### Built-in upgrade (v3.1+)
+
+```bash
+/upgrade check    # Preview what's changed
+/upgrade          # Interactive upgrade with backup
+```
+
+The upgrade skill creates a timestamped backup, shows diffs for each changed file, and never touches your content folders (Daily Notes, Goals, Projects, etc.).
+
+### Manual upgrade from v2.1
+
+```bash
+# Copy new skill directories
 cp -r vault-template/.claude/skills/project your-vault/.claude/skills/
 cp -r vault-template/.claude/skills/monthly your-vault/.claude/skills/
+cp -r vault-template/.claude/skills/review your-vault/.claude/skills/
+cp -r vault-template/.claude/skills/upgrade your-vault/.claude/skills/
 
-# 2. Update existing files (review diff first)
-cp vault-template/.claude/settings.json your-vault/.claude/
-cp vault-template/.claude/hooks/session-init.sh your-vault/.claude/hooks/
-
-# 3. Update agents (adds memory: project)
+# Update agents, hooks, settings
 cp vault-template/.claude/agents/*.md your-vault/.claude/agents/
-
-# 4. Update existing skills (adds cascade features)
-cp -r vault-template/.claude/skills/daily your-vault/.claude/skills/
-cp -r vault-template/.claude/skills/weekly your-vault/.claude/skills/
-cp -r vault-template/.claude/skills/goal-tracking your-vault/.claude/skills/
-cp -r vault-template/.claude/skills/onboard your-vault/.claude/skills/
-
-# 5. Review and merge CLAUDE.md changes
-# Add /project and /monthly to your skills table, bump version
-
-# 6. Make scripts executable
+cp vault-template/.claude/hooks/* your-vault/.claude/hooks/
+cp vault-template/.claude/settings.json your-vault/.claude/
 chmod +x your-vault/.claude/hooks/*.sh
 ```
 
-### From v1.x to v3.0
+### From v1.x
 
 ```bash
-# 1. Copy all new directories to your vault
 cp -r vault-template/.claude-plugin your-vault/
-cp -r vault-template/.claude/agents your-vault/.claude/
-cp -r vault-template/.claude/skills your-vault/.claude/
-cp -r vault-template/.claude/hooks your-vault/.claude/
-cp -r vault-template/.claude/rules your-vault/.claude/
-cp -r vault-template/.claude/scripts your-vault/.claude/
-cp vault-template/.claude/settings.json your-vault/.claude/
-cp vault-template/CLAUDE.local.md.template your-vault/
-
-# 2. Review and merge CLAUDE.md changes
-# Your customizations are preserved, just add references to new features
-
-# 3. Make hook scripts executable
+cp -r vault-template/.claude your-vault/
+cp vault-template/CLAUDE.md your-vault/
 chmod +x your-vault/.claude/hooks/*.sh
-chmod +x your-vault/.claude/scripts/*.sh
 ```
 
-## 🤝 Contributing
+## Documentation
 
-Found a bug or have a feature idea? Please open an issue or submit a PR!
+- **[Setup Guide](docs/SETUP_GUIDE.md)** — Detailed installation instructions
+- **[Customization](docs/CUSTOMIZATION.md)** — Make it yours
+- **[Workflow Examples](docs/WORKFLOW_EXAMPLES.md)** — Daily routines and best practices
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** — Common issues and solutions
+- **[Contributing](CONTRIBUTING.md)** — How to help
 
-## 📄 License
+## Contributing
 
-MIT - Use this freely for your personal knowledge management journey.
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Good first issues are labeled — check the [issues page](https://github.com/ballred/obsidian-claude-pkm/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
 
----
+## License
 
-**Ready to transform your note-taking?** Follow the [Setup Guide](docs/SETUP_GUIDE.md) to get started!
\ No newline at end of file
+MIT — Use this freely for your personal knowledge management journey.
diff --git a/vault-template/.claude/hooks/session-init.sh b/vault-template/.claude/hooks/session-init.sh
index 52bf961..6b76fd3 100755
--- a/vault-template/.claude/hooks/session-init.sh
+++ b/vault-template/.claude/hooks/session-init.sh
@@ -13,6 +13,25 @@ export CURRENT_WEEK=$(date +%Y-W%V)
 # Daily note path
 export DAILY_NOTE="$VAULT_PATH/Daily Notes/$TODAY.md"
 
+# First-run detection
+if [ -f "$VAULT_PATH/FIRST_RUN" ]; then
+    echo ""
+    echo "Welcome to the Obsidian + Claude Code AI Accountability System!"
+    echo ""
+    echo "  The Cascade — your goals-to-tasks execution system:"
+    echo ""
+    echo "  3-Year Vision -> Yearly Goals -> Projects -> Monthly -> Weekly -> Daily"
+    echo "       |               |             |           |          |        |"
+    echo "  /goal-tracking  /goal-tracking  /project   /monthly   /weekly   /daily"
+    echo ""
+    echo "  Run /onboard to personalize your vault (takes ~2 minutes)."
+    echo "  This will ask your name, preferred review day, and goal areas."
+    echo ""
+    echo "  After that, try /daily to start your first morning routine."
+    echo ""
+    exit 0
+fi
+
 # Verify vault structure
 if [ ! -f "$VAULT_PATH/CLAUDE.md" ]; then
     echo "Note: Not in a vault root directory (no CLAUDE.md found)"
diff --git a/vault-template/.claude/hooks/skill-discovery.sh b/vault-template/.claude/hooks/skill-discovery.sh
new file mode 100755
index 0000000..78d8165
--- /dev/null
+++ b/vault-template/.claude/hooks/skill-discovery.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+# Skill discovery hook — triggered on UserPromptSubmit
+# Lists available skills when user mentions "skill", "help", "command", or "what can"
+# Non-blocking: always exits 0
+
+# Read user prompt from stdin
+PROMPT=$(cat)
+
+# Case-insensitive check for trigger words
+if echo "$PROMPT" | grep -iqE '\b(skills?|commands?|what can|help me|available|slash)\b'; then
+    echo ""
+    echo "Available skills (invoke with /skill-name):"
+    echo ""
+
+    SKILLS_DIR="$(pwd)/.claude/skills"
+    if [ -d "$SKILLS_DIR" ]; then
+        for skill_dir in "$SKILLS_DIR"/*/; do
+            if [ -f "$skill_dir/SKILL.md" ]; then
+                skill_name=$(basename "$skill_dir")
+                # Extract description from YAML frontmatter
+                desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; q; } }' "$skill_dir/SKILL.md")
+                # Check if user-invocable
+                invocable=$(sed -n '/^---$/,/^---$/{ /^user-invocable:/{ s/^user-invocable: *//; p; q; } }' "$skill_dir/SKILL.md")
+                if [ "$invocable" = "true" ]; then
+                    printf "  /%s — %s\n" "$skill_name" "$desc"
+                else
+                    printf "  %s (auto) — %s\n" "$skill_name" "$desc"
+                fi
+            fi
+        done
+    fi
+    echo ""
+fi
+
+exit 0
diff --git a/vault-template/.claude/settings.json b/vault-template/.claude/settings.json
index 510db94..36967d0 100644
--- a/vault-template/.claude/settings.json
+++ b/vault-template/.claude/settings.json
@@ -47,6 +47,17 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/skill-discovery.sh",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
diff --git a/vault-template/.claude/skills/onboard/SKILL.md b/vault-template/.claude/skills/onboard/SKILL.md
index fe433f4..ca96e22 100644
--- a/vault-template/.claude/skills/onboard/SKILL.md
+++ b/vault-template/.claude/skills/onboard/SKILL.md
@@ -1,30 +1,96 @@
 ---
 name: onboard
-description: Load CLAUDE.md context files from vault for comprehensive understanding. Discovers hierarchical context, recent notes, and project states. Use at start of session or when Claude needs full vault context.
-allowed-tools: Read, Glob, Grep
+description: Interactive vault setup and context loading. On first run, personalizes your vault. On subsequent runs, loads full context. Use at start of session or when Claude needs full vault context.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
 model: sonnet
 user-invocable: true
 ---
 
 # Onboard Skill
 
-Loads all CLAUDE.md files from your vault to provide comprehensive context for intelligent assistance.
+Interactive vault setup (first run) and context loading (subsequent runs).
 
 ## Usage
 
-Invoke with `/onboard` or ask Claude to learn about your vault.
-
-### Full Context Load
 ```
-/onboard
+/onboard                    # Full onboard (setup if first run, context load if not)
+/onboard Projects/MyProject # Load specific project context
 ```
 
-### Specific Project Context
-```
-/onboard Projects/MyProject
+## First-Run Setup
+
+If the file `FIRST_RUN` exists in the vault root, this is a new vault. Run the interactive setup:
+
+### Step 1: Welcome
+Greet the user and explain what will happen:
+- "I'll ask a few questions to personalize your vault (~2 minutes)"
+- "Your answers are saved locally in vault-config.json"
+- "You can change these anytime by editing that file or running /onboard again"
+
+### Step 2: Ask Questions
+
+Use AskUserQuestion to ask these interactively:
+
+**Question 1: Your name**
+- "What should I call you?"
+- Used for personalized prompts and greetings
+
+**Question 2: Preferred review day**
+- "What day do you prefer for your weekly review?"
+- Options: Sunday (Recommended), Saturday, Monday, Friday
+- Used by `/review` auto-detection and session-init nudges
+
+**Question 3: Primary goal areas**
+- "Which areas are most important to you right now? (Pick 2-4)"
+- Options: Career & Professional, Health & Wellness, Relationships, Personal Growth
+- Also offer: Financial, Creativity & Fun, Learning, Other
+- multiSelect: true
+- Used to customize goal template suggestions
+
+**Question 4: Work style**
+- "How do you prefer Claude to interact?"
+- Options: Direct and concise (Recommended), Coaching and challenging, Detailed and thorough, Minimal — just do the task
+- Sets output style preference
+
+### Step 3: Save Configuration
+
+Write `vault-config.json` in the vault root:
+```json
+{
+  "name": "User's name",
+  "reviewDay": "Sunday",
+  "goalAreas": ["Career & Professional", "Health & Wellness"],
+  "workStyle": "Direct and concise",
+  "setupDate": "2026-02-15",
+  "version": "3.1"
+}
 ```
 
-## What This Skill Does
+### Step 4: Personalize CLAUDE.md
+
+Edit the root `CLAUDE.md`:
+- Replace `[CUSTOMIZE: Add your personal mission statement here]` with a prompt based on their goal areas
+- Update the "Current Focus" section to reference their chosen areas
+
+### Step 5: Remove First-Run Marker
+
+```bash
+rm FIRST_RUN
+```
+
+### Step 6: Confirm Setup
+
+Tell the user:
+- "Your vault is set up! Here's what's available:"
+- Brief cascade overview
+- "Try `/daily` to start your first morning routine"
+- "Try `/review` anytime — it auto-detects the right review type"
+
+Then proceed to the standard context loading below.
+
+## Standard Context Loading (Subsequent Runs)
+
+### What This Skill Does
 
 1. **Discovers Context Files**
    - Searches for all CLAUDE.md files
@@ -41,7 +107,12 @@ Invoke with `/onboard` or ask Claude to learn about your vault.
    - Extracts project name, phase, progress, and goal linkage
    - Displays active project count and summary in onboard output
 
-4. **Builds Understanding**
+4. **Reads User Preferences**
+   - Loads `vault-config.json` if present
+   - Applies name, review day, work style preferences
+   - Uses goal areas to prioritize context loading
+
+5. **Builds Understanding**
    - Your personal mission/goals
    - Project structures and status
    - Workflow preferences
diff --git a/vault-template/.claude/skills/review/SKILL.md b/vault-template/.claude/skills/review/SKILL.md
new file mode 100644
index 0000000..65b1c8e
--- /dev/null
+++ b/vault-template/.claude/skills/review/SKILL.md
@@ -0,0 +1,123 @@
+---
+name: review
+description: Smart review router. Detects context (morning, Sunday, end of month) and launches the appropriate review workflow. Use anytime for the right review at the right time.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList, TaskGet
+model: sonnet
+user-invocable: true
+---
+
+# Review Skill
+
+Smart router that detects context and launches the appropriate review workflow.
+
+## Usage
+
+```
+/review           # Auto-detect the right review based on time/context
+/review daily     # Force daily review
+/review weekly    # Force weekly review
+/review monthly   # Force monthly review
+```
+
+Or simply: "Help me review" — and the right workflow starts.
+
+## Auto-Detection Logic
+
+When invoked without arguments, detect context using these rules:
+
+### 1. Check the Time of Day
+
+```bash
+HOUR=$(date +%H)
+```
+
+- **Before noon (< 12):** Morning routine — delegate to `/daily` morning workflow
+- **After 5 PM (>= 17):** Evening shutdown — delegate to `/daily` evening workflow
+- **Midday (12-17):** Midday check-in — delegate to `/daily` midday workflow
+
+### 2. Check the Day of Week
+
+```bash
+DAY_OF_WEEK=$(date +%u)  # 1=Monday, 7=Sunday
+```
+
+- **Sunday (7) or Monday (1):** Weekly review — delegate to `/weekly`
+  - Override time-of-day detection
+  - Ask: "Ready for your weekly review?" before proceeding
+
+### 3. Check the Day of Month
+
+```bash
+DAY_OF_MONTH=$(date +%d)
+DAYS_IN_MONTH=$(date -v+1m -v1d -v-1d +%d 2>/dev/null || date -d "$(date +%Y-%m-01) +1 month -1 day" +%d)
+```
+
+- **Last 3 days of month (DAY_OF_MONTH >= DAYS_IN_MONTH - 2):** Monthly review — delegate to `/monthly`
+  - Override both time-of-day and day-of-week detection
+  - Ask: "End of month — ready for your monthly review?" before proceeding
+
+- **First day of month (DAY_OF_MONTH == 1):** Also suggest monthly review
+  - "It's the first of the month. Want to do your monthly review for last month?"
+
+### 4. Check Staleness
+
+Before routing, check for overdue reviews:
+
+```bash
+# Read weekly review file for last date
+WEEKLY_REVIEW="Goals/3. Weekly Review.md"
+# If last weekly review > 7 days ago, suggest weekly regardless of day
+```
+
+- **Weekly review overdue (>7 days):** Suggest weekly review
+  - "Your last weekly review was N days ago. Want to catch up?"
+  - If user says no, fall through to time-of-day detection
+
+## Routing Behavior
+
+After detecting context:
+
+1. Tell the user what was detected: "It's Sunday evening — launching your weekly review."
+2. Delegate to the appropriate skill's workflow
+3. The delegated skill handles everything from there
+
+### Delegation
+
+This skill does NOT duplicate the logic of `/daily`, `/weekly`, or `/monthly`. It:
+1. Detects context
+2. Informs the user
+3. Follows the instructions from the target skill's SKILL.md
+
+### Explicit Override
+
+If the user specifies a type (`/review weekly`), skip auto-detection entirely and go directly to that review type.
+
+## Output on Detection
+
+```markdown
+### Review Router
+
+**Time:** 7:15 AM (Morning)
+**Day:** Sunday
+**Month day:** 15th
+
+**Detected:** Weekly review (Sunday override)
+**Last weekly review:** 3 days ago (not overdue)
+
+Launching weekly review...
+```
+
+## Edge Cases
+
+- **Multiple triggers** (e.g., last Sunday of month): Monthly takes priority over weekly
+- **No daily note exists**: Create one first, then continue with review
+- **User says "no" to suggestion**: Fall through to next detection level
+- **Explicit argument overrides everything**: `/review monthly` runs monthly review even on a Tuesday morning
+
+## Integration
+
+Works with:
+- `/daily` — Morning, midday, and evening routines
+- `/weekly` — Full weekly review process
+- `/monthly` — Monthly review and planning
+- Session init hook — Staleness data already calculated
diff --git a/vault-template/.claude/skills/upgrade/SKILL.md b/vault-template/.claude/skills/upgrade/SKILL.md
new file mode 100644
index 0000000..87084b1
--- /dev/null
+++ b/vault-template/.claude/skills/upgrade/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: upgrade
+description: Update vault to the latest version of obsidian-claude-pkm. Creates backup, shows diffs, preserves your content. Use when a new version is available.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+user-invocable: true
+---
+
+# Upgrade Skill
+
+Updates your vault's system files to the latest version while preserving all your personal content.
+
+## Usage
+
+```
+/upgrade          # Interactive upgrade with backup and diff review
+/upgrade check    # Preview what's changed without making modifications
+```
+
+## What Gets Updated (System Files)
+
+- `.claude/skills/*/SKILL.md` — Skill definitions
+- `.claude/agents/*.md` — Agent configurations
+- `.claude/hooks/*.sh` — Automation scripts
+- `.claude/rules/*.md` — Convention rules
+- `.claude/output-styles/*.md` — Output style definitions
+- `.claude/settings.json` — Permissions and hook config
+- `CLAUDE.md` — Root context file (merged carefully)
+- `Templates/*.md` — Note templates
+
+## What Never Gets Touched (Your Content)
+
+- `Daily Notes/**` — Your daily journal entries
+- `Goals/**` — Your goal files and reviews
+- `Projects/**` — Your project folders and CLAUDE.md files
+- `Archives/**` — Your archived content
+- `Inbox/**` — Your captured items
+- `CLAUDE.local.md` — Your personal overrides
+- `vault-config.json` — Your preferences
+
+## Upgrade Process
+
+### Step 1: Check for Updates
+
+Read the current version from `CLAUDE.md` (look for "System Version:" line).
+
+Compare with the upstream repo. If using git:
+```bash
+git fetch origin
+git log HEAD..origin/main --oneline
+```
+
+If not a git repo or no remote, inform user they need to download the latest `vault-template/` manually.
+
+### Step 2: Create Backup
+
+Before any changes, create a timestamped backup:
+```bash
+BACKUP_DIR=".backup/upgrade-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+cp -r .claude "$BACKUP_DIR/"
+cp CLAUDE.md "$BACKUP_DIR/"
+cp -r Templates "$BACKUP_DIR/" 2>/dev/null
+```
+
+Tell the user: "Backup created at $BACKUP_DIR"
+
+### Step 3: Diff Review
+
+For each system file that differs from upstream:
+1. Show a summary of what changed (additions, removals, modifications)
+2. Ask user to confirm: "Apply this update? (yes/skip/stop)"
+3. If yes: apply the change
+4. If skip: leave this file unchanged
+5. If stop: halt the upgrade (backup remains, partial changes preserved)
+
+### Step 4: Apply Changes
+
+For each confirmed file:
+- Copy the new version from upstream
+- For `CLAUDE.md`: merge carefully — preserve user customizations (Personal Mission, Current Focus sections) while updating system sections (Skills table, version number)
+- For `settings.json`: merge — add new permissions/hooks, preserve existing customizations
+
+### Step 5: Post-Upgrade
+
+1. Make hook scripts executable: `chmod +x .claude/hooks/*.sh`
+2. Show summary of changes applied
+3. Update version in CLAUDE.md
+4. Suggest running `/onboard` to reload context
+
+## Check Mode (`/upgrade check`)
+
+When invoked with "check":
+1. Compare system files against upstream
+2. List files that would be updated with brief change description
+3. Show version numbers (current → available)
+4. Do NOT make any changes
+5. Suggest running `/upgrade` to apply
+
+## Output Format
+
+```markdown
+## Upgrade Check
+
+**Current version:** 3.0 (The Cascade)
+**Available version:** 3.1
+
+### Files to Update
+| File | Change Summary |
+|------|---------------|
+| `.claude/skills/daily/SKILL.md` | Added cascade context surfacing |
+| `.claude/agents/goal-aligner.md` | Added memory: project |
+| `.claude/hooks/session-init.sh` | Added priority surfacing |
+
+### New Files
+- `.claude/skills/review/SKILL.md` — Smart review router
+- `.claude/hooks/skill-discovery.sh` — Auto-list skills
+
+### No Changes Needed
+- `.claude/rules/` — Already up to date
+
+Run `/upgrade` to apply these updates (backup will be created first).
+```
+
+## Safety Features
+
+- Complete backup before any modification
+- File-by-file confirmation
+- Can be stopped at any point
+- User content folders are never touched
+- `CLAUDE.local.md` personal overrides preserved
+- Backup includes restoration instructions
+
+## Error Handling
+
+- If no git remote: guide user to download latest vault-template manually
+- If backup fails: abort entire upgrade
+- If a file copy fails: report error, continue with next file
+- Always leave vault in a usable state
+
+## Integration
+
+Works with:
+- `/onboard` — Reload context after upgrade
+- Session init hook — Will reflect updated priorities
diff --git a/vault-template/CLAUDE.md b/vault-template/CLAUDE.md
index 75f8dbd..9bd7b37 100644
--- a/vault-template/CLAUDE.md
+++ b/vault-template/CLAUDE.md
@@ -36,8 +36,10 @@ Skills are invoked with `/skill-name` or automatically by Claude when relevant.
 | `weekly` | `/weekly` | Run weekly review, reflect and plan |
 | `monthly` | `/monthly` | Monthly review, quarterly milestone check, next month planning |
 | `project` | `/project` | Create, track, and archive projects linked to goals |
+| `review` | `/review` | Smart router — auto-detects daily/weekly/monthly based on context |
 | `push` | `/push` | Commit and push changes to Git |
-| `onboard` | `/onboard` | Load full vault context |
+| `onboard` | `/onboard` | Interactive setup (first run) + load vault context |
+| `upgrade` | `/upgrade` | Update to latest version, preserving your content |
 | `goal-tracking` | (auto) | Track progress across goal cascade with project awareness |
 | `obsidian-vault-ops` | (auto) | Read/write vault files, manage wiki-links |
 
@@ -123,7 +125,7 @@ See `CLAUDE.local.md.template` for format.
 
 *See @.claude/rules/ for detailed conventions*
 *Last Updated: 2026-02-15*
-*System Version: 3.0 (The Cascade)*
+*System Version: 3.1*
 
 
 <claude-mem-context>
diff --git a/vault-template/FIRST_RUN b/vault-template/FIRST_RUN
new file mode 100644
index 0000000..4a40e5a
--- /dev/null
+++ b/vault-template/FIRST_RUN
@@ -0,0 +1,2 @@
+This file triggers the first-run welcome message.
+It is automatically removed after you run /onboard.